# Amazon Ads
Source: https://docs.runconverge.com/ad-platforms/integrations/amazon-ads

An introduction to the Amazon Ads marketing source

<Note>
  The Amazon Ads marketing source lets you see platform-specific metrics (like
  Ad Spend) in Converge.
</Note>

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and name your ad platform sync: e.g `Amazon Ads | {Amazon Ads Account ID}`

3. Select **Amazon Ads** from the drop-down list and sign in with your Amazon Ads account.

4. Once the Amazon account has been linked, **select the region and profile** you want to connect.

5. After pressing **Create** your Amazon Ads metrics will stream into Converge.

<Warning>
  Amazon data in Converge can be delayed by up to 16 hours. We sync hourly, but our integration with Amazon doesn't provide real-time data. Connecting this source means blended metrics that include Amazon will only be accurate up to 16 hours in the past.
</Warning>

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="xmark" /> |
| Custom Conversions                         | <Icon name="xmark" /> |

<Note>Amazon data can be delayed by up to 16 hours. While Converge syncs hourly, Amazon's API doesn't provide real-time data, meaning your metrics will reflect data from 16+ hours ago.</Note>

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Amazon Ads. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                         |
    | --------------- | ----------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your Amazon ads.                                 |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on Amazon ads.    |
    | **CTR**         | The average percentage of people who clicked on your Amazon ad after seeing it.     |
    | **CPA**         | The average cost associated with actions from your Amazon ads.                      |
    | **CPC**         | The average cost per click on your Amazon ads.                                      |
    | **CPM**         | The average cost per thousand impressions of your Amazon ads.                       |
    | **Conversions** | The number of Amazon-attributed purchases that happened because of your Amazon ads. |
    | **Clicks**      | The total number of clicks on your Amazon ads.                                      |
    | **Impressions** | The number of times your Amazon ads were on-screen.                                 |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report provides detailed performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand which elements are most effective.

    | Metric        | Description                                                          |
    | ------------- | -------------------------------------------------------------------- |
    | **Purchases** | The total number of purchases as attributed by Amazon to Amazon ads. |
    | **Revenue**   | The total revenue generated as attributed by Amazon to Amazon ads.   |
    | **ROAS**      | The return on ad spend as attributed by Amazon to Amazon ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by Amazon.          |
    | **Ad Spend**  | The total expenditure on Amazon Advertising.                         |
  </Accordion>
</AccordionGroup>


# AppLovin
Source: https://docs.runconverge.com/ad-platforms/integrations/applovin

An introduction to the AppLovin marketing source

<Note> The AppLovin marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to AppLovin, check out the [AppLovin Destination](/destinations/integrations/applovin) instead.</Note>

## Set up the Marketing source

1. Navigate to your <OutboundLink /> and choose **Account > Keys**.

2. Copy your **Report Key**.

<Frame>
  <img alt="AppLovin Report Key" />
</Frame>

3. In the Converge dashboard, navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms).

4. Click on **Connect a new ad platform** and then choose **AppLovin**.

5. Name your ad platform sync: e.g. `AppLovin Ad Account`.

6. Fill in the **Report Key** you copied from **AppLovin** in *Step 2*.

7. After pressing **Create** your AppLovin metrics will stream into Converge.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="check" /> |
| Custom Conversions                         | <Icon name="xmark" /> |

***

## Set up your Converge Tracking Parameters

1. Navigate to the AppLovin Ad Manager.

2. Open your campaign and go to the Objective section.

3. Edit the tracking template and select Converge under **Measurement partner parameters**.

<Frame>
  <img alt="AppLovin Tracking Parameters" />
</Frame>

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on AppLovin. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                    |
    | --------------- | ------------------------------------------------------------------------------ |
    | **Ad Spend**    | The total amount of money spent on your ads.                                   |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on ads.      |
    | **CTR**         | The average percentage of people who clicked on your ads after seeing them.    |
    | **CPA**         | The average cost associated with actions from your ads.                        |
    | **CPC**         | The average cost per click on your ads.                                        |
    | **CPM**         | The average cost per thousand impressions of your ads.                         |
    | **Conversions** | The number of AppLovin-attributed purchases that happened because of your ads. |
    | **Clicks**      | The total number of clicks on your ads.                                        |
    | **Impressions** | The number of times your ads were on-screen.                                   |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                              |
    | ------------- | ------------------------------------------------------------------------ |
    | **Purchases** | The total number of purchases as attributed by AppLovin to AppLovin ads. |
    | **Revenue**   | The total revenue generated as attributed by AppLovin to AppLovin ads.   |
    | **ROAS**      | The return on ad spend as attributed by AppLovin to AppLovin ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by AppLovin.            |
    | **Ad Spend**  | The total expenditure on AppLovin Advertising.                           |
  </Accordion>
</AccordionGroup>


# Attentive
Source: https://docs.runconverge.com/ad-platforms/integrations/attentive

An introduction to the Attentive marketing source

<Note>
  The Attentive marketing source brings your Attentive SMS and email performance
  (sends, deliveries, opens, clicks, and attributed revenue) into Converge, so
  you can analyze it alongside your other marketing channels.
</Note>

## How it works

Attentive does not offer a reporting API, so Converge reads Attentive's daily **SFTP data feeds** instead. Once your Attentive team enables them, Attentive drops two CSV files onto an SFTP server each day:

* **Conversions feed**: one row per attributed purchase, used for revenue and conversions.
* **General Events feed**: an event log of messaging engagement (sends, deliveries, opens, clicks, and more).

Converge imports each new file as Attentive publishes it. Attentive updates the feeds once per day, though the exact time varies, so your Attentive data refreshes daily. Events are grouped per message, and each Attentive message maps to a campaign in Converge. Attentive keeps a rolling 30 days of files, so Converge can backfill up to 30 days when you first connect.

***

## Before you start

Connecting Attentive requires two one-time steps on the Attentive side.

### 1. Request the SFTP data feeds

Attentive needs to provision the SFTP feeds for you. Send the email below to your Attentive CSM (or to [Attentive support](mailto:whiteglove@attentivemobile.com)), filling in the bracketed details.

<Note>Copy and edit the email below.</Note>

```text theme={null}
Subject: SFTP data feed setup - [Company]

Hi team,

We'd like to set up an SFTP data feed for our Attentive account to sync our
messaging performance into our analytics platform (Converge).

Account details:
- Company display name: [your company]
- Website: [yourdomain.com]
- Attentive account email: [your Attentive account email]

Could you please:
1. Create an SFTP account, and
2. Enable the daily Conversions and General Events data feeds.

CONVERSIONS FEED - columns:
- message_id
- message_name
- uuid
- amount
- timestamp

GENERAL EVENTS FEED - event types:
- MESSAGE_RECEIPT
- MESSAGE_LINK_CLICK
- EMAIL_PROCESSED
- EMAIL_DELIVERED
- EMAIL_MESSAGE_OPENED
- EMAIL_SOFT_BOUNCE
- EMAIL_HARD_BOUNCE
- EMAIL_DROPPED
- EMAIL_SPAM_REPORTED
- OPT_OUT

GENERAL EVENTS FEED - columns:
- type
- message_id
- message_name
- timestamp

Backfill: our system reads up to your 30-day retention window, so a 30-day
backfill on both feeds would be ideal.

Once the SFTP account is ready, please share the SFTP username and host; we'll
set the password from our Attentive settings.

Thanks!
[Your name]
```

### 2. Set your SFTP password

After Attentive creates the SFTP account, they will share your **SFTP username**. You set the **password** yourself from the [Attentive SFTP account settings page](https://ui.attentivemobile.com/settings/sftp-account-settings).

Keep the username and password handy for the next step. For more detail, see Attentive's [Connect to Attentive SFTP guide](https://docs.attentive.com/pages/developer-guides/sftp-solution/connect-to-attentive-sftp/).

***

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in Converge, click **Connect a new ad platform**, and choose **Attentive**.

2. Give your connection a name, e.g. `Attentive | {Account name}`.

3. Enter your SFTP credentials:
   * **SFTP Username**: the username Attentive shared with you.
   * **SFTP Password**: the password you set in the Attentive SFTP settings page.
   * **Currency**: the currency your Attentive account reports in. The feed has no currency column, so Converge tags all synced revenue with this value.

4. Press **Create**. Converge will connect to the feed and start syncing your Attentive data.

<Note>
  You do not need to enter an SFTP host. Converge uses Attentive's standard host
  (`sftp.client.attentivemobile.com`) automatically. If Attentive gave you a
  non-standard host, contact your Converge representative.
</Note>

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature   | Supported             |
| ------------------ | --------------------- |
| Sync Frequency     | Every day             |
| Custom Conversions | <Icon name="check" /> |

<Note>
  Attentive's data feed does not include billable spend, so spend based metrics
  such as ROAS and CPA are not available for this source. Converge ingests
  Attentive's attributed revenue, conversions, and engagement metrics.
</Note>

***

## Supported metrics

We ingest a focused set of metrics that mirror the definitions you see in Attentive's own reporting.

<AccordionGroup>
  <Accordion icon="cart-shopping" title="Revenue and Conversions">
    Sourced from the **Conversions feed**. These are the purchases Attentive attributes to your messaging.

    | Metric          | Description                                                         |
    | --------------- | ------------------------------------------------------------------- |
    | **Conversions** | The number of purchases Attentive attributes to a message.          |
    | **Revenue**     | The total revenue from purchases Attentive attributes to a message. |
  </Accordion>

  <Accordion icon="comment-sms" title="Engagement metrics">
    Sourced from the **General Events feed**. These count messaging engagement per message.

    <Note>
      These are raw event counts, so they can read slightly higher than the unique,
      bot-filtered figures shown in Attentive's own dashboard.
    </Note>

    | Metric                  | Description                                                               |
    | ----------------------- | ------------------------------------------------------------------------- |
    | **Text message sends**  | The number of SMS/MMS messages sent.                                      |
    | **Email message sends** | The number of emails Attentive processed for sending.                     |
    | **Emails delivered**    | The number of emails successfully delivered to the recipient.             |
    | **Email opens**         | The number of times a delivered email was opened.                         |
    | **Link clicks**         | The number of times a tracked link in a message was clicked.              |
    | **Soft bounces**        | The number of emails that failed to deliver due to a temporary issue.     |
    | **Hard bounces**        | The number of emails that failed to deliver due to a permanent issue.     |
    | **Emails dropped**      | The number of emails Attentive skipped sending (e.g. suppressed address). |
    | **Spam complaints**     | The number of times a recipient reported an email as spam.                |
    | **Unsubscribes**        | The number of times a recipient opted out.                                |
  </Accordion>
</AccordionGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="How often does the data update?">
    Attentive generates the feed files once per day, though the exact time
    varies. Converge imports the new file the same day, so your Attentive data
    updates once per day.
  </Accordion>

  <Accordion title="How far back can I backfill?">
    Attentive keeps a rolling 30 days of feed files, so Converge backfills up to
    30 days of history when you first connect. Data older than 30 days is not
    available from the feed.
  </Accordion>

  <Accordion title="Why are my open and click numbers higher than in Attentive?">
    Converge counts every engagement event in the feed. Attentive's dashboard
    typically shows unique, bot-filtered figures, so raw counts read slightly
    higher. Both are correct; they measure different things.
  </Accordion>

  <Accordion title="Can I track spend or ROAS for Attentive?">
    No. The Attentive feed does not include billable spend, so spend based metrics
    like ROAS and CPA are not available for this source. You still get attributed
    revenue, conversions, and engagement metrics.
  </Accordion>

  <Accordion title="Which Attentive messages show up in Converge?">
    Each Attentive message, whether a one-time campaign or an automated journey,
    maps to its own campaign in Converge. Metrics and revenue are grouped at the
    message level.
  </Accordion>
</AccordionGroup>


# Microsoft Ads (Bing Ads)
Source: https://docs.runconverge.com/ad-platforms/integrations/bing

An introduction to the Microsoft Ads marketing source

<Note> The Microsoft Ads marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to Microsoft Ads, check out the [Microsoft Ads Destination](/destinations/integrations/bing) instead.</Note>

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and then choose **Microsoft Ads (Bing Ads)**.

3. Name your ad platform sync: e.g. `Microsoft Ads | {Ad Account ID}` and then press **Sign in with Microsoft**. Go through the installation.

4. Once the Microsoft Ads account has been linked, you can **select your Microsoft Ads account**.

5. Once a Microsoft Ads account is selected, you can **select your conversion events**.

<Info>
  The selected conversion events will be used by Converge to sync the **Purchase**, **Revenue**, and related fields in the attribution dashboards.
  If *multiple events* are selected, the respective values will be summed up.
  If *no events* are selected, all conversion events will be used.
</Info>

<Info>
  The list of conversion events map to the **Conversion goals** defined in Microsoft Ads.
</Info>

<Info>
  Converge will also sync all individual conversion events into separate columns automatically.
</Info>

6. After pressing **Create** your Microsoft Ads metrics will stream into Converge.

<Info>
  If you encounter the `AADSTS650052` error, your Microsoft Ads account has insufficient permissions to provide access to Converge. You can find more information in Microsoft Ads' documentation [here](https://learn.microsoft.com/en-us/advertising/guides/handle-service-errors-exceptions?view=bingads-13#aadsts650052).

  There are two conditions for you to be able to authenticate:

  1. Your account requires **Allow user consent for apps** access (see "Configure User Consent Settings" [here](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-user-consent?pivots=portal)).
  2. You need a **Business account**, not a personal one. Personal accounts let you access the Microsoft Ads portal yourself, but don't allow you to authenticate to a 3rd party like Converge. You can verify your account type under **Settings > My Settings > Signed In With** in the Microsoft Ads portal.
</Info>

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="check" /> |
| Custom Conversions                         | <Icon name="check" /> |

***

## Set up your Converge Tracking Parameters

1. Navigate to your <OutboundLink />

2. Navigate to <IconText name="bullhorn" /> > **Settings** in the side-bar.
   <Frame>
     <img alt="Bing" />
   </Frame>

3. Choose **Account level options** from the top bar.

4. Under **Tracking template**, copy and paste the following tracking template.
   ```
   {lpurl}?utm_source=bing&utm_medium=paid&utm_campaign={Campaign}&utm_content={AdId}&cvg_source=bing&cvg_adid={AdId}&cvg_cid={CampaignId}
   ```
   <Frame>
     <img alt="Bing URL Params" />
   </Frame>

5. Scroll down and click on **Save**.

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Microsoft Ads. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                               |
    | --------------- | ----------------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your Microsoft Ads.                                    |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on Microsoft Ads.       |
    | **CTR**         | The average percentage of people who clicked on your Microsoft ad after seeing it.        |
    | **CPA**         | The average cost associated with actions from your Microsoft Ads.                         |
    | **CPC**         | The average cost per click on your Microsoft Ads.                                         |
    | **CPM**         | The average cost per thousand impressions of your Microsoft Ads.                          |
    | **Conversions** | The number of Microsoft-attributed purchases that happened because of your Microsoft Ads. |
    | **Clicks**      | The total number of clicks on your Microsoft Ads.                                         |
    | **Impressions** | The number of times your Microsoft Ads were on-screen.                                    |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                                |
    | ------------- | -------------------------------------------------------------------------- |
    | **Purchases** | The total number of purchases as attributed by Microsoft to Microsoft Ads. |
    | **Revenue**   | The total revenue generated as attributed by Microsoft to Microsoft Ads.   |
    | **ROAS**      | The return on ad spend as attributed by Microsoft to Microsoft Ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by Microsoft.             |
    | **Ad Spend**  | The total expenditure on Microsoft Advertising.                            |
  </Accordion>
</AccordionGroup>


# Criteo
Source: https://docs.runconverge.com/ad-platforms/integrations/criteo

An introduction to the Criteo marketing source

<Note>
  The Criteo marketing source lets you see platform-specific metrics (e.g. Ad
  Spend) in Converge. To send data from Converge to Criteo, check out the
  [Criteo Destination](/destinations/integrations/criteo) instead.
</Note>

Criteo's campaigns, ad sets, and ads map one-to-one onto Converge's, so your Criteo structure shows up unchanged in your reports. Converge groups Criteo data under the **Display** channel group.

***

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and then choose **Criteo**.

3. Name your ad platform sync: e.g. `Criteo | {Advertiser name}`, and then press **Sign in with Criteo**.

4. Sign in with a Criteo login that can manage your advertiser accounts, then approve the advertiser you want Converge to read.

5. Once the Criteo account has been linked, **select your advertiser**. Only the advertisers you approved during sign-in show up here.

6. **Select the currency** your Criteo account reports in.

7. After pressing **Create** your Criteo metrics will stream into Converge.

<Note>
  Each marketing source syncs one advertiser. To sync several, connect each
  advertiser as its own marketing source.
</Note>

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="check" /> |
| Custom Conversions                         | <Icon name="check" /> |

***

## Set up your Converge tracking parameters

1. Navigate to your <OutboundLink />

2. Navigate to **Campaigns** > **Ad sets** in the sidebar.

3. Click on the <Icon name="ellipsis-vertical" />-icon next to the ad set and click on **Ads tracking**.

4. Under **Apply a suffix (optional)**, copy and paste the following suffix.

   ```
   utm_source=criteo&utm_medium=paid&utm_campaign={{criteo_campaign_id}}&utm_content={{adid}}&cvg_source=criteo&cvg_cid={{criteo_campaign_id}}&cvg_adid={{adid}}
   ```

5. Scroll down and click on **Save and apply**.

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Criteo. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                         |
    | --------------- | ----------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your Criteo ads.                                 |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on Criteo ads.    |
    | **CTR**         | The average percentage of people who clicked on your Criteo ad after seeing it.     |
    | **CPA**         | The average cost associated with actions from your Criteo ads.                      |
    | **CPC**         | The average cost per click on your Criteo ads.                                      |
    | **CPM**         | The average cost per thousand impressions of your Criteo ads.                       |
    | **Conversions** | The number of Criteo-attributed purchases that happened because of your Criteo ads. |
    | **Clicks**      | The total number of clicks on your Criteo ads.                                      |
    | **Impressions** | The number of times your Criteo ads were on-screen.                                 |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                          |
    | ------------- | -------------------------------------------------------------------- |
    | **Purchases** | The total number of purchases as attributed by Criteo to Criteo ads. |
    | **Revenue**   | The total revenue generated as attributed by Criteo to Criteo ads.   |
    | **ROAS**      | The return on ad spend as attributed by Criteo to Criteo ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by Criteo.          |
    | **Ad Spend**  | The total expenditure on Criteo Advertising.                         |
  </Accordion>
</AccordionGroup>

***

## Attribution windows

**Conversions** and **Revenue** follow the default attribution setting on your Criteo account, so they line up with what your Criteo dashboard shows out of the box.

Converge syncs three fixed attribution windows on top of that, as custom conversions. Pick them in any report or dashboard to compare windows side by side.

| Custom conversion                       | What it counts                              |
| --------------------------------------- | ------------------------------------------- |
| **Criteo Sales (30d click)**            | Sales within 30 days of a click on your ad. |
| **Criteo Sales (24h view)**             | Sales within 24 hours of a view of your ad. |
| **Criteo Sales (30d click + 24h view)** | Sales within either window.                 |

Each window brings its own revenue, so you get ROAS and CPA per window too.

***

## FAQ

<AccordionGroup>
  <Accordion title="Why do I see an ad called “Unknown”?">
    Criteo reports part of your spend and performance against a catch-all ad
    instead of a specific creative. Converge keeps it, because dropping it would
    leave your Converge totals below what Criteo reports.
  </Accordion>

  <Accordion title="How far back does Converge sync?">
    Converge backfills 90 days when you first connect. Criteo serves two years of
    history, so reach out to your Converge representative if you need more.
  </Accordion>
</AccordionGroup>


# Meta Ads (Facebook Ads)
Source: https://docs.runconverge.com/ad-platforms/integrations/facebook

An introduction to the Meta Ads marketing source

<Note> The Meta Ads marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to Meta, check out the [Meta Ads Destination](/destinations/integrations/facebook) instead.</Note>

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and then choose **Facebook**.

3. Name your ad platform sync: e.g. `Facebook Ads | {Ad Account ID}` and then press **continue with Facebook**.

4. Once the Facebook account has been linked, you can **select your Facebook Ads account**.

5. After pressing **Create** your Facebook metrics will stream into Converge.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every 5 minutes       |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="check" /> |
| Custom Conversions                         | <Icon name="check" /> |

***

## Set up your tracking parameters

1. Navigate to your Facebook Ads Manager.

2. Navigate to the ad you'll set up tracking for. Click on **Edit**.

3. Scroll down to the **Tracking** section. There's a field called **URL parameters**. Paste in the following snippet.
   ```
   cvg_source={{site_source_name}}&cvg_adid={{ad.id}}&cvg_cid={{campaign.id}}
   ```
   <Frame>
     <img alt="Meta URL Params" />
   </Frame>

4. Repeat steps 1-3 for **every ad you run**, but **you can also bulk edit all your ads at once**.

<Warning>
  Changing the URL parameters will put the ad back into a processing state, which may last up to an hour. **In rare cases, the social proof of the ad could be reset** and the ad sent back into the learning phase.
</Warning>

<Info>
  If you want your tracking parameters to be compatible with **both** the Converge and [Google Analytics 4](/destinations/integrations/ga4) attribution report, use the following template instead

  ```
  utm_source=facebook&utm_medium=paid&utm_campaign={{campaign.name}}&utm_content={{ad.name}}&cvg_source={{site_source_name}}&cvg_adid={{ad.id}}&cvg_cid={{campaign.id}}
  ```
</Info>

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Meta Ads. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                     |
    | --------------- | ------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your Meta ads.                               |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on Meta ads.  |
    | **CTR**         | The average percentage of people who clicked on your Meta ad after seeing it.   |
    | **CPA**         | The average cost associated with actions from your Meta ads.                    |
    | **CPC**         | The average cost per click on your Meta ads.                                    |
    | **CPM**         | The average cost per thousand impressions of your Meta ads.                     |
    | **Conversions** | The number of Meta-attributed purchases that happened because of your Meta ads. |
    | **Clicks**      | The total number of clicks on your Meta ads.                                    |
    | **Impressions** | The number of times your Meta ads were on-screen.                               |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                      |
    | ------------- | ---------------------------------------------------------------- |
    | **Purchases** | The total number of purchases as attributed by Meta to Meta ads. |
    | **Revenue**   | The total revenue generated as attributed by Meta to Meta ads.   |
    | **ROAS**      | The return on ad spend as attributed by Meta to Meta ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by Meta.        |
    | **Ad Spend**  | The total expenditure on Meta Advertising.                       |
  </Accordion>
</AccordionGroup>


# Google Ads
Source: https://docs.runconverge.com/ad-platforms/integrations/google-ads

An introduction to the Google Ads marketing source

<Note> The Google Ads marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to Google, check out the [Google Ads - Remarketing](/destinations/integrations/google-ads-remarketing) or [Google Ads - Conversion tracking](/destinations/integrations/google-ads-conversions) destination instead.</Note>

## Set up the Marketing source

<Note> Converge will pull in the Conversions, CPA, and ROAS based on the **Date of conversion event** so these metrics can be straightforwardly compared with Converge numbers and other platforms. Note that Google Ads by default shows the conversions based on the date of click in the Ads Manager instead. </Note>

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and name your ad platform sync: e.g `Google Ads | {Google Ads Account ID}`

3. Select **Google Ads** from the drop-down list and sign in with your Google Ads Account.

4. Once the Google account has been linked, you can **select your Google Ads Account**.

5. After pressing **Create** your Google Ads metrics will stream into Converge.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported                      |
| ------------------------------------------ | ------------------------------ |
| Sync Frequency                             | Every hour                     |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | Partial (Performance Max only) |
| Custom Conversions                         | <Icon name="check" />          |

<Note>**Hourly spend breakdowns** are **only** available for **Performance Max campaigns** due to Google Ads API limitations. Other campaign types (Search, Display, Shopping, etc.) provide daily spend data.</Note>

***

## Set up your tracking parameters

1. In your Google Ads Manager, click `Settings` on the left-hand side, and then select **Account settings**.

2. Paste the following tracking parameters into the **Tracking Template** text field:
   ```
   {lpurl}?cvg_source=google&cvg_adid={creative}&cvg_cid={campaignid}
   ```
   <Frame>
     <img alt="Google Ads Example with Tracking Template Filled In" />
   </Frame>

<Note>
  **We recommend centralizing the tracking template into the account-level settings and removing all tracking templates from your specific ads, ad groups, and campaigns.**

  Importantly, if you also configured these parameters on the ad, ad group, or campaign level, these will be preferred.

  If you still wish to use your existing ad, ad group, or campaign-level tracking templates, then you need to follow the following instructions:

  <Accordion title="Set up campaign-level Tracking Parameters"> Go to `Settings` > `Campaign settings` > `Select a campaign` > `Edit` > `Change tracking template`. </Accordion>
  <Accordion title="Set up ad or ad group level Tracking Parameters">  Go to `Ad groups/Ads` and `assets` > `Select an ad group/ad `> `Edit` > `Change tracking template`. </Accordion>
</Note>

***

## FAQ

<AccordionGroup>
  <Accordion title="Is it possible to have fewer in-platform conversions than Google conversions in Converge?">
    Yes, this is possible.

    Google often uses a data-driven model for its in-platform conversions where it will try to adjust its contribution based on other touchpoints it observes.

    As such, Google can in-platform award `0.2` conversions to itself based on a purchase, whereas the Last Touch attribution model might attribute the full credit `1` to Google instead.
  </Accordion>

  <Accordion title="Why do my Google in-platform conversions in Converge not match my conversions in the Google Ads Dashboard?">
    Google, by default, shows you in the Ads Manager the conversions on the day the click happened.

    Converge will show you the conversions on the day the conversion happened, instead, as this makes it easier to cross-reference with Converge and Meta in-platform conversions that are reported at conversion time as well.

    In Google Ads, you can choose to add a column that shows `Conversions (by conv. time)`, which should match the numbers shown in the Converge Dashboard.
  </Accordion>
</AccordionGroup>

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Google Ads. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                         |
    | --------------- | ----------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your Google Ads.                                 |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on Google Ads.    |
    | **CTR**         | The average percentage of people who clicked on your Google ad after seeing it.     |
    | **CPA**         | The average cost associated with actions from your Google Ads.                      |
    | **CPC**         | The average cost per click on your Google Ads.                                      |
    | **CPM**         | The average cost per thousand impressions of your Google Ads.                       |
    | **Conversions** | The number of Google-attributed purchases that happened because of your Google Ads. |
    | **Clicks**      | The total number of clicks on your Google Ads.                                      |
    | **Impressions** | The number of times your Google Ads were on-screen.                                 |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                          |
    | ------------- | -------------------------------------------------------------------- |
    | **Purchases** | The total number of purchases as attributed by Google to Google Ads. |
    | **Revenue**   | The total revenue generated as attributed by Google to Google Ads.   |
    | **ROAS**      | The return on ad spend as attributed by Google to Google Ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by Google.          |
    | **Ad Spend**  | The total expenditure on Google Advertising.                         |
  </Accordion>
</AccordionGroup>


# Google Sheets
Source: https://docs.runconverge.com/ad-platforms/integrations/google-sheets

An introduction to the Google Sheets marketing source

<Note> The Google Sheets marketing source allows you to track ad spend from platforms without an API integration. This is useful for tracking influencer spend, offline advertising, or any custom marketing channels.</Note>

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and name your marketing source sync, e.g. `Google Sheets | Influencer Spend`.

3. Select **Custom Google Sheets** from the drop-down list and sign in with your Google Account to allow Converge to read your spreadsheets.
   <Frame>
     <img alt="Map spreadsheet columns to Converge fields" />
   </Frame>

4. Click **Sign in with Google**, then click **Pick a spreadsheet from Google Drive** and select the spreadsheet you want to import. Next, select the specific sheet (tab) within the spreadsheet.

   Converge loads the spreadsheet and displays a preview of the top 10 rows to help you map columns to the right fields.

   <Frame>
     <img alt="Sheet preview" />
   </Frame>

5. Select the **header row** of your spreadsheet. This labels each column and makes it easier to map them to the correct Converge fields.

6. Map your columns to Converge fields:
   * **Date** (required): Select the column containing dates.
   * **Currency** (required): Select the column or use "Manual input value" for a constant.
   * **Spend** (optional): Select the column containing spend amounts.
   * **Channel Group** (required): Select the column or use "Manual input value" for a constant.
   * **Channel** (required): Select the column or use "Manual input value" for a constant.
   * **Campaign Name** (required): Select the column or use "Manual input value" for a constant.
   * **Ad Set Name** (optional): Select the column or use "Manual input value" for a constant.
   * **Go Live** (optional): Select the column if applicable.
   <Frame>
     <img alt="Map spreadsheet columns to Converge fields" />
   </Frame>

7. Optionally, add custom conversions. See [Custom conversions](#custom-conversions) below.

8. Press **Create**. Converge will start pulling in your spend data.

<Note>
  For columns like Channel, Channel Group, Campaign Name, and Ad Set Name, you can choose **"Manual input value"** during mapping. This sets a constant value for all imported spend rows, which is useful when tracking a single campaign or channel in a sheet.
</Note>

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature   | Supported             |
| ------------------ | --------------------- |
| Sync Frequency     | Every hour            |
| Custom Conversions | <Icon name="check" /> |

***

## Sheet format requirements

Your Google Sheet should follow these formatting guidelines:

### Required columns

* **Date**: Must be in date format (Google Sheets recognizes standard date formats).
* **Channel**: The marketing channel (e.g. Influencer, Podcast, Billboard).
* **Channel Group**: The channel group (e.g. Paid Social, Paid Search, Organic).
* **Campaign Name**: The campaign name.
* **Currency**: The currency used for spend values.

### Optional columns

* **Spend**: Must be a number (no currency symbols or commas).
* **Ad Set Name**: For more granular tracking within campaigns.
* **Go Live**: If you track when campaigns go live.

### Example sheet structure

| Date      | Channel Group | Channel  | Campaign       | Ad Set Name | Currency | Spend   |
| --------- | ------------- | -------- | -------------- | ----------- | -------- | ------- |
| 1/19/2026 | Influencer    | youtube  | /influencer    |             | USD      | 1200.00 |
| 1/19/2026 | Paid Social   | facebook | Winter Launch  | Prospecting | USD      | 3500.00 |
| 1/19/2026 | Paid Search   | google   | Brand Keywords | Exact Match | USD      | 800.00  |

<Note>
  * Format the date column as a date in Google Sheets, not as text.
  * Format spend columns as numbers (no currency symbols or commas).
</Note>

***

## Custom conversions

Custom conversions let you import any conversion metric from your sheet into Converge — for example, leads, purchases, or impressions — and optionally pair them with a revenue column.

### How it works

When you map a custom conversion, you select a **count column** and an optional **revenue column**. Converge uses the **column header** as the conversion name in your reports. A column labeled `PPS` will appear as `PPS` in Converge.

You can add multiple custom conversion pairs — each maps independently to its own count and revenue columns.

### Setting up custom conversions

In step 7 of the setup, click **Add Custom Conversion** at the bottom of the mapping screen and configure:

* **Conversions column** (required): The column containing the conversion count. Must be a number column.
* **Revenue column** (optional): A column containing the revenue for those conversions. If omitted, revenue defaults to 0.

<Frame>
  <img alt="Custom Conversions" />
</Frame>

### Example sheet with custom conversions

| Date      | Channel Group | Channel | Campaign | Currency | Spend   | Post-Purchase Survey Responses |
| --------- | ------------- | ------- | -------- | -------- | ------- | ------------------------------ |
| 1/19/2026 | Influencer    | youtube | MrBeast  | USD      | 1200.00 | 5                              |
| 1/19/2026 | Influencer    | youtube | MrBeast  | USD      | 1200.00 | 8                              |
| 1/20/2026 | Influencer    | youtube | MrBeast  | USD      | 1200.00 | 3                              |

Here, `Post-Purchase Survey Responses` is the custom conversion column. The column header is used as-is as the conversion name in Converge.

***

## Syncing and updates

* Converge will automatically sync your Google Sheet data every hour.
* You can manually trigger a sync from the Marketing Sources dashboard.
* Each sync updates the entire sheet. The data in Converge will reflect the data in the sheet, so if anything is added, removed, or updated, it'll be reflected after the sync.

<Warning>
  If you modify the structure of your sheet (add/remove columns, change column names), you'll need to update your sync configuration in Converge.
</Warning>

***

## FAQ

<AccordionGroup>
  <Accordion title="Can I use the same sheet for multiple campaigns?">
    Yes, you can include multiple campaigns in a single sheet. During setup, map the Campaign Name column so Converge properly segments your spend data by campaign.
  </Accordion>

  <Accordion title="What happens if my sheet contains invalid data?">
    Converge will skip rows with invalid data and log an error in your sync status. Common issues include:

    * Date column not formatted as a date in Google Sheets.
    * Non-numeric values in the spend or custom conversion columns.
    * Missing required fields.

    You can view sync errors in the Marketing Sources dashboard to identify and fix issues.
  </Accordion>

  <Accordion title="When should I use 'Manual input value'?">
    Use "Manual input value" when you want to set a constant value for all rows in your sheet. For example, if you're tracking all influencer spend in one sheet, you can set Channel to "Influencer" as a manual input value instead of adding a Channel column to your spreadsheet.
  </Accordion>

  <Accordion title="How far back can I import historical spend data?">
    You can import historical spend data as far back as your sheet contains records. There's no limit on historical backfill, but keep in mind that very large datasets may take longer to initially sync.
  </Accordion>

  <Accordion title="Can I track conversions without spend?">
    Yes. If you leave the Spend field unmapped and configure at least one custom conversion column, Converge will import the row as a conversions-only entry. This is useful for owned channels like email where you don't have associated spend.
  </Accordion>
</AccordionGroup>

***

## What you can track

The Google Sheets integration imports spend and conversion data that can be analyzed alongside your other marketing channels in Converge:

* **Ad spend**: Total spend across custom channels.
* **Custom conversions**: Any metric you track in a column — Leads, PPS, Impressions, etc. — appears as a named conversion in Converge.
* **Custom revenue**: Pair a revenue column with each custom conversion for blended revenue metrics.
* **Channel and campaign reporting**: Spend and conversions broken down by channel, channel group, campaign, and ad set.

Performance metrics like ROAS and CPA are calculated from your tracked events and the imported spend data.


# impact.com
Source: https://docs.runconverge.com/ad-platforms/integrations/impact

An introduction to the impact.com marketing source

<Note>
  The impact.com marketing source brings your affiliate and partnership
  performance (spend, clicks, impressions, and impact.com-attributed conversions
  and revenue) into Converge, so you can analyze it alongside your other
  marketing channels.
</Note>

## How impact.com maps to Converge

impact.com uses its own names for the levels of your account. Here's how they line up with the campaign, ad set, and ad structure you already see in Converge.

| impact.com  | What it is                                                              | In Converge |
| ----------- | ----------------------------------------------------------------------- | ----------- |
| **Account** | Your whole impact.com brand account.                                    | Connection  |
| **Program** | The partnership program partners join and get paid under.               | Campaign    |
| **Partner** | The publisher, affiliate, or creator driving the traffic.               | Ad set      |
| **Ad**      | The creative a partner promotes: tracking link, banner, text link, etc. | Ad          |

<Note>
  In impact.com's API, programs are called "campaigns". Converge reads them as
  campaigns, so what you see as a program in the impact.com app shows up as a
  campaign in Converge.
</Note>

Converge syncs every active program in the account. Spend is everything you pay partners (action, click, and other costs) which matches **Total Cost** in impact.com's own reporting.

***

## Create an impact.com API token

Converge reads your data with an impact.com API access token: an **Account SID** and an **Auth Token**.

1. In impact.com, select your **user profile** in the top navigation bar, then **Settings**.

2. In the left column, scroll to **Technical** and select **API**.

3. Select **Create Access Token**. Enter a **Token Name**, e.g. `Converge Marketing Source`, and a short **Description**. Set the **API Version** to 14. Select **Next**.

4. Toggle on the categories below and check these scopes:

   | Category                | Scopes                                                 |
   | ----------------------- | ------------------------------------------------------ |
   | **Accounts (1)**        | Retrieve company information                           |
   | **Campaigns (1)**       | Retrieve campaigns                                     |
   | **Reports (3)**         | List reports, Export report, Retrieve report meta data |
   | **Jobs Management (4)** | Retrieve job, Retrieve jobs, Download job, Replay job  |

5. Select **Create**, then open the token to copy its **Account SID** and **Auth Token**.

For more detail, see impact.com's <OutboundLink /> guide.

***

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in Converge, click **Connect a new ad platform**, and choose **impact.com**.

2. Give your connection a name, e.g. `impact.com | {Account name}`.

3. Enter the **Account SID** and **Auth Token** from your impact.com API token.

4. Press **Create**. Converge checks the credentials, then starts syncing your impact.com data.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every 6 hours         |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="xmark" /> |
| Custom Conversions                         | <Icon name="xmark" /> |

***

## Set up your Converge tracking parameters

1. In impact.com, select your **user profile** in the top navigation bar, then **Settings**.

2. In the **Program Settings** column, select the program at the top, scroll to **Tracking**, and select **Gateway**.

3. Under **Program Tracking Template**, select **Add Another** and fill in one row per parameter:

   | Name         | Value               |
   | ------------ | ------------------- |
   | `cvg_source` | `impact`            |
   | `cvg_cid`    | `{ircid}`           |
   | `cvg_adid`   | `{irpid}::{iradid}` |

   `{ircid}`, `{irpid}`, and `{iradid}` are impact.com macros for the program, partner, and ad ID, respectively. Leave the parameters that are already there, such as your UTMs, in place.

4. Save your changes. Leave the rest of the page as it is: **Default Landing Page**, **Partner Tracking Template**, and **Deep Linking** don't affect your Converge parameters.

<Warning>
  Repeat steps 2-4 for **every program you run**, because each program has its
  own tracking template.
</Warning>

<Note>
  `cvg_adid` pairs the partner with the ad on purpose: dozens of partners
  promote the same link, so an ad ID alone can't tell you who drove the click.
  Keep the order and the `::` as shown, because Converge builds the same ID on
  the spend side.
</Note>

***

## Supported metrics

We support a variety of metrics to help you analyze your affiliate performance. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                                |
    | --------------- | ------------------------------------------------------------------------------------------ |
    | **Ad Spend**    | The total amount you paid partners, including action, click, and other costs.              |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on impact.com.           |
    | **CTR**         | The average percentage of people who clicked on a partner's ad after seeing it.            |
    | **CPA**         | The average cost associated with actions from your impact.com partners.                    |
    | **CPC**         | The average cost per click on your impact.com ads.                                         |
    | **CPM**         | The average cost per thousand impressions of your impact.com ads.                          |
    | **Conversions** | The number of impact.com-attributed purchases that happened because of your partners' ads. |
    | **Clicks**      | The total number of clicks on your impact.com ads.                                         |
    | **Impressions** | The number of times your impact.com ads were on-screen.                                    |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                                    |
    | ------------- | ------------------------------------------------------------------------------ |
    | **Purchases** | The total number of purchases as attributed by impact.com to partner activity. |
    | **Revenue**   | The total revenue generated as attributed by impact.com to partner activity.   |
    | **ROAS**      | The return on ad spend as attributed by impact.com.                            |
    | **CPA**       | The cost of acquiring a conversion as attributed by impact.com.                |
    | **Ad Spend**  | The total amount you paid partners through impact.com.                         |
  </Accordion>
</AccordionGroup>

Converge groups impact.com data under the **Affiliate** channel group.

***

## FAQ

<AccordionGroup>
  <Accordion title="How often does the data update?">
    Converge syncs impact.com every 6 hours.
  </Accordion>

  <Accordion title="Why is my spend spread evenly across the day?">
    impact.com reports performance per day, not per hour. Converge spreads each
    day's totals evenly over that day's hours so impact.com lines up with your
    other sources in hourly reports. Daily and longer date ranges are exact.
  </Accordion>

  <Accordion title="Converge says it can't find the report it needs. What now?">
    Converge exports impact.com's built-in **Performance by Ad / Partner / Date**
    report. The reports available to you depend on your impact.com account, so if
    yours doesn't carry it, ask your impact.com representative to enable it, then
    reach out to your Converge representative.
  </Accordion>

  <Accordion title="Which programs does Converge sync?">
    All active programs in the account. Each one becomes its own campaign in
    Converge. Closed programs keep the data they already synced but stop updating.
  </Accordion>

  <Accordion title="Can I connect more than one impact.com account?">
    Yes. Create a separate marketing source per account, each with its own Account
    SID and Auth Token.
  </Accordion>
</AccordionGroup>


# Klaviyo
Source: https://docs.runconverge.com/ad-platforms/integrations/klaviyo

An introduction to the Klaviyo marketing source

<Note> The Klaviyo marketing source allows you to see platform-specific metrics (e.g. Email Opens, Clicks, Revenue) in Converge.
To send data from Converge to Klaviyo, check out the [Klaviyo Destination](/destinations/integrations/klaviyo) instead.</Note>

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in Converge, click on **Connect a new ad platform** and then choose **Klaviyo**.

2. Give your connection a name: e.g. `Klaviyo | {Account ID}`, then click on **Sign in with Klaviyo** and complete the authentication process by signing in with your Klaviyo account and accepting the necessary permissions.

3. After successfully signing in, you will see the **Conversion data source** selection. Choose which data source you want to use for your conversion values (detailed guidance is provided in the next section).

4. In the **Which conversion metrics should we use** section, select one or more metrics from the chosen source. Most often this will be the "Placed Order" event, for example, Placed Order (Shopify), Placed Order (WooCommerce). The metrics you select will be available individually and also rolled up into a single conversions/revenue total.

5. After pressing **Create**, your Klaviyo data will stream into Converge.

***

## Which conversion data source should I choose?

Klaviyo can record "purchases" in two ways:

* **Integration events**: created automatically by ecommerce integrations (e.g., Shopify, WooCommerce) when an order is created/synced in the platform. In Klaviyo, these usually appear as "Placed Order" with the partner icon.
* **API events**: events you (or a third-party app) post to Klaviyo via the Events API. In Klaviyo, these metrics appear with a gear icon.

<Warning> Since these sources can overlap, Converge requires you to choose which data source to use to avoid double-counting conversions. This selection works similarly to how Klaviyo makes you pick conversion metrics in their own dashboards. </Warning>

<Info> This choice does not change anything in your Klaviyo account. It only controls how this integration reads and aggregates conversion values. </Info>

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="check" /> |
| Custom Conversions                         | <Icon name="check" /> |

***

## Set up your tracking parameters

1. Log into your Klaviyo account and navigate to the sidebar.

2. Click on your account name in the top-right corner, then go to **Settings > Other > UTM tracking**. Click **Edit** to modify the tracking settings.

3. Configure your tracking parameters:
   * Configure the standard Klaviyo UTM parameters as needed for your existing tracking requirements. These parameters are optional for the Converge integration.
   * **Add a custom UTM parameter** for Converge tracking. Click **Add UTM parameter**:
     * Enter `cvg_source` as the parameter name and set Campaign value to "Klaviyo" and Flow value to "Klaviyo"
     * Enter `cvg_adid` as the parameter name and set Campaign value to "Campaign Id" and Flow value to "Flow Id"
   * **Enable** the toggle for "Automatically add UTM parameters to links"

4. Click **Save** to apply your tracking configuration.

<Frame>
  <img alt="Klaviyo UTM Tracking" />
</Frame>

<Info>
  This configuration will automatically append UTM parameters to all links in your Klaviyo campaigns and flows, enabling proper attribution tracking in Converge. The `cvg_adid` parameter helps Converge identify traffic coming from your Klaviyo campaigns.
</Info>

***

## Supported metrics

We support a focused set of Klaviyo metrics that mirror the definitions you see in Klaviyo’s own reporting. Expand each category to see the specific events we aggregate.

<AccordionGroup>
  <Accordion icon="envelope" title="Email Metrics">
    These are email-level delivery and engagement events emitted by Klaviyo for email sends (campaigns and flows). Use them to trend deliverability and engagement over time.

    <Note>Click metrics exclude bot clicks, matching Klaviyo's native campaign reporting. This keeps your Converge numbers in sync with what you see in Klaviyo.</Note>

    | Metric                            | Description                                                                                                                                                                             |
    | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Email click rate**              | The percentage of emails where the recipient clicked on a link within your message. It is calculated as the unique email clicks divided by emails delivered.                            |
    | **Email open rate**               | The percentage of emails where the recipient opened your message. It is calculated as the unique email opens divided by emails delivered.                                               |
    | **Email deliverability rate**     | The percentage of emails that were actually delivered to the recipient, as opposed to being bounced, or dropped. It is calculated as the delivered emails divided by total emails sent. |
    | **Emails bounced**                | The total number of emails where the send failed due to a bounce (soft or hard). The message was not delivered to the recipient's mailbox.                                              |
    | **Emails clicked to unsubscribe** | The total number of times an unsubscribe link in your email was clicked, indicating intent to opt out via the message.                                                                  |
    | **Emails dropped**                | The total number of emails Klaviyo skips sending because an address is suppressed/undeliverable per an upstream provider, creating a suppression mismatch.                              |
    | **Emails marked as spam**         | The total number of times the recipient reported your email as spam through their mailbox provider.                                                                                     |
    | **Emails delivered**              | The total number of emails that were successfully delivered to the recipient's mailbox (i.e., not bounced/dropped).                                                                     |
    | **Total emails clicked**          | The total number of times a tracked link inside your email was clicked. Excludes bot clicks.                                                                                            |
    | **Total emails opened**           | The total number of times a recipient opens an email you sent.                                                                                                                          |
    | **Total emails sent**             | The total number of emails that Klaviyo attempted to send, including all delivery outcomes (bounced, dropped, and successfully delivered).                                              |
    | **Unique emails clicked**         | The number of unique recipients who clicked at least one tracked link in your email. Excludes bot clicks.                                                                               |
    | **Unique emails opened**          | The number of unique recipients who opened your email at least once.                                                                                                                    |
  </Accordion>

  <Accordion icon="users" title="Subscriber Metrics">
    These metrics reflect **list-level consent** changes. They're sourced from list subscription events and are the basis for "email subscribers" accounting.

    | Metric                        | Description                                                                                                  |
    | ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
    | **New email subscribers**     | The number of unique email profiles that **joined any email list** (Subscribed to List) during the period.   |
    | **Churned email subscribers** | The number of unique email profiles that **left any email list** (Unsubscribed from List) during the period. |
  </Accordion>
</AccordionGroup>


# OpenAI Ads
Source: https://docs.runconverge.com/ad-platforms/integrations/openai

An introduction to the OpenAI Ads marketing source

<Note> The OpenAI marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to OpenAI, check out the [OpenAI Ads Destination](/destinations/integrations/openai) instead.</Note>

## Set up the Marketing source

1. Navigate to your <OutboundLink /> and choose **Settings > General**.

2. Under **API Keys**, click **Create New Key**.

<Frame>
  <img alt="OpenAI Ads - Step 2" />
</Frame>

3. Give it a name (e.g., `Converge`) and click **Create**.

<Frame>
  <img alt="OpenAI Ads - Step 3" />
</Frame>

4. In the **Save Your Key** screen, click **Copy** to copy the key to your clipboard and keep it safe.

<Frame>
  <img alt="OpenAI Ads - Step 4" />
</Frame>

5. Navigate to the [Marketing Sources](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

6. Click on **Connect a new marketing source**  and select **OpenAI Ads** from the list.

7. Give it a name (e.g., `OpenAI Ads`) and click **Next**.

8. In the **Configuration** step, fill in the **Reporting API key** field with the key you copied in *step 4*, and click **Next**.

9. Review your changes and click **Connect marketing source**. Your OpenAI Ads metrics should begin streaming into Converge.

***

## Set up your Converge tracking parameters

You don't need to change the URL of each ad by hand. Instead, set your tracking parameters once in Ads Manager, and OpenAI appends them to your landing page URLs automatically.

1. Navigate to your <OutboundLink /> and open the **Campaigns** page.

2. Open the three-dot menu of your campaign and select **Edit campaign**.

3. Add the following snippet under **Landing page query parameters**:
   ```
   cvg_source=openai&cvg_adid={ad_id}&cvg_cid={campaign_id}
   ```
   `{ad_id}` and `{campaign_id}` are OpenAI macros that Ads Manager fills in automatically when your ad is served.

4. Repeat steps 1-3 for **every campaign you run**.

We recommend setting the parameters at the campaign level, as shown above. They then apply to every ad in the campaign, including ads you add later. You can also set them per ad group or per ad from the **Ad Groups** or **Ads** page.

<Note> More specific settings take precedence: Ad URL > Ad > Ad Group > Campaign. If a parameter is already set at a more specific level, the campaign-level value won't overwrite it. </Note>


# Outbrain Ads
Source: https://docs.runconverge.com/ad-platforms/integrations/outbrain

An introduction to the Outbrain Ads marketing source

<Note> The Outbrain marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to Outbrain, check out the [Outbrain Ads Destination](/destinations/integrations/outbrain) instead.</Note>

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and name your ad platform sync: e.g `Outbrain | {Outbrain Ads Account ID}`.

3. Select **Outbrain** from the drop-down list and sign in with your Outbrain Account.

4. Once the Outbrain account has been linked, you can **select your Outbrain Ads Account**.

5. After pressing **Create** your Outbrain Ads metrics will stream into Converge.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="xmark" /> |
| Custom Conversions                         | <Icon name="xmark" /> |

***

## Set up your Converge tracking parameters

<Note> If you have already set up the [Outbrain Destination](/destinations/integrations/outbrain) in Converge, then you might already have the tracking parameters set up correctly. </Note>

1. Navigate to your Outbrain Ads Dashboard and go to the **Campaign** overview.
   <Frame>
     <img alt="outbrain-campaign" />
   </Frame>

2. Click on the <Icon name="pencil" />-icon next to the campaign for which you want to modify the tracking parameters to open the campaign settings.

3. Add the following in the **Tracking** section:

```
utm_source=outbrain&utm_medium=discovery&utm_campaign={{campaign_name}}&utm_content={{ad_title}}&utm_term={{publisher_name}}_{{section_name}}&cvg_source=outbrain&cvg_adid={{ad_id}}&cvg_cid={{campaign_id}}&outbraincid={{ob_click_id}}
```

4. Click **Submit** to save your changes.

<Warning> You will need to change the URL of **all** of your campaigns following steps 1-4 above. **You should add these parameters for every new campaign as well**.  </Warning>

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Outbrain Ads. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                             |
    | --------------- | --------------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your Outbrain ads.                                   |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on Outbrain ads.      |
    | **CTR**         | The average percentage of people who clicked on your Outbrain ad after seeing it.       |
    | **CPA**         | The average cost associated with actions from your Outbrain ads.                        |
    | **CPC**         | The average cost per click on your Outbrain ads.                                        |
    | **CPM**         | The average cost per thousand impressions of your Outbrain ads.                         |
    | **Conversions** | The number of Outbrain-attributed purchases that happened because of your Outbrain ads. |
    | **Clicks**      | The total number of clicks on your Outbrain ads.                                        |
    | **Impressions** | The number of times your Outbrain ads were on-screen.                                   |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                              |
    | ------------- | ------------------------------------------------------------------------ |
    | **Purchases** | The total number of purchases as attributed by Outbrain to Outbrain ads. |
    | **Revenue**   | The total revenue generated as attributed by Outbrain to Outbrain ads.   |
    | **ROAS**      | The return on ad spend as attributed by Outbrain to Outbrain ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by Outbrain.            |
    | **Ad Spend**  | The total expenditure on Outbrain Advertising.                           |
  </Accordion>
</AccordionGroup>


# Pinterest Ads
Source: https://docs.runconverge.com/ad-platforms/integrations/pinterest

An introduction to the Pinterest Ads marketing source

<Note> The Pinterest marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to Pinterest, check out the [Pinterest Ads Destination](/destinations/integrations/pinterest) instead.</Note>

## Set up the Marketing source

<Note> Converge will pull in the Conversions, CPA, and ROAS based on the **Date of conversion event** and with a `30/30/1` (Days after click/engagement/view) Conversion window. </Note>

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and name your ad platform sync: e.g `Pinterest Ads | {Pinterest Ads Account ID}`

3. Select **Pinterest** from the drop-down list, and log in with your Pinterest Ads Account.

4. Once the Pinterest account has been linked, you can **select your Pinterest Ads Account**.

5. After pressing **Create** your Pinterest Ads metrics will stream into Converge.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="xmark" /> |
| Custom Conversions                         | <Icon name="xmark" /> |

***

## Set up your Converge tracking parameters

1. Navigate to your Pinterest Business Manager.

2. Navigate to the ad you'll set up tracking for: `Ads` > `Reporting`.

3. In your Campaigns Reporting Table, click on the pencil Icon at the left-hand side of the ad name.

4. Scroll down to the Ads - Set Up section and modify the **Destination URL** to include the right tracking parameters as follows:

   ```
   ?cvg_source=pinterest&cvg_adid={adid}&cvg_cid={campaignid}&utm_source=pinterest&utm_medium=cpc&utm_campaign={campaign_name}&utm_term={adgroupname}&utm_content={adid}
   ```

   <Accordion title="Example">
     If your Destination URL used to be `https://mywebsite.com`, then after adding the tracking parameters your Destination URL would look like this:

     ```
     https://mywebsite.com?cvg_source=pinterest&cvg_adid={adid}&cvg_cid={campaignid}&utm_source=pinterest&utm_medium=cpc&utm_campaign={campaign_name}&utm_term={adgroupname}&utm_content={adid}
     ```
   </Accordion>

5. Repeat steps 2-4 for **every ad you run** (including new ads that you will run in the future).

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Pinterest Ads. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                               |
    | --------------- | ----------------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your Pinterest ads.                                    |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on Pinterest ads.       |
    | **CTR**         | The average percentage of people who clicked on your Pinterest ad after seeing it.        |
    | **CPA**         | The average cost associated with actions from your Pinterest ads.                         |
    | **CPC**         | The average cost per click on your Pinterest ads.                                         |
    | **CPM**         | The average cost per thousand impressions of your Pinterest ads.                          |
    | **Conversions** | The number of Pinterest-attributed purchases that happened because of your Pinterest ads. |
    | **Clicks**      | The total number of clicks on your Pinterest ads.                                         |
    | **Impressions** | The number of times your Pinterest ads were on-screen.                                    |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                                |
    | ------------- | -------------------------------------------------------------------------- |
    | **Purchases** | The total number of purchases as attributed by Pinterest to Pinterest ads. |
    | **Revenue**   | The total revenue generated as attributed by Pinterest to Pinterest ads.   |
    | **ROAS**      | The return on ad spend as attributed by Pinterest to Pinterest ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by Pinterest.             |
    | **Ad Spend**  | The total expenditure on Pinterest Advertising.                            |
  </Accordion>
</AccordionGroup>


# Reddit Ads
Source: https://docs.runconverge.com/ad-platforms/integrations/reddit

An introduction to the Reddit Ads marketing source

<Note> The Reddit Ads marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to Reddit, check out the [Reddit Ads Destination](/destinations/integrations/reddit) instead.</Note>

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and name your ad platform sync: e.g `Reddit Ads | {Reddit Ads Account ID}`.

3. Select **Reddit** from the drop-down list and sign in with your Reddit Account.

4. Once the Reddit account has been linked, you can **select your Reddit Ads Account**.

5. After pressing **Create** your Reddit Ads metrics will stream into Converge.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="check" /> |
| Custom Conversions                         | <Icon name="xmark" /> |

***

## Set up your Converge tracking parameters

1. Navigate to your Reddit Ads Manager.

2. Navigate to the **Ads** tab and select the ad you'll set up tracking for. Click the three dots and go to **Edit Ad**.

3. The following snippet should be appended at the end of the **Destination URL** of your ad:
   ```
   ?cvg_source=reddit&cvg_adid={{AD_ID}}&cvg_cid={{CAMPAIGN_ID}}
   ```
   <Note>
     If you already have query parameters in your URL, make sure to add the Converge Tracking Parameters after the last existing parameter and separate them with an ampersand `&` instead of the leading question mark `?`.
   </Note>
   <Frame>
     <img alt="Reddit URL Parameters" />
   </Frame>

4. Repeat steps 1-3 for **every ad you run** (including new ads that you will run in the future).

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Reddit Ads. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                         |
    | --------------- | ----------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your Reddit ads.                                 |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on Reddit Ads.    |
    | **CTR**         | The average percentage of people who clicked on your Reddit ad after seeing it.     |
    | **CPA**         | The average cost associated with actions from your Reddit ads.                      |
    | **CPC**         | The average cost per click on your Reddit ads.                                      |
    | **CPM**         | The average cost per thousand impressions of your Reddit ads.                       |
    | **Conversions** | The number of Reddit-attributed purchases that happened because of your Reddit ads. |
    | **Clicks**      | The total number of clicks on your Reddit ads.                                      |
    | **Impressions** | The number of times your Reddit ads were on-screen.                                 |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                          |
    | ------------- | -------------------------------------------------------------------- |
    | **Purchases** | The total number of purchases as attributed by Reddit to Reddit Ads. |
    | **Revenue**   | The total revenue generated as attributed by Reddit to Reddit Ads.   |
    | **ROAS**      | The return on ad spend as attributed by Reddit to Reddit Ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by Reddit.          |
    | **Ad Spend**  | The total spent on Reddit Ads.                                       |
  </Accordion>
</AccordionGroup>


# Snapchat Ads
Source: https://docs.runconverge.com/ad-platforms/integrations/snapchat

An introduction to the Snapchat Ads marketing source

<Note> The Snapchat Ads marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to Snapchat, check out the [Snapchat Destination](/destinations/integrations/snapchat) instead.</Note>

## Set up the Marketing source

<Note> Make sure you have a valid payment method attached to your Snapchat Ad Account, otherwise Converge will not be able to find it.</Note>

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and then choose **Snapchat**.

3. Name your ad platform sync: e.g. `Snapchat | {Ad Account ID}` and then press **continue with Snapchat**.

4. Once the Snapchat account has been linked, you can **select your Snapchat Ads account**.

   <Warning> Only **approved** Snapchat ad accounts will appear in the dropdown. If your ad account status is "Pending" in Snapchat Business Manager, you won't be able to connect it to Converge until Snapchat approves it. This is a limitation on Snapchat's side.</Warning>

5. After pressing **Create** your Snapchat metrics will stream into Converge.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="xmark" /> |
| Custom Conversions                         | <Icon name="xmark" /> |

***

## Set up your Converge tracking parameters

<Note> You need to change the actual URL of all of your ads (including new ones you will set up in the future). </Note>

1. Navigate to your Snapchat Ads Manager.

2. Navigate to the ad for which you will change the URL by clicking **Design Your Web Site Ad** > **Website URL**.

3. The following snippet should be appended at the end of the URL of your ad:
   ```
   ?cvg_source=snapchat&cvg_adid={{ad.id}}&cvg_cid={{campaign.id}}
   ```

4. Repeat steps 1-3 for **every ad you run**.

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Snapchat Ads. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                             |
    | --------------- | --------------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your Snapchat ads.                                   |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on Snapchat ads.      |
    | **CTR**         | The average percentage of people who clicked on your Snapchat ad after seeing it.       |
    | **CPA**         | The average cost associated with actions from your Snapchat ads.                        |
    | **CPC**         | The average cost per click on your Snapchat ads.                                        |
    | **CPM**         | The average cost per thousand impressions of your Snapchat ads.                         |
    | **Conversions** | The number of Snapchat-attributed purchases that happened because of your Snapchat ads. |
    | **Clicks**      | The total number of clicks on your Snapchat ads.                                        |
    | **Impressions** | The number of times your Snapchat ads were on-screen.                                   |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                              |
    | ------------- | ------------------------------------------------------------------------ |
    | **Purchases** | The total number of purchases as attributed by Snapchat to Snapchat ads. |
    | **Revenue**   | The total revenue generated as attributed by Snapchat to Snapchat ads.   |
    | **ROAS**      | The return on ad spend as attributed by Snapchat to Snapchat ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by Snapchat.            |
    | **Ad Spend**  | The total expenditure on Snapchat Advertising.                           |
  </Accordion>
</AccordionGroup>


# Taboola Ads
Source: https://docs.runconverge.com/ad-platforms/integrations/taboola

An introduction to the Taboola Ads marketing source

<Note> The Taboola marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to Taboola, check out the [Taboola Ads Destination](/destinations/integrations/taboola) instead.</Note>

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and name your ad platform sync: e.g `Taboola | {Taboola Ads Account ID}`.

3. Select **Taboola** from the drop-down list and sign in with your Taboola Account.

4. Once the Taboola account has been linked, you can **select your Taboola Ads Account**.

5. After pressing **Create** your Taboola Ads metrics will stream into Converge.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="xmark" /> |
| Custom Conversions                         | <Icon name="xmark" /> |

***

## Set up your Converge tracking parameters

<Note> If you have already set up the [Taboola Destination](/destinations/integrations/taboola) in Converge, then you might already have the tracking parameters set up correctly. </Note>

1. Open the Taboola Ads Manager and navigate to **Campaigns**.

2. Click on the <Icon name="pencil" />-icon next to the campaign for which you want to modify the tracking parameters to open the campaign settings.

3. Add the following in the **Tracking** section:

```
utm_source=taboola&utm_medium=paid&utm_campaign={campaign_name}&tblcid={click_id}&cvg_source=taboola&cvg_adid={campaign_item_id}&cvg_cid={campaign_id}
```

4. Click **Submit** to save your changes.

<Warning> You will need to change the URL of **all** of your campaigns following steps 1-4 above. **You should add these parameters for every new campaign as well**.  </Warning>

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Taboola Ads. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                           |
    | --------------- | ------------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your Taboola ads.                                  |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on Taboola ads.     |
    | **CTR**         | The average percentage of people who clicked on your Taboola ad after seeing it.      |
    | **CPA**         | The average cost associated with actions from your Taboola ads.                       |
    | **CPC**         | The average cost per click on your Taboola ads.                                       |
    | **CPM**         | The average cost per thousand impressions of your Taboola ads.                        |
    | **Conversions** | The number of Taboola-attributed purchases that happened because of your Taboola ads. |
    | **Clicks**      | The total number of clicks on your Taboola ads.                                       |
    | **Impressions** | The number of times your Taboola ads were on-screen.                                  |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                            |
    | ------------- | ---------------------------------------------------------------------- |
    | **Purchases** | The total number of purchases as attributed by Taboola to Taboola ads. |
    | **Revenue**   | The total revenue generated as attributed by Taboola to Taboola ads.   |
    | **ROAS**      | The return on ad spend as attributed by Taboola to Taboola ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by Taboola.           |
    | **Ad Spend**  | The total expenditure on Taboola Advertising.                          |
  </Accordion>
</AccordionGroup>


# Tapjoy Ads
Source: https://docs.runconverge.com/ad-platforms/integrations/tapjoy

An introduction to the Tapjoy marketing source

<Note>
  The Tapjoy marketing source allows you to see platform-specific metrics
  (e.g. Ad Spend) in Converge.
</Note>

## Set up the Marketing source

1. Navigate to your <OutboundLink />.

2. Copy your **Marketing API Key**.

<Frame>
  <img alt="Tapjoy Marketing API Key" />
</Frame>

3. In the Converge dashboard, navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms).

4. Click on **Connect a new ad platform** and then choose **Tapjoy**.

5. Name your ad platform sync: e.g. `Tapjoy Ad Account`.

6. Fill in the **Marketing API Key** you copied from **Tapjoy** in *Step 2*.

7. After pressing **Create** your Tapjoy metrics will stream into Converge.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="xmark" /> |
| Custom Conversions                         | <Icon name="xmark" /> |

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on Tapjoy. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                  |
    | --------------- | ---------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your ads.                                 |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on ads.    |
    | **CTR**         | The average percentage of people who clicked on your ads after seeing them.  |
    | **CPA**         | The average cost associated with actions from your ads.                      |
    | **CPC**         | The average cost per click on your ads.                                      |
    | **CPM**         | The average cost per thousand impressions of your ads.                       |
    | **Conversions** | The number of Tapjoy-attributed purchases that happened because of your ads. |
    | **Clicks**      | The total number of clicks on your ads.                                      |
    | **Impressions** | The number of times your ads were on-screen.                                 |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric          | Description                                                            |
    | --------------- | ---------------------------------------------------------------------- |
    | **Purchases**   | The total number of purchases as attributed by Tapjoy to Tapjoy ads.   |
    | **Impressions** | The total number of impressions as attributed by Tapjoy to Tapjoy ads. |
    | **Clicks**      | The total number of clicks as attributed by Tapjoy to Tapjoy ads.      |
    | **Conversions** | The total number of conversions as attributed by Tapjoy.               |
    | **Ad Spend**    | The total expenditure on Tapjoy Advertising.                           |
  </Accordion>
</AccordionGroup>


# TikTok Ads
Source: https://docs.runconverge.com/ad-platforms/integrations/tiktok

An introduction to the TikTok Ads marketing source

<Note> The TikTok marketing source allows you to see platform-specific metrics (e.g. Ad Spend) in Converge.
To send data from Converge to TikTok, check out the [TikTok Ads Destination](/destinations/integrations/tiktok) instead.</Note>

## Set up the Marketing source

1. Navigate to the [Marketing Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

2. Click on **Connect a new ad platform** and name your ad platform sync: e.g `TikTok Ads | {TikTok Ads Account ID}`.

3. Select **TikTok** from the drop-down list and sign in with your TikTok Account.

4. Once the TikTok account has been linked, you can **select your TikTok Ads Account**.

5. After pressing **Create** your TikTok Ads metrics will stream into Converge.

***

## Converge functionality

This integration supports the following Converge marketing source functionality.

| Converge Feature                           | Supported             |
| ------------------------------------------ | --------------------- |
| Sync Frequency                             | Every hour            |
| <Tooltip>Hourly Spend Breakdowns</Tooltip> | <Icon name="check" /> |
| Custom Conversions                         | <Icon name="xmark" /> |

***

## Set up your Converge tracking parameters

1. Navigate to your TikTok Ads Manager.

2. Navigate to the ad you'll set up tracking for: `Campaign` > `Ad` > `Select an Ad` > `Destination page` > `URL`.

3. The following snippet should be appended at the end of the URL of your ad:
   ```
   ?cvg_source=tiktok&cvg_adid=__CID__&cvg_cid=__CAMPAIGN_ID__
   ```
   <Frame>
     <img alt="TikTok URL Params" />
   </Frame>

4. Repeat steps 1-3 for **every ad you run** (including new ads that you will run in the future).

***

## Supported metrics

We support a variety of metrics to help you analyze your ad performance on TikTok Ads. Click on each category to expand and see the specific metrics available.

<AccordionGroup>
  <Accordion icon="chart-column" title="Overview Report">
    The Attribution Overview Report provides a high-level snapshot of your ad performance, including efficiency and engagement metrics.

    | Metric          | Description                                                                         |
    | --------------- | ----------------------------------------------------------------------------------- |
    | **Ad Spend**    | The total amount of money spent on your TikTok ads.                                 |
    | **ROAS**        | The attributed revenue generated for every unit of currency spent on TikTok ads.    |
    | **CTR**         | The average percentage of people who clicked on your TikTok ad after seeing it.     |
    | **CPA**         | The average cost associated with actions from your TikTok ads.                      |
    | **CPC**         | The average cost per click on your TikTok ads.                                      |
    | **CPM**         | The average cost per thousand impressions of your TikTok ads.                       |
    | **Conversions** | The number of TikTok-attributed purchases that happened because of your TikTok ads. |
    | **Clicks**      | The total number of clicks on your TikTok ads.                                      |
    | **Impressions** | The number of times your TikTok ads were on-screen.                                 |
  </Accordion>

  <Accordion icon="network-wired" title="Channels Report">
    The Channels Report tab provides a detailed comparison of performance metrics across advertising channels, campaigns, ad sets, and ads, helping you understand the most effective elements.

    | Metric        | Description                                                          |
    | ------------- | -------------------------------------------------------------------- |
    | **Purchases** | The total number of purchases as attributed by TikTok to TikTok ads. |
    | **Revenue**   | The total revenue generated as attributed by TikTok to TikTok ads.   |
    | **ROAS**      | The return on ad spend as attributed by TikTok to TikTok ads.        |
    | **CPA**       | The cost of acquiring a conversion as attributed by TikTok.          |
    | **Ad Spend**  | The total expenditure on TikTok Advertising.                         |
  </Accordion>
</AccordionGroup>


# Monitoring
Source: https://docs.runconverge.com/ad-platforms/monitoring

Monitor and validate your ad platform integrations in Converge

## Overview

Converge provides the following tools to monitor and debug whether your marketing sources are working correctly:

* [Tracking parameters](#tracking-parameters)

***

## Tracking parameters

Converge will automatically flag when ads are not configured with the correct [tracking parameters](/attribution/tracking-parameters).

### Where to find tracking parameters

1. Navigate to the [Sources Tab](https://app.runconverge.com/-/ad-platforms) in your Converge dashboard.

<Frame>
  <img alt="navigate to marketing sources" />
</Frame>

2. Click on the marketing source you want to validate.

<Frame>
  <img alt="pick a source" />
</Frame>

3. Click on the **Tracking parameters** tab to see the tracking parameters.

<Frame>
  <img alt="marketing source home" />
</Frame>

4. Correct any ads with invalid tracking templates by pressing on the **Update** button and pasting the correct template.

<Frame>
  <img alt="tracking parameters tab" />
</Frame>


# Overview
Source: https://docs.runconverge.com/ad-platforms/overview



## What are marketing sources?

Marketing sources are ad platforms or other marketing tools that Converge pulls data from. They let you see platform-specific metrics, like **ad spend**, **impressions**, **clicks**, and **in-platform attribution** directly in your Converge reports.

Converge shows these metrics in reports and dashboards exactly as received from the source. They aren't modified in any way.

<Note> To send data from Converge to the ad platform, check out our [Destinations](/destinations/integrations/overview) instead.</Note>

## Available marketing sources

[//]: # "Easily find SVG logos at https://www.svgrepo.com/"

<CardGroup>
  <Card title="Amazon Ads" href="/ad-platforms/integrations/amazon-ads" icon={<AmazonIcon/>} />

  <Card title="AppLovin" href="/ad-platforms/integrations/applovin" icon={<AppLovinIcon/>} />

  <Card title="Attentive" href="/ad-platforms/integrations/attentive" icon={<AttentiveIcon/>} />

  <Card title="Criteo" href="/ad-platforms/integrations/criteo" icon={<CriteoIcon />} />

  <Card title="Google Ads" href="/ad-platforms/integrations/google-ads" icon={<GoogleAdsIcon/>} />

  <Card title="Google Sheets" href="/ad-platforms/integrations/google-sheets" icon={<GoogleSheetsIcon/>} />

  <Card title="impact.com" href="/ad-platforms/integrations/impact" icon={<ImpactIcon/>} />

  <Card title="Meta Ads (Facebook Ads)" href="/ad-platforms/integrations/facebook" icon={<FacebookIcon/>} />

  <Card title="Microsoft Ads (Bing Ads)" href="/ad-platforms/integrations/bing" icon={<MicrosoftAdsIcon/>} />

  <Card title="Klaviyo" href="/ad-platforms/integrations/klaviyo" icon={<KlaviyoIcon/>} />

  <Card title="OpenAI" href="/ad-platforms/integrations/openai" icon={<OpenAIAdsIcon/>} />

  <Card title="Outbrain" href="/ad-platforms/integrations/outbrain" icon={<OutbrainIcon/>} />

  <Card title="Pinterest Ads" href="/ad-platforms/integrations/pinterest" icon={<PinterestAdsIcon/>} />

  <Card title="Snapchat Ads" href="/ad-platforms/integrations/snapchat" icon={<SnapchatAdsIcon/>} />

  <Card title="Taboola" href="/ad-platforms/integrations/taboola" icon={<TaboolaIcon/>} />

  <Card title="Tapjoy" href="/ad-platforms/integrations/tapjoy" icon={<TapjoyIcon/>} />

  <Card title="TikTok Ads" href="/ad-platforms/integrations/tiktok" icon={<TikTokAdsIcon/>} />
</CardGroup>


# Channel classification
Source: https://docs.runconverge.com/attribution/channel-classification

How Converge automatically classifies your traffic into channel groups and channels

## Overview

Converge automatically classifies web traffic into **channel groups** (like *Paid Social* or *Organic Search*) and **channels** (like *Meta Ads* or *Google Ads*). This classification happens for each identified session and determines how your traffic sources appear in attribution reports.

Understanding how classification works helps you interpret your attribution data and troubleshoot unexpected categorization.

## Key concepts

**Channel group**: A high-level traffic category that describes the broad type of traffic source.

Examples: *Paid Social*, *Organic Search*, *Email*, *Direct*

**Channel**: The specific channel or source within a channel group.

Examples: *Meta Ads*, *Google Ads*, *Klaviyo*

**Classification priority**: When multiple signals are present (like UTM parameters and referrer data), Converge evaluates them in a specific order. Earlier matches take precedence.

## How classification works

Converge uses several data points from each touchpoint to determine the channel group and channel:

1. **Converge tracking parameters**: Internal channel identifiers (`cvg_source`, `cvg_adid`, etc.)
2. **UTM parameters**: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`
3. **Click IDs**: Channel-specific tracking parameters (`fbclid`, `gclid`, `ttclid`, etc.)
4. **Referrer**: The HTTP `referrer` domain (the previous domain where the user clicked a link to your site)

### Classification priority

The system evaluates rules in this order:

#### 1. The `cvg_source` parameter

When `cvg_source` is present in the tracking parameters, the traffic is always classified as **paid**. The channel group and channel are determined by the channel value in `cvg_source`.

For example, `cvg_source=facebook` will be classified with a channel group of **Paid Social** and a channel of **Meta Ads**.

#### 2. Paid medium detection

If the `utm_medium` parameter indicates paid traffic, Converge looks for channel identifiers to classify the traffic.

**Paid medium values:**

* `cpc`, `cpm`, `cpv`, `cpa`, `ppc`, `retargeting`
* Any value starting with `paid`

When paid traffic is detected, the specific channel is determined by checking (in order):

1. Click IDs (`fbclid`, `gclid`, etc.)
2. UTM source (`facebook`, `google`, etc.)
3. UTM medium (`display`, `affiliate`, etc.)
4. Referrer domain

For example, `utm_source=facebook&utm_medium=cpc` will be classified with a channel group of **Paid Social** and a channel of **Meta Ads**.

#### 3. Internal traffic detection

Converge classifies traffic as "Direct" when the landing URL domain matches the referrer domain. We compare top-level domains to handle subdomains correctly.

For example, if the landing URL is `https://www.example.com/cart` and the referrer is `https://shop.example.com/products`, the traffic will be classified as **Direct**, as Converge detects that the top-level domain is the same.
This avoids classifying internal traffic as organic.

#### 4. Organic traffic classification

If none of the paid rules match and the traffic isn't direct, Converge evaluates organic rules by checking (in order):

1. Click IDs
2. UTM source
3. UTM medium
4. Referrer domain

For example, if the referrer is `https://www.google.com/search?q=...`, the traffic will be classified as **Organic Search** and a channel of **Google**.

#### 5. Fallback rules

If no organic rules match:

* With a referrer → "Referral"
* Without referrer or UTM parameters → "Direct"
* With UTM parameters but no match → "Unknown"

## Supported classifications

This is a non-exhaustive list of channels and sources recognized by Converge.

### Paid marketing sources

| Marketing source | Channel Group | Recognized Sources                             |
| ---------------- | ------------- | ---------------------------------------------- |
| Facebook/Meta    | Paid Social   | facebook, fb, meta, ig, instagram, an, msg, th |
| Google Ads       | Paid Search   | google                                         |
| TikTok           | Paid Social   | tiktok                                         |
| Pinterest        | Paid Social   | pinterest                                      |
| Snapchat         | Paid Social   | snapchat                                       |
| Reddit           | Paid Social   | reddit                                         |
| Bing             | Paid Search   | bing, microsoft                                |
| AppLovin         | Display       | applovin, axon                                 |
| Criteo           | Display       | criteo                                         |
| Taboola          | Display       | taboola                                        |
| Outbrain         | Display       | outbrain                                       |
| Impact.com       | Affiliate     | impact                                         |

### Search engines

| Engine     | Channel Group  | Recognized Sources | Recognized Domains |
| ---------- | -------------- | ------------------ | ------------------ |
| Google     | Organic Search | google             | google.com         |
| Bing       | Organic Search | bing               | bing.com           |
| Yahoo      | Organic Search | yahoo              | yahoo.com          |
| DuckDuckGo | Organic Search | duckduckgo         | duckduckgo.com     |
| Baidu      | Organic Search | baidu              | baidu.com          |

### Social channels

| Channel   | Channel Group  | Recognized Sources | Recognized Domains |
| --------- | -------------- | ------------------ | ------------------ |
| Facebook  | Organic Social | facebook, fb       | facebook.com       |
| Instagram | Organic Social | instagram, ig      | instagram.com      |
| Twitter   | Organic Social | twitter            | twitter.com, x.com |
| LinkedIn  | Organic Social | linkedin           | linkedin.com       |
| TikTok    | Organic Social | tiktok             | tiktok.com         |
| Reddit    | Organic Social | reddit             | reddit.com         |
| Pinterest | Organic Social | pinterest          | pinterest.com      |
| YouTube   | Organic Video  | youtube            | youtube.com        |

### Click ID recognition

Channel-specific click tracking parameters:

| Click ID                           | Channel   | Type                |
| ---------------------------------- | --------- | ------------------- |
| fbclid                             | Facebook  | Paid/Organic Social |
| gclid, gad\_source, gbraid, wbraid | Google    | Paid/Organic Search |
| ttclid                             | TikTok    | Paid Social         |
| ScCid                              | Snapchat  | Paid Social         |
| epik                               | Pinterest | Paid Social         |
| rdt\_cid                           | Reddit    | Paid Social         |
| msclkid                            | Bing      | Paid Search         |
| \_kx                               | Klaviyo   | Email               |
| mc\_cid                            | Mailchimp | Email               |
| awc                                | Awin      | Affiliate           |
| igshid                             | Instagram | Organic Social      |

### UTM medium-based classification

| Medium                  | Channel Group | Notes                       |
| ----------------------- | ------------- | --------------------------- |
| email, mail, newsletter | Email         | Channel = utm\_source value |
| sms                     | SMS           |                             |
| affiliate               | Affiliate     |                             |
| display                 | Display       |                             |
| influencer              | Influencer    | Channel = utm\_source value |
| shop\_web               | Shopping      |                             |

## Related resources

* [Session attribution](/attribution/session-attribution)
* [Tracking parameters](/attribution/tracking-parameters)


# Attribution report
Source: https://docs.runconverge.com/attribution/channels

Analyze the sources of conversions on your website

<CloudinaryVideo />

<br />

## Where to find the Attribution Report

You can access the Attribution report by clicking on <IconText name="attribution" /> in the **Analytics** section of the main navigation. Or by navigating directly to the <OutboundLink /> report.

#### Video Demo

<LoomVideo />

***

## Introduction to conversions and attribution

Converge allows you to see attributed conversions based on:

1. **First-party Attribution**: these are conversions **attributed by Converge** based on the [attribution model](#changing-the-attribution-model-of-your-first-party-conversions) you pick in Converge and your Converge tracking parameters. You can recognize them by this icon: <ConvergeIcon />.
2. **In-Platform Attribution**: these are conversions **attributed by the ad platforms themselves**. You can recognize all in-platform data by this icon: <InPlatformIcon />

<Frame>
  <img alt="attribution-0" />
</Frame>

<br />

The screenshot above shows the purchase conversions based on **First-party Attribution** (*<ConvergeIcon /> Purchases*) and the **In-Platform Attribution** (*<InPlatformIcon /> Purchases*).

There is no notion of in-platform attribution for channel sources that are not ad platforms. An Organic channel has no built-in attribution, but the Facebook Ads Manager does.

***

## Why are my First-Party conversions and my In-Platform conversions different?

If you are using the Converge Destination product, then **the same data is powering your first-party attribution and your in-platform attribution**.
However, the attributed conversions based on first-party attribution and in-platform attribution **will likely not match** as they're based on different attribution models.

If you want to learn how to interpret these numbers and why they are different, then you should read our <OutboundLink />.

***

## Changing the attribution model of your first-party conversions

<Note>Changing the attribution model will only change the attribution model of **first-party metrics**. The In-Platform conversions and metrics are determined by the attribution model of the ad platform itself.</Note>

We allow you to change the attribution model that Converge should use to attribute its **first-party metrics** (e.g., **Purchases**).

<Frame>
  <img alt="change-attribution-model" />
</Frame>

<br />

<Info>See <OutboundLink /> for a detailed description of all our attribution models.</Info>

***

## Attribution Chart

The Attribution Chart provides a visual time-series view of your attribution data, helping you understand how conversions and other metrics evolve over time.

To include time context in your attribution analysis, you can enable the **Show chart** toggle in the top right corner of the module.

<Frame>
  <img alt="attribution-chart" />
</Frame>

#### Managing Chart Metrics

You can add or remove metrics from the chart in two ways:

1. **In the chart itself**: Click the <Icon name="plus" /> button in the chart header to add metrics from the available list. To remove a metric, click the <Icon name="x" /> icon on the metric toggle button. You can also toggle metric visibility on/off by clicking the metric toggle buttons directly.

2. **Through the table headers**: Each metric column header includes a checkbox that allows you to add or remove that metric from the chart. Checkboxes are only visible when the chart is enabled. For metrics not yet in the chart, the checkbox appears when you hover over the column header.

<Info>The chart will only display metrics that are present in your table.
If you want to visualize a metric in the chart, make sure it's added as a column in the table first.</Info>

Attribution chart metrics can be saved on a per-view basis.

#### Chart Data Selection

By default, when no rows are selected in the table, the chart displays all data that contributes to your current table view.
Once you start selecting specific rows using the checkboxes in the table, the chart automatically updates to show only the data for your selected items.

#### Advanced Customization

If you need more advanced chart customization options, such as different visualization types, additional filters, or the ability to save custom chart configurations, you can click the **Open in Insights** button in the top right corner of the chart header.

This link will open the chart with its current settings in the Insights module. From there, you can further customize and save your chart separately.

***

## Customizing the table columns

You can customize the table by adding, moving, or removing columns.

<Accordion title="Add custom columns" icon="circle-plus">
  1. Click on <Icon name="plus" /> in the top right corner of the table.
  2. Search or select the metric you want to add.
  3. Select how you want to aggregate the metric. (optional)
  4. Click **Save**.

  <Info> Check <OutboundLink /> to see which metrics you can add.</Info>
</Accordion>

<Accordion title="Change the order of the columns" icon="sort">
  1. Drag and re-order the columns by grabbing onto the name of the column and moving it above or below other columns.
  2. Click **Save**.
</Accordion>

<Accordion title="Remove a column" icon="eye">
  1. Hover over the column name and click the <Icon name="ellipsis-vertical" />-icon next to the name.
  2. Click <IconText name="trash" />.
  3. Click **Save**.
</Accordion>


# Introduction
Source: https://docs.runconverge.com/attribution/introduction

What is attribution and how does it work?

Attribution is how Converge assigns sessions or events to specific touchpoints—like channels, campaigns, or referrers. These events include conversions like **Placed Order** or earlier steps like **Viewed Product**.

Converge processes attribution in two steps:

1. **Session attribution**: assigning a session to a channel, campaign, adset or ad.
2. **Event attribution**: assigning credit for an event to the different sessions a user had.

This gives you a clear view of which channels are driving customers and how they contribute to your business success.

## Session attribution

Session attribution is how Converge determines where a visit on your site comes from based on the landing page URL, referrer, and certain click IDs or tracking parameters.

### What is a session?

A session is a single visit to your website from a specific source within a set time frame. Sessions start and end based on these rules:

* **Sessions time out after 60 minutes of inactivity** — If you visit our website, leave the window open, and continue more than 60 minutes later, a new session starts.
* **Different sources start new sessions** — If you land from a Facebook ad, leave, and return through a Google Ads ad 30 minutes later, that starts a new session.

### Example

Let’s say two users search for your company on Google. One clicks on a paid ad from Google Ads, the other clicks an organic search result. They land on:

* Paid Click: [https://www.example.com/?gclid=123456789](https://www.example.com/?gclid=123456789)
* Organic Click: [https://www.example.com/](https://www.example.com/)

Converge sees both users coming from `www.google.com`, but the `gclid` parameter that Google Ads attaches to the URL tells us the first came from a Google Ads campaign. The second visit has no `gclid`, so we attribute it to Google's organic search.

So we can attribute to the following Channels:

* Paid click: **Google**
* Organic click: **Google (Organic Search)**

To go any deeper—like understanding which *campaign*, *ad set*, or *ad* drove the click—we need tracking parameters.

### Tracking parameters

Tracking parameters provide context about session sources through extra URL fields.

For example, someone clicks your search ad from Google Ads. The URL might look like:

`https://www.example.com/?gclid=123456789&cvg_source=google&cvg_cid=98765&cvg_adid=12345`

Here's what we can extract:

* `gclid`: **123456789**
* `cvg_source`: **google**
* `cvg_cid`: **98765**
* `cvg_adid`: **12345**

If you've added Google Ads as a <OutboundLink />, Converge fetches your campaigns, ad sets, and ads—including their unique IDs. We then match those IDs with what we find in the landing page URL.

So we can attribute:

* Channel: **Google**
* Campaign: **Campaign A**
* Ad set: **Ad set 1**
* Ad: **Ad variant D**

Find more details on how Converge attributes sessions [here](/attribution/session-attribution).

<Note>
  Converge relies on accurate tracking parameters to correctly attribute your sessions.
  Learn more about setting up the tracking parameters [here](/attribution/tracking-parameters).
</Note>

## Event attribution

Event attribution assigns credit for a specific event, like a Placed Order or Started Subscription, to the different sessions within a customer journey. Here’s an example journey:

1. The user sees a Facebook ad but doesn’t click.
2. The user clicks a Google Search ad and lands on your site, browses products but doesn't purchase.
3. The user returns via organic search, adds a product to the cart, but doesn’t complete the checkout.
4. The user gets a cart abandonment email, clicks it, and completes a purchase with a value of \$1000.

The sum of all these interactions (touchpoints) a user has with your brand, either on your website or anywhere else, is called a *customer journey*.

Event attribution is the process of applying credit to each touchpoint to determine how much they contributed to the user performing a specific action, like making a purchase.

<Note>Converge doesn't mark events as **Conversions**. Apply attribution to any event you track in Converge.</Note>

### Converge vs In-Platform attribution

Converge attributes events to all observable touchpoints, with some limits. Converge tracks website interactions only, so we can't see ad views or emails without clicks.

**Converge only knows if someone viewed an ad or received an email if the user clicked a link and landed on your website**.

For the example [above](#event-attribution), Converge can only observe the following three sessions the user had on your website, since we can't track that a user viewed a Facebook ad without clicking a link in the ad.

```mermaid actions={false} theme={null}
flowchart LR
  id1("**Session 1**<br/>Google Ads<br/>_No purchases_") --> id2("**Session 2**<br/>Google (Organic Search)<br/>_No purchases_") --> id3("**Session 3**<br/>Email<br/>_1 purchase_")
```

In many cases, your ad platforms will also try to attribute your events. We call this **In-Platform Attribution** and it can show discrepancies when compared to Converge. Neither Converge nor the ad platform is wrong. They all just have a limited perspective on the truth.

In our earlier [example](#event-attribution):

* **Converge** attributes the purchase to any of the three sessions it observed according to the [attribution model](#attribution-models).
* **Facebook** attributes the purchase to the ad view (even without a click). It will ignore all other touchpoints.
* **Google Ads** attributes the purchase to the search ad click. It will also ignore all other touchpoints.

Each platform has limited visibility into user interactions with your brand and uses its own attribution model. This can cause the sum of in-platform attributed purchases to exceed your backend totals, since multiple platforms may each claim full credit for the same purchase.

### Attribution models

Converge supports different attribution models to apply credit to the different sessions in a customer journey.

See the following three attribution models where the \$1000 value from our [example](#event-attribution) is attributed to the different sessions Converge could observe.

**Last touch**

All credit goes to the last session Converge observed.

```mermaid actions={false} theme={null}
flowchart LR
  id1("**Session 1**<br/>Google Ads<br/>_$ 0_") --> id2("**Session 2**<br/>Google (Organic Search)<br/>_$ 0_") --> id3("**Session 3**<br/>Email<br/>_$ 1000_")
```

**First touch**

All credit goes to the first session Converge observed.

```mermaid actions={false} theme={null}
flowchart LR
  id1("**Session 1**<br/>Google Ads<br/>_$ 1000_") --> id2("**Session 2**<br/>Google (Organic Search)<br/>_$ 0_") --> id3("**Session 3**<br/>Email<br/>_$ 0_")
```

**U-shaped**

Credit is shared: 40% to the first and last sessions, 20% to the ones in between.

```mermaid actions={false} theme={null}
flowchart LR
  id1("**Session 1**<br/>Google Ads<br/>_$ 400_") --> id2("**Session 2**<br/>Google (Organic Search)<br/>_$ 200_") --> id3("**Session 3**<br/>Email<br/>_$ 400_")
```

See all [attribution models](/attribution/models) Converge offers and which use cases they apply to.


# Metric dictionary
Source: https://docs.runconverge.com/attribution/metrics

A glossary of the metrics that Converge shows in its reports

## Revenue and Profit

| Metric                        | Description                                                                                                |                                               Formula                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------: |
| **Gross Revenue**             | Total product sales (excluding taxes and shipping charges) before discounts.                               |                         $\Sigma(\text{Unit Price} \times \text{Quantity})$                         |
| **Discounts**                 | Total value of discounts applied to orders.                                                                |                                                                                                    |
| **Total Revenue**             | Total product sales after taking into account discounts.                                                   |                              $\text{Gross Revenue} - \text{Discounts}$                             |
| **Revenue per session**       | Average Total Revenue generated per session.                                                               |                           $\frac{\text{Total Revenue}}{\text{Sessions}}$                           |
| **Taxes**                     | Total taxes (paid by customers), collected across all orders.                                              |                                                                                                    |
| **Shipping Charges**          | Total shipping charges (paid by customers), collected across all orders.                                   |                                                                                                    |
| **Total Revenue After Taxes** | Total revenue minus taxes.                                                                                 |                                $\text{Total Revenue} - \text{Taxes}$                               |
| **Net Revenue**               | Total revenue minus taxes and shipping charges.                                                            |                   $\text{Total Revenue} - \text{Taxes} - \text{Shipping Charges}$                  |
| **COGS**                      | Total cost of goods sold. See [Expenses](/data-management/expenses) for how to configure product costs.    |                                                                                                    |
| **Gross Profit**              | Net revenue minus cost of goods sold.                                                                      |                                 $\text{Net Revenue} - \text{COGS}$                                 |
| **Gross Margin**              | Gross profit as a percentage of net revenue.                                                               |                          $\frac{\text{Gross Profit}}{\text{Net Revenue}}$                          |
| **Payment Processing Fees**   | Total payment processing fees across all orders.                                                           |                                                                                                    |
| **Shipping Costs**            | The total shipping cost you paid to deliver orders to the customer.                                        |                                                                                                    |
| **Contribution Profit**       | Gross profit minus payment processing fees and net shipping costs (shipping costs minus shipping charges). | $\text{Gross Profit} - \text{Processing Fees} - (\text{Shipping Costs} - \text{Shipping Charges})$ |
| **Contribution Margin**       | Contribution profit as a percentage of net revenue.                                                        |                       $\frac{\text{Contribution Profit}}{\text{Net Revenue}}$                      |
| **Net Profit**                | Contribution profit minus ad spend.                                                                        |                           $\text{Contribution Profit} - \text{Ad Spend}$                           |
| **Net Margin**                | Net profit as a percentage of net revenue.                                                                 |                           $\frac{\text{Net Profit}}{\text{Net Revenue}}$                           |

## Orders & conversion

| Metric                    | Description                                                                                                                                                   |                         Formula                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------------------------------: |
| **Orders**                | Total orders as tracked by a shopping platform (e.g., Shopify) or a custom server-side integration. Refunded orders and gift card purchases are also counted. |                                                         |
| **Customers**             | Number of unique profiles who have placed an order.                                                                                                           |                                                         |
| **AOV**                   | Average order value (Total Revenue).                                                                                                                          |       $\frac{\text{Total Revenue}}{\text{Orders}}$      |
| **Conversion rate**       | Percentage of sessions with a Placed Order event.                                                                                                             |   $\frac{\text{Sessions with Order}}{\text{Sessions}}$  |
| **Added to cart rate**    | Percentage of sessions with an Added To Cart event.                                                                                                           |    $\frac{\text{Sessions with ATC}}{\text{Sessions}}$   |
| **Started checkout rate** | Percentage of sessions with a Started Checkout event.                                                                                                         | $\frac{\text{Sessions with Checkout}}{\text{Sessions}}$ |

## Sessions & traffic

| Metric                     | Description                                                                                                                                                                                                                                                                   |                        Formula                        |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------: |
| **Profiles**               | Number of unique profiles who have performed an event.                                                                                                                                                                                                                        |                                                       |
| **Sessions**               | Total number of sessions tracked by the Converge Pixel.                                                                                                                                                                                                                       |                                                       |
| **New visitor sessions**   | Number of sessions from first-time visitors.                                                                                                                                                                                                                                  |                                                       |
| **New visitor sessions %** | Percentage of sessions from first-time visitors.                                                                                                                                                                                                                              | $\frac{\text{New Visitor Sessions}}{\text{Sessions}}$ |
| **Bounce rate**            | Percentage of sessions that "bounced." A session is considered bounced when its duration is 10 seconds or less AND only one page was visited. Similar to [GA4's definition](https://support.google.com/analytics/answer/12195621), but without considering conversion events. |   $\frac{\text{Bounced Sessions}}{\text{Sessions}}$   |
| **Session duration**       | Average duration of sessions in seconds.                                                                                                                                                                                                                                      |                                                       |

## Blended advertising

Blended metrics aggregate spend across all your [Marketing Sources](/ad-platforms/overview) and compare against Converge-tracked revenue.

| Metric           | Description                                                           |                     Formula                     |
| ---------------- | --------------------------------------------------------------------- | :---------------------------------------------: |
| **Ad spend**     | Total spend across all ad platforms.                                  |                                                 |
| **Blended ROAS** | Total Revenue divided by total ad spend.                              |  $\frac{\text{Total Revenue}}{\text{Ad Spend}}$ |
| **Blended ACOS** | Total ad spend divided by Total Revenue.                              |  $\frac{\text{Ad Spend}}{\text{Total Revenue}}$ |
| **Blended CPA**  | Total ad spend divided by total orders.                               |     $\frac{\text{Ad Spend}}{\text{Orders}}$     |
| **Blended POAS** | Gross Profit divided by total ad spend.                               |  $\frac{\text{Gross Profit}}{\text{Ad Spend}}$  |
| **Web MER**      | Total Revenue from web orders divided by total ad spend.              |   $\frac{\text{Web Revenue}}{\text{Ad Spend}}$  |
| **Web aMER**     | New customer Total Revenue from web orders divided by total ad spend. | $\frac{\text{NC Web Revenue}}{\text{Ad Spend}}$ |

## New customer

| Metric                   | Description                                                                                                |                       Formula                      |
| ------------------------ | ---------------------------------------------------------------------------------------------------------- | :------------------------------------------------: |
| **New Customer Revenue** | Total revenue from new customers.                                                                          |                                                    |
| **New customers**        | Number of new customers. A new customer is anyone who's never placed an order before, identified by email. |                                                    |
| **New customers %**      | Percentage of orders from new customers.                                                                   | $\frac{\text{New Customer Orders}}{\text{Orders}}$ |
| **NC-AOV**               | Average order value for new customers.                                                                     |    $\frac{\text{NC Revenue}}{\text{NC Orders}}$    |
| **Blended NC-ROAS**      | New Customer Revenue divided by total ad spend.                                                            |     $\frac{\text{NC Revenue}}{\text{Ad Spend}}$    |
| **Blended NC-ACOS**      | Total ad spend divided by New Customer Revenue.                                                            |     $\frac{\text{Ad Spend}}{\text{NC Revenue}}$    |
| **Blended NC-CPA**       | Total ad spend divided by the number of new customers.                                                     |   $\frac{\text{Ad Spend}}{\text{New Customers}}$   |

## Ad platform

Ad platform metrics come directly from each platform's own reporting. They reflect what the platform measures, not what Converge tracks.

| Metric          | Description                                                    |                        Formula                        |
| --------------- | -------------------------------------------------------------- | :---------------------------------------------------: |
| **Ad spend**    | Spend as reported by the ad platform.                          |                                                       |
| **Impressions** | Number of ad impressions as reported by the ad platform.       |                                                       |
| **Clicks**      | Number of ad clicks as reported by the ad platform.            |                                                       |
| **Conversions** | Number of purchase conversions as reported by the ad platform. |                                                       |
| **Revenue**     | Revenue from purchases as reported by the ad platform.         |                                                       |
| **ROAS**        | Return on ad spend as reported by the ad platform.             |         $\frac{\text{Revenue}}{\text{Spend}}$         |
| **ACOS**        | Advertising cost of sales as reported by the ad platform.      |         $\frac{\text{Spend}}{\text{Revenue}}$         |
| **CPA**         | Cost per acquisition as reported by the ad platform.           |       $\frac{\text{Spend}}{\text{Conversions}}$       |
| **CPC**         | Cost per click as reported by the ad platform.                 |          $\frac{\text{Spend}}{\text{Clicks}}$         |
| **CPM**         | Cost per thousand impressions as reported by the ad platform.  | $\frac{\text{Spend}}{\text{Impressions}} \times 1000$ |
| **CTR**         | Click-through rate as reported by the ad platform.             |       $\frac{\text{Clicks}}{\text{Impressions}}$      |

## Product

Product metrics break down revenue and efficiency by individual SKU.

| Metric                              | Description                                                                                                                                                   | Formula                                                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Product Total Revenue**           | Product's share of order total revenue, allocated proportionally by line item sales.                                                                          | $\Sigma\!\left(\text{Order Total} \times \frac{\text{Item Price} \times \text{Qty}}{\text{Total Item Sales}}\right)$    |
| **Product Net Revenue**             | Revenue after deducting taxes and shipping.                                                                                                                   | $\text{Product Revenue} - \text{Taxes} - \text{Shipping}$                                                               |
| **Product COGS**                    | Total cost of goods sold. Uses manually set product costs, platform-synced costs (e.g. Shopify), or a fallback gross margin rate — in that order of priority. | $\Sigma(\text{Unit Cost} \times \text{Quantity})$                                                                       |
| **Product Gross Profit**            | Profit after cost of goods.                                                                                                                                   | $\text{Product Net Revenue} - \text{Product COGS}$                                                                      |
| **Product Discount**                | Total discount allocated to this product. Includes item-level discounts plus a proportional share of any remaining order-level discount.                      | $\Sigma(\text{Item Discount} + \text{Order Discount} \times \text{Sales Weight})$                                       |
| **Product Shipping Charges**        | Shipping charges allocated proportionally to this product by line item sales.                                                                                 | $\Sigma\!\left(\text{Order Shipping} \times \frac{\text{Item Price} \times \text{Qty}}{\text{Total Item Sales}}\right)$ |
| **Product Taxes**                   | Taxes allocated proportionally to this product by line item sales.                                                                                            | $\Sigma\!\left(\text{Order Tax} \times \frac{\text{Item Price} \times \text{Qty}}{\text{Total Item Sales}}\right)$      |
| **Quantity**                        | Total units of this product sold across all orders.                                                                                                           | $\Sigma(\text{Quantity})$                                                                                               |
| **Avg Price**                       | Average unit price of this product across orders.                                                                                                             | $\text{avg}(\text{Unit Price})$                                                                                         |
| **Avg Discount**                    | Average discount per order. Includes item-level discounts plus a proportional share of any remaining order-level discount.                                    | $\text{avg}(\text{Product Discount})$                                                                                   |
| **Avg Units Per Order**             | Average number of units of this product per order.                                                                                                            | $\text{avg}(\text{Quantity per Order})$                                                                                 |
| **Product Sessions**                | Unique sessions that include any event for this product (e.g. product views, add to carts, or purchases).                                                     |                                                                                                                         |
| **Product Views**                   | Total Viewed Product events for this product.                                                                                                                 |                                                                                                                         |
| **Product Added To Cart**           | Product lines across Added To Cart events for this product.                                                                                                   |                                                                                                                         |
| **Product Started Checkout**        | Product lines across Started Checkout events for this product.                                                                                                |                                                                                                                         |
| **Product Added Payment Info**      | Product lines across Added Payment Info events for this product.                                                                                              |                                                                                                                         |
| **Product Orders**                  | Product lines across Placed Order events for this product.                                                                                                    |                                                                                                                         |
| **Product ROAS**                    | Return on Ad Spend for this product.                                                                                                                          | $\frac{\text{Product Total Revenue}}{\text{Ad Spend}}$                                                                  |
| **Product ACOS**                    | Advertising Cost of Sale for this product.                                                                                                                    | $\frac{\text{Ad Spend}}{\text{Product Total Revenue}}$                                                                  |
| **Product POAS**                    | Profit on Ad Spend for this product.                                                                                                                          | $\frac{\text{Gross Profit}}{\text{Ad Spend}}$                                                                           |
| **Product CPA**                     | Cost Per Acquisition for this product.                                                                                                                        | $\frac{\text{Ad Spend}}{\text{Quantity Sold}}$                                                                          |
| **Product Session Conversion Rate** | Percentage of sessions involving this product that resulted in a purchase.                                                                                    | $\frac{\text{Sessions with Purchase}}{\text{All Product Sessions}}$                                                     |
| **New customers**                   | Unique customers placing their first-ever order that includes this product.                                                                                   |                                                                                                                         |
| **New visitor sessions**            | Sessions from first-time visitors that include events for this product.                                                                                       |                                                                                                                         |
| **New visitor sessions %**          | Percentage of sessions for this product from first-time visitors.                                                                                             | $\frac{\text{New Visitor Sessions}}{\text{Total Sessions}}$                                                             |
| **Revenue per session**             | Average product revenue generated per session.                                                                                                                | $\frac{\text{Product Total Revenue}}{\text{All Product Sessions}}$                                                      |
| **Product Spend**                   | Ad spend allocated proportionally based on a product event from paid sessions. Defaults to "Viewed Product" but can be configured to any product event.       | $\text{Ad Spend} \times \frac{\text{Product Views}}{\text{Total Product Views}}$                                        |

<Note>
  Product event counts are based on **product lines**, not events. Events like Started Checkout or Placed Order can contain multiple products — each product line counts separately. For example, a single Started Checkout with three products increments each product's count by one.
</Note>

## Email (Klaviyo)

Email metrics come from your [Klaviyo](/ad-platforms/integrations/klaviyo) integration.

| Metric                        | Description                              |
| ----------------------------- | ---------------------------------------- |
| **Emails bounced**            | Number of emails that bounced.           |
| **Emails delivered**          | Number of emails successfully delivered. |
| **Total emails clicked**      | Total number of email link clicks.       |
| **Total emails opened**       | Total number of email opens.             |
| **New email subscribers**     | Number of new email subscribers.         |
| **Churned email subscribers** | Number of email subscribers who churned. |


# Attribution models
Source: https://docs.runconverge.com/attribution/models

Learn how different attribution models in Converge work

<CloudinaryVideo />

## Introduction

When configuring attribution in Converge, you make these choices:

* **Window**: How far back to look for touchpoints that should receive credit for a conversion (e.g., 1 day, 7 days, 90 days).
* **Model**: How to distribute credit across the touchpoints in a customer journey (e.g., first touch, last touch, linear).
* **Mode**: When to assign credit; at the time of the click on the ad (click time) or at the time of conversion (conversion time).
* **Lookback window** *(Click time mode only)*: How many days after a touchpoint a conversion is still counted toward that touchpoint's credit. Used to compare recent periods fairly before the full attribution window has elapsed. See [Lookback window](#lookback-window).

### Example

Consider a customer journey where a prospect clicks a Snapchat ad, then a Meta ad, then a Google Search ad before purchasing:

<Frame>
  <img />
</Frame>

Here's how Converge applies attribution to this journey:

1. **Apply attribution window (e.g. 7 days)**: Filter out touchpoints outside the window. Since the Snapchat click happened on Day 1 (outside a 7-day window from the Day 10 conversion), only the Meta and Google clicks qualify.

2. **Apply attribution model (e.g., Linear)**: Distribute credit across qualifying touchpoints. With a Linear model, the Meta and Google clicks each receive 50% credit.

3. **Apply attribution mode (e.g., Click time)**: Assign when revenue credit is recorded. With Click time attribution, the \$100 purchase is split: \$50 credited to Day 5 (Meta click) and \$50 to Day 10 (Google click).

4. **Apply lookback window (Click time mode only)**: Optionally drop credit from touchpoints whose conversion arrived too long after them. For example, with a **4-day** lookback, the Meta click's \$50 is dropped from the total (the conversion arrived 5 days later), while the Google click's \$50 is kept. Defaults to the **Full window** (equivalent to the attribution window). See [Lookback window](#lookback-window).

<Frame>
  <img />
</Frame>

## Overview table

The overview table shows how different models attribute a conversion journey with four different (non-direct) touchpoints.

| Attribution Model                                         | First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |   Only Paid Channels  |
| --------------------------------------------------------- | :---------: | :------------: | :------------: | :--------: | :-------------------: |
| [First touch](#first-touch)                               |     100%    |       0%       |       0%       |     0%     | <Icon name="xmark" /> |
| [First touch paid only](#first-touch-paid-only)           |     100%    |       0%       |       0%       |     0%     | <Icon name="check" /> |
| [Last touch](#last-touch)                                 |      0%     |       0%       |       0%       |    100%    | <Icon name="xmark" /> |
| [Last touch paid only](#last-touch-paid-only)             |      0%     |       0%       |       0%       |    100%    | <Icon name="check" /> |
| [Linear](#linear)                                         |     25%     |       25%      |       25%      |     25%    | <Icon name="xmark" /> |
| [Top of funnel](#top-of-funnel)                           |     25%     |       25%      |       25%      |     25%    | <Icon name="check" /> |
| [Participation](#participation)                           |     100%    |      100%      |      100%      |    100%    | <Icon name="xmark" /> |
| [J-shaped](#j-shaped)                                     |     20%     |       10%      |       10%      |     60%    | <Icon name="xmark" /> |
| [J-shaped paid only](#j-shaped-paid-only)                 |     20%     |       10%      |       10%      |     60%    | <Icon name="check" /> |
| [Inverse J-shaped](#inverse-j-shaped)                     |     60%     |       10%      |       10%      |     20%    | <Icon name="xmark" /> |
| [Inverse J-shaped paid only](#inverse-j-shaped-paid-only) |     60%     |       10%      |       10%      |     20%    | <Icon name="check" /> |
| [U-shaped](#u-shaped)                                     |     40%     |       10%      |       10%      |     40%    | <Icon name="xmark" /> |
| [Time decay](#time-decay)\*                               |      -      |        -       |        -       |      -     | <Icon name="xmark" /> |
| [Inverse time decay](#inverse-time-decay)\*               |      -      |        -       |        -       |      -     | <Icon name="xmark" /> |

\* The Time decay and Inverse time decay models consider the time between touchpoints, which isn't shown in the simplified table above.
Read more about the Time decay model [here](#time-decay).

<Note>
  All attribution models **except Direct** skip direct touchpoints whenever a non-direct touchpoint is available in the journey. If the entire journey is direct, they fall back to the direct session.

  For example, in this customer journey: `Facebook > Direct > Google > Direct > Conversion`, the last touch model attributes the entire conversion to Google,
  while a linear model attributes 50% to Facebook and 50% to Google.

  This is why numbers can differ meaningfully between the Direct model and all other models. If many of your conversions come through direct sessions (for example, repeat visitors who navigate straight to your site), non-direct models will attribute those conversions to an earlier non-direct touchpoint, while the Direct model attributes them to Direct.
</Note>

## Attribution window

The attribution window determines how far back Converge looks for touchpoints that should receive credit for a conversion.

Converge offers fixed attribution window options: **1 day**, **3 days**, **7 days**, **14 days**, **30 days**, or **90 days**.

**Example**: A customer has touchpoints on January 1st, January 2nd, and January 3rd, then converts on January 4th.

* With a **1-day** attribution window, only the January 3rd touchpoint receives credit (it's within 1 day of the conversion).

```mermaid actions={false} theme={null}
%%{init: {'theme':'default', 'flowchart': {'useMaxWidth': true}}}%%
flowchart LR
  id1("**Jan 1**<br/>Touchpoint<br/>_No credit (out of window)_") --> id2("**Jan 2**<br/>Touchpoint<br/>_No credit (out of window)_") --> id3("**Jan 3**<br/>Touchpoint<br/>_Receives credit_") --> id4("**Jan 4**<br/>Conversion")
```

* With a **7-day** attribution window, all three touchpoints receive credit (they're all within 7 days of the conversion).

```mermaid actions={false} theme={null}
flowchart LR
  id1("**Jan 1**<br/>Touchpoint<br/>_Receives credit_") --> id2("**Jan 2**<br/>Touchpoint<br/>_Receives credit_") --> id3("**Jan 3**<br/>Touchpoint<br/>_Receives credit_") --> id4("**Jan 4**<br/>Conversion")
```

## Attribution mode

The attribution mode determines when conversion and revenue credit are given. There are two modes:

**Click time**: Credit is given at the touchpoint time. For example, if a user clicks a Facebook ad on January 1st and converts on January 5th, the conversion credit is attributed to January 1st.

**Conversion time**: Credit is given at the transaction time. Using the same example, the conversion credit would be attributed to January 5th.

## Lookback window

<Note>The lookback window only applies in **Click time** mode. It has no effect in **Conversion time** mode.</Note>

The lookback window lets you compare recent performance fairly without waiting for the attribution window to fully elapse.

In Click time mode, credit for a click is recorded on the day of the click, but the conversions that earn that credit arrive over the following days. With a 30-day attribution window, today's numbers are artificially low and will keep growing for another 30 days. Comparing this week to last month is therefore unfair unless you wait for the full window to pass.

A shorter lookback window settles the data sooner, so you can spot trends and adjust spend without waiting weeks.

The lookback window caps how many days after a touchpoint a conversion is still counted toward that touchpoint's credit. It does not change which touchpoints qualify or how credit is split between them — it only restricts which conversions are summed into each touchpoint's total.

Converge offers fixed lookback window options: **1 day**, **3 days**, **7 days**, **14 days**, **30 days**, or **Full window**. The lookback window must be shorter than the attribution window, and defaults to **Full window** (equivalent to the attribution window).

**Example**: A customer has touchpoints on January 1st, January 5th, and January 8th, then converts on January 10th. The attribution window is **30 days** and the mode is **Click time**.

* With a **Full window** lookback (the default), all three touchpoints receive credit.

```mermaid actions={false} theme={null}
flowchart LR
  id1("**Jan 1**<br/>Touchpoint<br/>_Receives credit_") --> id2("**Jan 5**<br/>Touchpoint<br/>_Receives credit_") --> id3("**Jan 8**<br/>Touchpoint<br/>_Receives credit_") --> id4("**Jan 10**<br/>Conversion")
```

* With a **7-day** lookback, only the January 5th and January 8th touchpoints receive credit. The conversion arrived 9 days after the January 1st touchpoint — its share is dropped from the total rather than redistributed to the others.

```mermaid actions={false} theme={null}
flowchart LR
  id1("**Jan 1**<br/>Touchpoint<br/>_No credit (outside lookback)_") --> id2("**Jan 5**<br/>Touchpoint<br/>_Receives credit_") --> id3("**Jan 8**<br/>Touchpoint<br/>_Receives credit_") --> id4("**Jan 10**<br/>Conversion")
```

<Note>Because the lookback window only removes conversions from the total and never redistributes credit, totals with a shorter lookback window will be lower than totals with the full window. This is by design: only attribution that has had time to settle is counted.</Note>

## Attribution models

### Direct

**Description**: All credit goes to the channel of the session where the conversion occurred.

**Use case**: Understand which channel drove the conversion session.

<Info>
  The Direct model is the only model that uses the actual session in which the conversion happened, including direct sessions. All other models skip direct touchpoints whenever a non-direct touchpoint is available (see the note above).

  For example, with this customer journey:

  * `Facebook`-session > `Google`-session > `Direct`-session with **conversion**

  The Direct model attributes the conversion to `Direct`, while the last touch model attributes it to `Google`.
</Info>

### First touch

**Description**: All credit goes to the first touchpoint Converge observed in this customer journey.
This touchpoint can be either a **paid** channel (e.g. Facebook) or a **non-paid** channel (e.g. Organic Search).

**Use case**: Check how channels contribute to acquiring **prospective customers**.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|     100%    |       0%       |       0%       |     0%     |

### First touch paid only

<Note> If no paid touchpoint can be found, then the conversion will be attributed to *No web touchpoint*. </Note>

**Description**: All credit goes to the first **paid** touchpoint Converge observed in this customer journey.

**Use case**: Check how paid channels contribute to acquiring **prospective customers**.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|     100%    |       0%       |       0%       |     0%     |

### Last touch

**Description**: All credit goes to the last touchpoint Converge observed in this customer journey.
This touchpoint can be either a **paid** channel (e.g. Facebook) or a **non-paid** channel (e.g. Organic Search).

**Use case**: Check how channels contribute to **converting prospects into customers**.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|      0%     |       0%       |       0%       |    100%    |

### Last touch paid only

<Note> If no paid touchpoint can be found, then the conversion will be attributed to *No web touchpoint*. </Note>

**Description**: All credit goes to the last **paid** touchpoint Converge observed in this customer journey.

**Use case**: Check how channels contribute to **converting prospects into customers**.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|      0%     |       0%       |       0%       |    100%    |

### Linear

**Description**: Conversions are evenly attributed to all touchpoints in this customer journey.

For example, with 2 touchpoints each would receive **50%** credit and with 3 touchpoints each would receive **33.3%**.

**Use case**: Check how channels contribute to the complete customer journey to conversion.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|     25%     |       25%      |       25%      |     25%    |

### Top of funnel

<Note> If no top of funnel touchpoints are found, the model will fall back to a linear distribution across all touchpoints. If no touchpoints can be found at all, then the conversion will be attributed to *No web touchpoint*. </Note>

**Description**: Conversions are evenly attributed to all qualifying **paid** touchpoints in the customer journey, based on channel and campaign name.

**Includes**:

* Paid touchpoints from these channels: paid search, paid social, paid video, paid shopping, and display.
* Only touchpoints whose campaign name does **not** indicate "brand" (unless "non brand" or "NB" is present).

**Does not include**:

* Any unpaid touchpoints (e.g., organic, direct).
* Paid touchpoints with a campaign name containing "brand", "brd", or "SR" (unless the phrase includes "non brand" or "NB").

For example, with 2 qualifying touchpoints, each would receive **50%** credit, and with 3 qualifying touchpoints, each would receive **33.3%**.

**Use case**: Understand how top-of-funnel paid channels drive conversions while excluding brand-related touchpoints.

**Example for 5 touchpoints**:

|               |     First Touch     |     Middle Touch 1     |   Middle Touch 2   |   Middle Touch 3   |   Last Touch  |
| ------------- | :-----------------: | :--------------------: | :----------------: | :----------------: | :-----------: |
| Campaign Name | Summer Promo Search | Brand Awareness Search | Social Media Blast | Organic Blog Visit | Brand Display |
| Paid          |         Yes         |           Yes          |         Yes        |         No         |      Yes      |
| Branded       |          No         |           Yes          |         No         |         No         |      Yes      |
| Attribution   |         50%         |           0%           |         50%        |         0%         |       0%      |

Only paid, non-branded touchpoints are counted for attribution.\
In this example:

* "Summer Promo Search" and "Social Media Blast" are both paid and non-branded, so each receives 50% of the credit.
* "Brand Awareness Search" and "Brand Display" are excluded from attribution because their campaign names contain brand-related terms ("brand").
* "Organic Blog Visit" is not a paid touchpoint, so it gets 0%.

### Participation

<Note> It is normal for a participation model to show more attributed conversions than there are actual conversions because it will attribute the same conversion to multiple channels</Note>

**Description**: The participation model gives **100% credit** to every channel a user interacted with during their customer journey. If there are 2 channels, each gets 100% credit. If there are 3, each gets 100%. If a user interacts with multiple ads within the same channel, credit goes to the **last touchpoint** within that channel.

**Use case**: Compare first-party attribution to in-platform attribution, which also attributes **100%** credit to itself.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|     100%    |      100%      |      100%      |    100%    |

### J-shaped

**Description**: Conversions are attributed across all touchpoints but biased more towards the last touch.

For 3 or more touchpoints, **60%** of the credit is attributed to the last touch, **20%** to the first touch, the remaining **20%** is evenly distributed between the remaining touchpoints.
For 2 touchpoints, **75%** is credited to the last touch and **25%** to the first touch.

**Use case**: Use as your main model if you prefer Last touch attribution but want other touchpoints (especially first touch) to contribute.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|     20%     |       10%      |       10%      |     60%    |

### J-shaped paid only

<Note> If no paid touchpoint can be found, then the conversion will be attributed to *No web touchpoint*. </Note>

**Description**: Conversions are attributed across all **paid** touchpoints but biased more towards the last paid touch.

For 3 or more paid touchpoints, **60%** of the credit is attributed to the last paid touch, **20%** to the first paid touch, the remaining **20%** is evenly distributed between the remaining paid touchpoints.
For 2 paid touchpoints, **75%** is credited to the last paid touch and **25%** to the first paid touch.

**Use case**: Use as your main model if you prefer last touch paid attribution but want other paid touchpoints (especially first touch paid) to contribute.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|     20%     |       10%      |       10%      |     60%    |

### Inverse J-shaped

**Description**: Conversions are attributed across all touchpoints but biased more towards the first touch.

For 3 or more touchpoints, **60%** of the credit is attributed to the first touch, **20%** to the last touch, the remaining **20%** is evenly distributed between the remaining touchpoints.
For 2 touchpoints, **75%** is credited to the first touch and **25%** to the last touch.

**Use case**: Use as your main model if you prefer first touch attribution but want other touchpoints (especially last touch) to contribute.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|     60%     |       10%      |       10%      |     20%    |

### Inverse J-shaped paid only

<Note> If no paid touchpoint can be found, then the conversion will be attributed to *No web touchpoint*. </Note>

**Description**: Conversions are attributed across all **paid** touchpoints but biased more towards the first paid touch.

For 3 or more paid touchpoints, **60%** of the credit is attributed to the first paid touch, **20%** to the last paid touch, the remaining **20%** is evenly distributed between the remaining paid touchpoints.
For 2 paid touchpoints, **75%** is credited to the first paid touch and **25%** to the last paid touch.

**Use case**: Use as your main model if you prefer first touch paid attribution but want other paid touchpoints (especially last touch paid) to contribute.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|     60%     |       10%      |       10%      |     20%    |

### U-shaped

**Description**: Conversions are attributed across all touchpoints but bias more toward the first and last touches. Also known as position-based.

For 3 or more touchpoints, **40%** of the credit is attributed to the first and last touchpoints. The remaining **20%** is evenly distributed between the remaining touchpoints.
For 2 touchpoints, **50%** of the credit is attributed to both the first and last touchpoints.

**Use case**: Check how channels contribute to the complete customer journey if you believe first and last touches are more important than other touches.

**Example for 4 touchpoints**:

| First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| :---------: | :------------: | :------------: | :--------: |
|     40%     |       10%      |       10%      |     40%    |

### Time decay

**Description**: Conversions are attributed across all touchpoints using exponential decay with a 7-day half-life, normalized to 100% across all touchpoints.

Each touchpoint's weight depends on the time between the touchpoint and conversion.
The closer the touchpoint is to the conversion, the more credit it receives.
For example, a touchpoint 7 days before conversion receives half the credit of a touchpoint on the same day as conversion.

**Use case**: Check how channels contribute to the complete customer journey if you believe channels are less important when further from conversion.

**Example for 4 touchpoints**:

|             | First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| ----------- | :---------: | :------------: | :------------: | :--------: |
| Days ago    |      21     |       14       |        7       |      0     |
| Weight      |    0.125    |      0.25      |       0.5      |      1     |
| Attribution |   **6.7%**  |    **13.3%**   |    **26.7%**   |  **53.3%** |

### Inverse time decay

**Description**: Conversions are attributed across all touchpoints using an inverse exponential decay with a 7-day half-life, normalized to 100% across all touchpoints.

Each touchpoint's weight depends on the time between the touchpoint and conversion.
The earlier the touchpoint happened, the more credit it receives.
For example, a touchpoint 7 days before conversion receives double the credit of a touchpoint on the same day as the conversion.

**Use case**: Check how channels contribute to the complete customer journey if you believe that channels are more important if they are earlier in the buying journey.

**Example for 4 touchpoints**:

|             | First Touch | Middle Touch 1 | Middle Touch 2 | Last Touch |
| ----------- | :---------: | :------------: | :------------: | :--------: |
| Days ago    |      21     |       14       |        7       |      0     |
| Weight      |      1      |      0.50      |      0.25      |    0.125   |
| Attribution |  **53.3%**  |    **26.7%**   |    **13.3%**   |  **6.7%**  |


# Overview report
Source: https://docs.runconverge.com/attribution/overview

Build your own custom executive dashboard

## Where to find the Overview Report

You can access the Overview Report by clicking on <IconText name="piggybank" /> in the **Analytics** section.

## Video Demo

<CloudinaryVideo />

<Info> Check the <OutboundLink /> to understand the precise definition of all of these metrics </Info>

## Customizing the Overview

You can customize the overview by clicking on <IconText name="line-columns" /> in the top right corner.

<Accordion title="Add or remove metrics" icon="circle-plus">
  You can choose to hide an entire section (e.g. all Facebook Metrics) or specific metrics within a section.

  **Hide an entire section**

  1. Click on <IconText name="line-columns" /> in the top right corner of the Overview dashboard
  2. Click on the <Icon name="eye" />-icon next to the category you want to hide so it appears in a disabled state.
  3. Click **Save**.

  **Hide a metric within a section**

  1. Click on <IconText name="line-columns" /> in the top right corner of the Overview dashboard
  2. Click on the <Icon name="pencil" />-icon next to the category to which you want to remove or add a card.
  3. In the list of metrics of the section, click on the <Icon name="eye" />-icon next to the metric you want to hide so it appears in a disabled state.
  4. Click **Save**.
</Accordion>

<Accordion title="Change the order of the metrics" icon="sort">
  You can change the order of an entire section (e.g., all Facebook Metrics) or specific metrics within a section.

  **Re-order an entire section**

  1. Click on <IconText name="line-columns" /> in the top right corner of the Overview dashboard
  2. Drag and re-order the section by grabbing onto the <Icon name="grip-vertical" />-icon and moving it above or under other sections.
  3. Click **Save**.

  **Re-order metrics within a section**

  1. Click on <IconText name="line-columns" /> in the top right corner of the Overview dashboard
  2. Click on the <Icon name="pencil" />-icon next to the category in which you want to reorganize cards.
  3. Drag and re-order the metric by grabbing onto the <Icon name="grip-vertical" />-icon and moving it above or under other sections.
  4. Click **Save**.
</Accordion>

## Overview Report on Mobile

Converge doesn't have a mobile app, but you can add the Overview Report to your home screen to check your main acquisition KPIs on the go.

### Add to Home Screen on iOS

1. Navigate to [app.runconverge.com](https://app.runconverge.com) in Safari

2. Tap the Share button at the bottom of the screen

   <img alt="iOS share menu" />

3. Scroll down and tap **Add to Home Screen**

   <img alt="iOS share options" />

4. Tap **Add** in the top right corner

   <img alt="Add to Home Screen confirmation" />

5. The Converge icon will now appear on your home screen.
   <img alt="Converge app icon on iOS home screen" />

### Add to Home Screen on Android

1. Navigate to [app.runconverge.com](https://app.runconverge.com) in Chrome
2. Tap the three-dot menu in the top right corner
3. Tap **Add to Home screen**
4. Enter a name (or keep the default) and tap **Add**
5. Tap **Add** again in the confirmation dialog
6. The Converge icon will now appear on your home screen

***

## FAQ

<Accordion title="Why are my Shopify Sales and Converge Revenues misaligned?">
  The Converge Revenues card and the Shopify Sales card show slightly different metrics.

  Specifically, Converge includes gift card revenue in your total revenue number, and it doesn't subtract refunds.
  Shopify, however, shows a sales number with refunds already subtracted and without gift card revenue.

  **In short**:

  * **Shopify Sales** = `Gross Revenue` - `Refunds` - `Gift card revenue`
  * **Converge Revenue** = `Gross Revenue`

  If you want to make a comparison between Converge and Shopify, please follow this <OutboundLink />.
</Accordion>


# Pacing Sheet
Source: https://docs.runconverge.com/attribution/pacing

Track your core metrics over time in a real-time table

<Frame>
  <img alt="data quality" />
</Frame>

## Where to find the Pacing Sheet

You can access the Pacing Sheet by clicking on <IconText name="activity" /> in the **Analytics** section. Or by navigating directly to the <OutboundLink /> sheet.

<Info> Check the <OutboundLink /> to understand the precise definition of all of these metrics. </Info>

## Understanding the Pacing Sheet

The Pacing Sheet replaces your daily spreadsheet with up-to-date, accurate data directly from Converge. Track your marketing performance over time to spot trends and anomalies in real-time.

Your marketing data is displayed in a table format where:

* **Rows** represent time periods (day, week, month, or hour)
* **Columns** represent metrics (e.g., Ad spend, Revenue, ROAS)
* **Cells** are color-coded to highlight performance relative to the selected date range's average
* **Totals row** at the bottom shows totals or averages for each metric

Color coding helps you quickly identify:

* **Green cells**: Performance above the average
* **Red cells**: Performance below the average
* **Intensity**: Darker colors indicate larger deviations from the average

## Customizing the Pacing Sheet

You can customize the Pacing Sheet by adding metrics, adjusting the date range, changing time granularity, and configuring display options.

<Warning> If you navigate away without saving, you will lose all unsaved changes to your Pacing Sheet configuration. Make sure to click the <IconText name="floppy-disk" /> button in the top right before leaving the page. </Warning>

<Accordion title="Add a metric" icon="circle-plus">
  You can add metrics from predefined categories or create custom calculations.

  **Add a built-in metric**

  1. Click the <Icon name="plus" /> button in the rightmost column of the table
  2. Select a metric section (e.g., Blended, Facebook, Google)
  3. Choose the specific metric you want to add
  4. Optionally customize the metric name and icon
  5. Click **Add** to add the metric to your table

  **Add a custom conversion metric**

  1. Click the <Icon name="plus" /> button in the rightmost column
  2. Select a metric channel (e.g., Facebook, Google)
  3. Select **Conversion metric** from the metric dropdown
  4. Configure your custom calculation using event names and aggregations
  5. Set a name and icon for your metric
  6. Click **Add** to add the metric to your table
</Accordion>

<Accordion title="Remove a metric" icon="trash">
  1. Hover over the metric column header you want to remove
  2. Click the <Icon name="ellipsis-vertical" /> menu icon that appears
  3. Select **Remove** from the dropdown menu
</Accordion>

<Accordion title="Re-order columns" icon="grip-vertical">
  You can reorder metric columns by dragging and dropping them.

  1. Click and hold on a metric column header
  2. Drag it to the desired position
  3. Release to drop the column in its new position
</Accordion>

<Accordion title="Configure color coding" icon="palette">
  Color coding helps you quickly spot trends and anomalies. You can customize how colors are displayed.

  1. Click <IconText name="gear" /> in the top right
  2. Choose a color coding mode:
     * **Show positive and negative colors**: Highlights both high and low performance
     * **Show only positive colors**: Highlights only above-average performance
     * **Show only negative colors**: Highlights only below-average performance
     * **Disable color formatting**: Removes all color coding
  3. Changes are applied immediately
</Accordion>

<Accordion title="Use compact notation" icon="calculator">
  Compact notation displays large numbers in a shortened format (e.g., 1.52K instead of 1,523.23).

  1. Click <IconText name="gear" /> in the top right
  2. Toggle **Use compact notation** on or off
  3. Changes are applied immediately
</Accordion>

***

## FAQ

<Accordion title="How does color coding work?">
  Color coding uses statistical analysis (z-scores) to compare each cell's performance against the selected date range's average for that metric.

  * Values that are significantly performing better than the average are highlighted in green
  * Values that are significantly performing worse than the average are highlighted in red
  * The intensity of the color indicates how far from average the value is
  * Values close to the average remain uncolored

  This helps you quickly spot time periods with unusual performance that might require attention.
</Accordion>

<Accordion title="Why don't I see any data in my Pacing Sheet?">
  If your Pacing Sheet is empty, check the following:

  * **Date range**: Make sure your selected date range includes dates with data
  * **Marketing sources**: If you're tracking ad platform metrics, verify your marketing sources are connected
  * **Time granularity**: Try changing the time granularity (e.g., from day to week) to see if data appears
</Accordion>

<Accordion title="Can I export my Pacing Sheet data?">
  Full export functionality is coming soon!
</Accordion>

<Accordion title="Can I create different Pacing Views?">
  View functionality (similar to attribution) is coming soon!
</Accordion>

<Accordion title="How do I include comparison percentages (e.g., DoD)?">
  Full comparison functionality is coming soon!
</Accordion>

<Accordion title="How is the Pacing Sheet different from the Attribution Report?">
  The **Attribution Report** shows performance by channel, campaign, ad set, or ad. The **Pacing Sheet** shows performance over time, making it ideal for:

  * Performance tracking over time
  * Spotting trends and anomalies
  * Comparing performance across different time periods
  * Replacing manual spreadsheet tracking

  Both reports use the same underlying data but present it in different formats for different use cases.
</Accordion>


# Products report
Source: https://docs.runconverge.com/attribution/products

Analyze performance metrics on a per-product basis

<Frame>
  <img alt="Products Report" />
</Frame>

## Where to find the Products Report

You can access the Products Report by clicking on <IconText name="package" /> in the **Analytics** section, or by navigating directly to the <OutboundLink />.

<Info> Check the <OutboundLink /> to understand the precise definition of all product metrics. </Info>

## Understanding the Products Report

The Products Report gives you a per-product breakdown of your store's performance. Each row represents a product, so you can quickly see which items drive revenue, which ones get added to cart most often, and which are actually profitable after accounting for costs.

Your product data is displayed in a table format where:

* **Rows** represent individual products (by default grouped by product name)
* **Columns** represent metrics (e.g., Items sold, Revenue, Added to Cart, COGS)
* **Totals row** at the bottom shows totals or averages across all products

Click the dropdown on the first column header to change how rows are grouped. You can switch between **Product name** (default), **Product ID**, **Variant ID**, **Variant name**, or **SKU**.

<Frame>
  <img alt="View products by product id, product name, variant id, variant name or sku" />
</Frame>

### Key metrics

The Products Report includes metrics across several categories:

* **Sales metrics**: Items sold, Total Revenue, Net Revenue, Avg Price
* **Funnel metrics**: Product Sessions, Product Views, Added to Cart, Started Checkout, Conversion Rate
* **Cost & profitability metrics**: COGS, Gross Profit, POAS (Profit on Ad Spend)
* **Advertising metrics**: Ad spend, ROAS, ACOS, CPA

### Profitability metrics

The Products Report includes profitability columns like **COGS**, **Gross Profit**, and **POAS** (Profit on Ad Spend), giving you insight into the gross margin and profit profile of each product.

<Warning>
  Profitability metrics are only accurate if your costs are configured. See the [Expenses](/data-management/expenses) page for more information on setting up the Expenses module for profit tracking. Without cost data, Converge uses a fallback estimate which can lead to inaccurate results.
</Warning>

POAS is especially useful as an alternative to ROAS — instead of measuring revenue per dollar of ad spend, it measures **profit** per dollar of ad spend. This gives you a much clearer picture of which products are actually worth advertising.

See the [Metrics Dictionary](/attribution/metrics#product) for all available profitability metrics.

### Ad spend allocation

Ad spend is allocated proportionally to products based on a product event from paid sessions. By default, Converge uses "Viewed Product" events, but you can configure this to any product event (e.g., "Added to Cart" or "Started Checkout") in your [Settings](https://app.runconverge.com/-/settings).

<Frame>
  <img alt="Product spend allocation setting" />
</Frame>

For example, if an ad costs \$3 and leads to 2 "Viewed Product" events for Product A and 1 for Product B, then \$2 is allocated to Product A and \$1 to Product B.

All product-level ad metrics (ROAS, POAS, ACOS, CPA) are derived from this allocated spend.

## Common workflows

There are two common ways to use the Products Report with filters:

1. **Start from a product, find the best campaigns.** Filter the report to a specific product and then break down by campaign or ad. This shows you which campaigns and ads are converting best for that product — so you can double down on what's working.

2. **Start from a campaign, see which products convert.** Filter by a specific campaign or ad and see how spend is distributed across products. This helps you understand which products a campaign is actually selling and whether the product mix aligns with your goals.

## Customizing the Products Report

You can customize which metrics appear, adjust the date range, and sort by any column to find your best (or worst) performing products.

<Accordion title="Add a metric" icon="circle-plus">
  1. Click the <Icon name="plus" /> button in the rightmost column of the table
  2. Select a metric from the product metrics list
  3. The new column appears in your table immediately
</Accordion>

<Accordion title="Remove a metric" icon="trash">
  1. Hover over the metric column header you want to remove
  2. Click the <Icon name="ellipsis-vertical" /> menu icon that appears
  3. Select **Remove** from the dropdown menu
</Accordion>

<Accordion title="Re-order columns" icon="grip-vertical">
  1. Click and hold on a metric column header
  2. Drag it to the desired position
  3. Release to drop the column in its new position
</Accordion>

***

## FAQ

<Accordion title="How is ad spend allocated to products?">
  Product spend is calculated based on "Viewed Product" events from paid sessions. Converge attributes a share of ad spend to each product proportional to the product views it received from paid traffic.
</Accordion>

<Accordion title="Why are my profitability metrics missing or inaccurate?">
  Profitability metrics (COGS, Gross Profit, POAS) rely on cost data. If you haven't configured your product costs, Converge either estimates them using a fallback gross margin or can't calculate them at all.

  To fix this, go to **Data Management > [Expenses](/data-management/expenses)** and set your product costs. You can set individual costs per SKU or configure a fallback gross margin as a starting point.
</Accordion>

<Accordion title="What's the difference between ROAS and POAS?">
  * **ROAS** (Return on Ad Spend) = Revenue / Ad Spend
  * **POAS** (Profit on Ad Spend) = Gross Profit / Ad Spend

  ROAS tells you how much revenue each ad dollar generates. POAS tells you how much **profit** each ad dollar generates. A product with high ROAS but low margins might have a low POAS — meaning it's not actually profitable to advertise.
</Accordion>

<Accordion title="How is the Products Report different from the Attribution Report?">
  The **Attribution Report** shows performance by channel, campaign, ad set, or ad. The **Products Report** shows performance by individual product, making it ideal for:

  * Identifying your most (and least) profitable products
  * Understanding which products drive the most ad-attributed revenue
  * Optimizing your product catalog based on real cost and profit data
  * Spotting products with high traffic but low conversion
</Accordion>


# Session attribution
Source: https://docs.runconverge.com/attribution/session-attribution

How does session attribution work in Converge?

Session attribution is how Converge determines where a visit to your site came from. The end result is a session that has been attributed at the following levels:

* **Channel group**: the broad type of traffic source (e.g., Paid Social, Organic Search, Email, Direct)
* **Channel**: the specific platform or source within a channel group (e.g., Google, Facebook)
* **Campaign**: the campaign the user clicked before landing on your site
* **Adset**: the adset within the campaign
* **Ad**: the specific ad they clicked

<Note>For a more general introduction into attribution in Converge, read [this](/attribution/introduction).</Note>

## Channel group and channel

Channel group and channel are the broadest source categories. It helps you see which traffic source of your marketing is performing best.

In a broad sense, Converge will classify the session into a channel group and channel based on the landing page URL, referrer, and certain click IDs or tracking parameters.
For example, a session with a landing page URL that contains a `gclid` parameter will be classified with a channel group of Paid Search and a channel of Google.

<Note>
  For more details on how Converge classifies sessions into channel groups and channels, read [this](/attribution/channel-classification).
</Note>

### Events without sessions

Sometimes Converge receives a server-side event that can't be matched to a web session. For example, if a user completes a purchase and your store sends a `Placed Order` event from your server, but the user's web session was not tracked because an ad blocker was used.

In that case, Converge still tries to attribute the event to a channel:

1. If available, use metadata from the event itself. (e.g. `Recurring subscriptions`, `Shopify`)
2. If nothing else is available, fall back to `(no value)`.

## Campaign, Adset, Ad

Below the channel level, Converge will try to attribute a session to a specific campaign, ad set, or ad the user clicked on before visiting your website.

To attribute a session to a campaign, Converge follows this process:

1. Look for **cvg\_cid** or **cvg\_adid** in the landing page url. (containing the ID from the campaign and ad clicked on by the user)
2. Look for **utm\_campaign** in the landing page url.

If Converge can't find any of these values, the sessions won't be attributed to a campaign, ad set, or ad and will be shown as **(No campaign name)**, **(No ad set name)**, or **(No ad)** respectively.

<Note>Converge relies on <OutboundLink /> and <OutboundLink /> to correctly attribute a session to a campaign, ad set, or ad.</Note>


# Tracking parameters
Source: https://docs.runconverge.com/attribution/tracking-parameters

Set up your tracking parameters for first-party Converge attribution

This page combines all of the tracking parameters you will need to set up for Converge's first-party attribution to work correctly.

<Note> This is a general guide. For detailed, **platform-specific** instructions, click the **Link** in the table below.</Note>

|                      | Channel                      | Type        | Instructions                                                                           | Example                                                           |
| -------------------- | ---------------------------- | ----------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| <AppLovinIcon />     | **AppLovin**                 | Mobile Ads  | [Link](/ad-platforms/integrations/applovin#set-up-your-converge-tracking-parameters)   | `cvg_source=axon&cvg_adid=456&cvg_cid=123`                        |
| <AWINIcon />         | **AWIN**                     | Affiliate   | <OutboundLink />                                                                       | `utm_source=awin&utm_medium=affiliate&utm_campaign=123`           |
| <CriteoIcon />       | **Criteo**                   | Native      | [Link](/ad-platforms/integrations/criteo#set-up-your-converge-tracking-parameters)     | `cvg_source=criteo&cvg_cid=123&cvg_adid=456`                      |
| <GoogleAdsIcon />    | **Google Ads**               | Paid Search | [Link](/ad-platforms/integrations/google-ads#set-up-your-converge-tracking-parameters) | `cvg_source=google&cvg_cid=123&cvg_adid=456`                      |
| <ImpactIcon />       | **impact.com**               | Affiliate   | [Link](/ad-platforms/integrations/impact#set-up-your-converge-tracking-parameters)     | `cvg_source=impact&cvg_cid=123&cvg_adid=456::789`                 |
| <KlaviyoIcon />      | **Klaviyo**                  | Email       | [Link](/ad-platforms/integrations/klaviyo#set-up-your-tracking-parameters)             | `cvg_source=klaviyo&cvg_adid=01K6JNV2W892QG11ZG7ECHXG8H`          |
| <FacebookIcon />     | **Meta (Facebook)**          | Paid Social | [Link](/ad-platforms/integrations/facebook#set-up-your-converge-tracking-parameters)   | `cvg_source=facebook&cvg_cid=123&cvg_adid=456`                    |
| <MicrosoftAdsIcon /> | **Microsoft Ads (Bing Ads)** | Paid Search | [Link](/ad-platforms/integrations/bing#set-up-your-converge-tracking-parameters)       | `cvg_source=bing&cvg_cid=123&cvg_adid=456`                        |
| <OutbrainIcon />     | **Outbrain**                 | Native      | [Link](/ad-platforms/integrations/outbrain#set-up-your-converge-tracking-parameters)   | `cvg_source=outbrain&cvg_cid=123&cvg_adid=456&outbraincid=xyz`    |
| <PinterestAdsIcon /> | **Pinterest Ads**            | Paid Social | [Link](/ad-platforms/integrations/pinterest#set-up-your-converge-tracking-parameters)  | `cvg_source=pinterest&cvg_cid=123&cvg_adid=456`                   |
| <PostscriptIcon />   | **Postscript**               | SMS         | <OutboundLink />                                                                       | `utm_source=postscript&utm_medium=sms&utm_campaign=summer`        |
| <RedditIcon />       | **Reddit**                   | Paid Social | [Link](/ad-platforms/integrations/reddit#set-up-your-converge-tracking-parameters)     | `cvg_source=reddit&cvg_cid=123&cvg_adid=456`                      |
| <SnapchatAdsIcon />  | **Snapchat Ads**             | Paid Social | [Link](/ad-platforms/integrations/snapchat#set-up-your-converge-tracking-parameters)   | `cvg_source=snapchat&cvg_cid=123&cvg_adid=456`                    |
| <TaboolaIcon />      | **Taboola**                  | Native      | [Link](/ad-platforms/integrations/taboola#set-up-your-converge-tracking-parameters)    | `cvg_source=taboola&cvg_cid=123&cvg_adid=456&tblcid=x`            |
| <TikTokAdsIcon />    | **TikTok Ads**               | Paid Social | [Link](/ad-platforms/integrations/tiktok#set-up-your-converge-tracking-parameters)     | `cvg_source=tiktok&cvg_cid=123&cvg_adid=456`                      |
|                      | **Attentive**                | SMS         | <OutboundLink />                                                                       | `utm_source=attentive&utm_medium=sms&utm_campaign=123`            |
|                      | **Influencer Marketing**     | Influencer  | [Link](/guides/tracking-influencer-campaigns)                                          | `utm_source=instagram&utm_medium=influencer&utm_campaign=JohnDoe` |


# Changelog
Source: https://docs.runconverge.com/changelog

An overview of changes in Converge.

<Update label="2026-05-08">
  ## Routines

  Schedule an AI agent powered by the Converge MCP to post analytics straight to Slack or email. Daily revenue snapshots, weekly conversion deep-dives, anything you'd otherwise pull by hand.

  Each routine runs a prompt on a recurring basis and delivers the result to your channel or inbox, using live data from your workspace every time.

  [Learn more](/mcp/routines) or [set one up](https://app.runconverge.com/-/routines)

  <CloudinaryVideo />
</Update>

<Update label="2026-04-15">
  ## Converge MCP

  Ask your AI assistant questions about your marketing data. No dashboards, no exports, just plain language.

  The Converge MCP server connects to Claude, ChatGPT, or any MCP-compatible client and gives it read access to your analytics data. Compare campaigns, break down ROAS by ad, or check channel performance without leaving the chat.

  Set it up in under a minute: point your AI assistant to `https://app.runconverge.com/api/mcp`, sign in with Google, and start asking.

  [Learn more](/mcp/overview)

  <Frame>
    <img alt="Chat with Converge data" />
  </Frame>
</Update>

<Update label="2026-02-25">
  ## Product analytics

  See which products are bringing in the most revenue and which channels are generating their sales in the new Product report.

  [Find it here](https://app.runconverge.com/-/attribution/products)

  <CloudinaryVideo />
</Update>

<Update label="2026-02-12">
  ## Views in Overview

  You can now create Views in the Overview report to save customized versions of the report.

  Use it to view results per country or focus on specific metrics.

  <CloudinaryVideo />
</Update>

<Update label="2026-02-03">
  ## Cohort report

  View how your customer lifetime value grows month over month with the Cohort report.

  <CloudinaryVideo />
</Update>

<Update label="2026-01-29">
  ## New Landing pages report

  The Landing pages report received an upgrade.

  Use it to see how your landing pages are performing.

  <CloudinaryVideo />
</Update>

<Update label="2026-01-20">
  ## Ad filters

  Filter the Attribution report by ad status, ad creation date, or ad landing page.

  Use it to narrow down the ads that need your attention.

  <CloudinaryVideo />
</Update>

<Update label="2026-01-15">
  ## Action menu

  Apply quick actions in the Attribution report by using the Action menu.

  <CloudinaryVideo />
</Update>

<Update label="2026-01-09">
  ## Attribution update

  You can now change the attribution window and attribution mode on the fly.

  <CloudinaryVideo />
</Update>

<Update label="2026-01-05">
  ## Ad details

  View your Meta ads details directly in Converge.

  No more switching between Meta and Converge to add context to the results you're seeing.

  <CloudinaryVideo />
</Update>

<Update label="2025-12-30">
  ## Store Dimensions

  Model your real business structure in Converge with custom dimensions like brand, region, or channel.

  Then report marketing performance across them to clearly see how Brand 1 actually performs vs Brand 2.

  [Learn more](/data-management/store-dimensions)

  <CloudinaryVideo />
</Update>

<Update label="2025-12-10">
  ## Charting in the attribution table

  Turn any set of attribution table rows and metrics into a trend chart.
  See at a glance whether a "losing" ad is just having a bad day - or actually fatiguing.

  [Try it out](https://app.runconverge.com/-/attribution/channels)

  <CloudinaryVideo />
</Update>

<Update label="2025-11-21">
  ## Pacing Product

  Analyze your acquisition metrics and spend pacing over time to spot trends and outliers in the new Pacing tab.

  [Learn more](/attribution/pacing) or [Try it out](https://app.runconverge.com/-/attribution/pacing)

  <CloudinaryVideo />
</Update>

<Update label="2025-11-21">
  ## New visitor metrics

  Analyze whether your ads are bringing in new or recurring visitors with our new visitor metrics.
  New visitor metrics are available in the [Overview](/attribution/overview), [Attribution](/attribution/channels)-table and in [Insights](/insights-dashboards/overview)

  <CloudinaryVideo />
</Update>

<Update label="2025-11-19">
  ## Google Sheets Import

  Import and report on all of your out-of-platform spend such as influencers, newsletters, podcasts, etc. using our new Google Sheets integration.

  [Learn more](/ad-platforms/integrations/google-sheets)

  <CloudinaryVideo />
</Update>

<Update label="2025-10-29">
  ## Channel Groups

  Get a high-level overview of how the different types of channels are performing with Channel Groups in the Attribution report.

  [Learn more](/attribution/channels)

  <CloudinaryVideo />
</Update>

<Update label="2025-10-23">
  ## Klaviyo marketing source

  You can now connect Klaviyo directly to Converge. Import metrics such as emails sent, opened, clicked, and converted to enrich your email performance reporting.

  [Learn more](/ad-platforms/integrations/klaviyo)

  <Frame>
    <img alt="Klaviyo marketing source" />
  </Frame>
</Update>

<Update label="2025-10-14">
  ## Add views in the Attribution

  You can now save your Attribution reports as Views, giving you instant access to your most customized reporting setups.

  [Learn more](/attribution/channels)

  <CloudinaryVideo />
</Update>

<Update label="2025-09-08">
  ## Share Dashboards & Insights

  Now you can generate a public link to a Dashboard or Insight and share it directly with agencies, partners, or teams.

  [Learn more](/insights-dashboards/export)

  <CloudinaryVideo />
</Update>

<Update label="2025-08-07">
  ## Pixel Monitor

  Pixel Monitors allow you to automatically check your tracking pixel across all your sites and alert you if it's removed in an update.

  [Learn more](/sources/monitoring#pixel-monitor)

  <CloudinaryVideo />
</Update>

<Update label="2025-07-18">
  ## Tracking Parameter Check

  Check if all your Converge tracking parameters have been set up correctly.

  Optimizing your tracking parameters will enhance your reports in Converge.

  <CloudinaryVideo />
</Update>

<Update label="2025-06-04">
  ## Data Warehouse Sync

  Syncing the Attribution report to your data warehouse is now in beta.

  Export all your results, with all attribution models, to Google BigQuery to use in your favorite BI tool.

  <CloudinaryVideo />
</Update>

<Update label="2025-05-27">
  ## Email invites

  Invite new members to your workspace by email.

  <Frame>
    <img alt="Email invites" />
  </Frame>
</Update>

<Update label="2025-05-24">
  ## Audit Logs

  Keep track of which changes are made in your workspace with the new Audit Logs.

  <CloudinaryVideo />
</Update>

<Update label="2025-05-20">
  ## Server-Side Only event mapping

  Only forward your events server-side, with the Server-Side Only event mapping for the Facebook and TikTok destinations.

  <Frame>
    <img alt="Server-Side Only - Event Mapping" />
  </Frame>
</Update>

<Update label="2025-05-16">
  ## Client-side filters available in Destination

  You can now add filters for your client-side events to every Destination.

  <CloudinaryVideo />
</Update>

<Update label="2025-05-02">
  ## Session-based metrics added to reports

  You can now add the following session-based metrics to your reports:

  * **Bounce rate**: Percentage of sessions that resulted in a bounce.
  * **Session duration**: Average session duration.
  * **Revenue per session**: Average revenue generated per session.

  Available in the Attribution report and Insights.

  <CloudinaryVideo />
</Update>

<Update label="2025-04-11">
  ## User access control

  Control what your users can access in your workspace by giving them any of the following roles:

  * **Admin**: Full access to all features and settings.
  * **Editor**: Access to all features and settings, except removing members.
  * **Analyst**: Can only create insights and dashboards.
  * **Viewer**: Read-only to features and settings without the ability to make changes.

  You can change the role for each member on the **Members** page under **Settings**.

  <CloudinaryVideo />
</Update>

<Update label="2025-03-17">
  ## Custom event mapping for Destinations

  Take control of your destination mappings with Custom Mappings.

  * Use the **Default mapping** from Converge.
  * Use a **Custom mapping** to add, edit, or remove mappings.
  * Select a **forwarding mode** (client and/or server) for each of your events.

  Available for all destinations. (if possible)

  <CloudinaryVideo />
</Update>


# Data quality
Source: https://docs.runconverge.com/data-management/data-quality



The Data quality page helps you monitor the quality of data sent to Converge. It flags issues that might impact your reports or configured destinations.

The Data quality page consists of two main sections:

* **Events overview** *(left)*: Displays all tracked events within the selected time period.
* **Event details** *(right)*: Shows detailed warnings and information for a selected event.

<Frame>
  <img alt="Data quality" />
</Frame>

<Note>The Data quality report only covers data from the past 3 months.</Note>

***

## Events overview

The **Events overview** lists all events tracked from any of your event sources within the selected time period. For each event, you’ll see:

1. **Tracking method**: How the event was tracked. Through a browser or server-side source or both.
2. **Event name**: The name of the event as it was sent to Converge.
3. **Frequency**: The average amount the event has been tracked each hour.
4. **Property warnings**: A warning indicating issues with the event properties that could affect report accuracy or how events are sent to destinations.
5. **Stitching percentage**: Percentage of server-side events that have been successfully stitched to web sessions. Read more about stitching percentage and why it matters [here](/data-management/data-quality#stitching).
6. **Deduplication percentage**: The percentage of deduplicated events if sent through browser and server-side sources both. Read more about deduplication percentage and why it matters [here](/data-management/data-quality#deduplication).

<Frame>
  <img alt="Data quality - Events overview" />
</Frame>

***

## Event details

After selecting an event in the Events overview, you'll see the details about it in the right pane. At the top of this section, you'll find the following information:

* **Tracking method**: The method used to track the events. This can be a browser or server source, or both.
* **Sales channel**: Which <OutboundLink /> are used for the tracked events.

On the top right, you'll find a button that sends you to the filtered event logs showing the individual events that were tracked in Converge.

<Frame>
  <img alt="Data quality - Event details" />
</Frame>

### Overview

In the Overview tab you'll find the following details:

* **Events tracked**: A graph showing how many events you have tracked per day.
* **Sources**: A tab showing the sources through which the events were tracked.
* **Destinations**: A tab showing the destinations which received the events.

<Frame>
  <img alt="Data quality - Event details - Overview" />
</Frame>

### Properties

In the properties tab, you'll see all the properties sent with the event at the profile, session, and event levels.

If there are any issues with the properties, a warning will appear. Clicking on the warning provides an overview of the detected issues and how often they occurred within the selected time period.

By clicking on the arrow in the top right of each warning you will be sent to the filtered event logs showing the
individual events which have incorrect values.

<Frame>
  <img alt="Data quality - Event details - Properties" />
</Frame>

### Stitching

To attribute server-side tracked events and enrich them with browser data, Converge must link these events to a corresponding web session tracked via a browser-based source, such as the Converge JS tracking pixel.

<Warning>
  We consider a stitching rate of **95%+** healthy. If you have a lower rate, attribution and destinations might not behave as expected.
</Warning>

<Note>
  You can find more information about how Converge uses aliases to stitch browser and server events together in
  our [Aliases](/sources/concepts/aliases) documentation.
</Note>

In the stitching tab you will find:

* **Events per day**: A graph displaying the stitching rate per day.
* **Stitching metrics**: A table showing the number of server events received, unstitched events, and the stitching rate.
* **Unstitched events**: A detailed view of individual unstitched events, including the aliases sent to Converge, event properties, and a\
  link to a filtered event log for reviewing the specific event.
* **Delayed events**: A list of delayed aliases, showing server events that Converge couldn’t stitch at the time of receipt but stitched later.\
  These events were already sent to your destinations with potentially limited data but will be properly attributed in Converge reporting.

<Frame>
  <img alt="Data quality - Event details - Stitching" />
</Frame>

### Deduplication

If you are sending an event through both a server-side and browser-side event source, Converge will need to deduplicate
these events to avoid duplicate tracking in Converge or your destinations.

<Warning>
  We consider a deduplication rate of **95%+** healthy. If you have a lower rate, your events might not be deduplicated properly and will cause duplicate tracking in your destinations.
</Warning>

<Note>
  You can find more information about how Converge uses event IDs to deduplicate browser and server events in
  our [Deduplication](/sources/concepts/deduplication) documentation.
</Note>

In the Deduplication tab you will find the following information:

* **Events tracked**: A graph showing how many events you have tracked through server and browser per day.
* **Deduplication metrics**: A table showing the overlap of server and browser events per deduplication key.
* **Missing event IDs**: A list of all the events which are either missing a matching server-side or browser-side event.

By clicking **View event id** you will be sent to the filtered Event logs showing the specific event.

<Frame>
  <img alt="Data quality - Event details - Deduplication" />
</Frame>


# Event logs
Source: https://docs.runconverge.com/data-management/event-logs



The Event Logs show you a detailed view of each event that was tracked and possibly forwarded to any of
your destinations. You can view historical data or watch a live feed of events coming in from your event sources.

<Note>The Event Logs only covers data from the past 3 months.</Note>

## Overview

In the Event Logs you'll find the following sections:

1. **Date Picker**: A date picker to select a date range in which you want to see your events.
2. **Filters**: Filters you can use to view a specific subset of your events.
3. **Live polling**: A button to start live polling new events directly when they come in.
4. **Events Overview**: An overview of all the events matching your selected date range and filters.

<Frame>
  <img alt="pick filters" />
</Frame>

***

## Log types

The Event Logs showcase different log types:

* **Tracked**: the events which are tracked in Converge.
* **Browser Passthrough**: Browser-side events that are only used for client-side forwarding and don't get tracked.
* **Destination**: Forwarded events sent to your destinations based on Tracked and Browser Passthrough events.
* **Property Spec Warning**: Events with warnings for one or more properties sent with the event.

By default, when accessing the Event Logs from the menu, the Tracked and Browser Passthrough logs are pre-filtered.

***

## Filters

Use filters to view a specific subset of events. Combine multiple filters to show only the events you need.\
Click the **Filters** button to access the following options:

* **Log type**: Filter by log types as described [here](#log-types).
* **Sales channel types**: Filter by the [sales channel](/sources/concepts/sales-channels) of your events.
* **Event name**: Filter by event names.
* **Property spec warnings**: Filter by property warnings in your events.
* **Destinations**: Filter by the destinations where an event was forwarded.
* **Datasources**: Filter by server-side event sources.
* **Pixels**: Filter by browser-side event sources.
* **Event ID**: Filter by unique event IDs.

After selecting one or more filters, the active filters appear next to the **Filters** button.\
Click a filter to change its values or remove it. To remove all filters, click **Clear all filters**.

<Frame>
  <img alt="Event Logs - Filters" />
</Frame>

***

## Event log lines

In the Event Logs, the log shows you different kinds of information based on the log type.

<AccordionGroup>
  <Accordion title="Tracked">
    For each Tracked event you will see the following information in the overview:

    <Frame>
      <img alt="pick filters" />
    </Frame>

    * **Event type**: The type of event: Tracked.
    * **Event time**: The time the event was received.
    * **Event name**: The name of the event.
    * **Event ID**: The unique Event ID.
    * **Sales channel**: The <OutboundLink /> of the event.
    * **Event source**: The source of the event.
  </Accordion>

  <Accordion title="Browser Passthrough">
    For each Browser Passthrough event you will see the following information in the overview:

    <Frame>
      <img alt="pick filters" />
    </Frame>

    * **Event type**: The type of event: Browser Passthrough.
    * **Event time**: The time the event was received.
    * **Event name**: The name of the event.
    * **Event ID**: The unique Event ID.
    * **Sales channel**: The <OutboundLink /> of the event.
    * **Event source**: The source of the event.
  </Accordion>

  <Accordion title="Destination">
    For each Destination event you will see the following information in the overview:

    <Frame>
      <img alt="pick filters" />
    </Frame>

    * **Event type**: The type of event: Destination.
    * **Event time**: The time the event was received.
    * **Event name**: The name of the event triggering the forward.
    * **Event ID**: The unique Event ID.
    * **Event source**: The source of the event.
    * **Event destination**: The destination of the event.
    * **Forwarding method**: The forwarding method of the event, either browser or server.
    * **Forwarding status**: The status of the forwarded event.
  </Accordion>

  <Accordion title="Property Spec Warning">
    For each Property Spec Warning event you will see the following information in the overview:

    <Frame>
      <img alt="pick filters" />
    </Frame>

    * **Event type**: The type of event: Property Spec Warning.
    * **Event time**: The time the event was received.
    * **Event name**: The name of the event.
    * **Event ID**: The unique Event ID.
    * **Sales channel**: The sales channel of the event.
    * **Event source**: The source of the event.
    * **Warning**: The type of warning.
  </Accordion>
</AccordionGroup>

***

## Log details

After clicking on a specific log entry, the log details are shown in the right pane of the Event Logs. For each log you'll find the following:

* **Log type**: The log type the event is from.
* **Event name**: The name of the event.
* **Inserted At**: The date and time the event was received by Converge.
* **Timestamp**: The date and time the event was created according to its source.
* **Destination**: The destination the event was forwarded to. (Destination log type only)
* **Event ID**: The unique event ID.
* **Pixel**: The browser-side event source of the event.
* **Datasource**: The server-side event source of the event.
* **Property warnings**: Warnings about issues with specific properties.
* **Properties**: All the event properties after processing by Converge.

You can view all raw properties of the event or use the tabs to view specific sections like the aliases, profile\_properties, and event properties. You can expand the **Properties** section by clicking the <img /> icon on the right.

<Frame>
  <img alt="Event Logs - Log Details" />
</Frame>


# Costs & Expenses
Source: https://docs.runconverge.com/data-management/expenses



Configure your costs in the **Costs & Expenses** module so Converge can calculate profitability metrics. Without cost data, Converge tracks revenue but can't tell you how much is actually profit. Each tab covers a different cost type, and a final **Fallback costs** tab handles any gaps.

Converge supports three cost types:

* [**Product costs (COGS)**](#product-costs-cogs): the cost of goods sold per product variant
* [**Transaction costs**](#transaction-costs): payment processing fees per order
* [**Shipping costs**](#shipping-costs): inbound fulfillment and delivery costs per order

The example report below shows a step-by-step breakdown of how revenue is reduced by discounts, costs, and expenses to arrive at gross, contribution, and net profit.

<Frame>
  <img alt="Profit waterfall" />
</Frame>

## Product costs (COGS)

The [**Product costs**](https://app.runconverge.com/-/data-management/expenses) tab shows every product variant (with SKU) per event source, alongside its cost of goods sold (COGS) data. Use this tab to review synced unit costs (from your e-commerce platform), spot gaps, and set manual overrides.

<Frame>
  <img alt="Product costs" />
</Frame>

| Column            | Description                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------- |
| **Status**        | The mapping status of the product variant (see below)                                     |
| **Source**        | The source that ingested the order                                                        |
| **Product**       | The product name                                                                          |
| **Variant**       | The variant name                                                                          |
| **Orders**        | The number of orders that include this variant                                            |
| **SKU**           | The product variant's SKU identifier                                                      |
| **Unit Price**    | The selling price of the variant                                                          |
| **Synced COGS**   | The (in-platform) cost of goods sold synced from your e-commerce platform (e.g. Shopify)  |
| **COGS Override** | A manual cost override you set in Converge. This takes priority over the in-platform cost |

<Note>
  Automatic COGS syncing is currently supported for **Shopify**,
  **BigCommerce**, and **Magento**. You can monitor the sync status in the
  **Products** tab of the corresponding event source. If your e-commerce
  platform is not listed but supports cost-of-goods data, reach out to the
  Converge team to request support. In the meantime, you can use cost overrides
  or a CSV upload to configure costs manually.
</Note>

Each SKU has a data status indicator:

* <Icon icon="circle-exclamation" /> = No
  COGS data exists for this variant. The COGS value will be estimated using the
  fallback gross margin.
* <Icon icon="circle-check" /> = COGS data is
  available for this variant (either an override, an in-platform cost, or both).

The **COGS coverage** badge in the top-right corner of the table shows what percentage of orders have a COGS mapping. It reflects your current view, including the selected date range and any active filters. The badge is color-coded:

* **Green**: 85% or more of orders are covered
* **Yellow**: between 50% and 85%
* **Red**: below 50%

### Product cost hierarchy

Converge determines the cost for each variant using a three-tier hierarchy. The first available value wins:

1. **Cost override** (highest priority): If you've set a manual override in the COGS Override column, Converge uses that value.
2. **In-platform cost**: If no override exists, Converge uses the cost price synced from your e-commerce platform (shown in the Unit COGS column).
3. **Fallback gross margin** (lowest priority): If neither of the above is available, Converge estimates the cost using the gross margin percentage configured in the [Fallback costs](https://app.runconverge.com/-/data-management/expenses/fallback-costs) tab.

### Setting a (single) manual override

1. Find the product variant in the table (use the search bar to filter by SKU, product name, or variant name).
2. Click **Set cost...** in the COGS Override column for that variant.
3. Enter the cost value, click **Save**.

The override takes effect shortly after saving and applies to all future cost and profit calculations for that variant.

### Bulk override using a CSV upload

To set or update COGS for many product variants at once, use the **Upload CSV** button in the top-right corner of the table.

<Tip>
  A common workflow is: filter the table to only show variants with missing
  costs, export the result, fill in the COGS values in the exported file, and
  upload it back into Converge.
</Tip>

Your CSV file should have the following columns:

| Column          | Required | Description                                                                |
| --------------- | -------- | -------------------------------------------------------------------------- |
| `sku`           | Yes      | The product variant's SKU                                                  |
| `datasource_id` | Yes      | The numeric ID of the event source (find it in **Event Sources**)          |
| `cogs`          | Yes      | The cost of goods sold for one unit (non-negative number)                  |
| `currency`      | No       | ISO 4217 currency code (e.g. `USD`, `EUR`). Defaults to workspace currency |

To upload a CSV file:

1. Click **Upload CSV** in the top-right corner of the Product costs table.
2. Drag and drop a `.csv` file into the upload area, or click to browse for one.
3. Review the preview table (it shows the first 10 valid rows), and check for any validation warnings.
4. Click **Upload** to apply the overrides. Only the valid rows are saved.

<Note>
  If your CSV contains duplicate SKU + datasource ID combinations, the last
  occurrence wins. After upload, a toast notification shows how many SKUs were
  updated and how many duplicates were detected.
</Note>

### Fallback gross margin

In the [**Fallback costs**](https://app.runconverge.com/-/data-management/expenses/fallback-costs) tab, you can configure a default **gross margin percentage**. Converge uses this to estimate COGS for any product variant without a specific cost mapping. Always set this field.

Gross margin is the percentage of a product's selling price that's profit after subtracting the cost of goods. For example, a product selling for **\$100** with a gross margin of **60%** has:

* **\$60** in gross profit
* **\$40** in estimated cost (COGS)

The fallback gross margin applies the same margin to every product. For more accurate profitability data, set individual cost prices in the **Product costs** tab, especially for high-volume or high-value items.

## Transaction costs

Transaction costs represent payment processing fees. Converge subtracts these from revenue when calculating contribution profit. The [**Transaction costs**](https://app.runconverge.com/-/data-management/expenses/transaction-costs) tab shows every payment method per event source, alongside its transaction cost configuration. Use this tab to review synced fees, spot gaps, and set manual overrides. Orders without a payment method or synced fees default to the fallback transaction costs.

<Frame>
  <img alt="Transaction costs" />
</Frame>

| Column                      | Description                                                                    |
| --------------------------- | ------------------------------------------------------------------------------ |
| **Status**                  | Whether the payment method has a cost mapping (see below)                      |
| **Source**                  | The event source that ingested the order                                       |
| **Payment method**          | The payment method name (e.g. "Stripe", "PayPal")                              |
| **Total orders**            | The number of orders using this payment method from this source                |
| **Orders with synced fees** | How many of those orders have actual transaction fees synced from the platform |
| **Gateway rate**            | A percentage rate charged per transaction for this payment method (editable)   |
| **Gateway flat fee**        | A fixed fee charged per transaction for this payment method (editable)         |

Each payment method has a data status indicator:

* <Icon icon="circle-check" /> = The payment
  method has a cost mapping configured, or all orders have synced fees.
* <Icon icon="circle-exclamation" /> = No
  mapping exists and not all orders have synced fees. The missing transaction
  cost will be estimated using the fallback processing fees.

The **Transaction cost coverage** badge in the top-right corner of the table shows what percentage of orders have a transaction cost mapping. It reflects your current view, including the selected date range and any active filters. The badge is color-coded using similar thresholds as the COGS coverage.

### Transaction cost hierarchy

Converge determines the transaction cost for each order using a three-tier hierarchy. The first available value wins:

1. **Synced transaction fees** (highest priority): If your e-commerce platform provides actual transaction fees per order, Converge uses those. Currently, only **Shopify** syncs transaction fees (for Shopify Payments).
2. **Payment method override**: If no synced fees exist, Converge uses the per-payment-method gateway rate and flat fee configured in the [Transaction costs](https://app.runconverge.com/-/data-management/expenses/transaction-costs) tab.
3. **Fallback processing fees** (lowest priority): If neither of the above is available, Converge estimates the cost using the processing rate and flat fee configured in the [Fallback costs](https://app.runconverge.com/-/data-management/expenses/fallback-costs) tab.

### Setting a manual override

1. Find the payment method in the table (use the search bar to filter by payment method name or source).
2. Click the **Gateway rate** or **Gateway flat fee** cell for that payment method.
3. Enter the value and click **Save**.

The override takes effect shortly after saving and applies to all future transaction cost calculations for orders using that payment method (where synced fees are not available).

### Fallback transaction costs

In the [**Fallback costs**](https://app.runconverge.com/-/data-management/expenses/fallback-costs) tab, configure fallback transaction costs. These are used when neither synced fees nor a payment method override are available. Any field that has not been configured shows an amber warning indicator.

Depending on your payment provider, you may need one or both settings:

* **Payment processing rate**: A percentage of the order total charged per transaction.
* **Payment processing flat fee**: A fixed amount charged per order. You can select the currency for this fee separately from your workspace currency.

Most providers combine both (e.g. **2.9% + \$0.30** per transaction), but some only charge a flat fee or only a percentage. Configure whichever applies to your setup. Converge uses the formula: `order total × rate + flat fee`.

## Shipping costs

Shipping costs represent inbound fulfillment and delivery expenses. Converge subtracts these from revenue alongside COGS and transaction costs when calculating contribution profit.

<Note>
  Converge does not currently sync shipping costs from your e-commerce platform,
  and there is no dedicated Shipping costs tab. You can configure a
  workspace-level estimate in the [**Fallback
  costs**](https://app.runconverge.com/-/data-management/expenses/fallback-costs)
  tab. For per-order shipping cost configuration, please contact support.
</Note>

### Fallback shipping costs

In the [**Fallback costs**](https://app.runconverge.com/-/data-management/expenses/fallback-costs) tab, you can configure how Converge estimates shipping costs.

Two modes are available, choose whichever best matches your business:

* **Use customer shipping charges**: Sets your shipping cost equal to what customers paid for shipping on each order. This works well when your shipping charges closely reflect your actual fulfillment costs.
* **Flat fee per order**: A fixed amount representing the average cost you pay to ship one order. You can set the amount and currency independently. This is useful when your shipping costs are relatively uniform regardless of what customers are charged.


# Store dimensions
Source: https://docs.runconverge.com/data-management/store-dimensions



Use **store dimensions** to understand marketing performance across **countries**, **brands**, and **sales channels**.

A store dimension is a reusable way to group your website and marketing data and use those groups as filters in all analytics.

## Example

If your brand operates in multiple regions (for example the US, Canada, and Europe), you can create a **Region** store dimension with one group per region: **United States**, **Canada**, and **Europe**.

<Frame>
  <img alt="store-dimensions-example" />
</Frame>

You can then filter any report in Converge by this Region dimension.

<Frame>
  <img alt="store-dimensions-example" />
</Frame>

In the Overview report above, you can see all blended metrics per region.

## Adding a store dimension

1. Go to the [**Store dimensions** tab](https://app.runconverge.com/-/data-management/store-dimensions) in the main menu and click **Create store dimension**.
2. Name your dimension, e.g. **Region** or **Brand**.
3. Add the first group and give it a name, e.g. **United States**.
4. Select which **sources** contain data for this group. Optionally add **filters** to further narrow down the data. See [Choosing sources and filters](#choosing-sources-and-filters).
5. Click **Add group** to create more groups. You can also duplicate an existing group using the icon next to it. Repeat steps 3 and 4 for each group.
6. Click **Save** to create the store dimension.

## Choosing sources and filters

The key decision is how you split your data into groups.

### Events and Marketing

To understand marketing performance for a store, you need **blended metrics** (CPA, ROAS, ...). This means you must identify both:

* **Events** - which website traffic and revenue belong to which store?\
  *For example, all traffic landing on `us.mybrand.com` or `mybrand.com/us`.*
* **Marketing** - which marketing spend drives traffic to which store?\
  *For example, all campaigns running in the United States, tagged with a `US | ...` naming convention.*

### Sources

The simplest way to split data is by **source**.

If each store already has separate websites and ad accounts, and these are set up as different sources in Converge, you can reference those sources directly in the store dimension groups.

### Filters

Splitting by source alone is not always enough.

If a single ad account or website serves multiple countries or brands, you must use **filters** to define which data belongs to each group.

<AccordionGroup>
  <Accordion title="Filtering marketing data">
    If a single marketing source serves multiple stores, you need to specify which spend drives traffic to which store.

    This requires differentiating your spend with a **naming convention** on the campaign, adset, or ad name.

    If you have this in place, add a **filter on the campaign, adset, or ad name** under the Marketing section of each group. For example: *Campaign name starts with `US | ...`*.

    Store dimensions cannot be used to break out spend for campaigns, adsets, or ads that run across multiple stores.
  </Accordion>

  <Accordion title="Filtering website data by landing URL">
    If your website has a subdomain or page per store, we recommend filtering **Events** by the **landing URL of the session**.

    For example:

    * Session properties > Landing URL > Contains `us.mybrand.com`
    * Session properties > Landing URL > Contains `mybrand.com/us`
  </Accordion>

  <Accordion title="Filtering website data by visitor location">
    If your website does not have a subdomain or page per store, we recommend filtering by the **country code of the session**.

    For example:

    * Session properties > Country Code > Equals `US`
    * Session properties > Country Code > Equals `CA`
  </Accordion>

  <Accordion title="Other filters">
    We **recommend using session properties for events**. This ensures the property is set for every session and stays consistent. Otherwise, session metrics such as conversion rate may not be correct.

    You can use other properties such as the shipping address, but then you cannot review session metrics such as conversion rate or new visitor %.
  </Accordion>
</AccordionGroup>

### Matching groups

For every event or marketing spend line, Converge assigns it to the **first** group in the dimension that matches it.

A group matches if for **any** of the **Event** or **Marketing** sections:

* its **sources** match, and
* **any** of its filters match.

This matching always follows the group order shown in the UI.

Anything that matches no group goes into an **Others** group.

## Common store dimensions

### Sales Channel

If you sell through multiple channels — for example a DTC website and Amazon — create a **Sales Channel** dimension to compare blended metrics across channels.

<Frame>
  <img alt="store-dimensions-sales-channel-name" />
</Frame>

Create one group per channel:

<AccordionGroup>
  <Accordion title="DTC" icon="shopify">
    Add all website sources (e.g. Shopify Backend, Shopify Web) under **Events** and all ad platform sources (e.g. Meta Ads, Google Ads, TikTok Ads) under **Marketing**.

    <Frame>
      <img alt="store-dimensions-sales-channel-dtc" />
    </Frame>
  </Accordion>

  <Accordion title="Amazon" icon="amazon">
    Add your Amazon Event Source under **Events** and your Amazon Ads Marketing Source under **Marketing**.

    <Frame>
      <img alt="store-dimensions-sales-channel-amazon" />
    </Frame>
  </Accordion>
</AccordionGroup>

## Analytics

Store dimensions become very powerful once you start using them across your analytics.

<AccordionGroup>
  <Accordion title="Overview">
    <Frame>
      <img alt="store-dimensions-example" />
    </Frame>
  </Accordion>

  <Accordion title="Pacing">
    <Frame>
      <img alt="store-dimensions-example" />
    </Frame>
  </Accordion>

  <Accordion title="Attribution">
    <Frame>
      <img alt="store-dimensions-example" />
    </Frame>
  </Accordion>

  <Accordion title="Landing pages">
    Store dimensions are currently not available for **Landing pages**. We will add support for this soon. Reach out to let us know if you are interested.
  </Accordion>

  <Accordion title="Insights">
    <Frame>
      <img alt="store-dimensions-example" />
    </Frame>
  </Accordion>

  <Accordion title="Dashboards">
    <Frame>
      <img alt="store-dimensions-example" />
    </Frame>
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="The Others group contains more data than I expect, why is that?">
    The Others group contains all data that was not matched to any group.

    * Confirm that all of your sources are assigned to at least one group.
    * Confirm that the filters you applied are available across both website and server-side events or marketing spend.
    * If you still see too much data in Others and you are correctly filtering on session properties, you may have many "unstitched" events that do not have any session properties. See our [Debugging stitching issues](/guides/debugging-stitching-issues) guide for more information.
  </Accordion>

  <Accordion title="I want to use the shipping address to split my data by country, why should I not do this?">
    The shipping address only lets you split **order data** by country, not the rest of your website data.

    As a result, all website data is added to the Others group, so you cannot review website analytics such as conversion rate or new visitor % per country.
  </Accordion>

  <Accordion title="Why should I use store dimensions if I already have campaigns set up per region or brand?">
    If you rely only on attribution models, you exclude traffic that is not directly attributed to a specific campaign.

    For example, you may have a large organic presence in a region or traffic leaking into direct. These should still be included when reviewing region or brand performance at an aggregated level.

    Instead of splitting the dimension by the session's source, split it by where the traffic lands. That way, you can review blended metrics across all sources.
  </Accordion>

  <Accordion title="What if my ads are targeting multiple regions?">
    It is not possible to use store dimensions in this case. Converge does not break out performance for an individual ad down to the region level.

    If reviewing blended marketing performance per region is critical, you should restructure your campaigns so that each campaign targets a single region and includes that region in the naming convention.
  </Accordion>
</AccordionGroup>


# BigQuery
Source: https://docs.runconverge.com/data-warehouse/integrations/bigquery

Setting up a destination with BigQuery

## Installation instructions

<Steps>
  <Step icon="table" title="1. Create service account in Google Cloud">
    1. Log into your Google Cloud console at <OutboundLink />

    2. Choose your relevant Google Cloud Project from the top bar. If you don't have a Google Cloud Project yet, you can create one following the instructions [here](https://developers.google.com/workspace/guides/create-project).

    3. In the sidebar menu, choose *IAM and admin* > *Service accounts*.
        
       <Frame>
         <img alt="bq-s-1" />
       </Frame>

    4. Click on **Create Service Account**.
        
       <Frame>
         <img alt="bq-s-2" />
       </Frame>

    5. Fill in service account name, e.g. `converge-bigq-account` and click on **Create and continue**.
        

    <Frame>
      <img alt="bq-s-3" />
    </Frame>

    11. Under *Grant this service account access to the project*, choose the **BigQuery Data Owner** and **BigQuery Job User** scopes and click on **Done**.
         

    <Frame>
      <img alt="bq-s-4" />
    </Frame>

    12. Pick your newly created service account from the list of Service Accounts and choose **Manage keys**.
         

    <Frame>
      <img alt="bq-s-5" />
    </Frame>

    13. Click on **Add Key** and **Create new key**. In the popup choose **JSON** and click on **Create**. This will download a file that ends with `.json`.
         

    <Frame>
      <img alt="bq-s-6" />
    </Frame>
  </Step>

  <Step icon="bars-staggered" title="2. Send Converge Data to your BigQuery table">
    14. In the Converge sidebar, click on <IconText name="cloud-arrow-up" /> and then click **Connect data warehouse**.
    15. Select the **BigQuery** destination and click **Next**.
    16. Give your destination a **name** (e.g. BigQuery Data Warehouse) and click **Next**.
    17. Click the **Credentials** field and select the `.json` file containing your service account key created in step 13.
    18. Fill in the **Dataset ID** with the dataset ID from **Google Cloud**.
    19. Fill in the **Table ID** with the table ID you'd like to send data. This table should not exist in BigQuery yet as it will be updated by the destination.
    20. In *Advanced configuration*, you can optionally fill in the **Staging Table ID**, if you would like to use a different table name. By default, Converge will use the same table name as the **Table ID** but with a `_staging` suffix.
    21. Click **Next**.
    22. Fill in the **Start date** with a date in the past from which you'd like to send data. Click **Next**.
    23. Review any issues and click **Connect data warehouse**.

    Converge will now start sending data to your BigQuery table.
  </Step>
</Steps>

***

## Data sent to BigQuery

Converge will send attributed data to BigQuery aggregated by day and ad. The following columns are currently sent to BigQuery:

| Column name in BigQuery                         | Type     | Description                                                                                                      | Attribution model                                        |
| ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `date`                                          | `DATE`   | The date of the breakdown                                                                                        | N/A                                                      |
| `channel`                                       | `STRING` | The attributed channel                                                                                           | N/A                                                      |
| `campaign`                                      | `STRING` | The attributed campaign                                                                                          | N/A                                                      |
| `campaign_name`                                 | `STRING` | The name of the attributed campaign                                                                              | N/A                                                      |
| `adset`                                         | `STRING` | The attributed ad set                                                                                            | N/A                                                      |
| `adset_name`                                    | `STRING` | The name of the attributed ad set                                                                                | N/A                                                      |
| `ad`                                            | `STRING` | The attributed ad                                                                                                | N/A                                                      |
| `ad_name`                                       | `STRING` | The name of the attributed ad                                                                                    | N/A                                                      |
| `spend_sum`                                     | `FLOAT`  | The total spend for the day, as reported by the ad platform (if available for the channel)                       | N/A                                                      |
| `clicks_sum`                                    | `FLOAT`  | The total clicks for the day, as reported by the ad platform (if available for the channel)                      | N/A                                                      |
| `impressions_sum`                               | `FLOAT`  | The total impressions for the day, as reported by the ad platform (if available for the channel)                 | N/A                                                      |
| `purchase_conversions_sum`                      | `FLOAT`  | The total purchase conversions for the day, as reported by the ad platform (if available for the channel)        | N/A                                                      |
| `purchase_conversions_revenue`                  | `FLOAT`  | The total purchase conversion revenue for the day, as reported by the ad platform (if available for the channel) | N/A                                                      |
| `sessions_direct_session`                       | `FLOAT`  | The total number of sessions attributed by Converge                                                              | N/A                                                      |
| `placed_order_events_direct_session`            | `FLOAT`  | The total number of Placed Order events attributed by Converge                                                   | [Direct](/attribution/models#direct)                     |
| `placed_order_revenue_sum_direct_session`       | `FLOAT`  | The total revenue for Placed Order events attributed by Converge                                                 | [Direct](/attribution/models#direct)                     |
| `new_customer_order_events_direct_session`      | `FLOAT`  | The total number of New Customer Order events attributed by Converge                                             | [Direct](/attribution/models#direct)                     |
| `new_customer_order_revenue_sum_direct_session` | `FLOAT`  | The total revenue for New Customer Order events attributed by Converge                                           | [Direct](/attribution/models#direct)                     |
| `placed_order_events_first_touch`               | `FLOAT`  | The total number of Placed Order events attributed by Converge                                                   | [First Touch](/attribution/models#first-touch)           |
| `placed_order_revenue_sum_first_touch`          | `FLOAT`  | The total revenue for Placed Order events attributed by Converge                                                 | [First Touch](/attribution/models#first-touch)           |
| `new_customer_order_events_first_touch`         | `FLOAT`  | The total number of New Customer Order events attributed by Converge                                             | [First Touch](/attribution/models#first-touch)           |
| `new_customer_order_revenue_sum_first_touch`    | `FLOAT`  | The total revenue for New Customer Order events attributed by Converge                                           | [First Touch](/attribution/models#first-touch)           |
| `placed_order_events_inv_j_shaped`              | `FLOAT`  | The total number of Placed Order events attributed by Converge                                                   | [Inverse J Shaped](/attribution/models#inverse-j-shaped) |
| `placed_order_revenue_sum_inv_j_shaped`         | `FLOAT`  | The total revenue for Placed Order events attributed by Converge                                                 | [Inverse J Shaped](/attribution/models#inverse-j-shaped) |
| `new_customer_order_events_inv_j_shaped`        | `FLOAT`  | The total number of New Customer Order events attributed by Converge                                             | [Inverse J Shaped](/attribution/models#inverse-j-shaped) |
| `new_customer_order_revenue_sum_inv_j_shaped`   | `FLOAT`  | The total revenue for New Customer Order events attributed by Converge                                           | [Inverse J Shaped](/attribution/models#inverse-j-shaped) |
| `placed_order_events_j_shaped`                  | `FLOAT`  | The total number of Placed Order events attributed by Converge                                                   | [J Shaped](/attribution/models#j-shaped)                 |
| `placed_order_revenue_sum_j_shaped`             | `FLOAT`  | The total revenue for Placed Order events attributed by Converge                                                 | [J Shaped](/attribution/models#j-shaped)                 |
| `new_customer_order_events_j_shaped`            | `FLOAT`  | The total number of New Customer Order events attributed by Converge                                             | [J Shaped](/attribution/models#j-shaped)                 |
| `new_customer_order_revenue_sum_j_shaped`       | `FLOAT`  | The total revenue for New Customer Order events attributed by Converge                                           | [J Shaped](/attribution/models#j-shaped)                 |
| `placed_order_events_last_touch`                | `FLOAT`  | The total number of Placed Order events attributed by Converge                                                   | [Last Touch](/attribution/models#last-touch)             |
| `placed_order_revenue_sum_last_touch`           | `FLOAT`  | The total revenue for Placed Order events attributed by Converge                                                 | [Last Touch](/attribution/models#last-touch)             |
| `new_customer_order_events_last_touch`          | `FLOAT`  | The total number of New Customer Order events attributed by Converge                                             | [Last Touch](/attribution/models#last-touch)             |
| `new_customer_order_revenue_sum_last_touch`     | `FLOAT`  | The total revenue for New Customer Order events attributed by Converge                                           | [Last Touch](/attribution/models#last-touch)             |
| `placed_order_events_linear`                    | `FLOAT`  | The total number of Placed Order events attributed by Converge                                                   | [Linear](/attribution/models#linear)                     |
| `placed_order_revenue_sum_linear`               | `FLOAT`  | The total revenue for Placed Order events attributed by Converge                                                 | [Linear](/attribution/models#linear)                     |
| `new_customer_order_events_linear`              | `FLOAT`  | The total number of New Customer Order events attributed by Converge                                             | [Linear](/attribution/models#linear)                     |
| `new_customer_order_revenue_sum_linear`         | `FLOAT`  | The total revenue for New Customer Order events attributed by Converge                                           | [Linear](/attribution/models#linear)                     |
| `placed_order_events_participation`             | `FLOAT`  | The total number of Placed Order events attributed by Converge                                                   | [Participation](/attribution/models#participation)       |
| `placed_order_revenue_sum_participation`        | `FLOAT`  | The total revenue for Placed Order events attributed by Converge                                                 | [Participation](/attribution/models#participation)       |
| `new_customer_order_events_participation`       | `FLOAT`  | The total number of New Customer Order events attributed by Converge                                             | [Participation](/attribution/models#participation)       |
| `new_customer_order_revenue_sum_participation`  | `FLOAT`  | The total revenue for New Customer Order events attributed by Converge                                           | [Participation](/attribution/models#participation)       |
| `placed_order_events_time_decay`                | `FLOAT`  | The total number of Placed Order events attributed by Converge                                                   | [Time Decay](/attribution/models#time-decay)             |
| `placed_order_revenue_sum_time_decay`           | `FLOAT`  | The total revenue for Placed Order events attributed by Converge                                                 | [Time Decay](/attribution/models#time-decay)             |
| `new_customer_order_events_time_decay`          | `FLOAT`  | The total number of New Customer Order events attributed by Converge                                             | [Time Decay](/attribution/models#time-decay)             |
| `new_customer_order_revenue_sum_time_decay`     | `FLOAT`  | The total revenue for New Customer Order events attributed by Converge                                           | [Time Decay](/attribution/models#time-decay)             |
| `placed_order_events_u_shaped`                  | `FLOAT`  | The total number of Placed Order events attributed by Converge                                                   | [U Shaped](/attribution/models#u-shaped)                 |
| `placed_order_revenue_sum_u_shaped`             | `FLOAT`  | The total revenue for Placed Order events attributed by Converge                                                 | [U Shaped](/attribution/models#u-shaped)                 |
| `new_customer_order_events_u_shaped`            | `FLOAT`  | The total number of New Customer Order events attributed by Converge                                             | [U Shaped](/attribution/models#u-shaped)                 |
| `new_customer_order_revenue_sum_u_shaped`       | `FLOAT`  | The total revenue for New Customer Order events attributed by Converge                                           | [U Shaped](/attribution/models#u-shaped)                 |


# Overview
Source: https://docs.runconverge.com/data-warehouse/overview



## What are data warehouse destinations?

Data warehouse destinations in Converge are integrations that let you send attributed data from Converge to other platforms and services.

<CloudinaryVideo />

## Available destinations

<CardGroup>
  <Card title="BigQuery" href="/data-warehouse/integrations/bigquery" icon={<BigQueryIcon />} />
</CardGroup>


# Consent
Source: https://docs.runconverge.com/destinations/consent

Configure how destinations handle consent

## Overview

You can configure how the Converge destinations should behave based on the visitor's consent preferences.

<Note>
  Check out the [Consent implementation](/sources/consent) to learn how to send consent preferences to Converge.
</Note>

<Warning>All Google and Microsoft destinations in Converge comply with Consent Mode and forward the current consent mode status, but it does not implement it. Please read [this](/guides/implementing-consent-mode) guide on how to implement Google and Microsoft Consent Mode.</Warning>

## Converge destinations

There are two ways to customize how Converge destinations handle consent: the **consent category** and the **consent mode**.

### Consent category

You can classify Converge destinations into two consent categories: `analytics` and `marketing`. Consent is tracked separately for each category.

The consent category can be set under the **Consent** subtab of the destination **Configuration**

<Frame>
  <img alt="Consent categories" />
</Frame>

### Consent mode

The consent mode controls when Converge forwards events to a destination based on the user's consent preference for the selected category.

* **Always forward (client & server)** (default): Forward all events, ignoring user consent. Includes both client and server-side events.
* **Always forward (server only)**: Forward all server-side events, ignoring user consent. Client events respect the user's consent preference.
* **Implied consent**: Forward events unless the user has explicitly denied consent. If no consent preference was recorded, events are still sent.
* **Require consent**: Forward events only if the user has explicitly consented. If no preference was recorded, events are not sent.

<Frame>
  <img alt="Consent modes" />
</Frame>

#### Choosing a mode

A few rules of thumb:

* **Always forward (client & server)** suits destinations that aren't subject to consent (internal analytics, server-to-server data warehouse pipelines, attribution platforms processing first-party data on your behalf).
* **Always forward (server only)** is useful when you want server-side conversions to keep flowing for measurement purposes while still respecting consent on the browser-side pixel.
* **Implied consent** fits an opt-out model: in regions or for visitors where tracking is allowed by default, only stopping when the user explicitly opts out. Use this when your cookie banner is opt-out (e.g. most US states under current state privacy laws) or only shown to specific regions.
* **Require consent** fits an opt-in model: nothing is forwarded until the user explicitly grants consent. Use this for GDPR-style regimes (EU/EEA, UK) where consent must be collected before any marketing tracking takes place.

## How consent is recorded

Converge stores consent in two places:

* **On the profile** (`profile_properties.$consent`), so server-side events for a known visitor inherit the most recent preference.
* **On each event**, snapshotting the consent state at the moment the event was tracked.
  Server-side forwarding always uses the profile-level consent. Client-side forwarding uses the event-level consent. This means that for a net-new visitor whose first hit is client-side (e.g. a `$page_load`), Converge needs to know their consent **before that event is tracked** — there's no earlier profile state to fall back on.

For that reason, if you've configured **Implied consent** or **Require consent**, make sure your site is sending a consent signal to Converge before the first event fires. You have two options:

1. Use one of the [automatically integrated CMPs](/sources/consent#automatic-cmp-integrations) (OneTrust, Cookiebot, CookieFirst, CookieYes, Cookie Information, Usercentrics, Avada, Consentmo).
2. Push a default consent state into Converge yourself, before the first `track` call. See the [default-consent snippet](/sources/consent#sending-consent).
   Without one of these, Converge defaults to `denied` for any visitor it hasn't seen before, and Implied/Require modes will drop client-side events for net-new visitors until consent is sent.

## Common pitfalls

<AccordionGroup>
  <Accordion title="Implied consent dropping client-side events for net-new visitors">
    Implied consent only forwards when consent is granted or unset — but Converge treats "never received any consent signal" as denied for client-side events. If you switch a destination to Implied consent and notice client-side events (`page_view`, `add_to_cart`, etc.) dropping for new visitors, you almost certainly need to push a default consent state from your site before the first event fires. See [Sending consent](/sources/consent#sending-consent).
    Server-side events and events from returning visitors with a stored profile-level consent will still flow.
  </Accordion>

  <Accordion title="Shopify checkout events dropping under Require consent">
    Cookie banners typically live on the main marketing site and don't always carry consent into Shopify's checkout context. If a destination is set to **Require consent** and you depend on checkout events (`begin_checkout`, `purchase`), those events may be dropped because the checkout-surface visitor has no consent signal attached. Either implement consent on the checkout surface as well, or use a less strict mode for destinations that need checkout events.
  </Accordion>

  <Accordion title="GA4 / Google Ads dropping client-side events after switching modes">
    Converge's consent mode and Google Consent Mode v2 are two separate gates. Even if Converge is set to **Always forward**, gtag.js may still throttle hits if Google's own consent state is unset or denied. To address this, make sure a `gtag('consent', 'default', ...)` snippet runs on the page before gtag.js loads. See the [Implementing Consent Mode guide](/guides/implementing-consent-mode) for the full pattern.
  </Accordion>
</AccordionGroup>


# Conversion amount
Source: https://docs.runconverge.com/destinations/conversion-amount

Configure which revenue value Converge forwards to a destination

For conversion events like `Placed Order`, Converge forwards a revenue value to the destination. The **Conversion amount** setting controls which revenue value is sent. For example, you can pick whether to include or exclude taxes and shipping.

<Frame>
  <img alt="Conversion amount dropdown" />
</Frame>

## Available values

| Option                           | Description                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------ |
| **Gross Revenue**                | Unit price times quantity, summed across items. Before any adjustments. Also known as GMV. |
| **Total Revenue** (default)      | Gross revenue plus shipping and taxes, minus discounts.                                    |
| **Total Revenue After Taxes**    | Total Revenue minus taxes.                                                                 |
| **Total Revenue After Shipping** | Total Revenue minus shipping.                                                              |
| **Net Revenue**                  | Total Revenue minus taxes and shipping.                                                    |

See the [Metric dictionary](/attribution/metrics#revenue) for the formal definitions.

## Configure the conversion amount

The setting is applied per destination and covers every conversion event forwarded to it.

1. Navigate to the [Destinations tab](https://app.runconverge.com/-/connections) and click the destination you want to configure.
2. Click on **Configuration**.
3. Open the **Advanced configuration (optional)** section.
4. Pick your desired **Conversion amount** and click **Save**.

<Note>
  Availability of shipping and tax values depends on the source. Orders from shop platforms like Shopify and WooCommerce include both; orders from custom server-side integrations include them only when you send them in the event payload.
</Note>

## Supported destinations

Check the **Converge functionality** table on each [destination page](/destinations/overview) to see if Conversion amount is supported.


# Event mapping
Source: https://docs.runconverge.com/destinations/event-mapping

Configure how events should be mapped and forwarded to Destinations

## Introduction to event mappings

Event mappings tell Converge how to translate your Converge events to a destination.
For example, consider this mapping:

<Frame>
  <img alt="mapping" />
</Frame>

This mapping tells Converge to forward an `AddToCart`-event to the destination, whenever an `Added To Cart`-event is tracked in Converge.

## Event Mapping Modes

Converge supports three mapping modes for most Destinations:

* **Use default mapping** (Recommended): Use the predefined Converge recommended mapping for the Destination.
* **Use custom mapping**: Configure your own event mapping rules to freely map your Converge events to the Destination.
* **Use server-side only** (if supported): Use only server-side event mappings. The corresponding pixel will not be installed and no event will be tracked client-side.

<Frame>
  <img alt="default vs custom mapping" />
</Frame>

<Note> Use custom mapping only if you have a specific use case and understand its impact. Use server-side only when you want to avoid client-side tracking entirely. </Note>

## Forwarding modes

Event mappings define not only how event names are translated, but also how events are forwarded.

There are three forwarding modes:

* **Client**: Forward the event to the destination client-side.
* **Server**: Forward the event to the destination server-side.
* **Client & Server**: Forward the event to the destination client-side and server-side.

<Note>
  Some destinations support only one forwarding mode. In those cases, you can map only events that match that mode.

  For example, if your `Cancelled Subscription`-event is implemented only server-side, you **cannot** map it to a destination that supports only client-side forwarding.
</Note>

## Modify your event mapping configuration

Converge allows you to configure mapping modes for all of your Destinations.

1. Navigate to the [Destinations Tab](https://app.runconverge.com/-/connections) in your Converge dashboard
2. Click on the destination for which you want to modify your mapping configuration.
3. Click on the **Configuration**, then click on **Event mapping** in the dropdown menu.
   <Frame>
     <img alt="event mapping" />
   </Frame>
4. Click on the mapping configuration you'd like to modify, if you'd like to map a new event, click on **Add new mapping**.
   <Note> Default mappings can only be turned on or off, you cannot modify them. When using server-side only mode, only server-side mappings will be active. </Note>
5. Select an existing event or type in a new event you'd like to forward and then fill in the name you want to forward it as. Also choose the forwarding mode you'd like to use.
   <Info> For example, in the screenshot below, we forward an `AddToWishlist` event whenever a Started Checkout event triggers in Converge. The forwarding mode is set to Client & Server. </Info>
   <Frame>
     <img alt="set up custom event" />
   </Frame>
6. Make any additional changes as needed. When you're satisfied with your mapping, click **Save**.
7. Use the [Destination Log](/destinations/monitoring#destination-logs) to confirm that your event is forwarding correctly.

<Note> Your configuration may take up to 10 minutes to take effect. Clearing your browser cache can help ensure you're testing the latest settings. </Note>


# Filters
Source: https://docs.runconverge.com/destinations/filters

Filter out events in your Destinations

## Overview

Converge allows you to filter out events based on **Event Properties**, **Profile Properties** or by their **Source**.

* [Property filters](#event-and-profile-property-filters)
* [Source filters](#source-filters)

***

## Property filters

Converge allows you to filter out events granularly based on their event properties and profile properties according to the [Converge event spec](/sources/converge-spec).

<Note>
  A Converge property filter only forwards events if a condition is **True**. As such, a destination with the following filter only forwards `Placed Order` events if the property is not equal to `subscription_contract`.

  <Frame>
    <img alt="subscription filters" />
  </Frame>
</Note>

<Warning>
  Property filters apply to both event properties and profile properties. If the same property name exists in the event and profile properties, the filter will check both.
</Warning>

### How to set up a property filter

1. Navigate to the [Destinations Tab](https://app.runconverge.com/-/connections) in your Converge dashboard
2. Click on the Destination for which you want to filter out certain events.
3. Click on the **Configuration** tab and on the **Filters**-subtab to open the Filter Configuration
4. Click on **Add condition** and choose the Event for which you want to set up a filtering rule.
5. Click on **Select Property** and choose the property on which you want to filter.
6. Once you are happy with your rule, click **Save**.
   <Frame>
     <img alt="pick filters" />
   </Frame>

### Examples

#### Filtering out subscription orders from a Destination

Subscription brands typically want to filter out recurring purchases when forwarding to ad platforms. To achieve this, you can set up a Filter on the `Placed Order` event on a per-destination basis.

<Steps>
  <Step title="Find a property and property value that defines a recurring subscription order">
    1. Navigate to the <OutboundLink /> and filter on the `Placed Order` event.

    2. Check a few `Placed Order` events by clicking on them to see all of their properties, **find a property and property value that uniquely define a subscription purchase**.

       <Note>
         If you are using the [Shopify Server Integration](/sources/server-integrations/shopify.mdx) in a standard setup, then the following property and property value pair defines a recurring purchase:

         `source_name` → `subscription_contract`
       </Note>
  </Step>

  <Step title="Set up your filter accordingly">
    3. Set up a filter for the `Placed Order` event as follows. Replace the property and property value with the ones you identified in *Step 2*.
       <Frame>
         <img alt="subscription filters" />
       </Frame>
  </Step>
</Steps>

***

## Source filters

Converge allows you to filter out all events of a specific source with a single filter.
This is especially helpful when you have multiple sales channels, such as multiple storefronts.

### How to set up a source filter

1. Navigate to the [Destinations Tab](https://app.runconverge.com/-/connections) in your Converge dashboard
2. Click on the Destination for which you want to filter out certain sources.
3. Click on the **Configuration** tab and on the **Sources**-subtab to open the Source Filter Configuration
4. Choose the Sources for which you want to send events.
5. Once you are happy with your selection, click **Save**.
   <Frame>
     <img alt="pick filters" />
   </Frame>

### Multi-store or multi-website setups

A typical example of source filters is when you are setting up multiple stores.
You might want to set up different Google Ads Destinations for each store for example.
You can use source filters to filter out the appropriate sources per destination.

As an example, if you have a US and CA store, and you are creating a Google Ads Destination for the CA Store -- you will want to configure your Canadian Sources to be the only ones streaming into this Destination.

<Frame>
  <img alt="CAD Example" />
</Frame>


# AppLovin
Source: https://docs.runconverge.com/destinations/integrations/applovin

An introduction to the AppLovin Destination

## Overview

Destination Type: <IconText name="browser" />

***

## Installation instructions

<Note>
  This is a client-side destination, so you must track all events client-side, including `Placed Order` and `Started Subscription`, for it to work properly.
</Note>

1. Navigate to your <OutboundLink /> and choose **Account > Keys**.

2. Copy your **AppLovin Event Key**.

<Frame>
  <img alt="AppLovin Report Key" />
</Frame>

3. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

4. Select the **AppLovin** destination and click **Next**.

5. Give your destination a **name** (e.g. AppLovin Destination) and click **Next**.

6. Fill in the **Event Key** you copied from **AppLovin** and click **Next**.

7. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the AppLovin destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

8. Select the sources you want to forward events from, then click **Next**.

<Note>This is a client-side destination, meaning that only client-side sources can be used with this destination. You can still select server-side sources but the events will not be sent to AppLovin.</Note>

9. Review any issues and click **Submit**.

<Warning> Once you have installed your Converge Destination, you should **pause or remove all existing AppLovin tracking**. Leaving these on will lead to duplicate tracking.  </Warning>

***

## Modify your Content ID

The Converge AppLovin Destination will use the **Default** content mode to define the Content ID forwarded by default.
However, you can configure the destination to use explicitly the **Product ID**, the **Variant ID** or **SKU** instead.

1. Navigate to your AppLovin Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of Content ID Modes**

| Content ID Mode | Behavior                                                          |
| --------------- | ----------------------------------------------------------------- |
| Default         | Use the `variant_id` if available, otherwise use the `product_id` |
| Product Id      | Always use the `product_id`                                       |
| Variant Id      | Always use the `variant_id`                                       |
| SKU             | Always use the `sku`                                              |

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature        |       Supported       |
| ----------------------- | :-------------------: |
| Custom Events           | <Icon name="xmark" /> |
| Filters                 | <Icon name="xmark" /> |
| Server-side Conversions | <Icon name="xmark" /> |

***

## FAQ

<AccordionGroup>
  <Accordion title="Can I use Enhanced User Identification?">
    *TLDR:* Not for Shopify stores.

    AppLovin recommends implementing *Enhanced User Identification* by setting the `axwrt` cookie through the backend of your store. As **Converge**, by default, is not served under your store's domain, we cannot set this cookie directly in the client, as this would not truly enhance identification. As such, to enable *Enhanced User Identification*, the `axwrt` cookie needs to be implemented directly in your store backend.

    Notice that for Shopify stores, as you have no control over the backend, this cookie cannot be set and *Enhanced User Identification* cannot be used.

    For other setups where you have control over the backend of your store, please refer to <OutboundLink /> for instructions on how to enable *Enhanced User Identification*.
  </Accordion>
</AccordionGroup>

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the <OutboundLink />:

| Converge Event Name                                             | AppLovin Event Name |
| --------------------------------------------------------------- | ------------------- |
| [\$page\_load](/sources/converge-spec#page-load)                | `page_view`         |
| [Viewed Product](/sources/converge-spec#viewed-product)         | `view_item`         |
| [Added To Cart](/sources/converge-spec#added-to-cart)           | `add_to_cart`       |
| [Removed From Cart](/sources/converge-spec#removed_from_cart)   | `remove_from_cart`  |
| [Started Checkout](/sources/converge-spec#started-checkout)     | `begin_checkout`    |
| [Searched](/sources/converge-spec#searched)                     | `search`            |
| [Added Payment Info](/sources/converge-spec#added-payment-info) | `add_payment_info`  |
| [Placed Order](/sources/converge-spec#placed-order)             | `purchase`          |


# AWIN
Source: https://docs.runconverge.com/destinations/integrations/awin

An introduction to the AWIN affiliate tracking destination

## Overview

Destination Type: <IconText name="browser" />  and <IconText name="server" />

* Loads the <OutboundLink /> on all pages
* Sends conversions through the <OutboundLink /> integration
* Includes <OutboundLink />, if multiple voucher codes are used, the first one will be sent
* Supports distinguishing between <OutboundLink />
* Supports <OutboundLink />
* Supports <OutboundLink />

***

## Installation instructions

1. Obtain your AWIN advertiser ID. You can find this ID in the top right corner of your <OutboundLink />.

2. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

3. Select the **AWIN** destination and click **Next**.

4. Give your destination a **name** (e.g. AWIN Destination) and click **Next**.

5. Fill in the **Advertiser ID** you copied from **AWIN** and click **Next**.

6. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the AWIN destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

7. Select the sources you want to forward events from, then click **Next**.

8. Review any issues and click **Submit**.

<Warning>
  Set this destination to **Deactivated** while you remove your existing AWIN tracking setup. Running both in parallel leads to duplicate conversion data. Follow the **Turn off your old AWIN tracking** instructions below, then set the destination to **Active** when you're ready.
</Warning>

***

## Turn off your old AWIN tracking

### Uninstalling the Shopify AWIN app

1. Navigate to your <OutboundLink />.

2. Click on <IconText name="gear" /> and choose **Apps and sales channels** from the menu.

3. Click on <Icon name="ellipsis" /> next to **Awin - Affiliate Marketing**, and click on **Uninstall**.

   <Frame>
     <img alt="settings-awin" />
   </Frame>

***

## Exclude VAT and shipping from commission payments

Some companies send the order value with tax and shipping costs included back to AWIN in their conversion tracking setup.

However, AWIN calculates commission (usually somewhere between 10% - 15%) on the order value that is passed back.
When you send the order value with tax and shipping included back to AWIN, you will effectively pay a commission on those.

Therefore, many companies prefer to pay AWIN commission based on their **net revenue**.

### An example

As an example, take a product that has a price of 100 USD.
Now, the total price that the customer will pay will look something like `price + tax + shipping`, for example: `$100 + $15 + $5 = $120`.

Now, imagine that you are paying AWIN 15% commission.

* In the case that you send back the **gross order value** with VAT and shipping, then you will pay AWIN `15% * $120` or **\$18**.
* However, in the case that you would send back the **net order value**, then you will pay AWIN `15% * 100` or **\$15**

### Setting up Net Order Value in your AWIN configuration

In the destination configuration, under the advanced tab, you can configure whether you want to send **gross** or **net** order values.

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| :--------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="xmark" /> |
| Filters                                              | <Icon name="xmark" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## FAQ

<AccordionGroup>
  <Accordion title="Why are my events not being forwarded?">
    Verify that you've configured the events you want to forward as **Conversion events** in the destination configuration.

    If your events are showing up as **skipped** in the destination logs, double-check that your event properties conform with the [Placed Order](/sources/converge-spec#placed-order) event spec.
    If Converge cannot parse the event into an AWIN order, the event cannot be forwarded and shows as **skipped**.
  </Accordion>

  <Accordion title="Can I send other events to AWIN?">
    AWIN only supports tracking orders. You can configure which events are forwarded as orders, but cannot register events besides orders.

    The following customizations are possible

    * **Customer type**: Converge by default includes whether the order comes from a new or existing customer.
    * **Custom parameters**: you can include event properties as custom parameters on your orders.
  </Accordion>

  <Accordion title="How do I send custom parameters to AWIN?">
    Under the **Advanced** tab in the AWIN destination, you can add custom parameters to your events. Only string or numeric parameters are supported. These are sent as a list of values.

    For example, when specifying <code>order\_type</code> and <code>language</code> custom parameters, the following lists could be sent to AWIN

    ```
    [Placed Order, sample, en]
    [Placed Order, gold, de]
    ```

    <Note>The Converge event name is automatically included as a custom parameter.</Note>
  </Accordion>

  <Accordion title="Do you support differentiating between new and existing customers?">
    Yes, this is enabled by default.
  </Accordion>

  <Accordion title="How do I track the channel parameter">
    By default, this is set to <code>aw</code>, as recommended by AWIN. You can customize this by setting an <code>\$awin\_channel</code> profile property on your events.

    ```javascript theme={null}
    cvg({
        method: 'track',
        eventName: 'Registered Custom Channel',
        profileProperties: {
            $awin_channel: 'custom_channel'
        }
    })
    ```
  </Accordion>
</AccordionGroup>

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to AWIN events:

| Converge Event Name                                 | AWIN Event Name |
| --------------------------------------------------- | --------------- |
| [Placed Order](/sources/converge-spec#placed-order) | `Order`         |


# BigQuery
Source: https://docs.runconverge.com/destinations/integrations/bigquery

Setting up a destination with BigQuery

## Overview

Destination Type:  <IconText name="server" />

***

## Installation instructions

<Steps>
  <Step icon="table" title="1. Create a BigQuery Table for your Converge Data">
    1. Log into your Google Cloud console at `console.cloud.google.com`

    2. Choose your relevant Google Cloud Project from the top bar. If you do not have a Google Cloud Project yet, you can create one following the instructions [here](https://developers.google.com/workspace/guides/create-project).

    3. From the top search bar, search for `bigquery` and pick the **BigQuery** service.
        
       <Frame>
         <img alt="bq-1" />
       </Frame>

    4. In the BigQuery Explorer, click on **Add**.
        
       <Frame>
         <img alt="bq-2" />
       </Frame>

    5. From the side-pane, choose **Google Cloud Storage**, this will open the *Create table* modal.
        
       <Frame>
         <img alt="bq-3" />
       </Frame>

    6. In the *Create table* modal, choose `Empty table` as a Source. Create a new *Data set* and call it `converge_data`, in the *Table*-field choose a name for your table, e.g. `events`.
        
       <Frame>
         <img alt="bq-4" />
       </Frame>

    7. In the Schema section, flip the switch to **Edit as text** and paste the schema below. Click on **Create Table** after.

       <Frame>
         <img alt="bq-5" />
       </Frame>

       <Accordion icon="code" title="Schema">
         ```json JSON theme={null}
         [
           {
             "name": "id",
             "type": "STRING",
             "mode": "REQUIRED",
             "description": "Event ID"
           },
           {
             "name": "timestamp",
             "type": "DATETIME",
             "mode": "REQUIRED",
             "description": "Timestamp when the event occurred"
           },
           {
             "name": "event_name",
             "type": "STRING",
             "mode": "REQUIRED"
           },
           {
             "name": "profile_id",
             "type": "INTEGER",
             "mode": "REQUIRED",
             "description": "Profile ID"
           },
           {
             "name": "event_properties",
             "type": "JSON",
             "mode": "NULLABLE",
             "description": "Properties of the event"
           },
           {
             "name": "profile_properties",
             "type": "JSON",
             "mode": "NULLABLE",
             "description": "Properties of the profile this event belongs to"
           },
           {
             "name": "session_id",
             "type": "STRING",
             "mode": "NULLABLE",
             "description": "Session Id of the session this event belongs to"
           },
           {
             "name": "session_properties",
             "type": "JSON",
             "mode": "NULLABLE",
             "description": "Properties of the session this event belongs to"
           },
           {
             "name": "source_id",
             "type": "STRING",
             "mode": "NULLABLE",
             "description": "ID of the source that generated this event prefixed with 'datasource_' or 'pixel_' depending on the source type"
           },
           {
             "name": "source_name",
             "type": "STRING",
             "mode": "NULLABLE",
             "description": "Name of the source that generated this event"
           }
         ]
         ```
       </Accordion>

    Great, now you have a table for your Converge Events, follow the guide below to set up a destination that streams Converge events into this BigQuery Table
  </Step>

  <Step icon="bars-staggered" title="2. Stream Converge Data into your BigQuery table">
    8. The first thing we need to do in Google Cloud is set up a service account. Start by going to the sidebar menu and choosing *IAM and admin* > *Service accounts*.
        
       <Frame>
         <img alt="bq-s-1" />
       </Frame>

    9. Click on **Create Service Account**.
        
       <Frame>
         <img alt="bq-s-2" />
       </Frame>

    10. Fill in service account name, e.g. `converge-bigq-account` and click on **Create and continue**.
         

    <Frame>
      <img alt="bq-s-3" />
    </Frame>

    11. Under *Grant this service account access to the project*, choose the **BigQuery Data Owner** scope and click on **Done**.
         

    <Frame>
      <img alt="bq-s-4" />
    </Frame>

    12. Pick your newly created service account from the list of Service Accounts and choose **Manage keys**.
         

    <Frame>
      <img alt="bq-s-5" />
    </Frame>

    13. Click on **Add Key** and **Create new key**. In the popup choose **JSON** and click on **Create**. This will download a file that ends with `.json`.
         

    <Frame>
      <img alt="bq-s-6" />
    </Frame>

    14. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.
    15. Select the **BigQuery** destination and click **Next**.
    16. Give your destination a **name** (e.g. BigQuery Destination) and click **Next**.
    17. Fill in the **Credentials** from your service account, **Dataset ID** and **Table ID** you copied from **Google Cloud** and click **Next**.

    <Info>You can also stream profile merges to BigQuery. This is optional, but recommended for constructing accurate profile journeys. Enter a **Merged Profiles Table ID** to enable it.</Info>

    18. Select the sources you want to forward events from, then click **Next**.
    19. Review any issues and click **Submit**.

    <Note>Converge automatically sends all implemented events from the Converge event spec and any custom events to BigQuery.</Note>
  </Step>
</Steps>

***

## Multi-touch attribution support

Converge preprocesses all events and enriches them with all available **profile** and **session** information to make your attribution data warehouse queries as simple as possible.

### Profile Information

Every event that is forwarded includes all available information Converge has on that profile until that moment, ranging from `$ip_address` all the way to `$email`.

Events that typically do not have an `$email` property associated with them (e.g. `$page_load`) will *still* contain this property if we were able to identify this profile before the `$page_load` happened.

<Accordion title="Profile Information Overview" icon="address-card">
  <ParamField type="int">
    A unique profile ID
  </ParamField>

  <ParamField type="Profile Properties Object">
    Properties related to the profile of the forwarded event.

    <Expandable title="properties">
      <ParamField type="string">
        IP address of the user.
      </ParamField>

      <ParamField type="string">
        Converge cookie ID.
      </ParamField>

      <ParamField type="string">
        User Agent of the last browser session of the user.
      </ParamField>

      <ParamField type="string">
        Email Address of the subscriber.
      </ParamField>

      <ParamField type="string">
        Phone Number of the subscriber including the `+` sign and country code. For example: `"+1 (917) 123-4567"` or `"+3295123456"`.
      </ParamField>

      <ParamField type="string">
        City of the subscriber's address.
      </ParamField>

      <ParamField type="string">
        Country code of the subscriber's address as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, e.g. `"US"`. Three-letter alpha-3 codes such as `"USA"` are not supported.
      </ParamField>

      <ParamField type="string">
        State of the subscriber's address.
      </ParamField>

      <ParamField type="string">
        Zip code of the subscriber's address.
      </ParamField>
    </Expandable>
  </ParamField>
</Accordion>

### Profile Merging

Converge may combine multiple profiles into one if there is an overlap in aliases.
This means that the `profile_id` field in your events table may become out of date.
Under the 'Advanced' tab of the BigQuery destination configuration, you can configure a table to stream these profile merges to.
You can create this table as follows:

* Under your Converge dataset (`converge_data`), create a new table, e.g. `profile_merges`.
* In the Schema section, flip the switch to **Edit as text** and paste the schema below. Click on **Create Table** after.
  <Accordion icon="code" title="Schema">
    ```json JSON theme={null}
    [
      {
        "name": "timestamp",
        "type": "DATETIME",
        "mode": "REQUIRED",
        "description": "Timestamp when the event occurred"
      },
      {
       "name": "old_profile_id",
       "type": "INTEGER",
       "mode": "REQUIRED",
       "description": "Old Profile ID that was merged"
      },
      {
        "name": "new_profile_id",
        "type": "INTEGER",
        "mode": "REQUIRED",
        "description": "New Profile ID resulting from the merge"
      }
    ]
    ```
  </Accordion>

To use this table, it's important to note that profiles maybe merged multiple times. For example profile A and B could be mapped to C as follows:

* `(A, C)`
* `(B, C)`
  Later on, profile C could be merged into profile D:
* `(C, D)`
  In this case, profiles A, B, and C, would all be mapped to D. To deal with this, we recommend creating a (materialized) view that recursively resolves these mappings. Here's an example query to achieve this:

```sql SQL theme={null}
WITH RECURSIVE profile_merges AS (
  SELECT 
    timestamp, 
    old_profile_id, 
    new_profile_id, 
    ARRAY[old_profile_id] AS visited_profiles,
    1 AS depth,
    FALSE AS is_circular_reference
  FROM 
    `your-project-name.your-dataset-name.profile_merges`
  UNION ALL
  SELECT 
    pmr.timestamp, 
    pm.old_profile_id,
    pmr.new_profile_id, 
    ARRAY_CONCAT(pm.visited_profiles, [pmr.new_profile_id]) AS visited_profiles,
    pm.depth + 1 AS depth,
    IF(pmr.new_profile_id IN UNNEST(pm.visited_profiles), TRUE, pm.is_circular_reference) AS is_circular_reference
  FROM 
    profile_merges pm
  JOIN 
    `your-project-name.your-dataset-name.profile_merges` pmr
  ON 
    pm.new_profile_id = pmr.old_profile_id
  WHERE
    pmr.timestamp > pm.timestamp
    AND NOT pm.is_circular_reference
)
SELECT 
  old_profile_id, 
  MAX_BY(new_profile_id, depth) AS new_profile_id
FROM 
  profile_merges
GROUP BY 
  old_profile_id;
```

### Querying attribution data

<Warning>
  The attributed `first_touch_properties` etc. columns are deprecated and are no longer being filled, see [here](#deprecation-of-pre-processed-attribution-columns).
</Warning>

The events table contains all the data you need to build custom attribution models.
You can easily construct the customer's touchpoints through the `session_id` and `session_properties` columns.

A multi-touch model can be broken down into the following steps:

1. Selecting conversion events
2. Selecting touchpoints
3. Joining touchpoints with conversion events according to the attribution window
4. Applying the attribution model
5. Aggregating conversion metrics by touchpoint

This model can be adapted to 100% flexibly build attribution insights.
The examples below show how to build basic first-touch and last-touch models and count the number of orders in BigQuery.

<Accordion title="First Touch" icon="backward">
  For example, the following query represents a 28-day first-touch model.

  ```sql theme={null}
    WITH _events AS (SELECT * FROM `your-project-name.your-dataset-name.your-table-name`),
    _1_conversions AS (
      SELECT
          id,
          profile_id,
          timestamp
      FROM _events
      WHERE
          timestamp > CURRENT_DATETIME() - INTERVAL 7 day
          AND event_name = 'Placed Order'
    ), 
    _2_touchpoints AS (
      SELECT
          profile_id,
          session_id,
          MIN_BY(session_properties, timestamp) AS session_properties,
          MIN(timestamp) AS timestamp
      FROM _events
      WHERE
          timestamp > CURRENT_DATETIME() - INTERVAL 7 day - INTERVAL 28 day
          AND event_name = '$page_load'
      GROUP BY profile_id, session_id
    ),
    _3_conversions_touchpoints AS (
      SELECT
        c.id AS id,
        t.timestamp AS touchpoint_timestamp,
        t.session_properties AS touchpoint_properties
      FROM _1_conversions AS c
      LEFT JOIN _2_touchpoints AS t
      ON c.profile_id = t.profile_id
          AND t.timestamp BETWEEN c.timestamp - INTERVAL 28 day AND c.timestamp
    ),
    _4_attributed_conversions AS (
      SELECT
          id,
          MIN_BY(touchpoint_properties, touchpoint_timestamp) AS touchpoint_properties,
          MIN(touchpoint_timestamp) AS touchpoint_timestamp
      FROM _3_conversions_touchpoints
      GROUP BY id
    )
    SELECT
        JSON_VALUE(touchpoint_properties, '$.utm_source') AS first_touch_utm_source,
        JSON_VALUE(touchpoint_properties, '$.utm_medium') AS first_touch_utm_medium,
        COUNT(*) AS conversions
    FROM _4_attributed_conversions
    GROUP BY first_touch_utm_source, first_touch_utm_medium
  ```
</Accordion>

<Accordion title="Last Touch" icon="forward">
  For example, the following query represents a 7-day last-touch model.

  ```sql theme={null}
    WITH _events AS (SELECT * FROM `your-project-name.your-dataset-name.your-table-name`),
    _1_conversions AS (
      SELECT
          id,
          profile_id,
          timestamp
      FROM _events
      WHERE
          timestamp > CURRENT_DATETIME() - INTERVAL 7 day
          AND event_name = 'Placed Order'
    ), 
    _2_touchpoints AS (
      SELECT
          profile_id,
          session_id,
          MIN_BY(session_properties, timestamp) AS session_properties,
          MIN(timestamp) AS timestamp
      FROM _events
      WHERE
          timestamp > CURRENT_DATETIME() - INTERVAL 7 day - INTERVAL 28 day
          AND event_name = '$page_load'
      GROUP BY profile_id, session_id
    ),
    _3_conversions_touchpoints AS (
      SELECT
        c.id AS id,
        t.timestamp AS touchpoint_timestamp,
        t.session_properties AS touchpoint_properties
      FROM _1_conversions AS c
      LEFT JOIN _2_touchpoints AS t
      ON c.profile_id = t.profile_id
          AND t.timestamp BETWEEN c.timestamp - INTERVAL 28 day AND c.timestamp
      ),
    _4_attributed_conversions AS (
      SELECT
          id,
          MAX_BY(touchpoint_properties, touchpoint_timestamp) AS touchpoint_properties,
          MAX(touchpoint_timestamp) AS touchpoint_timestamp
      FROM _3_conversions_touchpoints
      GROUP BY id
    )
    SELECT
        JSON_VALUE(touchpoint_properties, '$.utm_source') AS last_touch_utm_source,
        JSON_VALUE(touchpoint_properties, '$.utm_medium') AS last_touch_utm_medium,
        COUNT(*) AS conversions
    FROM _4_attributed_conversions
    GROUP BY last_touch_utm_source, last_touch_utm_medium
  ```
</Accordion>

The session columns have the following structure:

<ParamField type="string">
  Session ID of the event
</ParamField>

<ParamField type="Session Properties Object">
  Properties containing information about the session of the forwarded event

  <Expandable title="properties">
    <ParamField type="string">
      The landing URL of the session.
    </ParamField>

    <ParamField type="string">
      Referrer information for the session.
    </ParamField>

    <ParamField type="string">
      UTM source information for the session.
    </ParamField>

    <ParamField type="string">
      UTM medium information for the session.
    </ParamField>

    <ParamField type="string">
      UTM campaign information for the session.
    </ParamField>

    <ParamField type="string">
      UTM content information for the session.
    </ParamField>

    <ParamField type="string">
      UTM term information for the session.
    </ParamField>
  </Expandable>
</ParamField>

#### Deprecation of pre-processed attribution columns

Converge previously supported the following columns:

* `first_touch_properties` and `first_touch_session_id`
* `last_touch_properties` and `last_touch_session_id`
* `first_touch_paid_properties` and `first_touch_paid_session_id`
* `last_touch_paid_properties` and `last_touch_paid_session_id`

These columns are deprecated and are no longer being filled.
The recommended way to build multi-touch attribution models is to use the `session_id` and `session_properties` columns in the Converge data.
These allow full flexibility in building custom attribution models while maintaining correctness.

***

## An example query

As an example, the following query on top of the Converge Table gives you the number of times an SKU was ordered:

```sql SQL theme={null}
SELECT
  string(item.sku) sku, count(*) order_count
FROM `your-project-name.your-dataset-name.your-table-name`
LEFT JOIN unnest(json_extract_array(event_properties.items,'$')) item
WHERE event_name = 'Placed Order'
GROUP BY sku
ORDER BY order_count DESC
```

<Note> Make sure you replace `your-project-name`, `your-dataset-name` and `your-table-name` with your appropriate values. </Note>

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature        |       Supported       |
| ----------------------- | :-------------------: |
| Custom Events           | <Icon name="check" /> |
| Filters                 | <Icon name="check" /> |
| Server-side Conversions | <Icon name="check" /> |

***

## Event mapping

Converge automatically sends all implemented events from the [Converge Spec](/sources/converge-spec) and any custom events to BigQuery.


# Microsoft Ads (Bing Ads)
Source: https://docs.runconverge.com/destinations/integrations/bing

An introduction to the Bing Ads Destination

## Overview

Destination Type: <IconText name="browser" />

* Includes support for <OutboundLink />
* Includes support for  <OutboundLink />

***

## Installation instructions

<Note> This is a client-side-only destination, meaning that you will need to be tracking all events client-side (including `Placed Order`) for this destination to work properly. </Note>
<Warning>Set up consent mode to track conversion in the EEA. See [below](#consent-mode).</Warning>

<Steps>
  <Step icon="list" title="1. Set up the Destination">
    1. Navigate to your Microsoft Advertising Dashboards and choose **Tools > UET Tag**.

    2. If you already have a UET Tag, copy the **Tag ID** and go to *Step 6*, otherwise go to *Step 3*
        

    3. Click on **Create**
        

    4. Choose a UET tag name, and UET Tag Description and click on **Save and next**.
        

    5. Choose `Install the tag yourself` and click on **Next**. From the code snippet, copy your Tag ID (marked in pink in the screenshot below) and click on **Next**. After that click on **Done**
       <Frame>
         <img alt="bing-1" />
       </Frame>

    6. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

    7. Select the **Microsoft Ads (Bing Ads)** destination and click **Next**.

    8. Give your destination a **name** (e.g. Microsoft Ads Destination) and click **Next**.

    9. Fill in the **Tag ID** you copied from **Microsoft Ads** and click **Next**.

    10. Select **Use default mapping** and click **Next**.

    <Note>You can find the Default mapping for the Microsoft Ads destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

    11. Select the sources you want to forward events from, then click **Next**.

    <Note>This is a client-side destination, meaning that only client-side sources can be used with this destination. You can still select server-side sources but the events will not be sent to Microsoft Ads.</Note>

    12. Review any issues and click **Submit**.
  </Step>

  <Step icon="circle-dollar-to-slot" title="2. Create your Conversion goals">
    13. Navigate to your Microsoft Advertising Dashboards and choose **Tools > Conversion goals**.

    14. Click on the **Create** button.
         

    15. Choose `Website` as your conversion goal type and press **Next**.
         

    16. Choose your conversion goal category and press **Next**.

    <Info>For most businesses, we advise setting up at least a `Purchase` conversion goal but Converge supports any of the events in the [Bing Ads Event Mapping](#event-mapping).</Info>

    17. As a Goal Type, choose **Event** and click **Next**.
         

    18. Give your conversion goal a name, e.g. `[Converge] Purchase` and choose `Conversion action value may vary` as **Revenue**. Leave the other options unchanged and click **Next**.

    <Frame>
      <img alt="bing set up conversion action" />
    </Frame>

    19. Choose **Turn on enhanced conversions** and tick the checkbox to enable enhanced conversions. Click on **Save and next**.

    20. Choose the Tag you set up in `Installation instructions` and click **Skip base tag setup**.

    21. Ignore the enhanced conversion instructions. Just click on **Next**.

    22. Choose **Manual installation** and click **Next**.

    23. Fill in `purchase` in the Action Name field.

    <Info>If you are not setting up a `purchase` event, you should check the [Bing Ads Event Mapping](#event-mapping) for the appropriate action name (e.g. `add_to_cart`).</Info>

    <Frame>
      <img alt="bing install event tag" />
    </Frame>

    24. Choose **Track event on inline action** under **When do you want to track this event?**. Ignore the code generated below and click **Save and next.**

    25. You are done. Your conversion goal should populate with conversions from the Bing Ads Destination.

    <Note>Repeat the steps above for all the conversion goals you want to report on in Bing Ads.</Note>
  </Step>
</Steps>

<Warning> Once you have installed your Converge Destination, you should **pause or remove all existing Bing Ads tracking**. Leaving these on will lead to duplicate tracking.  </Warning>

***

## Consent mode

Bing Ads requires implementing [consent mode](https://help.ads.microsoft.com/#apex/ads/en/60119/1).
In EEA, conversions may be ignored if consent is not explicitly granted.

You should configure consent mode through your cookie banner, or instrument it manually according to the [documentation](https://help.ads.microsoft.com/#apex/ads/en/60119/1).

The Converge destination will automatically pick up on the configured consent configuration.

***

## Modify your Content ID

The Converge Bing Ads Connection will use the **Default** content mode to define the Content ID forwarded by default.
However, you can configure the connection to use explicitly the **Product ID**, the **Variant ID** or **SKU** instead.

1. Navigate to your Microsoft Ads (Bing Ads) Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of Content ID Modes**

| Content ID Mode | Behavior                                                          |
| --------------- | ----------------------------------------------------------------- |
| Default         | Use the `variant_id` if available, otherwise use the `product_id` |
| Product Id      | Always use the `product_id`                                       |
| Variant Id      | Always use the `variant_id`                                       |
| SKU             | Always use the `sku`                                              |

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="xmark" /> |
| Server-side Conversions                              | <Icon name="xmark" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Bing Ads spec.

| Converge Event Name                                             | Bing Ads Event Name   |
| --------------------------------------------------------------- | --------------------- |
| [\$page\_load](/sources/converge-spec#page-load)                | `page_view`           |
| [Viewed Product](/sources/converge-spec#viewed-product)         | `view_item`           |
| [Viewed Collection](/sources/converge-spec#viewed-collection)   | `view_item_list`      |
| [Added To Cart](/sources/converge-spec#added-to-cart)           | `add_to_cart`         |
| [Searched](/sources/converge-spec#searched)                     | `view_search_results` |
| [Started Checkout](/sources/converge-spec#started-checkout)     | `begin_checkout`      |
| [Added Payment Info](/sources/converge-spec#added-payment-info) | `add_payment_info`    |
| [Placed Order](/sources/converge-spec#placed-order)             | `purchase`            |


# Convert
Source: https://docs.runconverge.com/destinations/integrations/convert

An introduction to the Convert Destination

## Overview

Destination Type: <IconText name="server" />

<Note> This Converge Destination only supports <OutboundLink /> in Convert.</Note>

***

## Installation instructions

<Steps>
  <Step icon="bullseye" title="1. Create a new revenue goal">
    1. In your Convert dashboard, go to **Goals**  and select **New Goal**.
    2. Click on **Revenue goal**.
       <Frame>
         <img alt="revenue-goal-picker" />
       </Frame>
    3. Give your goal a name, e.g. `[Converge] Revenue` and choose **Manual Revenue Tracking**. You can leave Goal Description blank.
    4. Click on **Save Goal**.
    5. Copy the Revenue **Goal ID**, you will need it later.
       <Frame>
         <img alt="revenue-goal-picker" />
       </Frame>
    6. Also write down your **Account Id**, you can find it in the top right corner of the Convert Dashboard.
       <Frame>
         <img alt="account-id" />
       </Frame>
    7. Lastly, navigate to **Configuration** > **General Settings** and copy your **Project ID**.
  </Step>

  <Step icon="list" title="2. Create the Converge Destination">
    8. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.
    9. Select the **Convert** destination and click **Next**.
    10. Give your destination a **name** (e.g. Convert Destination) and click **Next**.
    11. Fill in the **Account ID** and **Project ID** you copied from **Convert** and click **Next**.
    12. Click on <IconText name="plus" /> and select Placed Order as the source event.
    13. In the Forward As value enter the **Goal ID** you copied from Convert.
    14. Select **Server** as the Forwarding Mode and click **Next**.

    <Frame>
      <img alt="convert-4" />
    </Frame>

    15. Select the sources you want to forward events from, then click **Next**.
        <Note>This is a server-side destination, meaning that only server-side sources can be used with this destination. You can still select client-side sources but the events will not be sent to Convert.</Note>
    16. Review any issues and click **Submit**.
  </Step>
</Steps>

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="xmark" /> |
| Filters                                              | <Icon name="xmark" /> |
| Server-side Conversions                              | <Icon name="xmark" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Convert spec.

<Note> This destination does not forward events like a regular destination. It only sends revenue data to Convert goals. </Note>

| Converge Event Name                                 | Convert   |
| --------------------------------------------------- | --------- |
| [Placed Order](/sources/converge-spec#placed-order) | `Revenue` |


# Criteo
Source: https://docs.runconverge.com/destinations/integrations/criteo

An introduction to the Criteo Destination

## Overview

Destination Type: <IconText name="browser" />  and <IconText name="server" />

***

## Installation instructions

1. Navigate to the <OutboundLink />

2. Find your **Account Partner ID**, as per the screenshot below
   <Frame>
     <img alt="criteo" />
   </Frame>

3. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

4. Select the **Criteo** destination and click **Next**.

5. Give your destination a **name** (e.g. Criteo Destination) and click **Next**.

6. Fill in the **Account Partner ID** you copied from **Criteo** and click **Next**.

7. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the Criteo destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

8. Select the sources you want to forward events from, then click **Next**.

9. Review any issues and click **Submit**.

<Warning> Once you have installed your Converge Destination, you should **pause or remove all existing Criteo tracking**. Leaving these on will lead to duplicate tracking.  </Warning>

***

## Modify your Content ID

The Converge Criteo Destination will use the **Product ID** by default.
However, you can configure the destination to use explicitly the **Variant ID** or **SKU** instead.

1. Navigate to your Criteo Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of available Content ID Modes**

| Content ID Mode | Behavior                    |
| --------------- | --------------------------- |
| Product Id      | Always use the `product_id` |
| Variant Id      | Always use the `variant_id` |
| SKU             | Always use the `sku`        |

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature        |       Supported       |
| :---------------------- | :-------------------: |
| Custom Events           | <Icon name="xmark" /> |
| Filters                 | <Icon name="xmark" /> |
| Server-side Conversions | <Icon name="check" /> |

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Criteo spec.

| Converge Event Name                                             | Criteo Event Name  |
| --------------------------------------------------------------- | ------------------ |
| [\$page\_load](/sources/converge-spec#page-load)                | `viewPage`         |
| [Logged In](/sources/converge-spec#logged-in)                   | `login`            |
| [Viewed Product](/sources/converge-spec#viewed-product)         | `viewItem`         |
| [Added To Cart](/sources/converge-spec#added-to-cart)           | `addToCart`        |
| [Viewed Cart](/sources/converge-spec#viewed-cart)               | `viewBasket`       |
| [Started Checkout](/sources/converge-spec#started-checkout)     | `beginCheckout`    |
| [Viewed Collection](/sources/converge-spec#viewed-collection)   | `viewList`         |
| [Added Payment Info](/sources/converge-spec#added-payment-info) | `addPaymentInfo`   |
| [Placed Order](/sources/converge-spec#placed-order)             | `trackTransaction` |


# Custom HTML
Source: https://docs.runconverge.com/destinations/integrations/custom-html

Setting up a Custom HTML destination

## Overview

Destination Type: <IconText name="browser" />

For cases where the native destinations supported by Converge are not enough for your requirements, the Custom HTML destination allows you to deploy arbitrary HTML code to your website.

Any HTML content (HTML, scripts, styles) can be injected into your website either during [initialization](#setup-script) or in response to an [event](#event-scripts). Your custom HTML can also reference event variables allowing you to implement dynamic behavior based on those properties.

<Warning>
  Notice that any script added through the Custom HTML destination has full access to the website. In addition, scripts may affect performance and potentially break your website.

  As such, make sure to only add content that you trust and to always verify your changes.
</Warning>

***

## Installation instructions

1. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.
2. Select the **Custom HTML** destination and click **Next**.
3. Give your destination a **name** (e.g. Custom HTML Destination) and click **Next**.
4. In **Setup script**, fill in the setup script (if any).
5. In **Event scripts**, click **Add Event Script**
6. In **Event name**, select the desired event to trigger the script.
7. In **Event script**, fill in the script you want to trigger.
8. Click **Next**.
9. Select the sources you want to trigger the Custom HTML, then click **Next**.
   <Note>This is a client-side destination, meaning that only client-side sources can be used with this destination. You can still select server-side sources but the events will not trigger the Custom HTML.</Note>
10. Review any issues and click **Submit**.

***

## Definitions

### HTML Content

Any arbitrary HTML can be used, including text, images, styles, and Javascript. The HTML content is dynamically injected into your website by the [Converge pixel](/sources/website-integrations/converge-pixel). The content can be injected into your website either during [initialization](#setup-script) or in response to an [event](#event-scripts). Regardless of the timing, the content will always be added as the last element of the `<body>` tag of your page.

<Info>
  The HTML content follows the same structure as a normal HTML file. As such, always make sure to wrap Javascript code with the `<script>` tag. Otherwise, the content will be rendered as normal text content rather than executed.
</Info>

### Setup script

Defines a custom HTML that is injected into your website upon initialization. As soon as the [Converge pixel](/sources/website-integrations/converge-pixel) is initialized, this content will be injected into your website.

It can be used to add any custom HTML content or execute a script that doesn't depend on any action from the user. For example, to install a pixel/snippet that is not provided natively by Converge or to make any necessary preparation for the handling of events by an [Event script](#event-scripts).

#### Examples

<Accordion icon="clipboard" title="Install PostHog">
  ```Markup Custom HTML theme={null}
  <script>
      !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
      posthog.init('<ph_project_api_key>', {api_host: "<ph_instance_address>"})
  </script>
  ```
</Accordion>

<Accordion icon="clipboard" title="Install Hotjar">
  ```Markup Custom HTML theme={null}
  <script>
      (function(h,o,t,j,a,r){
          h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
          h._hjSettings={hjid:<hjid>,hjsv:<hjsv>};
          a=o.getElementsByTagName('head')[0];
          r=o.createElement('script');r.async=1;
          r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
          a.appendChild(r);
      })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
  </script>
  ```
</Accordion>

### Event scripts

Defines a custom HTML that is injected into your website when a given event occurs. Event scripts are always linked to exactly one **Event** type. The custom HTML will be injected into your website whenever (potentially multiple times) the configured event occurs.

It can be used to add any custom HTML content or execute a script as soon as an event has occurred. For example, to send an event to a pixel/tag that is not provided natively by Converge.

Event scripts can also reference event [variables](#variables).

<Note>
  Note that the Custom HTML destination can only be triggered by events that are implemented client-side. If your event is solely tracked server-side, it will not be compatible with the Custom HTML destination.
</Note>

#### Examples

<Accordion icon="clipboard" title="Viewed Product">
  ```Markup Custom HTML theme={null}
  <script>
  console.log('Viewed Product', {
      product: {
          productId: {{ product_id }},
          productName: {{ name }},
          productPrice: {{ price }}
      },
  })
  </script>
  ```
</Accordion>

<Accordion icon="clipboard" title="Placed Order">
  ```Markup Custom HTML theme={null}
  <script>
  var items = {{ items }} || []
  console.log('Placed Order', {
      totalPrice: {{ total_price }},
      itemsCount: items.reduce((total, item) => total + item.quantity, 0),
      products: items.map(item => ({
          productId: item.product_id,
          productName: item.name,
          productPrice: item.price
      }))
  })
  </script>
  ```
</Accordion>

### Variables

When using [Event scripts](#event-scripts), it's possible to reference event properties by making use of variables. These variables are referenced by wrapping the variable name with double braces: `{{ variable_name }}`.

For each occurrence of an event linked to a Custom HTML script, Converge will resolve all the referenced variables, replace the variables in the template and finally inject the resulting content.

The available variables depend on the selected Event type. For the native events, the list of available properties and their types can be found in the [event spec](/sources/converge-spec). For custom events, all properties sent in the events are available for usage automatically.

As an example, for the **Place Order** event, the following variables are available (among others):

| Property                | Type        | Template                 | Injected                     |
| :---------------------- | :---------- | ------------------------ | ---------------------------- |
| **id**                  | **string**  | `{{ id }}`               | `"123"`                      |
| **total\_price**        | **float**   | `{{ total_price }}`      | `123`                        |
| **items**               | **array**   | `{{ items }}`            | `[{"product_id": ...}, ...]` |
| **\$is\_new\_customer** | **boolean** | `{{ $is_new_customer }}` | `true`                       |

<Note>
  Notice that variables can be undefined. As such, it's important to always validate the variable value to avoid runtime errors. This can be done, for example:

  * by checking the value directly. e.g.

  ```
  if ({{ variable_name }} != null) { ... }
  ```

  * by providing a default value, e.g.

  ```
  var items = {{ items }} || []
  ```

  * or any other pattern you may prefer.
</Note>

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature        |       Supported       |
| :---------------------- | :-------------------: |
| Custom Events           | <Icon name="xmark" /> |
| Filters                 | <Icon name="xmark" /> |
| Server-side Conversions | <Icon name="xmark" /> |


# Customer.io
Source: https://docs.runconverge.com/destinations/integrations/customerio

An introduction to the Customer.io Destination

## Overview

Destination Type: <IconText name="server" />

***

## Installation instructions

1. Navigate to your <OutboundLink />.

2. On the left sidebar of the dashboard, click on **Data & Integration** and then on **Integrations**.

<Frame>
  <img alt="customerio-1" />
</Frame>

3. Under the **Directory**-tab, type in **customer.io**.

4. Click on **Customer.io API** labeled Data In.

<Frame>
  <img alt="customerio-1" />
</Frame>

5. Copy the **API Key**, you will need it later.

<Frame>
  <img alt="customerio-1" />
</Frame>

6. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

7. Select the **Customer.io** destination and click **Next**.

8. Give your destination a **name** (e.g. Customer.io Destination) and click **Next**.

9. Fill in the **Private API Key** you copied from **Customer.io** and click **Test Connection**.

10. Back in the Customer.io dashboard, click on **Test Connection**

11. Click on **Complete Setup**

<Frame>
  <img alt="customerio-1" />
</Frame>

12. Back in Converge, click **Next**.

13. Select **Use default mapping** and click **Next**.

14. Select the sources you want to forward events from, then click **Next**.

15. Review any issues and click **Submit**.

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature        |       Supported       |
| ----------------------- | :-------------------: |
| Custom Events           | <Icon name="check" /> |
| Filters                 | <Icon name="check" /> |
| Server-side Conversions | <Icon name="xmark" /> |


# Meta Ads (Facebook Ads)
Source: https://docs.runconverge.com/destinations/integrations/facebook

An introduction to the Meta/Facebook Ads Destination

## Overview

Destination Type: <IconText name="browser" />  and <IconText name="server" />

* Includes support for the <OutboundLink />

***

## Installation instructions

1. Navigate to your [Facebook Events Manager](https://business.facebook.com/events_manager2).

2. From your Events Manager, **click on the Facebook Pixel** you would like to connect.

3. In the Facebook Pixel menu, choose the **Settings** subtab.

4. From this subtab, you can find your **Pixel ID**, and copy it -- you will need it in a later step.

<Warning>
  Ensure that the **Track events automatically without code** setting is turned off in the **Event Setup** subtab.
  This can lead to over-reporting of events and incorrect conversion values.
</Warning>

5. Scroll down in the Settings subtab until you find **Generate access token**, and click on it. Copy this token as well.

6. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

7. Select the **Meta Ads (Facebook Ads)** destination and click **Next**.

8. Give your destination a **name** (e.g. Meta Ads Destination) and click **Next**.

9. Fill in the **Pixel ID** and **Access Token** you copied from **Facebook** and click **Next**.

10. Fill in your homepage domain name in the **Your Domain name** field, it does not need to include `https://`. Click **Next**.

11. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the Meta Ads (Facebook Ads) destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

12. Select the sources you want to forward events from, then click **Next**.

13. Review any issues and click **Submit**.

<Warning>
  Set this destination to **Deactivated** while you remove your existing Facebook tracking setup. Running both in parallel leads to duplicate conversion data. Follow the **Turn off your old Facebook tracking** instructions below, then set the destination to **Active** when you're ready.
</Warning>

***

## Turn off your old Facebook tracking

### Turning off the Shopify Facebook Sales Channel data sharing

1. Navigate to your <OutboundLink />.

2. Click on **Sales channels** and choose **Facebook & Instagram** from the *Installed sales channels* menu.

3. Click on **Settings**.

   <Frame>
     <img alt="settings-facebook" />
   </Frame>

4. Click on **Change** in the **Share data** submenu.

   <Frame>
     <img alt="settings-facebook-1" />
   </Frame>

5. Turn the **Share data** switch **off** (it should be gray) and press **Save**.

   <Frame>
     <img alt="settings-facebook-2" />
   </Frame>

***

## Modify your Content ID

The Converge Meta Ads Destination will use the **Default** content mode to define the Content ID forwarded by default.
However, you can configure the destination to use explicitly the **Product ID**, the **Variant ID** or **SKU** instead.

1. Navigate to your Meta Ads Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of Content ID Modes**

| Content ID Mode | Behavior                                                          |
| --------------- | ----------------------------------------------------------------- |
| Default         | Use the `variant_id` if available, otherwise use the `product_id` |
| Product Id      | Always use the `product_id`                                       |
| Variant Id      | Always use the `variant_id`                                       |
| SKU             | Always use the `sku`                                              |

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| :--------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## FAQ

<AccordionGroup>
  <Accordion title="Why do I see a Duplicate Pixel ID warning in my console?">
    If you are a Shopify store, Converge needs to load both a `theme.liquid` pixel and a Shopify Custom Pixel to track reliably.
    See the [FAQ in the Shopify Integration](/sources/website-integrations/shopify#faq) for more detailed information.

    Converge makes sure that no duplicate events get sent, even though the Facebook Pixel needs to be loaded in two separate places for complete event coverage.

    <Note> If you are not using the Shopify Web integration, you might have an old pixel installed using a different tracking method, and you should turn this one off.</Note>
  </Accordion>

  <Accordion title="Why do I see &#x22;increase coverage&#x22;-warnings in my Events Manager?">
    <Frame>
      <img alt="increase-coverage" />
    </Frame>

    Meta is warning you here that not all of your events are receiving identifiable information (e.g. `email`).
    Ideally, Facebook would have an email for every Added To Cart that ever happens on your website so they can easily attribute it.

    However, many people on the website are anonymous (they have never given their email to your store and thus Converge cannot track it). If the user never gives their email or address, then we can never send that email back.

    **Converge sends as many of these parameters as there are available.**

    The only events where you'd expect a very high email match rate are events where the user always has to give an email (e.g., `purchase`).

    For all events where certain parameters are not always available (e.g., you don't expect all `AddToCart` or an `InitiateCheckout` to have an `email`), you can safely ignore this warning.
  </Accordion>

  <Accordion title="Why is my Click ID (fbc) percentage low?">
    <Frame>
      <img alt="Facebook Click ID (fbc)" />
    </Frame>

    When inspecting the Event match quality score in Meta Events Manager, it's common to see a low percentage for the `Click ID (fbc)` parameter. In most cases, this is an expected value given how the `fbc` parameter works.

    The `Click ID (fbc)` is a parameter generated by Meta that's added to the URLs of your ads and used by Meta to track and identify events and conversions. See <OutboundLink /> for additional information.

    In an extreme scenario where all of your visitors arrive from a Meta ad, the `Click ID (fbc)` parameter would be present in 100% of your events.

    Not all your traffic will originate from Meta, though. Users can reach your store through, for example, search engines, other ad platforms, or even directly. This traffic won't contain the `fbc` parameter in the URL, as it's exclusive to Meta ads.

    Given that, consider another extreme scenario where none of your traffic originates from Meta ads—it's expected that `Click ID (fbc)` would be zero.

    Overall, you should expect the percentage of `Click ID (fbc)` to be directly related to the percentage of traffic your store receives that originates from Meta ads.

    In summary, if your store uses multiple marketing channels with no particular focus on Meta, it's expected to see low percentages for the `Click ID (fbc)` parameter. On the other hand, if your store relies heavily on Meta with a majority of your traffic coming through it, you should expect higher percentages.
  </Accordion>

  <Accordion title="How do I use the NewCustomerPurchase event?">
    Converge automatically sends the `NewCustomerPurchase` event to Facebook. To start using it for reporting and optimization, you need to create a custom conversion in Facebook Events Manager.

    We have a guide on setting up this custom event in the Meta Ads Manager [here](/guides/set-up-nc-purchase).
  </Accordion>

  <Accordion title="Why do I see &#x22;update recommended&#x22; warnings about IPv6 addresses in the Events Manager?">
    <Frame>
      <img alt="update-recommended" />
    </Frame>

    Meta asks you to send an IP Address as part of the Event Matching parameters when you send over events. There are currently two versions of IP addresses in use: IPv4 and IPv6.

    Both are still widely in use, but the IPv6 standard is newer, which is why Meta flags that it's still receiving IPv4 addresses. Converge supports IPv6 and sends IPv6 addresses whenever they're available.

    However, there's not always an IPv6 address available. In that case, Converge sends the IPv4 address instead. The IP address version is dependent on the customer's browser and network configuration. If the customer's network configuration and browser only support IPv4, then Converge will need to send an IPv4 address as well.

    Note that Meta does accept IPv4 addresses—it just wants to make sure that all advertisers support IPv6 as well. Therefore, you can safely ignore this warning.
  </Accordion>

  <Accordion title="The Facebook Ads manager is over-reporting conversions and/or the conversion value is wrong.">
    Confirm the following steps to troubleshoot:

    * The Facebook pixel is correctly configured. When the Facebook **Automatic Events** are enabled, Facebook tracks purchases automatically across your website—typically with a wrong AOV. This is a common source of over-reporting. You can turn this off in the Facebook Events Manager under **Settings** > **Event setup** > **Track events automatically without code**.
    * Converge is the only active Facebook integration. In the Converge destination logs, you can recognize it as **External** pixel events. Make sure all other Facebook tracking integrations other than Converge are turned off. See [here](#turn-off-your-old-facebook-tracking).
    * Converge tracks the correct number of `Placed Order` events. Compare the **Attribution** > **Orders** numbers with your backend.
    * The correct dataset is linked to your Facebook ads. The dataset ID should match your Converge destination configuration.

    If none of the above provides a solution to your problem, take a closer look at the **Facebook Events Manager**. Verify the Purchase event by looking at the number of events arriving from the server and browser, and the sampled activities.
  </Accordion>
</AccordionGroup>

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Meta spec.

| Converge Event Name                                                                               | Meta Event Name                         |
| ------------------------------------------------------------------------------------------------- | --------------------------------------- |
| [\$page\_load](/sources/converge-spec#page-load)                                                  | `PageView`                              |
| [Viewed Product](/sources/converge-spec#viewed-product)                                           | `ViewContent`                           |
| [Viewed Collection](/sources/converge-spec#viewed-collection)                                     | `ViewContent`                           |
| [Added To Cart](/sources/converge-spec#added-to-cart)                                             | `AddToCart`                             |
| [Added To Wishlist](/sources/converge-spec#added-to-wishlist)                                     | `AddToWishlist`                         |
| [Started Checkout](/sources/converge-spec#started-checkout)                                       | `InitiateCheckout`                      |
| [Added Payment Info](/sources/converge-spec#added-payment-info)                                   | `AddPaymentInfo`                        |
| [Placed Order](/sources/converge-spec#placed-order)                                               | `Purchase`                              |
| [Started Subscription](/sources/converge-spec#started-subscription)                               | `Subscribe`                             |
| [Activated Subscription](/sources/converge-spec#activated-subscription)                           | `Subscribe`                             |
| [Placed Recurring Subscription Order](/sources/converge-spec#placed-recurring-subscription-order) | `RecurringSubscriptionPaymentSucceeded` |
| [Cancelled Subscription](/sources/converge-spec#cancelled-subscription)                           | `CancelSubscription`                    |
| [Subscribed To Newsletter](/sources/converge-spec#subscribed-to-newsletter)                       | `Lead`                                  |
| [Searched](/sources/converge-spec#searched)                                                       | `Search`                                |
| [Searched for Store](/sources/converge-spec#searched-for-store)                                   | `FindLocation`                          |

This integration also auto-tracks some additional events that are not part of the Meta Base Spec but are so heavily requested that we automatically forward them.

| Converge Event Name                                                       | Meta Event Name       |
| ------------------------------------------------------------------------- | --------------------- |
| [Placed Order](/sources/converge-spec#placed-order)  (New Customers Only) | `NewCustomerPurchase` |
|                                                                           |                       |

<Warning>
  To track custom conversion events in Converge, you must first set up the corresponding custom conversions in the [Facebook Ad Manager](https://www.facebook.com/events_manager2/custom_conversions). Without setting up these custom conversions, Converge will be unable to display the associated metrics.
</Warning>


# Google Analytics 4
Source: https://docs.runconverge.com/destinations/integrations/ga4

An introduction to the GA4 Destination

## Overview

Destination Type: <IconText name="browser" />  and <IconText name="server" />

* Includes support for <OutboundLink />
* Includes support for <OutboundLink />

***

## Installation instructions

1. Navigate to your GA4 Property and choose <IconText name="gear" /> > **Data collection and modification** > **Data streams**.

2. If you do not have a data stream yet, you should click **Add stream** > **Web**. If you do have a data stream already, you should click on the datastream.

3. Copy the **Measurement ID** from the top right corner. You will need it later.

4. Click on **Measurement Protocol API secrets** on the same page.

   <Info> If you do not see the Measurement Protocol API secrets option, this means that you do not have `Edit` permissions for this GA4 Property.  </Info>

5. Click on **Create** to generate a new secret, and give it the name Converge. After creating, copy the **Secret value**.

6. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

7. Select the **Google Analytics 4** destination and click **Next**.

8. Give your destination a **name** (e.g. GA4 Destination) and click **Next**.

9. Fill in the **Measurement ID** and **Measurement Protocol API Secret** you copied from **GA4** and click **Next**.

10. Keep the defaults on the Configuration page and click **Next**.

11. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the Google Analytics 4 destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

12. Select the sources you want to forward events from, then click **Next**.

13. Review any issues and click **Submit**.

<Warning>
  Set this destination to **Deactivated** while you remove your existing GA4 tracking setup. Running both in parallel leads to duplicate conversion data. Follow the **Turn off your old GA4 tracking** instructions below, then set the destination to **Active** when you're ready.
</Warning>

***

## Turn off your old GA4 tracking

### Turning off the Shopify Google Sales Channel data sharing

1. Navigate to your <OutboundLink />.

2. Click on **Sales channels** and choose **Google & YouTube** from the *Installed sales channels* menu.

3. Click the **Google Analytics** tab. Then click the **...** menu and select **Manage settings**.

   <Frame>
     <img alt="settings-google-0" />
   </Frame>

4. Click **Disconnect** next to **Google Analytics**.

   <Frame>
     <img alt="settings-google-1" />
   </Frame>

***

## Configuration Options

The following options can be configured in the Destination Configuration.

***

#### Modify your Content ID

The Converge GA4 Destination will use the **Default** content mode to define the Content ID forwarded by default.
However, you can configure the destination to use explicitly the **Product ID**, the **Variant ID** or **SKU** instead.

1. Navigate to your GA4 Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of Content ID Modes**

| Content ID Mode | Behavior                                                          |
| --------------- | ----------------------------------------------------------------- |
| Default         | Use the `variant_id` if available, otherwise use the `product_id` |
| Product Id      | Always use the `product_id`                                       |
| Variant Id      | Always use the `variant_id`                                       |
| SKU             | Always use the `sku`                                              |

#### Connection Type

How Converge forwards events to Google Analytics 4.
Options include:

* **Client-side**: loads the `gtag` and sends every Converge event client-side.
* **Server-side**: loads the `gtag` and sends every Converge event (except for `$page_load`) server-side through the Measurement Protocol.
* **Server-side GTM (Recommended)**: loads the `gtag` in a server-side GTM container, and sends server-side conversions through the Measurement Protocol.

#### Custom Events

The GA4 destination supports setting up custom events, see [here](/destinations/event-mapping) for a deep-dive.

When the (recommended) sGTM mode is selected, there are two additional configuration options for each custom event:

* **Client** or **Server**.
  Configure where the custom event is sent from.
  By default, custom events are triggered from the browser.
  In some cases, you may want to trigger the event from the server instead.
  This is useful for events that are exclusively sent server-side to Converge.
* **Event** or **Conversion**.
  Choose whether the custom event should be marked as a conversion in GA4.

#### Custom Event Properties

Converge allows you to map properties that were tracked on a source from Converge into a custom property in Google Analytics 4.

<AccordionGroup>
  <Accordion title="Forward a custom event property to GA4">
    <Note>
      We **do not allow nested event properties** to be forwarded as a custom property.

      <Accordion title="Expand for more information">
        I.e. if the event properties look like this:

        ```json theme={null}
        {
        property_1: "value", 
        items: {
              property_2: "value_2"
           }
        }
        ```

        then we do support forwarding `property_1` as a custom property, but we do not support forwarding `property_2`.
      </Accordion>
    </Note>

    <Steps>
      <Step title="Set up the forwarding rule in Converge">
        1. Navigate to the <OutboundLink />, and click on the GA4 Destination.
        2. Navigate to the **Configuration** > **Advanced** sub-tab, and click on **Edit Configuration**.
        3. Click on  <IconText name="plus" />
        4. Choose the mapping from the Converge property to the desired GA4 property.

           <Frame>
             <img alt="custom event property map" />
           </Frame>
      </Step>

      <Step title="Set up a custom definition in GA4">
        5. Navigate to your Google Analytics Property and click on <IconText name="gear" /> > <br /> <IconText name="shapes" />
        6. Click on **Create custom dimension**.
        7. Fill in your desired **Dimension name** (this is how your dimension/property will show up in GA4), and choose **Event** as your Scope. Optionally add a description and choose the mapped property that you set up in *Step 4* to fill in **Event parameter**.

           <Frame>
             <img alt="custom event property map" />
           </Frame>
        8. Press **Save**
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

#### Custom Ecommerce Properties

You might want to add a custom property on the `items` array for ecommerce events as per the GA4 documentation [here](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce).
For example, you could include a custom `in_stock` parameter on all of the `item` arrays in your GA4 Ecommerce events.

The steps for setting up these custom properties are functionally similar to the steps described above in the [Custom Event Properties](#custom-event-properties)-paragraph.
The only distinction is that you should choose an `item-scoped custom dimension` in the GA4 <IconText name="shapes" /> settings.

#### Custom User Properties

You might want to forward a profile property as a custom user property.

The steps for setting up these custom properties are functionally similar to the steps described above in the [Custom Event Properties](#custom-event-properties)-paragraph.
The only distinction is that you should choose a `user-scoped custom dimension` in the GA4 <IconText name="shapes" /> settings.

#### Deploy a separate data layer for Converge

When enabled, Converge creates a new `dataLayer` object, even if there is already an existing `dataLayer` object. This makes sure that any existing implementation does not accidentally push events on the `dataLayer` object that Converge uses to forward events to its destinations.
When you use the `sGTM` connection type, Converge will always use a separate data layer.

#### Pass consent parameters on server-side events

When enabled, Converge makes sure to inject the Google Consent Parameters on server-side captured events as per the corresponding browser session.

***

## Cross-Domain tracking

If you need to track users across multiple domains you will need to set up cross-domain tracking in GA4.

1. Go to your **GA4 property**.
2. Go to **Admin**.
3. Go to **Data streams**.
4. Select your active data stream(s).
5. Click **Configure tag settings**.
6. Under Settings click **Configure your domains**.
7. Add the different domains the user will interact with.
8. Click **Save**.

GA4 will automatically add cross-domain tracking parameters to every link going from domain A to domain B.

<Note>If you also want cross-domain tracking in Converge. You can follow these [instructions](/sources/website-integrations/converge-pixel#cross-domain-tracking).</Note>

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## FAQ

<AccordionGroup>
  <Accordion title="Why do I see a lot of events with a Skipped status in the Destination Log?">
    Google Analytics 4 does not natively deduplicate events that are being sent from **both** the server and the browser.

    As such, the Converge destination will automatically not forward the **server** copy of the event and only send the browser copy of the event.

    These server-side copies will show up with a `Skipped` status in the Destination Log. However, the event will still arrive in GA4 through the browser-side copy.
  </Accordion>

  <Accordion title="Why do I see a discrepancy between purchases in GA4 and Placed Orders in Converge?">
    If you see a discrepancy, check the following:

    1. Make sure that your GA4 property and your Converge dashboard are in the same time zone. There might be a difference due to timezone misalignment.
    2. Verify that you have no active <OutboundLink /> that are filtering out certain purchases. You can check this in the <OutboundLink />.
    3. Make sure that you configured the [connection type](#connection-type) for this destination to be sGTM or server-side. If you're only tracking client-side, then your purchases might not get tracked due to ad blockers and tag-loading issues.
    4. Verify that you've **disabled** "Collect automatically detected user-provided data" under <IconText name="gear" /> > <IconText name="database" />.
    5. If your cookie banner informs Converge that the user hasn't given consent, then Converge will pass this `denied` consent parameter to GA4 and GA4 will drop this purchase. You can verify whether this is the case by inspecting the GA4 Destination Logs for the `Placed Order` events. If you find a `denied` consent parameter under the profile properties, it means that your cookie banner passed a `denied` status for these purchases.
       <Frame>
         <img alt="img" />
       </Frame>
  </Accordion>

  <Accordion title="How to configure cross-domain tracking in GA4?">
    If your customer journey goes through multiple domains (e.g. landing pages or checkout on a different domain), it is important to configure this in GA4 to avoid broken customer journey reports.

    You can configure cross-domain tracking through the following steps:

    1. Go to <IconText name="gear" /> > **Data collection and modification** > **Data streams**.
    2. Select your data stream > **Configure tag settings** > **Configure your domains**.
    3. You have now arrived at the Cross-domain Linking Configuration. In some cases, GA4 will already provide you with some suggestions. If not, then you can add your domains by adding a condition. When setting up a condition, make sure that you use the **Contains** match type.
    4. Save your changes.
  </Accordion>

  <Accordion title="Why do I see redundant &#x22;Viewed Product&#x22; and &#x22;Added Product&#x22;-events arriving in my GA4 property?">
    This is most likely a legacy Universal Analytics property/pixel that is streaming events into your new GA4 property.

    1. Navigate into your old Universal Analytics Property (usually you can do this by clicking on your GA4 property and then choosing the property whose property ID starts with `UA-`)
       <Frame>
         <img alt="ua-1" />
       </Frame>

    2. Click on **Admin** > **GA4 Setup Assistant**.
       <Frame>
         <img alt="ua-2" />
       </Frame>

    3. Make sure that your Google Analytics 4 property is **not connected**.
  </Accordion>

  <Accordion title="Does Converge support the GA4 user ID feature?">
    Converge does not integrate with the GA4 user ID. This is a conscious decision because it leads to downstream data accuracy issues.

    Capturing the GA4 user ID limits the number of anonymous sessions captured for a customer to one. Therefore, it doesn't make sense to capture this in a marketing attribution context where as much anonymous activity as possible should be captured.

    For example, when an entirely new visitor visits your website, the following activity could be captured:

    * They land on your website after clicking on a Facebook ad.
    * Later in the day, they search Google for your product.
    * They place a purchase, and the user ID is captured.

    In the above case, only the Google session would be attributed to the user ID, and the Facebook session remains anonymous. When the user ID option is not used, all sessions are captured and attributed to the correct source.
  </Accordion>
</AccordionGroup>

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Google Analytics 4 spec.

| Converge Event Name                                                                               | GA4 Event Name         |
| ------------------------------------------------------------------------------------------------- | ---------------------- |
| [\$page\_load](/sources/converge-spec#page-load)                                                  | `page_view`            |
| [Viewed Product](/sources/converge-spec#viewed-product)                                           | `view_item`            |
| [Viewed Collection](/sources/converge-spec#viewed-collection)                                     | `view_item_list`       |
| [Added To Cart](/sources/converge-spec#added-to-cart)                                             | `add_to_cart`          |
| [Added To Wishlist](/sources/converge-spec#added-to-wishlist)                                     | `add_to_wishlist`      |
| [Removed From Cart](/sources/converge-spec#removed-from-cart)                                     | `remove_from_cart`     |
| [Removed From Wishlist](/sources/converge-spec#removed-from-wishlist)                             | `remove_from_wishlist` |
| [Viewed Cart](/sources/converge-spec#viewed-cart)                                                 | `view_cart`            |
| [Started Checkout](/sources/converge-spec#started-checkout)                                       | `begin_checkout`       |
| [Added Payment Info](/sources/converge-spec#added-payment-info)                                   | `add_payment_info`     |
| [Added Contact Info](/sources/converge-spec#added-contact-info)                                   | `add_contact_info`     |
| [Added Shipping Info](/sources/converge-spec#added-shipping-info)                                 | `add_shipping_info`    |
| [Placed Order](/sources/converge-spec#placed-order)                                               | `purchase`             |
| [Started Subscription](/sources/converge-spec#start-subscription)                                 | `start_subscription`   |
| [Placed Recurring Subscription Order](/sources/converge-spec#placed-recurring-subscription-order) | `renew_subscription`   |
| [Received Refund](/sources/converge-spec#received-refund)                                         | `refund`               |
| [Logged In](/sources/converge-spec#logged-in)                                                     | `login`                |
| [Signed Up](/sources/converge-spec#signed-up)                                                     | `sign_up`              |
| [Select Product](/sources/converge-spec#select-product)                                           | `select_item`          |
| [Choose Option](/sources/converge-spec#choose-option)                                             | `select_item`          |
| [Searched](/sources/converge-spec#searched)                                                       | `search`               |


# Google Ads - Conversion tracking (Browser)
Source: https://docs.runconverge.com/destinations/integrations/google-ads-conversions

An introduction to the Google Ads client-side conversion tracking destination

## Overview

Destination Type: <IconText name="browser" />

* Includes support for <OutboundLink />
* Includes support for <OutboundLink />

***

## Installation instructions

<Note>
  This is a client-side destination, meaning that you must track all events client-side (including `Placed Order` and `Started Subscription`) for this destination to work properly.

  If you want to set up a Google Ads conversion for a server-side tracked event, use the [Google Ads - Server-side Conversion Tracking](/destinations/integrations/google-ads-conversions-server-side) destination instead.
</Note>

<Steps>
  <Step icon="list" title="Get Tag ID & Conversion Label(s)">
    1. Navigate to your Google Ads Dashboards and choose **Goals > Summary**.
       <Frame>
         <img alt="gads-1" />
       </Frame>
        

    2. Choose <IconText name="plus" />
       <Frame>
         <img alt="gads-2" />
       </Frame>
        

    3. Choose **Conversions on a website**.

       <Frame>
         <img alt="gads-3" />
       </Frame>

       <Note>
         Google Ads sometimes skips this step and goes directly to step 2. In this case, click **Back** at the bottom of the page.

         <Frame>
           <img alt="gads-warning" />
         </Frame>
       </Note>

       <Note>
         Google Ads might propose a GA4 tag instead of a G-tag. Choose **Edit**, scan your website and select the Google Tag.

         <Frame>
           <img alt="gads-warning" />
         </Frame>
       </Note>

        

    4. Choose **Purchase** from the list of conversion actions.
       <Frame>
         <img alt="gads-5" />
       </Frame>
        

    5. Click on **Add conversion actions** and select your Google Tag.
       <Frame>
         <img alt="gads-2" />
       </Frame>
        

    6. Select **Set up manually using code**.
       <Frame>
         <img alt="gads-2" />
       </Frame>
        

    7. Open the Conversion settings and pick a name for your conversion: e.g. `[Converge] Purchase`. Then click on **Done**.
       <Frame>
         <img alt="gads-2" />
       </Frame>
        

    8. Click **Save and continue**.
       <Frame>
         <img alt="gads-3" />
       </Frame>

    9. Click on **See event snippet**.
       <Frame>
         <img alt="gads-3" />
       </Frame>

    [//]: # "cspell:disable-next-line"

    10\. Copy the **Tag ID** and the **Conversion ID**, in this example the Tag ID is `AW-11288325266`; the Conversion ID is `5CTkCNPJvIcZEJLZ2IYq`. You will need both for the Converge destination.
     

    <Frame>
      <img alt="gads-4" />
    </Frame>
  </Step>

  <Step icon="list" title="Set up the destination">
    10. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

    11. Select the **Google Ads - Conversion tracking** destination and click **Next**.

    12. Give your **destination** a name (e.g. Google Ads - Conversion Destination) and optional **description** and click **Next**.

    13. Copy the **Tag ID** you found earlier in the **Tag ID field** and click **Next**.

    14. Click on <IconText name="plus" /> and select Placed Order as the source event.

    15. In the Forward As value copy the **Tag ID** and the **Conversion Label** separated by a `/`. From our example it would be `AW-11288325266/5CTkCNPJvIcZEJLZ2IYq`

    16. Select **Client** as the Forwarding Mode and click **Next**.

    <Frame>
      <img alt="gads-4" />
    </Frame>

    17. Select the sources you want to forward events from, then click **Next**.

    <Note>This is a client-side destination, meaning that only client-side sources can be used with this destination. You can still select server-side sources but the events will not be sent to Google Ads.</Note>

    18. Review if there are any issues found in your setup and click **Submit**.
  </Step>

  <Step title="Activate enhanced conversions" icon="sparkles">
    11. In the sidebar, click on **Goals** > **Settings**.

    <Frame>
      <img alt="gads-5" />
    </Frame>

    12. Choose **Enhanced conversions** from the list of dropdowns.

    <Frame>
      <img alt="gads-5" />
    </Frame>

    13. Check the box next to **Turn on enhanced conversions** and pick **Google tag**, then click **Save**.

    <Frame>
      <img alt="gads-5" />
    </Frame>
  </Step>
</Steps>

<Warning>
  Set this destination to **Deactivated** while you remove your existing Google Ads tracking setup. Running both in parallel leads to duplicate conversion data. Follow the **Turn off your old Google Ads tracking** instructions below, then set the destination to **Active** when you're ready.
</Warning>

<Warning> Converge automatically loads the AW tag on all pages. If you already have an AW tag with the same tag ID in GTM, pause or remove it to prevent tracking conflicts. </Warning>

***

## Turn off your old Google Ads tracking

### Turning off the Shopify Google Sales Channel data sharing

1. Navigate to your <OutboundLink />.

2. Click on **Sales channels** and choose **Google & YouTube** from the *Installed sales channels* menu.

3. Click the **Google Ads** tab. Then click the **...** menu and select **Manage settings**.

   <Frame>
     <img alt="settings-googleads-0" />
   </Frame>

4. Click **Disconnect** next to **Google Ads**.

   <Frame>
     <img alt="settings-googleads-1" />
   </Frame>

***

## Set up additional conversions

This section explains how to set up conversions for auxiliary events like **Added to Cart** and **Started Checkout**.

<Warning>
  Before setting up additional conversions, make sure you have the **Converge Google Ads - Conversion tracking destination** and the **Converge Purchase conversion** configured. If not, follow the [Installation instructions](#installation-instructions) first.
</Warning>

1. Open your **Google Ads Dashboard** and go to **Goals > Summary**.

   <Frame>
     <img alt="gads-1" />
   </Frame>

2. Click <IconText name="plus" />.

   <Frame>
     <img alt="gads-2" />
   </Frame>

3. Select **Conversions on a website**, confirm a **Google Tag** is already connected, and click **Continue**.

   <Frame>
     <img alt="gads-3" />
   </Frame>

4. Choose the conversion type that best matches your event.\
   *Example: Select **Begin checkout** for a **Started Checkout** conversion.*

   <Frame>
     <img alt="gads-4" />
   </Frame>

5. Click **Set up** next to your **Google Tag**.

   <Frame>
     <img alt="gads-5" />
   </Frame>

6. Click **Create a manual event**, name your conversion (e.g., `[Converge] Begin Checkout`), and click **Use event**.

   <Frame>
     <img alt="gads-2" />
   </Frame>

7. Click **Save and continue**.

   <Frame>
     <img alt="gads-3" />
   </Frame>

8. Click **See event snippet**.

   <Frame>
     <img alt="gads-3" />
   </Frame>

9. Copy the **Conversion ID** (e.g., `5CTkCNPJvIcZEJLZ2IYq`).

   <Frame>
     <img alt="gads-4" />
   </Frame>

10. In your Converge dashboard, under Destinations, click on **Configuration** > **Event mapping** > **Add new mapping**.

11. Click on <IconText name="plus" /> and select the event you want as the source event.

12. In the Forward As value, copy the **Tag ID** and the **Conversion Label** separated by a `/`. From our example it would be `AW-11288325266/5CTkCNPJvIcZEJLZ2IYq`

13. Select **Client** as the Forwarding Mode.

14. Click **Save**.

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="xmark" /> |
| Server-side Conversions                              | <Icon name="xmark" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## Import server-side conversions in Google Ads through GA4

<Note>
  Looking for native server-side conversion tracking? Check out the [Google Ads - Server-side Conversion Tracking](/destinations/integrations/google-ads-conversions-server-side) destination.
</Note>

You can also get a Converge server-side event in Google Ads through the **GA4 import** functionality.

<Steps>
  <Step title="Make sure your conversion arrives in GA4">
    If your conversion event already exists in GA4 (e.g. when you want to import a `purchase` or `add_to_cart` -conversion), then you can move straight onto *Step 2*.

    If you are looking to set up a custom event as a conversion in Google (e.g. a `new_customer_purchase` -event), you should first make sure that your event is configured as a <OutboundLink /> in the GA4 Destination.
  </Step>

  <Step title="Import your GA4 event in Google Ads as a conversion">
    <Info> The steps below demonstrate importing the `new_customer_purchase` event. But you should import the event/conversion that applies to your use case. </Info>

    1. Navigate to your GA4 dashboard and click on the settings icon in the bottom left corner.
       <Frame>
         <img alt="ga-2" />
       </Frame>

    2. In the submenu, navigate to **Events**.
       <Frame>
         <img alt="ga-3" />
       </Frame>

    3. Under the Events submenu, go to **Recent events** and mark `new_customer_purchase` as a conversion, if you'd like to import any other conversions, then mark these too.
       <Frame>
         <img alt="ga-4" />
       </Frame>

    4. Go to **Attribution settings** on top of the Events page.
       <Frame>
         <img alt="ga-2" />
       </Frame>

    5. Under **Channels that can receive credit**, select **Google paid channels**
       <Frame>
         <img alt="ga-2" />
       </Frame>

    6. The custom conversion is now created in GA4, time to import it into Google Ads. Navigate to your Google Ads Dashboards and choose **Goals > Summary**.
       <Frame>
         <img alt="gads-1" />
       </Frame>
        

    7. Choose <IconText name="plus" />
       <Frame>
         <img alt="gads-2" />
       </Frame>
        

    8. Choose **Conversions on a website**.

       <Frame>
         <img alt="gads-3" />
       </Frame>

       <Note>
         Google Ads sometimes skips this step and goes directly to step 2. In this case, click **Back** on the bottom of the page.

         <Frame>
           <img alt="gads-warning" />
         </Frame>
       </Note>

       <Note>
         Google Ads might not show **via Google Analytics** as an option. Choose **Edit**, scan your website and select or link your GA4 property.

         <Frame>
           <img alt="gads-warning" />
         </Frame>
       </Note>

        

    9. Choose **Purchase** from the list of conversion actions.
       <Frame>
         <img alt="gads-5" />
       </Frame>
        

    10. Click on **Add conversion actions** and select your GA4 property.
        <Frame>
          <img alt="gads-2" />
        </Frame>
         

    11. Select **new\_customer\_purchase** event and click **Select events**.
        <Frame>
          <img alt="gads-warning" />
        </Frame>
         

    12. Click **Save and continue**.
        <Frame>
          <img alt="gads-warning" />
        </Frame>
  </Step>
</Steps>

## Cross-Domain tracking

If you need to track conversions across multiple domains you will need to set up cross-domain tracking in your Google Ads account.

1. Go to your **Google Ads account**.
2. Go to **Tools** -> **Data manager**.
3. Find your Google tag and click **Manage**.
4. Under Settings click **Configure your domains**.
5. Add the different domains the user will interact with.
6. Click **Save**

Google Ads will automatically add cross-domain tracking parameters to every link going from domain A to domain B.

<Note>If you also want cross-domain tracking in Converge. You can follow these [instructions](/sources/website-integrations/converge-pixel#cross-domain-tracking).</Note>

***

## FAQ

<AccordionGroup>
  <Accordion title="Why are one or more of my campaigns not receiving conversion data since Converge?">
    If none of your campaigns are receiving any conversions, you likely did not configure your conversions correctly and should revise the [Installation instructions](#installation-instructions).

    If only some of your campaigns are not receiving conversions, then check the following:

    1. Make sure that the campaigns are still active and have significant ad spend
    2. Verify that you have set the **Goals** of all campaigns to **"Using Account settings"** in their respective campaign settings.
  </Accordion>

  <Accordion title="Can I have an existing (different) Google Ads Tag running side-by-side Converge?">
    In general, you should be OK running a separate Google Ads Tag and the Converge Google Ads Destination side-by-side.

    However, in rare cases, your existing Google Ads tag and the Converge Google Ads Destination can interfere with each other, especially when the *Deploy a separate data layer for Converge*-option is enabled.

    If you notice under-reporting of your conversions set up through the Converge Google Ads Destination and you have an existing Google Ads Tag installed on the website, turn this functionality off under **Advanced > Edit Configuration**.

    <Frame>
      <img alt="img" />
    </Frame>
  </Accordion>
</AccordionGroup>


# Google Ads - Conversion tracking (Server)
Source: https://docs.runconverge.com/destinations/integrations/google-ads-conversions-server-side

An introduction to the Google Ads server-side conversion tracking destination

## Overview

Destination Type: <IconText name="server" />

* Includes support for <OutboundLink />
* Includes support for <OutboundLink />
* Tags conversions for <OutboundLink />

***

## Installation instructions

<Note>
  This is a server-side destination, meaning that conversions are sent directly from Converge's servers to Google Ads. This is ideal for tracking events that happen on your backend, like subscription renewals or offline conversions.
</Note>

<Steps>
  <Step icon="list" title="Create a conversion action">
    1. Navigate to your Google Ads Dashboards and choose **Goals > Summary**.
       <Frame>
         <img alt="gads-1" />
       </Frame>
        

    2. Choose <IconText name="plus" />
       <Frame>
         <img alt="gads-2" />
       </Frame>
        

    3. Choose **Conversions offline**.
       <Frame>
         <img alt="gads-3" />
       </Frame>

    <Note>
      Google Ads sometimes skips this step and goes directly to step 2. In this case, click **Back** at the bottom of the page.

      <Frame>
        <img alt="gads-warning" />
      </Frame>
    </Note>

    4. Click **Edit data sources**, select **Skip this step and set up a data source later**, enable the checkbox under **Customer data** and click **Done**.

    <Note>
      If enhanced conversions for leads is disabled, also select **Turn on enhanced conversions for leads** and select **Google tag** as the method.

      <Frame>
        <img alt="gads-warning" />
      </Frame>
    </Note>

    5. Click **Save and continue**.

    6. Select a conversion category, click **Create conversion** and select the offline datasource if Google Ads hasn't created one already.

    7. Give your conversion a name (e.g., `[Converge] Server Purchase`) and configure the conversion settings.

    8. Click **Create and continue**.
  </Step>

  <Step icon="list" title="Set up the destination in Converge">
    1. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

    2. Select the **Google Ads API - Conversion tracking (Server)** destination and click **Next**.

    3. Give your **destination** a name (e.g., Google Ads - Server Conversion Destination) and optional **description** and click **Next**.

    4. Sign in with Google Ads and select the Google Ads account.

       a. Server-side conversion tracking requires customer data terms and enhanced conversions for leads to be enabled.
       If a setting is not approved, you'll see an error with a link to update your settings. Update the settings and come back to check.

       <Frame>
         <img alt="Google Ads server-side authentication error" />
       </Frame>

       <Note>
         If you see an error like this, check that you've granted the correct permissions and selected the right Google Ads account during authentication.
       </Note>

       b. If both settings are enabled, click **Next**.

       <Frame>
         <img alt="Google Ads server-side authentication valid settings" />
       </Frame>

    5. Configure your Google Ads tag ID. Additional settings are available in the advanced configuration. By default, the connection uses the product ID field and gross conversion amount.

       <Frame>
         <img alt="Google Ads server-side conversion configuration" />
       </Frame>

    6. Configure your event mappings.

       a. If you see "No conversion actions found," no conversion actions exist in Google Ads yet. Follow the installation instructions above to create conversion actions, then click **Retry** to load them.

       <Frame>
         <img alt="Google Ads server-side no conversion actions" />
       </Frame>

       b. If conversion actions exist, map your events to them using the dropdown. Only conversion actions labeled Import from clicks can be forwarded.

       <Frame>
         <img alt="Google Ads server-side with conversion actions" />
       </Frame>

    7. Select the sources you want to forward events from, then click **Next**.

    8. Review if there are any issues found in your setup and click **Submit**.
  </Step>
</Steps>

<Warning>
  Set this destination to **Deactivated** while you remove your existing Google Ads tracking setup. Running both in parallel leads to duplicate conversion data. Follow the **Turn off your old Google Ads tracking** instructions below, then set the destination to **Active** when you're ready.
</Warning>

<Warning>If you're also using the client-side Google Ads destination, make sure you don't track the same conversions in both destinations to avoid duplicate tracking.</Warning>

***

## Turn off your old Google Ads tracking

### Turning off the Shopify Google Sales Channel data sharing

1. Navigate to your <OutboundLink />.

2. Click on **Sales channels** and choose **Google & YouTube** from the *Installed sales channels* menu.

3. Click the **Google Ads** tab. Then click the **...** menu and select **Manage settings**.

   <Frame>
     <img alt="settings-googleads-0" />
   </Frame>

4. Click **Disconnect** next to **Google Ads**.

   <Frame>
     <img alt="settings-googleads-1" />
   </Frame>

***

## New customer acquisition

Converge automatically tags each `Placed Order` conversion with Google's `customer_type` field so you can bid differently on new and returning customers with <OutboundLink />.

* `NEW` when the order's [`$is_new_customer`](/sources/converge-spec#placed-order) property is `true`.
* `RETURNING` when it's `false`.

Converge sets `$is_new_customer` automatically for orders from supported shop platforms, so no extra configuration is needed.

<Note>
  Only the server-side Google Ads destination forwards `customer_type`. The client-side Google Ads destination doesn't support this.
</Note>

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## FAQ

<AccordionGroup>
  <Accordion title="Why are my server-side conversions not showing in Google Ads?">
    Server-side conversions can take up to 24 hours to appear in Google Ads reporting. If you don't see your conversions after 24 hours:

    1. Verify your Customer ID is correct
    2. Check that the Conversion ID and Label are properly formatted
    3. Review the destination logs in Converge for any errors
    4. Ensure the conversion action is set to "Active" in Google Ads
  </Accordion>
</AccordionGroup>


# Google Ads - Remarketing
Source: https://docs.runconverge.com/destinations/integrations/google-ads-remarketing

An introduction to the Google Ads - Remarketing Destination

## Overview

Destination Type: <IconText name="browser" />

* Includes support for the <OutboundLink />
* Includes support for <OutboundLink />

***

## Installation instructions

<Note>
  This is a client-side destination, meaning that you must track all events client-side (including `Placed Order` and `Started Subscription`) for this destination to work properly.

  If you want to set up a Google Ads conversion, then you should follow the instructions for our [Google Ads - Conversion tracking](/destinations/integrations/google-ads-conversions) destination.
</Note>

<Steps>
  <Step title="Get your Tag ID">
    1. Navigate to your Google Ads account

    2. Go to **Tools** -> **Data manager**

    3. Find your Google Tag and click **Manage**

    4. Find and copy your Tag ID on the top of the page underneath the name of your tag. It should have a pattern matching: AW-XXXXXXXXXX
  </Step>

  <Step title="Set up the destination">
    5. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

    6. Select the **Google Ads - Remarketing** destination and click **Next**.

    7. Give your **destination** a name (e.g. Google Ads Remarketing Destination) and optional **description** and click **Next**.

    8. Copy the **Tag ID** you found earlier in the **Tag ID field** and click **Next**.

    9. Keep the **Default mapping** or setup **Custom mapping** and click **Next**.

    <Note>You can find the Default mapping for this destination [here](/destinations/integrations/google-ads-remarketing#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

    10. Select the sources you want to forward events from, then click **Next**.

    <Note>This is a client-side destination, meaning that only client-side sources can be used with this destination. You can still select server-side sources but the events will not be sent to Google Ads.</Note>

    11. Review if there are any issues found in your setup and click **Submit**.
  </Step>
</Steps>

<Warning>
  Set this destination to **Deactivated** while you remove your existing Google Ads tracking setup. Running both in parallel leads to duplicate conversion data. Follow the **Turn off your old Google Ads tracking** instructions below, then set the destination to **Active** when you're ready.
</Warning>

<Warning> Converge automatically loads the AW tag on all pages. If you already have an AW tag with the same tag ID in GTM, pause or remove it to prevent tracking conflicts. </Warning>

***

## Turn off your old Google Ads tracking

### Turning off the Shopify Google Sales Channel data sharing

1. Navigate to your <OutboundLink />.

2. Click on **Sales channels** and choose **Google & YouTube** from the *Installed sales channels* menu.

3. Click the **Google Ads** tab. Then click the **...** menu and select **Manage settings**.

   <Frame>
     <img alt="settings-googleads-0" />
   </Frame>

4. Click **Disconnect** next to **Google Ads**.

   <Frame>
     <img alt="settings-googleads-1" />
   </Frame>

***

## Modify your Content ID

The Converge Google Ads - Remarketing Destination will use the **Default** content mode to define the Content ID forwarded by default.
However, you can configure the destination to use explicitly the **Product ID**, the **Variant ID** or **SKU** instead.

1. Navigate to your Google Ads - Remarketing Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of Content ID Modes**

| Content ID Mode | Behavior                                                          |
| --------------- | ----------------------------------------------------------------- |
| Default         | Use the `variant_id` if available, otherwise use the `product_id` |
| Product Id      | Always use the `product_id`                                       |
| Variant Id      | Always use the `variant_id`                                       |
| SKU             | Always use the `sku`                                              |

***

## Cross-Domain tracking

If you need to track users across multiple domains you will need to set up cross-domain tracking in your Google Ads account.

1. Go to your **Google Ads account**.
2. Go to **Tools** -> **Data manager**.
3. Find your Google tag and click **Manage**.
4. Under Settings click **Configure your domains**.
5. Add the different domains the user will interact with.
6. Click **Save**

Google Ads will automatically add cross-domain tracking parameters to every link going from domain A to domain B.

<Note>If you also want cross-domain tracking in Converge. You can follow these [instructions](/sources/website-integrations/converge-pixel#cross-domain-tracking).</Note>

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="xmark" /> |
| Server-side Events                                   | <Icon name="xmark" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## FAQ

<AccordionGroup>
  <Accordion title="Can I have an existing (different) Google Ads Tag running side-by-side Converge?">
    In general, you should be OK running a separate Google Ads Tag and the Converge Google Ads Destination side-by-side.

    However, in rare cases, your existing Google Ads tag and the Converge Google Ads Destination can interfere with each other, especially when the *Deploy a separate data layer for Converge*-option is enabled.

    If you notice under-reporting of your conversions set up through the Converge Google Ads Destination and you have an existing Google Ads Tag installed on the website, turn this functionality off under **Advanced > Edit Configuration**.

    <Frame>
      <img alt="img" />
    </Frame>
  </Accordion>
</AccordionGroup>

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Google Ads spec.

| Converge Event Name                                             | Google Ads Event Name |
| --------------------------------------------------------------- | --------------------- |
| [Viewed Product](/sources/converge-spec#viewed-product)         | `view_item`           |
| [Viewed Collection](/sources/converge-spec#viewed-collection)   | `view_item_list`      |
| [Added To Cart](/sources/converge-spec#added-to-cart)           | `add_to_cart`         |
| [Started Checkout](/sources/converge-spec#started-checkout)     | `begin_checkout`      |
| [Added Payment Info](/sources/converge-spec#added-payment-info) | `add_payment_info`    |
| [Placed Order](/sources/converge-spec#placed-order)             | `purchase`            |


# Klaviyo
Source: https://docs.runconverge.com/destinations/integrations/klaviyo

An introduction to the Klaviyo Destination

## Overview

Destination Type: <IconText name="browser" />  and <IconText name="server" />

***

## Installation instructions

1. Navigate to your <OutboundLink />.

2. In the left-bottom corner of the dashboard, click on your Klaviyo Workspace Name and then on <IconText name="gear" />

<Frame>
  <img alt="klaviyo-1" />
</Frame>

3. Under the **Account**-tab, choose **API keys**.

4. Copy your **Public API Key**, you will need it later.

5. Click on **Create Private API Key**

6. Give your key a name and select **Custom Key** in **Select Access Level**

7. Select **Read/Write Access** to the **Events** scope.

<Frame>
  <img alt="klaviyo-2" />
</Frame>

8. Press **Create**

9. Copy the newly created **Private API Key**, you will need it later.

10. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

11. Select the **Klaviyo** destination and click **Next**.

12. Give your destination a **name** (e.g. Klaviyo Destination) and click **Next**.

13. Fill in the **Public API Key** and **Private API Key** you copied from **Klaviyo** and click **Next**.

14. Keep the defaults on the Configuration page and click **Next**.

15. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the Klaviyo destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

16. Select the sources you want to forward events from, then click **Next**.

17. Review any issues and click **Submit**.

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="xmark" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## Using Converge to increase abandoned cart revenue on Klaviyo

You may already be using Klaviyo's abandoned cart flows based on the `Added To Cart` events and `Started Checkout` events tracked by the Klaviyo pixel on the browser.

However, Klaviyo's browser identification is based on a third-party cookie meaning that most customers will not be successfully identified after 7 days (see our section on <OutboundLink /> ).

```mermaid actions={false} theme={null}
flowchart LR

  id4("*User* visits website with Klaviyo cookie and **Subscribes to Newsletter**") -. 8 days later (Klaviyo cookie is lost).-> id5("*User* visits website without cookie and **Adds to cart**") ~~~ id6(["**Abandoned Cart Email** ✖"])
  style id6 color:#d40027,stroke:none

```

When Converge is set up with a first-party cookie, it can reliably re-identify customers past that 7-day mark (see: [Setting up a server-side first-party cookie](/sources/concepts/aliases#setting-up-a-server-side-first-party-cookie)).
Customers using our pre-built [Shopify](/sources/website-integrations/shopify) or [Magento](/sources/website-integrations/magento) integrations already have a first-party cookie as part of their Converge setup.

```mermaid actions={false} theme={null}
flowchart LR

  id4("*User* visits website with first-party cookie and **Subscribes to Newsletter**") -. 8 days later (Converge cookie stays).-> id5("*User* visits website with cookie and **Adds to cart**") ~~~ id6(["**Abandoned Cart Email** ✓"])
  style id6 color:#d40027,stroke:none

```

For most customers, we expect an abandoned cart revenue uplift of 20-50%.

## Adding product URL and image URL to Converge events to power Klaviyo flows

A common use case of the Klaviyo Destination is to build Klaviyo Email Flows based on Converge Events.
As such, you might want to include a Product URL or Product Image URL in the Converge Event so you can leverage these in your email flows.

To that end, you will want to extend the Converge event spec for the following events.
Once you add the custom properties to your events, Converge will automatically forward these to the Klaviyo Destination.

### Extending your Converge Event implementation for Klaviyo

Find code examples below that illustrate where **you should add the Product URL and Product Image URL custom event properties**.

<AccordionGroup>
  <Accordion title="Viewed Product" icon="code">
    See the original `Viewed Product` spec [here](/sources/converge-spec.mdx#viewed-product)

    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Viewed Product",
        properties: {
          product_id: "123456",
          variant_id: "78910", 
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla", 
          price: 42,
          currency: "USD",
          vendor: "My Store",
          url: "https://mystore.com/this-product", // This is new
          image_url: "https://mystore.com/assets/product.png" // This is new
        },
      });
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Added To Cart" icon="code">
    See the original `Added To Cart` spec [here](/sources/converge-spec.mdx#added-to-cart)

    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Added To Cart",
        properties: {
          product_id: "123456",
          variant_id: "78910",
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla",
          price: 42,
          currency: "USD",
          quantity: 1,
          vendor: "My Store",
          url: "https://mystore.com/this-product", // This is new
          image_url: "https://mystore.com/assets/product.png" // This is new
        },
      });

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Removed From Cart" icon="code">
    See the original `Removed From Cart` spec [here](/sources/converge-spec.mdx#removed-from-cart)

    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Removed From Cart",
        properties: {
          product_id: "123456",
          variant_id: "78910",
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla",
          price: 42,
          currency: "USD",
          quantity: 1,
          vendor: "My Store",
          url: "https://mystore.com/this-product", // This is new
          image_url: "https://mystore.com/assets/product.png" // This is new
        },
      });

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="I already have the Klaviyo integration for Shopify, should I also set up a Converge destination?">
    If you're using any of Klaviyo's prebuilt integrations, there's still value in setting up the Converge Klaviyo Destination to track the `Viewed Product`, `Viewed Category`, and `Added To Cart` events, or to send [Custom Events](/sources/extending-the-spec/custom-events) to Klaviyo.
  </Accordion>

  <Accordion title="Why do I see events with a Skipped status in the Destination Log?">
    Klaviyo only processes events for identified profiles, visitors with a known email address, phone number, or Klaviyo click ID (`_kx`). When none of these identifiers are present, for example, an anonymous visitor, Converge intentionally skips the event and logs it with a `Skipped` status. This is expected behavior and means the destination is working correctly.
  </Accordion>
</AccordionGroup>

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Klaviyo spec.

| Converge Event Name                                           | Klaviyo Event Name  |
| ------------------------------------------------------------- | ------------------- |
| [\$page\_load](/sources/converge-spec#page-load)              | `__activity__`      |
| [Viewed Product](/sources/converge-spec#viewed-product)       | `Viewed Product`    |
| [Viewed Collection](/sources/converge-spec#viewed-collection) | `Viewed Category`   |
| [Added To Cart](/sources/converge-spec#added-to-cart)         | `Added to Cart`     |
| [Removed From Cart](/sources/converge-spec#removed-from-cart) | `Removed from Cart` |
| [Started Checkout](/sources/converge-spec#started-checkout)   | `Started Checkout`  |
| [Placed Order](/sources/converge-spec#placed-order)           | `Placed Order`      |
| [Searched](/sources/converge-spec#searched)                   | `Searched Site`     |

This integration also auto-tracks some additional events that are not part of the Klaviyo Base Spec but are so heavily requested that we automatically forward them.

| Converge Event Name | Klaviyo Event Name |
| ------------------- | ------------------ |
| Ordered Product     | `Ordered Product`  |


# MGID
Source: https://docs.runconverge.com/destinations/integrations/mgid

An introduction to the MGID Ads Destination

## Overview

Destination Type: <IconText name="server" />

***

## Installation Instructions

1. Navigate to your <OutboundLink /> and go to your campaign settings.

2. In your campaign settings, enable **Conversion sensors** and select the **Postback** condition.

3. Fill in the event name field (e.g., `purchase`, `lead`, `signup`). You'll map Converge events to these MGID goal names later.

4. Copy your postback URL from MGID. It will look like:
   ```
   https://a.mgid.com/postback/123456?c={click_id}&e={event_name}&r={revenue}
   ```

5. Note down the **Postback ID** (the digits at the end of the URL path, e.g., `123456` in the example above).

6. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

7. Select the **MGID** destination and click **Next**.

8. Give your destination a **name** (e.g., MGID Destination) and click **Next**.

9. Enter your **Postback ID** from step 5.

10. In the **Set up your conversion events** section, map your Converge events to MGID event names:
    * **Converge Event**: Select the event you want to track (e.g., `Placed Order`)
    * **MGID Event Name**: Enter the exact event name you configured in MGID (e.g., `purchase`)

11. Add additional event mappings as needed for your other conversion goals.

12. Click **Next**.

13. Select the sources you want to forward events from, then click **Next**.

<Note>This is a server-side destination, meaning that only server-side sources can be used with this destination. You can still select client-side sources but the events will not be sent to MGID.</Note>

14. Review any issues and click **Submit**.

<Warning>For this destination to work, you must add the click ID parameter to **all** of your MGID campaigns following step 15 below. **You should add this parameter for every new campaign as well**.</Warning>

15. In your MGID campaign settings, navigate to **Tracking Tags** > **Add custom tracking tag** and add the following parameter:
    ```
    mgidcid={click_id}
    ```

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| :--------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## Event Mapping

MGID uses custom event mapping, meaning you define which Converge events should be forwarded and what they should be called in MGID.

During the destination setup, you configure:

* **Converge Event**: The event from your Converge tracking (e.g., `Placed Order`, `Added To Cart`)
* **MGID Event Name**: The corresponding event name in your MGID campaign goals (e.g., `purchase`, `lead`)

### Revenue Tracking

The MGID destination automatically includes revenue data when available:

* Revenue is taken from the `total_price` property of your Converge events
* Revenue is sent as the `r` parameter in the postback URL
* You can configure whether to use gross or net revenue in the advanced settings

### Click ID Requirements

For attribution to work correctly, MGID requires a click ID to connect ad clicks to conversions:

* The click ID is captured when users click on your MGID ads with the `mgidcid={click_id}` parameter
* This click ID is stored as the `$mgid_click_id` profile property in Converge
* Events will only be forwarded to MGID if this click ID is present

<Note>Events without a valid MGID click ID will be skipped and not forwarded to MGID.</Note>


# OpenAI Ads
Source: https://docs.runconverge.com/destinations/integrations/openai

An introduction to the OpenAI Ads Destination

## Overview

Destination Type: <IconText name="browser" />  and <IconText name="server" />

***

## Installation instructions

1. Navigate to your <OutboundLink /> and choose **Tools > Conversions**.

2. Click **Create > Data source**.

<Frame>
  <img alt="OpenAI Ads - Step 2" />
</Frame>

3. Give it a name (e.g., `Converge Pixel`), select Type **Web**, and click **Create**.

<Frame>
  <img alt="OpenAI Ads - Step 3" />
</Frame>

4. In the **Copy data source** screen, copy the **ID** and keep it handy. Click **Confirm** when you're done.

<Frame>
  <img alt="OpenAI Ads - Step 4" />
</Frame>

5. In the same **Tools > Conversions** page, click **Manage conversion keys > Create new key**.

<Frame>
  <img alt="OpenAI Ads - Step 5" />
</Frame>

6. Give it a name (e.g., `Converge`) and click **Create**.

<Frame>
  <img alt="OpenAI Ads - Step 6" />
</Frame>

7. In the **Save your key** screen, click **Copy** to copy the key to your clipboard and keep it safe.

<Frame>
  <img alt="OpenAI Ads - Step 7" />
</Frame>

8. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

9. Select the **OpenAI Ads** destination and click **Next**.

10. Give your destination a **name** (e.g. OpenAI Ads Destination) and click **Next**.

11. In the **Authentication** screen, fill in the **Pixel Id** you copied on *step 4*, fill in **Conversions API Key** with the key you copied on *step 7*, and click **Next**.

12. In the **Configuration** screen, fill in the **Domain name** with your domain name (e.g. example.com), and click **Next**.

13. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the OpenAI Ads destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

14. Select the sources you want to forward events from, then click **Next**.

15. Review any issues and click **Submit**.

<Warning>Once you have installed your Converge Destination, you should **pause or remove all existing OpenAI Ads tracking**. Leaving these on will lead to duplicate tracking.</Warning>

***

## Modify your Item ID

The Converge OpenAI Ads destination, by default, will use the **Product ID** as the item identifier for the events being tracked.
However, you can configure the destination to use explicitly the **Product ID**, the **Variant ID** or **SKU** if you so choose, or use a custom item ID.

1. Navigate to your OpenAI Ads destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Item ID, and click on **Save**

**List of Item ID Modes**

| Content ID Mode | Behavior                                            |
| --------------- | --------------------------------------------------- |
| Product ID      | The ID of the product (`product_id`)                |
| Variant ID      | The ID of the variant of the product (`variant_id`) |
| SKU             | The SKU of the product (`sku`)                      |
| Custom          | An arbitrary item ID derived from the event data    |

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| :--------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the OpenAI Ads events spec:

| Converge Event Name                                                         | Meta Event Name          |
| --------------------------------------------------------------------------- | ------------------------ |
| [\$page\_load](/sources/converge-spec#page-load)                            | `page_viewed`            |
| [Viewed Product](/sources/converge-spec#viewed-product)                     | `contents_viewed`        |
| [Viewed Collection](/sources/converge-spec#viewed-collection)               | `contents_viewed`        |
| [Added To Cart](/sources/converge-spec#added-to-cart)                       | `items_added`            |
| [Added To Wishlist](/sources/converge-spec#added-to-wishlist)               | `items_added`            |
| [Started Checkout](/sources/converge-spec#started-checkout)                 | `checkout_started`       |
| [Added Payment Info](/sources/converge-spec#added-payment-info)             | `checkout_started`       |
| [Placed Order](/sources/converge-spec#placed-order)                         | `order_created`          |
| [Started Subscription](/sources/converge-spec#started-subscription)         | `subscription_created`   |
| [Activated Subscription](/sources/converge-spec#activated-subscription)     | `subscription_created`   |
| [Subscribed To Newsletter](/sources/converge-spec#subscribed-to-newsletter) | `lead_created`           |
| [Signed Up](/sources/converge-spec#signed-up)                               | `registration_completed` |


# Outbrain Ads
Source: https://docs.runconverge.com/destinations/integrations/outbrain

An introduction to the Outbrain Ads Destination

## Overview

Destination Type: <IconText name="server" />

***

## Installation instructions

1. Navigate to your <OutboundLink /> and choose **Conversions** from the side-bar.
   <Frame>
     <img alt="outbrain-sidebar" />
   </Frame>

2. Click on **Create Conversion** in the top right corner.

3. Choose **Server-to-Server Conversions** as a Data source.

4. Under Conversion Type, choose your Event Category, most likely **Purchase** and give your conversion a name, e.g. `[Converge] Purchase`.

5. Click on **Create Conversion**.

6. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

7. Select the **Outbrain** destination and click **Next**.

8. Give your destination a **name** (e.g. Outbrain Destination) and click **Next**.

9. Keep the defaults on the Configuration page and click **Next**.

10. Click on <IconText name="plus" /> and select Placed Order as the source event.

11. In the Forward As value enter `[Converge] Purchase`.

12. Select **Server** as the Forwarding Mode and click **Next**.

13. Add other conversion events in Outbrain following steps 2-5 above and map them in your destination by following steps 10-12. Then click **Next**.

<Frame>
  <img alt="outbrain-4" />
</Frame>

14. Select the sources you want to forward events from, then click **Next**.

<Note>This is a server-side destination, meaning that only server-side sources can be used with this destination. You can still select client-side sources but the events will not be sent to Outbrain.</Note>

15. Review any issues and click **Submit**.

<Warning> For this destination to work, you will need to change the URL of **all** of your campaigns following steps 13-16 below. **You should add these parameters for every new campaign as well**. </Warning>

16. Navigate to the Campaigns overview.
    <Frame>
      <img alt="outbrain-campaign" />
    </Frame>

17. Click on the <Icon name="pencil" />-icon next to the campaign for which you want to modify the tracking parameters to open the campaign settings.

18. Add the following in the **Tracking**-section

```
utm_source=outbrain&utm_medium=discovery&utm_campaign={{campaign_name}}&utm_content={{ad_title}}&utm_term={{publisher_name}}_{{section_name}}&cvg_source=outbrain&cvg_adid={{ad_id}}&cvg_cid={{campaign_id}}&outbraincid={{ob_click_id}}
```

19. Save your modification by clicking the Submit button.

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="xmark" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## FAQ

<AccordionGroup>
  <Accordion title="Why do I need to change my tracking parameters for the Outbrain Destination and in-platform attribution to work?">
    Outbrain's in-platform attribution works based on Outbrain Click IDs. If a purchase gets sent to Outbrain without a Click ID, it won't get attributed.

    Unfortunately, Outbrain doesn't add the Click ID automatically to the landing page URL (as opposed to other ad platforms such as Google Ads or Facebook Ads). You need to manually make sure that all links include a click ID by modifying the tracking parameters for **every** ad you run.
  </Accordion>
</AccordionGroup>

***

## Event mapping

Events are not automatically mapped, you need to configure the mapping of the [Converge event spec](/sources/converge-spec) to your Outbrain conversions manually.
We recommend the following mapping to the Event Type:

| Converge Event Name                                             | Outbrain Event Type            |
| --------------------------------------------------------------- | ------------------------------ |
| [Added To Cart](/sources/converge-spec#added-to-cart)           | `[Converge] Add To Cart`       |
| [Started Checkout](/sources/converge-spec#started-checkout)     | `[Converge] Initiate Checkout` |
| [Added Payment Info](/sources/converge-spec#added-payment-info) | `[Converge] Add Payment Info`  |
| [Placed Order](/sources/converge-spec#placed-order)             | `[Converge] Purchase`          |


# Pinterest Ads
Source: https://docs.runconverge.com/destinations/integrations/pinterest

An introduction to the Pinterest Ads Destination

## Overview

Destination Type: <IconText name="browser" />  and <IconText name="server" />

* Includes support for the <OutboundLink />

***

## Installation instructions

1. Navigate to your <OutboundLink /> . If the direct link does not open your Events Manager, you can access it from the Pinterest Ads Manager dashboard under **Tools** > **Events**.

2. From your Ads Manager click on <IconText name="bars" /> in the top left corner.

3. Click on **Conversions** under the Business section.
   <Frame>
     <img alt="pinterest-1" />
   </Frame>

4. Navigate to the **Pinterest Tag** > **Tag Manager** tab and copy your **Tag ID**, you will need it later. Create a tag if you do not have one.
   <Frame>
     <img alt="pinterest-2" />
   </Frame>

5. Lastly, get your **Ad Account ID**, you can find it in the URL of the ad manager. It consists of 12 numbers.
   <Frame>
     <img alt="pinterest-3" />
   </Frame>

6. Navigate to the **API for conversions** > **Conversion access token** tab. Click on **Generate new token** and copy the token, you will need it later.

7. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

8. Select the **Pinterest** destination and click **Next**.

9. Give your destination a **name** (e.g. Pinterest Destination) and click **Next**.

10. Fill in the **Ad Account ID**, **Tag ID** and **Access Token** you copied from **Pinterest** and click **Next**.

11. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the Pinterest destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

12. Select the sources you want to forward events from, then click **Next**.

13. Review any issues and click **Submit**.

<Warning>
  Set this destination to **Deactivated** while you remove your existing Pinterest tracking setup. Running both in parallel leads to duplicate conversion data. Follow the **Turn off your old Pinterest tracking** instructions below, then set the destination to **Active** when you're ready.
</Warning>

***

## Turn off your old Pinterest tracking

### Turning off the Shopify Pinterest Ads Sales Channel

<Warning>
  The Pinterest Ads app for Shopify does not support disabling tracking without uninstalling the app. Uninstalling also stops your product sync to Pinterest. Before you continue, switch to a third-party feed manager as described <OutboundLink />.
</Warning>

1. Navigate to your <OutboundLink />.

2. Click on **Sales channels** and choose **Pinterest** from the *Installed sales channels* menu.

3. Click on the menu icon in the top right, and click on **Uninstall**.

4. Confirm by clicking **Uninstall**.

***

## Modify your Content ID

The Converge Pinterest Destination will use the **Product ID** by default.
However, you can configure the destination to use explicitly the **Variant ID** or **SKU** instead.

1. Navigate to your Pinterest Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of available Content ID Modes**

| Content ID Mode | Behavior                    |
| --------------- | --------------------------- |
| Product Id      | Always use the `product_id` |
| Variant Id      | Always use the `variant_id` |
| SKU             | Always use the `sku`        |

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="xmark" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Pinterest Ads spec.

| Converge Event Name                                                         | Pinterest Ads Event Name |
| --------------------------------------------------------------------------- | ------------------------ |
| [\$page\_load](/sources/converge-spec#page-load)                            | `page`                   |
| [Viewed Product](/sources/converge-spec#viewed-product)                     | `page_visit`             |
| [Viewed Collection](/sources/converge-spec#viewed-collection)               | `view_category`          |
| [Added To Cart](/sources/converge-spec#added-to-cart)                       | `add_to_cart`            |
| [Searched](/sources/converge-spec#searched)                                 | `search`                 |
| [Subscribed To Newsletter](/sources/converge-spec#subscribed-to-newsletter) | `lead`                   |
| [Placed Order](/sources/converge-spec#placed-order)                         | `checkout`               |


# Postscript
Source: https://docs.runconverge.com/destinations/integrations/postscript

An introduction to the Postscript Destination

## Overview

Destination Type: <IconText name="server" />

***

## Installation instructions

<Steps>
  <Step icon="key" title="1. Create a Postscript API key">
    1. In your Postscript dashboard, select your Shop Name and navigate to **API**.
    2. Click on **Create Security Key Pair** and confirm by selecting **Yes**.
    3. Click in **Add a label** and use a label that helps you identify the API key (e.g. `Converge`).
    4. Under **Private Key**, click on **Show** and to copy the Private Key.

    <Frame>
      <img alt="postscript-1" />
    </Frame>
  </Step>

  <Step icon="list" title="2. Create the Converge Destination">
    5. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.
    6. Select the **Postscript** destination and click **Next**.
    7. Give your destination a **name** (e.g. Postscript Destination) and click **Next**.
    8. Fill in the **Private API Key** you copied from **Postscript** and click **Next**.
    9. Select **Use default mapping** and click **Next**.

    <Note>You can find the Default mapping for the Postscript destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

    10. Select the sources you want to forward events from, then click **Next**.

    <Note>This is a server-side destination, meaning that only server-side sources can be used with this destination. You can still select client-side sources but the events will not be sent to Postscript.</Note>

    11. Review any issues and click **Submit**.

    <Warning>If you are migrating from a previous Postscript to a Converge integration, make sure to **modify your Flows** to use the Converge Event Names and Event Properties [here](#event-mapping)</Warning>
  </Step>
</Steps>

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="xmark" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## Adding product URL and image URL to Converge events to power Postscript flows

A common use case of the Postscript Destination is to build Postscript SMS Flows based on Converge Events.
As such, you might want to include a Product URL or Product Image URL in the Converge Event so you can leverage these in your flows.

To that end, you will want to extend the Converge event spec for the following events.
Once you add the custom properties to your events, Converge will automatically forward these to the Postscript Destination.

Find code examples below that illustrate where **you should add the Product URL and Product Image URL custom event properties**.

<AccordionGroup>
  <Accordion title="Viewed Product" icon="code">
    See the original `Viewed Product` spec [here](/sources/converge-spec.mdx#viewed-product)

    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Viewed Product",
        properties: {
          product_id: "123456",
          variant_id: "78910", 
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla", 
          price: 42,
          currency: "USD",
          vendor: "My Store",
          url: "https://mystore.com/this-product", // This is new
          image_url: "https://mystore.com/assets/product.png" // This is new
        },
      });
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Added To Cart" icon="code">
    See the original `Added To Cart` spec [here](/sources/converge-spec.mdx#added-to-cart)

    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Added To Cart",
        properties: {
          product_id: "123456",
          variant_id: "78910",
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla",
          price: 42,
          currency: "USD",
          quantity: 1,
          vendor: "My Store",
          url: "https://mystore.com/this-product", // This is new
          image_url: "https://mystore.com/assets/product.png" // This is new
        },
      });

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Removed From Cart" icon="code">
    See the original `Removed From Cart` spec [here](/sources/converge-spec.mdx#removed-from-cart)

    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Removed From Cart",
        properties: {
          product_id: "123456",
          variant_id: "78910",
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla",
          price: 42,
          currency: "USD",
          quantity: 1,
          vendor: "My Store",
          url: "https://mystore.com/this-product", // This is new
          image_url: "https://mystore.com/assets/product.png" // This is new
        },
      });

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Postscript spec.

| Converge Event Name                                           | Postscript Event Name          |
| ------------------------------------------------------------- | ------------------------------ |
| [Viewed Product](/sources/converge-spec#viewed-product)       | `Converge - viewed_product`    |
| [Added To Cart](/sources/converge-spec#added-to-cart)         | `Converge - add_to_cart`       |
| [Started Checkout](/sources/converge-spec#started-checkout)   | `Converge - initiate_checkout` |
| [Viewed Collection](/sources/converge-spec#viewed-collection) | `Converge - viewed_collection` |
| [Placed Order](/sources/converge-spec#placed-order)           | `Converge - purchase`          |

You can find the property mapping for each event below:

<AccordionGroup>
  <Accordion title="Converge - viewed_product">
    | Postscript Property | Converge Property          |
    | ------------------- | -------------------------- |
    | `name`              | `name`                     |
    | `price_in_cents`    | `price` converted to cents |
    | `resource_id`       | `product_id`               |
    | `resource_type`     | Fixed to `"product"`       |
    | `sku`               | `sku`                      |
    | `variant_name`      | `variant_name`             |
    | `variant_id`        | `variant_id`               |
    | `vendor`            | `vendor`                   |
    | `currency`          | `currency`                 |
    | `url`               | `url`                      |
    | `image_url`         | `image_url`                |
  </Accordion>

  <Accordion title="Converge - add_to_cart">
    | Postscript Property | Converge Property    |
    | ------------------- | -------------------- |
    | `name`              | `name`               |
    | `price_in_cents`    | `price`              |
    | `resource_id`       | `product_id`         |
    | `resource_type`     | Fixed to `"product"` |
    | `sku`               | `sku`                |
    | `variant_name`      | `variant_name`       |
    | `variant_id`        | `variant_id`         |
    | `vendor`            | `vendor`             |
    | `currency`          | `currency`           |
    | `url`               | `url`                |
    | `image_url`         | `image_url`          |
    | `quantity`          | `quantity`           |
  </Accordion>

  <Accordion title="Converge - initiate_checkout">
    | Postscript Property       | Converge Property                                        |
    | ------------------------- | -------------------------------------------------------- |
    | `item_names`              | `name` for each item                                     |
    | `item_vendors`            | `vendor` for each item                                   |
    | `coupon`                  | `coupon` (separated by `,`)                              |
    | `total_value_in_cents`    | `total_price` converted to cents                         |
    | `discount_value_in_cents` | `total_discount` converted to cents                      |
    | `tax_value_in_cents`      | `total_tax` converted to cents                           |
    | `shipping_value_in_cents` | `total_shipping` converted to cents                      |
    | `currency`                | `currency`                                               |
    | `items`                   | list of items (same mapping as `Converge - add_to_cart`) |
  </Accordion>

  <Accordion title="Converge - viewed_collection">
    | Postscript Property | Converge Property |
    | ------------------- | ----------------- |
    | `category`          | `name`            |
    | `category_id`       | `id`              |
    | `image_url`         | `image_url`       |
    | `quantity`          | `quantity`        |
  </Accordion>

  <Accordion title="Converge - purchase">
    | Postscript Property       | Converge Property                                        |
    | ------------------------- | -------------------------------------------------------- |
    | `order_id`                | `event_id`                                               |
    | `item_names`              | `name` for each item                                     |
    | `item_vendors`            | `vendor` for each item                                   |
    | `coupon`                  | `coupon` (separated by `,`)                              |
    | `total_value_in_cents`    | `total_price` converted to cents                         |
    | `discount_value_in_cents` | `total_discount` converted to cents                      |
    | `tax_value_in_cents`      | `total_tax` converted to cents                           |
    | `shipping_value_in_cents` | `total_shipping` converted to cents                      |
    | `currency`                | `currency`                                               |
    | `items`                   | list of items (same mapping as `Converge - add_to_cart`) |
  </Accordion>
</AccordionGroup>


# Reddit
Source: https://docs.runconverge.com/destinations/integrations/reddit

An introduction to the Reddit Ads Destination

## Overview

Destination Type: <IconText name="browser" />  and <IconText name="server" />

* Includes support for the <OutboundLink />

***

## Installation instructions

1. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

2. Select the **Reddit** destination and click **Next**.

3. Give your destination a **name** (e.g. Reddit Destination) and click **Next**.

4. Click on the **Sign in with Reddit**-button.

5. Click on **Allow**.
   <Frame>
     <img alt="" />
   </Frame>

6. Select your Reddit Ads Account.

7. Click **Next**.

8. Keep the defaults on the Configuration page and click **Next**.

9. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the Reddit destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

10. Select the sources you want to forward events from, then click **Next**.

11. Review any issues and click **Submit**.

<Warning> Once you have installed your Converge Destination, you should **pause or remove all existing Reddit tracking**. Leaving these on will lead to duplicate tracking.  </Warning>

***

## Modify your Content ID

The Converge Reddit Destination will use the **Product ID** by default.
However, you can configure the destination to use explicitly the **Variant ID** or **SKU** instead.

1. Navigate to your Reddit Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of available Content ID Modes**

| Content ID Mode | Behavior                    |
| --------------- | --------------------------- |
| Product Id      | Always use the `product_id` |
| Variant Id      | Always use the `variant_id` |
| SKU             | Always use the `sku`        |

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| :--------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Reddit spec.

| Converge Event Name                                                         | Reddit Event Name  |
| --------------------------------------------------------------------------- | ------------------ |
| [\$page\_load](/sources/converge-spec#page-load)                            | `PageVisit`        |
| [Viewed Product](/sources/converge-spec#viewed-product)                     | `ViewContent`      |
| [Added To Cart](/sources/converge-spec#added-to-cart)                       | `AddToCart`        |
| [Added To Wishlist](/sources/converge-spec#added-to-wishlist)               | `AddToWishlist`    |
| [Started Checkout](/sources/converge-spec#started-checkout)                 | `InitiateCheckout` |
| [Added Payment Info](/sources/converge-spec#added-payment-info)             | `AddPaymentInfo`   |
| [Placed Order](/sources/converge-spec#placed-order)                         | `Purchase`         |
| [Subscribed To Newsletter](/sources/converge-spec#subscribed-to-newsletter) | `Lead`             |
| [Searched](/sources/converge-spec#searched)                                 | `Search`           |

This integration also auto-tracks some additional events that are not part of the Reddit Spec but are so heavily requested that we automatically forward them.

| Converge Event Name                                                       | Reddit Event Name     |
| ------------------------------------------------------------------------- | --------------------- |
| [Placed Order](/sources/converge-spec#placed-order)  (New Customers Only) | `NewCustomerPurchase` |
|                                                                           |                       |


# Snapchat
Source: https://docs.runconverge.com/destinations/integrations/snapchat

An introduction to the Snapchat Ads Destination

## Overview

Destination Type: <IconText name="browser" />  and <IconText name="server" />

* Includes support for the <OutboundLink />

***

## Installation instructions

1. Navigate to your [Snapchat Ads](https://ads.snapchat.com) > Events Manager (under assets).

2. From your Events Manager, **click on the Snapchat Pixel** you would like to connect or create a new one through 'New Event Source'.

3. Under the name of the pixel, you can find the **Pixel ID**, copy it and save it for later.

4. Go to the business dashboard > Business details > Conversions API tokens. Click the 'Generate Token' button and copy the new **API token** and save it for later.

5. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

6. Select the **Snapchat** destination and click **Next**.

7. Give your destination a **name** (e.g. Snapchat Destination) and click **Next**.

8. Fill in the **Pixel ID** and **API Token** you copied from **Snapchat** and click **Next**.

9. Enter the main URL of your website. Be sure to include the https\:// prefix as well. Then click **Next**.

10. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the Snapchat destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

11. Select the sources you want to forward events from, then click **Next**.

12. Review any issues and click **Submit**.

<Warning>
  Set this destination to **Deactivated** while you remove your existing Snapchat tracking setup. Running both in parallel leads to duplicate conversion data. Follow the **Turn off your old Snapchat tracking** instructions below, then set the destination to **Active** when you're ready.
</Warning>

***

## Turn off your old Snapchat tracking

### Turning off the Shopify Snapchat Ads Sales Channel data sharing

1. Navigate to your <OutboundLink />.

2. Click on **Sales channels** and choose **Snapchat Ads** from the *Installed sales channels* menu.

3. Click on **Data Sharing**, and finally click on **Disconnect**.

   <Frame>
     <img alt="settings-snapchat-1" />
   </Frame>

***

## Modify your Content ID

The Converge Snapchat Destination will use the **Default** content mode to define the Content ID forwarded by default.
However, you can configure the destination to use explicitly the **Product ID**, the **Variant ID** or **SKU** instead.

1. Navigate to your Snapchat Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of Content ID Modes**

| Content ID Mode | Behavior                                                          |
| --------------- | ----------------------------------------------------------------- |
| Default         | Use the `variant_id` if available, otherwise use the `product_id` |
| Product Id      | Always use the `product_id`                                       |
| Variant Id      | Always use the `variant_id`                                       |
| SKU             | Always use the `sku`                                              |

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| :--------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

<Warning>Snapchat does not support multiple pixels on the same website. Installing multiple Snapchat destinations will lead to duplicate tracking.</Warning>

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Snapchat spec.

| Converge Event Name                                                 | Snapchat Event Name |
| ------------------------------------------------------------------- | ------------------- |
| [\$page\_load](/sources/converge-spec#page-load)                    | `PAGE_VIEW`         |
| [Viewed Product](/sources/converge-spec#viewed-product)             | `VIEW_CONTENT`      |
| [Viewed Collection](/sources/converge-spec#viewed-collection)       | `LIST_VIEW`         |
| [Added To Cart](/sources/converge-spec#added-to-cart)               | `ADD_CART`          |
| [Added To Wishlist](/sources/converge-spec#added-to-wishlist)       | `ADD_TO_WISHLIST`   |
| [Started Checkout](/sources/converge-spec#started-checkout)         | `START_CHECKOUT`    |
| [Added Payment Info](/sources/converge-spec#added-payment-info)     | `ADD_BILLING`       |
| [Placed Order](/sources/converge-spec#placed-order)                 | `PURCHASE`          |
| [Started Subscription](/sources/converge-spec#started-subscription) | `SUBSCRIBE`         |
| [Logged In](/sources/converge-spec#logged-in)                       | `LOGIN`             |
| [Signed Up](/sources/converge-spec#signed-up)                       | `SIGN_UP`           |
| [Searched](/sources/converge-spec#searched)                         | `SEARCH`            |

<Warning>
  Snapchat only supports up to 5 custom events, and they must be named **exactly** `CUSTOM_EVENT_1`, `CUSTOM_EVENT_2`, `CUSTOM_EVENT_3`, `CUSTOM_EVENT_4`, or `CUSTOM_EVENT_5`. Any other name (e.g. `custom_event_1`, `CustomEvent1`, or a descriptive name like `QUIZ_COMPLETED`) will cause events to fail and be rejected by Snapchat.
</Warning>


# Taboola Ads
Source: https://docs.runconverge.com/destinations/integrations/taboola

An introduction to the Taboola Ads Destination

## Overview

Destination Type: <IconText name="server" />

***

## Installation instructions

1. Navigate to your <OutboundLink /> and choose **Tracking** from the top-bar.
   <Frame>
     <img alt="taboola-sidebar" />
   </Frame>

2. Click on **New Conversion** in the top right corner.

3. Choose a name for your conversion and choose **Event** as the Conversion Type.
   <Frame>
     <img alt="taboola-conversion-type" />
   </Frame>

4. Scroll down, you can ignore the "Fixed Value"-field. Choose the Category that fits your event best, for a `Placed Order` event this would be **Make Purchase**.

5. Choose your Event Name, e.g. `converge_placed_order`.
   <Frame>
     <img alt="taboola-event-name" />
   </Frame>

6. Keep all the other fields in default settings, and click on the **Create**-button at the bottom of the page.

7. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

8. Select the **Taboola** destination and click **Next**.

9. Give your destination a **name** (e.g. Taboola Destination) and click **Next**.

10. Click **Next** on the Configuration page. You don't have to enter anything.

11. Click on <IconText name="plus" /> and select Placed Order as the source event.

12. In the Forward As value enter `converge_placed_order`.

13. Select **Server** as the Forwarding Mode and click **Next**.

14. Add other conversion events in Taboola following steps 2-6 above and map them in your destination by following steps 11-13. Then click **Next**.

<Frame>
  <img alt="taboola-4" />
</Frame>

15. Select the sources you want to forward events from, then click **Next**.

<Note>This is a server-side destination, meaning that only server-side sources can be used with this destination. You can still select client-side sources but the events will not be sent to Taboola.</Note>

16. Review any issues and click **Submit**.

17. Navigate to the Campaigns overview in Taboola.

18. Click on the <Icon name="pencil" />-icon next to the campaign for which you want to modify the tracking parameters to open the campaign settings.

19. Add the following in the **Tracking**-section:

```
utm_source=taboola&utm_medium=paid&utm_campaign={campaign_name}&tblcid={click_id}&cvg_source=taboola&cvg_adid={campaign_item_id}&cvg_cid={campaign_id}
```

20. Save your modification by clicking the Submit button.

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="xmark" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="xmark" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## FAQ

<AccordionGroup>
  <Accordion title="Why do I need to change my tracking parameters for the Taboola Destination and in-platform attribution to work?">
    Taboola's in-platform attribution works based on Taboola Click IDs. If a purchase gets sent to Taboola without a Click ID, it won't get attributed.

    Unfortunately, Taboola doesn't add the Click ID automatically to the landing page URL (as opposed to other ad platforms such as Google Ads or Facebook Ads). You need to manually make sure that all links include a click ID by modifying the tracking parameters for **every** ad you run.
  </Accordion>
</AccordionGroup>

***

## Event mapping

Events are not automatically mapped, you need to configure the mapping of the [Converge event spec](/sources/converge-spec) to your Taboola conversions manually.
We recommend the following mapping to the Event Type:

| Converge Event Name                                             | Taboola Event Type           |
| --------------------------------------------------------------- | ---------------------------- |
| [Added To Cart](/sources/converge-spec#added-to-cart)           | `converge_add_to_cart`       |
| [Started Checkout](/sources/converge-spec#started-checkout)     | `converge_initiate_checkout` |
| [Added Payment Info](/sources/converge-spec#added-payment-info) | `converge_add_payment_info`  |
| [Placed Order](/sources/converge-spec#placed-order)             | `converge_placed_order`      |


# TikTok Ads
Source: https://docs.runconverge.com/destinations/integrations/tiktok

An introduction to the TikTok Ads Destination

## Overview

Destination Type: <IconText name="browser" />  and <IconText name="server" />

* Includes support for the <OutboundLink />

***

## Installation instructions

1. Navigate to your [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/). If the direct link does not open your Events Manager, you can access it from the TikTok Ads Manager dashboard under **Tools** > **Events**.

2. From your Events Manager, **click on "Manage"** under **Web Events**.

3. Click on your pixel, you might have to go through 2FA.

4. From the TikTok Pixel menu, copy your **Pixel ID**, you will need it later. The Pixel ID looks as follows: `CJQBODJC77UB4MRTGFRF`

5. Navigate to the **Settings** subtab and scroll down until you find the **Generate Access Token** button. Click on it to generate your token and keep it around for the next steps.

6. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

7. Select the **TikTok** destination and click **Next**.

8. Give your destination a **name** (e.g. TikTok Destination) and click **Next**.

9. Fill in the **Pixel ID** and **Access Token** you copied from **TikTok** and click **Next**.

10. Fill in your homepage domain name in the **Your Domain name** field, including `https://`. Click **Next**.

11. Select **Use default mapping** and click **Next**.

<Note>You can find the Default mapping for the TikTok destination [here](#event-mapping). For more information on setting up Custom mappings, look [here](/destinations/event-mapping).</Note>

12. Select the sources you want to forward events from, then click **Next**.

13. Review any issues and click **Submit**.

<Warning>
  Set this destination to **Deactivated** while you remove your existing TikTok tracking setup. Running both in parallel leads to duplicate conversion data. Follow the **Turn off your old TikTok tracking** instructions below, then set the destination to **Active** when you're ready.
</Warning>

***

## Turn off your old TikTok tracking

### Turning off the Shopify TikTok Sales Channel data sharing

1. Navigate to your <OutboundLink />.

2. Click on **Sales channels** and choose **TikTok** from the *Installed sales channels* menu.

3. Click on **Settings**, then **Data sharing**, and finally click on **Disconnect**.

   <Frame>
     <img alt="settings-tiktok-1" />
   </Frame>

4. After reading and confirming the impact of disconnecting the pixel, click on **Disconnect**.

   <Frame>
     <img alt="settings-tiktok-2" />
   </Frame>

   <Note>This will prevent you from creating TikTok campaigns from the Sales Channel, but **it won't impact any campaigns or ads in your TikTok Ads Manager**. We strongly recommend running ads from the Ads Manager instead of the TikTok Sales Channel.</Note>

***

## Modify your Content ID

The Converge TikTok Destination will use the **Default** content mode to define the Content ID forwarded by default.
However, you can configure the destination to use explicitly the **Product ID**, the **Variant ID** or **SKU** instead.

1. Navigate to your TikTok Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of Content ID Modes**

| Content ID Mode | Behavior                                                          |
| --------------- | ----------------------------------------------------------------- |
| Default         | Use the `variant_id` if available, otherwise use the `product_id` |
| Product Id      | Always use the `product_id`                                       |
| Variant Id      | Always use the `variant_id`                                       |
| SKU             | Always use the `sku`                                              |

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="check" /> |
| Filters                                              | <Icon name="check" /> |
| Server-side Conversions                              | <Icon name="check" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the TikTok Ads spec.

| Converge Event Name                                                                               | TikTok Ads Event Name                   |
| ------------------------------------------------------------------------------------------------- | --------------------------------------- |
| [\$page\_load](/sources/converge-spec#page-load)                                                  | `PageView`                              |
| [Viewed Product](/sources/converge-spec#viewed-product)                                           | `ViewContent`                           |
| [Viewed Collection](/sources/converge-spec#viewed-collection)                                     | `ViewContent`                           |
| [Added To Cart](/sources/converge-spec#added-to-cart)                                             | `AddToCart`                             |
| [Started Checkout](/sources/converge-spec#started-checkout)                                       | `InitiateCheckout`                      |
| [Added Payment Info](/sources/converge-spec#added-payment-info)                                   | `AddPaymentInfo`                        |
| [Placed Order](/sources/converge-spec#placed-order)                                               | `Purchase`                              |
| [Started Subscription](/sources/converge-spec#started-subscription)                               | `Subscribe`                             |
| [Placed Recurring Subscription Order](/sources/converge-spec#placed-recurring-subscription-order) | `RecurringSubscriptionPaymentSucceeded` |
| [Cancelled Subscription](/sources/converge-spec#cancelled-subscription)                           | `CancelSubscription`                    |
| [Activated Subscription](/sources/converge-spec#activated-subscription)                           | `Subscribe`                             |
| [Searched](/sources/converge-spec#searched)                                                       | `Search`                                |
| [Subscribed To Newsletter](/sources/converge-spec#subscribed-to-newsletter)                       | `CompleteRegistration`                  |

This integration also auto-tracks some additional events that are not part of the TikTok Base Spec but are so heavily requested that we automatically forward them.

| Converge Event Name                                                       | TikTok Event Name     |
| ------------------------------------------------------------------------- | --------------------- |
| [Placed Order](/sources/converge-spec#placed-order)  (New Customers Only) | `NewCustomerPurchase` |
|                                                                           |                       |


# X Ads (Twitter Ads)
Source: https://docs.runconverge.com/destinations/integrations/twitter

An introduction to the X Ads (Twitter Ads) Destination

## Overview

Destination Type: <IconText name="browser" />

* Includes support for passing <OutboundLink />
* Includes support for  <OutboundLink />

***

## Installation instructions

<Note> This is a client-side-only destination, meaning that you will need to be tracking all events client-side (including `Placed Order`) for this destination to work properly. </Note>

<Steps>
  <Step icon="list" title="Set up tracking in Twitter Ads">
    1. Navigate to your X Ads account and choose **Tools > Events Manager**.

    2. Copy your X **Pixel ID**
       1. If you already have an events source, at the top of the page, find the 'X pixel' section and copy the ID. (e.g. `obarl`)
       2. If not, you will be prompted to create a new event source, follow the instructions and copy the **Pixel ID** when you are done.

    3. Go to X Ads > Tools > Events Manager and click on the **Create Event** button.

    4. Give your event a name, e.g. 'Placed Order' when you are setting up a purchase conversion.

    5. Pick a X event type, e.g. 'Purchase'. You can find a suggested mapping of Converge to X Ads event types [below](#event-mapping).

    6. Configure your attribution settings and click on **Next**.

    7. Choose the 'Define event with code' setup method and click on **Next**.

    8. Click 'Save' to finish the setup.

    9. You can now find the event in the Events table in the X Ads Events manager.
       Under the event, the ID is composed as `tw-{pixelID}-{eventID}`.
       Copy the `eventID` save it for the Converge destination configuration.

    <Note> Repeat the steps 3-9 above for all the conversions you want to track in X Ads.</Note>
  </Step>

  <Step icon="list" title="2. Set up your destination">
    10. In the Converge sidebar, click on <IconText name="arrow-right-from-line" /> and then click **Create new Destination**.

    11. Select the **X Ads (Twitter Ads)** destination and click **Next**.

    12. Give your destination a **name** (e.g. X Ads Destination) and click **Next**.

    13. Fill in the **Pixel ID** you copied from **X Ads** and click **Next**.

    14. Click on <IconText name="plus" /> and select Placed Order as the source event.

    15. In the Forward As value enter **eventID** you saved for the purchase conversion in X Ads.

    16. Select **Client** as the Forwarding Mode and click **Next**.

    <Note> Repeat the steps 14-16 above for all the conversions you track in X Ads </Note>

    <Frame>
      <img alt="x-ads-4" />
    </Frame>

    17. Select the sources you want to forward events from, then click **Next**.

    <Note>This is a client-side destination, meaning that only client-side sources can be used with this destination. You can still select server-side sources but the events will not be sent to X.</Note>

    18. Review any issues and click **Submit**.
  </Step>
</Steps>

<Warning> Once you have installed your Converge Destination, you should **pause or remove all existing X Ads tracking**. Leaving these on will lead to duplicate tracking.  </Warning>

***

## Modify your Content ID

The Converge X Ads Destination will use the **Product ID** by default.
However, you can configure the destination to use explicitly the **Variant ID** or **SKU** instead.

1. Navigate to your X Ads Destination, click on **Configuration**.
2. Click on the **Configuration**-subtab
3. Open the **Advanced configuration (optional)** section
4. Pick your desired Content ID, and click on **Save**

**List of available Content ID Modes**

| Content ID Mode | Behavior                    |
| --------------- | --------------------------- |
| Product Id      | Always use the `product_id` |
| Variant Id      | Always use the `variant_id` |
| SKU             | Always use the `sku`        |

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature                                     |       Supported       |
| ---------------------------------------------------- | :-------------------: |
| Custom Events                                        | <Icon name="xmark" /> |
| Filters                                              | <Icon name="xmark" /> |
| Server-side Conversions                              | <Icon name="xmark" /> |
| [Conversion amount](/destinations/conversion-amount) | <Icon name="check" /> |

***

## Event mapping

Events are not automatically mapped, you need to configure the mapping of the [Converge event spec](/sources/converge-spec) to your X Ads events manually.
We recommend the following mapping to the Event Type:

| Converge Event Name                                             | Twitter Event Type   |
| --------------------------------------------------------------- | -------------------- |
| [\$page\_load](/sources/converge-spec#page-load)                | `Page view`          |
| [Viewed Product](/sources/converge-spec#viewed-product)         | `Content view`       |
| [Added To Cart](/sources/converge-spec#added-to-cart)           | `Add to cart`        |
| [Started Checkout](/sources/converge-spec#started-checkout)     | `Checkout initiated` |
| [Added Payment Info](/sources/converge-spec#added-payment-info) | `Added payment info` |
| [Placed Order](/sources/converge-spec#placed-order)             | `Purchase`           |


# Vibe
Source: https://docs.runconverge.com/destinations/integrations/vibe

An introduction to the Vibe Destination

## Overview

Destination Type: <IconText name="browser" />

* Converge automatically loads the Vibe Pixel (`vbpx.js`) and forwards supported events.
* For Vibe's official pixel reference, see <OutboundLink />.

***

## Installation instructions

<Steps>
  <Step title="Find your Vibe Advertiser ID (also called Pixel ID)">
    1. In your Vibe account, go to **Settings** → **Tracking** → **Web Pixel**.
    2. Choose your **Advertiser** and click **Setup**.
    3. Copy the **Advertiser ID** from the pixel setup page.

    <Note>
      If you are using the manual implementation in Vibe, this is the same ID that appears inside the pixel snippet you would normally paste between your site's <code>\<head></code> tags.
    </Note>
  </Step>

  <Step title="Create the destination in Converge">
    4. In the Converge sidebar, click <IconText name="arrow-right-from-line" /> → **Create new Destination**.
    5. Select **Vibe** and click **Next**.
    6. Give your destination a **name** (e.g. Vibe Destination) and click **Next**.
    7. Paste your **Advertiser ID** and click **Next**.
    8. Keep **Default mapping** or configure **Custom mapping**, then click **Next**.
    9. Select the sources you want to forward events from, then click **Next**.
    10. Review any issues and click **Submit**.
  </Step>
</Steps>

<Warning>
  If you already installed the Vibe Pixel directly in your site or via GTM, pause or remove that setup to avoid duplicate tracking. Converge will load <code>vbpx.js</code> on your pages.
</Warning>

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature   |       Supported       |
| ------------------ | :-------------------: |
| Custom Events      | <Icon name="xmark" /> |
| Filters            | <Icon name="xmark" /> |
| Server-side Events | <Icon name="xmark" /> |

***

## Verify your implementation

After activating this connection, verify that events are being sent to Vibe by checking your Vibe Advertisers dashboard:

1. In your Vibe account, go to **Settings** → **Tracking** → **Web Pixel** (same location as when finding your Advertiser ID).
2. On the Web Pixel page, you'll see a table showing your advertisers and their event metrics.
3. Check the event counts for **Page view**, **Lead**, and **Purchase** to confirm events are being received. Also, verify the **Last event** date shows recent activity.

<img alt="Vibe Web Pixel Dashboard" />

<Note>
  It may take some time for Vibe to display this data. Vibe's dashboard is not always real-time, so there may be a delay before events appear.
</Note>

Alternatively, you can verify your implementation using your browser's Developer Tools:

1. Open the page(s) where the pixel should fire.
2. Open **Developer Tools** → **Network** tab.
3. Filter by "Vibe".
4. You should see two network rows:
   * `vbpx.js`
   * `s?aid...`
5. Click the `s?aid...` row → **Payload**.
   * The `aid` parameter should show your Advertiser ID.
   * The `a` parameter should show the event name (e.g. `page_view`, `lead`, or `purchase`).

For more details, refer to the Vibe documentation: <OutboundLink />.

***

## Event mapping

Converge automatically maps the following events from the [Converge event spec](/sources/converge-spec) to the Vibe pixel.

| Converge Event Name                                 | Vibe Event Name |
| --------------------------------------------------- | --------------- |
| [\$page\_load](/sources/converge-spec#page-load)    | `page_view`     |
| [Lead](/sources/extending-the-spec/custom-events)   | `lead`          |
| [Placed Order](/sources/converge-spec#placed-order) | `purchase`      |

### Purchase parameters sent

* **price\_usd**: Converge forwards the total purchase value converted to USD when available.
* **purchase\_id**: Forwarded when present, enabling per-order reconciliation in Vibe.

<Note>
  Vibe allows you to attribute purchases with dynamic values. Converge handles currency conversion by sending <code>price\_usd</code> to Vibe when the original event is in a non-USD currency.
</Note>

***

## Additional events and custom mapping

Vibe does not accept arbitrary custom event names. The Vibe Pixel recognizes only three event types: `page_view`, `lead`, and `purchase`.


# Monitoring
Source: https://docs.runconverge.com/destinations/monitoring

Test and monitor your destination configuration

## Overview

Converge provides the following tools to monitor and debug whether your destinations are correctly set up.

* [Destination Logs](#destination-logs)

***

## Destination Logs

Converge stores detailed logs of every event that gets sent to Converge, including [event properties](/sources/converge-spec), [profile properties](/sources/source-concepts#profile-properties), and [aliases](/sources/source-concepts#aliases).

### Where to find Destination logs

1. Navigate to the [Destinations Tab](https://app.runconverge.com/-/connections) in your Converge dashboard
2. Click on the Destination you want to debug
3. Click on the **Logs** tab to see the logs
4. Click on any of the Log Lines to inspect a Log instance

<Frame>
  <img alt="destination logs" />
</Frame>

### Filter through the logs

* **By Event Name**: You can select a subset of events to show in the log by clicking **Select events** and then ticking the relevant events.
* **By Date**: You can use the date picker in the top right corner to select log lines from a particular date range.
* **By Forwarding Status**: You can click **Select status** to see the [Forwarding Status](#forwarding-status) of a particular event.
* **By Destination Type**: Whether the forwarding is processed through the **Server** or through the **Browser** (client-side).

### Forwarding Status

Every event that gets processed by the Destination gets a forwarding status.
This status gives you insight as to *how* the Destination processed this data.

| Status       | Definition                                                                                                                                                                                                                                                                                                                                         |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Success`    | The event was correctly received by the destination                                                                                                                                                                                                                                                                                                |
| `Failure`    | The event failed to be delivered, read the log detail for more information                                                                                                                                                                                                                                                                         |
| `Retry`      | The event is being retried (until `Success` or `Failure`)                                                                                                                                                                                                                                                                                          |
| `Filtered`   | The event was processed by the Destination and filtered out (i.e. it has **not** been sent to the destination) based on one of the [Destination Filters](/destinations/filters)                                                                                                                                                                    |
| `External`   | An event was fired to this destination that was **not triggered by Converge**  <Note> If you see a bunch of events with an `External` status, this means that another tracking source is still active and should likely be turned off </Note>                                                                                                      |
| `Skipped`    | An event was processed by the Destination and skipped by the Destination to adhere to the Destination Specification <Info> This status usually occurs when Converge processes both browser-side and server-side events but the Destination does not accept server-side events or cannot effectively deduplicate events from two sources.   </Info> |
| `No consent` | The server-side event was not forwarded because the visitor has not given consent for the destination consent category.                                                                                                                                                                                                                            |


# Overview
Source: https://docs.runconverge.com/destinations/overview



## What are destinations?

Destinations in Converge are integrations that let you send data from Converge to other platforms and services. They help you streamline your data flow and improve marketing efficiency.

## What can you do with destinations?

* **Ad platforms**: Replace traditional tracking pixels by sending data directly from Converge. This helps with conversion tracking and remarketing.
* **Analytics and marketing tools**: Send data to analytics services, email marketing tools, and customer data platforms.

<Note> If you are looking to pull in ad platform-specific data (e.g. Ad Spend) in Converge, then check out our [Ad Platform Source Integrations](/ad-platforms/integrations/overview) </Note>

## Available destinations

### Ad Platforms

<CardGroup>
  <Card
    title="AppLovin"
    href="/destinations/integrations/applovin"
    icon={
<AppLovinIcon/>
}
  />

  <Card
    title="AWIN"
    href="/destinations/integrations/awin"
    icon={
<AWINIcon/>
}
  />

  <Card
    title="Criteo"
    href="/destinations/integrations/criteo"
    icon={
<CriteoIcon/>
}
  />

  <Card
    title="Meta Ads (Facebook Ads)"
    href="/destinations/integrations/facebook"
    icon={
<FacebookIcon/>
}
  />

  <Card
    title="Google Ads - Conversion tracking (Browser)"
    href="/destinations/integrations/google-ads-conversions"
    icon={
 <GoogleAdsIcon/>
}
  />

  <Card
    title="Google Ads API - Conversion tracking (Server)"
    href="/destinations/integrations/google-ads-conversions-server-side"
    icon={
 <GoogleAdsIcon/>
}
  />

  <Card
    title="Google Ads - Remarketing"
    href="/destinations/integrations/google-ads-remarketing"
    icon={
 <GoogleAdsIcon/>
}
  />

  <Card
    title="Microsoft Ads (Bing Ads)"
    href="/destinations/integrations/bing"
    icon={
<MicrosoftAdsIcon/>
}
  />

  <Card
    title="MGID"
    href="/destinations/integrations/mgid"
    icon={
<MGIDIcon/>
}
  />

  <Card
    title="OpenAI Ads"
    href="/destinations/integrations/openai"
    icon={
<OpenAIAdsIcon/>
}
  />

  <Card
    title="Outbrain"
    href="/destinations/integrations/outbrain"
    icon={
<OutbrainIcon/>
}
  />

  <Card
    title="Pinterest Ads"
    href="/destinations/integrations/pinterest"
    icon={
<PinterestAdsIcon/>
}
  />

  <Card
    title="Reddit"
    href="/destinations/integrations/reddit"
    icon={
<RedditIcon/>
}
  />

  <Card
    title="Snapchat Ads"
    href="/destinations/integrations/snapchat"
    icon={
<SnapchatAdsIcon/>
}
  />

  <Card
    title="Taboola"
    href="/destinations/integrations/taboola"
    icon={
<TaboolaIcon/>
}
  />

  <Card
    title="TikTok Ads"
    href="/destinations/integrations/tiktok"
    icon={
<TikTokAdsIcon/>
}
  />

  <Card
    title="Twitter/X"
    href="/destinations/integrations/twitter"
    icon={
<XAdsIcon/> 
}
  />

  <Card
    title="Vibe"
    href="/destinations/integrations/vibe"
    icon={
<VibeIcon/>
}
  />
</CardGroup>

### Analytics

<CardGroup>
  <Card
    title="Google Analytics 4 (GA4)"
    href="/destinations/integrations/ga4"
    icon={
<GA4Icon/>
}
  />
</CardGroup>

### Email/SMS Marketing

<CardGroup>
  <Card
    title="Klaviyo"
    href="/destinations/integrations/klaviyo"
    icon={
<KlaviyoIcon/>
}
  />

  <Card
    title="Postscript"
    href="/destinations/integrations/postscript"
    icon={
<PostscriptIcon/>
}
  />

  <Card
    title="Customer.io"
    href="/destinations/integrations/customerio"
    icon={
<CustomerIOIcon/>
}
  />
</CardGroup>

### A/B-testing

<CardGroup>
  <Card
    title="Convert"
    href="/destinations/integrations/convert"
    icon={
<ConvertIcon/>
}
  />
</CardGroup>

### Data Warehouse

<CardGroup>
  <Card
    title="BigQuery"
    href="/destinations/integrations/bigquery"
    icon={
<BigQueryIcon />
}
  />
</CardGroup>

### Misc

<CardGroup>
  <Card title="Custom HTML" href="/destinations/integrations/custom-html" icon="code" />
</CardGroup>


# Analytics
Source: https://docs.runconverge.com/getting-started/analytics

How to analyze your data in Converge

<CloudinaryVideo />

## Introduction

Converge offers multiple reporting options to analyze data from your **Event sources** and **Marketing sources**.

<Note>Insights and Dashboards require a separate license. Contact your Converge rep for access.</Note>

***

## Overview report

The Overview Report gives you a quick look at your **key metrics**.

It includes:

* **Blended**: Metrics based on all your connected sources.
* **Platforms**: In-platform metrics from each marketing source.

You can customize the report to show only the metrics and sections you care about.

<Frame>
  <img alt="data quality" />
</Frame>

***

## Pacing Sheet

Many merchants use separate daily spreadsheets to track their core metrics, but these spreadsheets are not real-time and are prone to data entry errors.

The Pacing Sheet replaces your daily spreadsheet with **up-to-date, accurate data** directly from Converge, helping you to spot **trends and anomalies**.

It includes:

* **Blended**: Metrics based on all your connected sources.
* **Platforms**: In-platform metrics from each marketing source.

You can customize the table to show only the metrics and sections you care about.

<Frame>
  <img alt="data quality" />
</Frame>

***

## Attribution report

The Attribution Report shows how your **Channels**, **Campaigns**, **Ad sets**, or **Ads** are performing—and what’s driving your business.

Metrics are attributed using:

* **First-party attribution**: Converge attribution based on the model you select and your tracking parameters. Identified with this icon: <ConvergeIcon />.
* **In-platform attribution**: Metrics from the ad platforms themselves. Identified with this icon: <InPlatformIcon />.

You can adjust your **first-party attribution** with the attribution models described [here](/attribution/models).

<Frame>
  <img alt="data quality" />
</Frame>

***

## Landing pages report

The Landing Pages Report shows performance for each page users landed on. Metrics include **sessions**, **purchases**, **revenue**, and **conversion rate**.

You can customize this report to focus on metrics that matter to you.

<Frame>
  <img alt="data quality" />
</Frame>

***

## Product report

The Product Report shows how individual **products** are performing across your store. Use it to make smarter ad buying decisions on a per-product level and scale budgets toward your best performers.

It includes metrics like:

* **Items sold**: Number of units sold per product.
* **Revenue**: Total revenue generated per product.
* **Spend**: Estimated ad spend per product.
* **Average price**: Average selling price per product.
* **CPA**: Cost per acquisition for each product.
* **Conversion rate**: How often views of a product lead to a purchase.

You can filter and sort by any metric to quickly find your top and bottom performers.

<Note>
  **Spend** is calculated by taking your total ad spend and dividing it across products proportionally based on the number of "Viewed Product" events that originated from paid sessions.
</Note>

<Frame>
  <img alt="data quality" />
</Frame>

***

## Insights

Insights are **custom reports** you can create to further analyze your data. Reports can use data from your **Event sources** and **Marketing sources**, and can show **predefined metrics** or **calculate custom metrics**.

You can visualize Insights as:

|                                             |                                             |   |
| :------------------------------------------ | :------------------------------------------ | - |
| <Frame> <img alt="data quality" /> </Frame> | <Frame> <img alt="data quality" /> </Frame> |   |
| <Frame> <img alt="data quality" /> </Frame> | <Frame> <img alt="data quality" /> </Frame> |   |
| <Frame> <img alt="data quality" /> </Frame> | <Frame> <img alt="data quality" /> </Frame> |   |
| <Frame> <img alt="data quality" /> </Frame> | <Frame> <img alt="data quality" /> </Frame> |   |

***

## Dashboards

Dashboards are **custom overviews** where you can view multiple **Insights** side-by-side.

You can rearrange the layout to make dashboards easy to read.

<Frame>
  <img alt="data quality" />
</Frame>

***

## Further reading

* [Learn how attribution works in Converge](/attribution/introduction)
* [Learn how to use the Overview Report](/attribution/overview)
* [Learn how to use the Pacing Sheet](/attribution/pacing)
* [Learn how to use the Attribution Report](/attribution/channels)
* [Learn how to use the Products Report](/attribution/products)
* [Learn how to create Insights](/insights-dashboards/insights)
* [Learn how to create Dashboards](/insights-dashboards/dashboards)


# Destinations
Source: https://docs.runconverge.com/getting-started/destinations

How to forward data from Converge to your marketing tools

<CloudinaryVideo />

## Introduction

Destinations in Converge let you forward data to other platforms and services. They help streamline your data flow and make your marketing setup more efficient.

***

## Available destinations

Converge supports destinations across your marketing stack, including:

* **Ad platforms**: Meta Ads (Facebook Ads), Google Ads, Pinterest Ads, TikTok Ads
* **Analytics**: Google Analytics 4
* **Other tools**: BigQuery, Klaviyo, Postscript

See the full list of supported destinations [here](/destinations/integrations/overview).

***

## Event mapping

Converge automatically maps your tracked events to the expected format for each destination. For example:

* `Placed Order` → `Purchase` in **Meta Ads**
* `Placed Order` → `purchase` in **GA4**
* `Placed Order` → `PURCHASE` in **Snapchat**

Each destination has a **default mapping**, which automatically translates events that follow the [event spec](/sources/converge-spec) to the right format for your destination.

You can also send **custom events** and map them manually to destination-specific events.

<Frame>
  <img alt="forwarding modes" />
</Frame>

***

## Client-side and Server-side

Each destination can forward events either **client-side**, **server-side** or both, depending on what the destination integration supports. You’ll find this info when adding a new destination or in the [docs](/destinations/integrations/overview) for each destination.

<Frame>
  <img alt="forwarding modes" />
</Frame>

How an event can be forwarded depends on **how the event was tracked**:

| Event source | Forwarding mode |           Supported          |
| :----------- | :-------------- | :--------------------------: |
| Client-side  | Client-side     | <Icon icon="circle-check" /> |
| Client-side  | Server-side     | <Icon icon="circle-check" /> |
| Server-side  | Client-side     | <Icon icon="circle-xmark" /> |
| Server-side  | Server-side     | <Icon icon="circle-check" /> |

## Event enrichment

Converge enriches **server-side forwarded events** with data from the user’s profile.

For example, if the event itself doesn’t include an email address, but the profile of user identified by Converge does, Converge will add the email before forwarding the event.

<Frame>
  <img alt="consent settings" />
</Frame>

## Consent

You can control whether an event is forwarded to your destination based on user consent.

Each destination is categorized as either **Analytics** or **Marketing**. You can configure how to forward events in different scenarios.

<Frame>
  <img alt="consent settings" />
</Frame>

<Warning>Consent in Converge is different from Google Consent Mode or Microsoft Consent Mode. If you need to use those, you’ll need to implement them separately. Learn more [here](/guides/implementing-consent-mode).</Warning>

## Monitoring destinations

Use **Event Quality** to inspect the properties being forwarded with your events and **Logs** to review individual events sent to each destination.

<Frame>
  <img alt="event quality" />
</Frame>

## Finding Destinations

You can find your destinations by going to **Event streams** under **Destinations** in the main menu.

<Frame>
  <img alt="forwarding modes" />
</Frame>

## Further reading

* [How to monitor your destinations](/destinations/monitoring)
* [How to apply filters to your destinations](/destinations/filters)
* [How to map events to your destinations](/destinations/event-mapping)
* [How to set consent for a destination](/destinations/consent)


# Getting help
Source: https://docs.runconverge.com/getting-started/getting-help

How to get help with Converge

If you need help using Converge, here are your options:

## Documentation

Our documentation explains how Converge works. Use the side menu, search bar, or the [overview](/) to find what you need.

<Frame>
  <img alt="data quality" />
</Frame>

## AI Agent

Instead of searching, you can ask our AI agent a question directly in the search field. It will try to answer based on the docs.

<Frame>
  <img alt="data quality" />
</Frame>

## Chat

You can chat with our support team from inside your workspace. They’ll respond as soon as possible during business hours.

<Frame>
  <img alt="data quality" />
</Frame>

## Email

You can also email our support team. You can find the email inside your workspace. We'll get back to you as soon as possible during business hours.


# Sources
Source: https://docs.runconverge.com/getting-started/sources

How to get data into Converge?

<CloudinaryVideo />

## Introduction

For Converge to work, it first needs data. You can get data into Converge by connecting it to **Sources**. There are two types of sources:

1. **Event sources**: Collect real-time customer event data from the Converge web pixel, server webhooks, or integrations (like Shopify).
2. **Marketing sources**: Pull in pre-attributed metrics—like Ad Spend, Impressions, Clicks, and Conversions from platforms like Facebook Ads and Google Ads.

All source data is blended and used by Converge to power your **Analytics**.

***

## Event sources

Tracking first-party events is at the core of Converge. You can track any event you want, but in most cases Converge will automatically track key events like *Viewed Product*, *Added to Cart*, and *Placed Order*.

### Client-side vs. server-side tracking

You can track events using two methods:

* **Client-side**: Events are sent directly from the user's browser to Converge. For example *Viewed Product*, *Added to Cart*, and *Started Checkout* are tracked by the **Converge JS Pixel**, added to your website directly or via an integration.

* **Server-side**: Events are sent from your servers to Converge after users interact with your website. For example *Placed Order* or *Cancelled Subscription* are sent to Converge via integrations like **Shopify**, **WooCommerce**, or the **Converge Webhook**.

### Profiles and sessions

Converge groups all events into **Profiles** and **Sessions**:

* **Profiles**: A profile is a long-term view of a user’s behavior. All events tied to a user are grouped here.
* **Sessions**: A session represents a single visit to your site. Sessions are attributed to Channels or Ad Campaigns, helping you understand how users arrive on your website and what they do.

<Frame>
  <img alt="data quality" />
</Frame>

### Monitoring event sources

You can see which events are being sent with which properties by checking the [Data Quality](/data-management/data-quality) report or the [Event Logs](/data-management/event-logs).

### Finding event sources

Go to **Event sources** under **Data management** in the main menu to see all connected event sources.

<Frame>
  <img alt="data quality" />
</Frame>

***

## Marketing sources

Marketing sources pull in metrics from platforms like **Facebook Ads**, **Google Ads**, and **TikTok Ads**. Once connected, Converge will sync metrics like **Ad Spend**, **Impressions**, **Clicks**, **Conversions**, **Revenue**, and metadata like **Campaign**, **Ad Set**, and **Ad** names.

### Blended reports

Marketing source data is blended with first-party event data from your Event sources to create richer reports.

For example, if you connect **Google Ads**, you can report on both **Sessions** and **Purchases** (from events) and **Impressions** and **Ad Spend** (from marketing data), and you can calculate metrics like **ROAS** based on both.

<Frame>
  <img alt="blended sources" />
</Frame>

<Note>Converge doesn’t alter the metrics it receives from your marketing sources. But your destinations setup can influence how these platforms attribute results.</Note>

### Finding marketing sources

Go to **Marketing Sources** under **Data management** in the main menu to view all connected Marketing sources.

<Frame>
  <img alt="data quality" />
</Frame>

***

## Further reading

* [Learn more about client-side event sources](/sources/website-integrations/converge-pixel)
* [Learn more about server-side event sources](/sources/server-integrations/webhook)
* [Learn how Converge stitches client-side and server-side events](/sources/concepts/aliases)
* [Learn how Converge deduplicates events](/sources/concepts/deduplication)
* [Learn about all available Marketing sources](/ad-platforms/integrations/overview)


# What is Converge?
Source: https://docs.runconverge.com/getting-started/what-is-Converge

An introduction to the Converge platform

<CloudinaryVideo />

## Introduction

Converge is the **all-in-one marketing measurement platform** for e-commerce. It helps you manage tracking and understand what drives your business.

The platform has two main products:

1. **Destinations**: Set up tracking once, and we forward your data to ad platforms, analytics tools, email providers, and more. Everything’s optimized automatically.
2. **Analytics**: Blend your first-party tracking with performance data from your marketing tools. Build custom reports to see what’s driving your business.

<ConvergeHeroAnimation />

***

## Benefits of Converge

Setting up a high-quality marketing measurement stack is getting increasingly difficult.

It requires:

* **Deep knowledge** in your team about marketing and engineering.
* **Constant maintenance** to keep up with an ever-evolving tracking landscape.
* **24/7 observability** to monitor if everything works as expected.

Lacking any of these will result in **inaccurate reports** or **under-optimized campaigns**.

Converge fixes this by giving you an integrated platform that handles:

* **Data collection** from your web and server-side data sources.
* **In-platform tracking** that forwards your data to your marketing tools.
* **Unified profiles** that track your users over their entire customer journey.
* **Blended dataset** that joins your first-party data with in-platform metrics.
* **Advanced attribution** that tells you what's actually driving results.

All in an **easy-to-implement** platform that **guarantees accurate reporting** and **optimized tracking**.

***

## How Converge works

Converge connects your data sources, blends and enriches the data, sends it to your destinations, and powers your reports.

We group data sources into:

* **Event sources**: Event data from a web pixel, e-commerce integrations or webhooks.
* **Marketing sources**:  Data like spend, clicks and conversions from your ad platforms.

We blend everything together into unified profiles, enrich your events, and send them to your destinations like:

* **Ad platforms**: Google Ads, Facebook Ads, TikTok, and more.
* **Analytics**: Google Analytics 4.
* **Email**: Klaviyo, Postscript.

Based on the blended dataset you can create reports like:

* **Overview report**: A quick overview of all your key metrics.
* **Attribution report**: Which of your channels and campaigns are performing the best.
* **Insights**: Custom reports based on your blended dataset.
* **Dashboards**: Custom dashboards bringing your Insights together.


# Comparing Shopify with Converge
Source: https://docs.runconverge.com/guides/compare-shopify-converge

How to check if your results in Converge match with Shopify Analytics

## Introduction

If you're comparing orders, revenue, or new customer counts between Shopify and Converge, you should expect some discrepancy. Converge and Shopify use different definitions, different identity models, and (sometimes) different sets of orders, so the two will rarely align to the order or the dollar.

For most use cases (comparing channels, watching CAC trends, optimizing ads) the **trend** is what matters, not the exact figures. This guide explains the common reasons your numbers won't match, then walks through how to track down a specific discrepancy when you need to.

## Common reasons for order or revenue discrepancies

When the gap is in orders or revenue, it's usually one of these:

<AccordionGroup>
  <Accordion title="Different revenue definitions">
    Shopify and Converge calculate revenue differently:

    * **Shopify Sales** = `Gross Revenue` — `Refunds` — `Gift Card Revenue`
    * **Converge Revenue** = `Gross Revenue` + `Gift Card Revenue`

    Shopify subtracts refunds and excludes gift card sales. Converge includes gift card sales as regular revenue and doesn't subtract refunds (refund data isn't always available server-side). To compare apples to apples, build a Shopify report that adds gift card sales back in and excludes returns — see [Create a custom report in Shopify](#step-3-create-a-custom-report-in-shopify) below.
  </Accordion>

  <Accordion title="Post-order edits">
    Converge only receives the original order. If an order is edited after it's placed, Converge won't reflect the change. Common cases:

    * Manual edits in Shopify admin (line items added or removed, totals changed).
    * Post-purchase upsells (e.g. via apps like Zipify).
    * Refunds and cancellations.

    Shopify reports always show the latest state of the order; Converge shows the order as it was when first received.
  </Accordion>

  <Accordion title="Different time anchors">
    Shopify reports use your store's configured timezone. Converge reports use the timezone of your workspace and the insight's date filter. If those don't match, an order placed late in the evening can land on a different day in each system — which matters most when comparing a single day or a short window.

    Also keep in mind that Shopify reports usually anchor an order to its **created** date, while some Converge views anchor to the date the event was received (these are almost always the same, but not always).
  </Accordion>
</AccordionGroup>

## Common reasons for New Customer Order discrepancies

The Converge **New Customer Order** count rarely matches the **First-time customer** count in Shopify exactly, and the gap is usually largest right after you onboard. The four reasons below cover almost every case.

<AccordionGroup>
  <Accordion title="Reason 1: Converge only knows about orders it has received">
    Shopify's "first-time customer" flag is anchored to the customer's first order **ever placed in your store**. Converge's flag is anchored to the first `Placed Order` event **Converge has actually received** for that profile.

    This shows up most clearly in three situations:

    * **Recent onboarding.** If you connected Converge to Shopify recently, customers whose first order pre-dates your Converge installation will look like new customers to Converge the next time they buy. Shopify still has the earlier order; Converge doesn't.
    * **Migrated or merged stores.** If you migrated to a new Shopify store, or merged multiple stores into one, the historical orders Shopify imported during the migration may not flow through to Converge. Converge sees those re-imported customers as new on their next purchase, while Shopify recognises them as returning.
    * **POS, draft orders, and other off-website channels.** By default Converge tracks orders from the Shopify Online Store. If a customer first buys through Shopify POS or another channel that isn't being forwarded to Converge, their first online order will be marked as a new customer order in Converge but as a returning one in Shopify.
  </Accordion>

  <Accordion title="Reason 2: Converge and Shopify identify customers differently">
    Converge identifies customers by **email**. Shopify identifies customers by its own internal **customer ID**. These usually agree, but they diverge in a few common cases:

    * **Email changes.** If a returning customer checks out with a different email address than they used previously, Converge will see them as a new customer (no prior `Placed Order` for that email), while Shopify will still link them to their existing customer record via the Shopify customer ID. Typos in the email field have the same effect.
    * **Guest checkouts.** Customers who repeatedly check out as guests, sometimes with slightly different email addresses, will be counted as new customers more often in Converge than in Shopify.
    * **Household accounts.** If two people in the same household share a payment method but use different email addresses, Converge will treat them as two separate customers; Shopify may collapse them depending on its own customer-matching rules.
  </Accordion>

  <Accordion title="Reason 3: Gift cards and subscription orders">
    A few specific order types behave differently between the two systems:

    * **Gift card purchases.** Shopify doesn't count a gift card purchase as a "first-time customer" purchase. Converge treats a gift card order like any other `Placed Order`, so a customer whose first purchase is a gift card will be counted as a new customer in Converge but not in Shopify.
    * **Subscription first orders.** If you use a subscription app, the first order of a new subscription may be tagged or routed differently in Shopify than in Converge. Check whether the first-order tag your subscription app applies is excluded from either system's reporting.
    * **Refunded and cancelled orders.** Shopify can retroactively remove a customer from "first-time customers" if their only order is fully refunded. Converge does not subtract refunds from the New Customer Order count, since refund events aren't always available server-side.
  </Accordion>

  <Accordion title="Reason 4: Timezone and reporting window">
    The same timezone and date-anchor differences that affect revenue comparisons (see [Common reasons for order or revenue discrepancies](#common-reasons-for-order-or-revenue-discrepancies) above) apply to new customer counts too. An order placed late in the evening can land on a different calendar day in each system, which matters most when comparing a single day or a short window.
  </Accordion>
</AccordionGroup>

## Troubleshooting discrepancies

When you have a specific discrepancy you want to track down in a metric such as revenue, orders, or new customers, work through the steps below in order. Steps 1 and 2 catch the most common avoidable causes; step 3 lets you isolate the exact orders behind the gap.

### Step 1: Check filters on your Shopify source

Filters can prevent certain orders from being tracked in Converge at all. A filtered-out first order will also cause the customer's *next* order to be marked as a new customer order in Converge, even though Shopify still treats them as returning. To check:

1. Go to <OutboundLink /> in Converge.
2. Open your Shopify source.
3. Check whether any filters are enabled under **Exclude orders with these tags**.
4. Check whether any filters are enabled under **Exclude orders from these channels**.
5. Check whether **Include orders from these shipping country codes** is enabled.

If any filters are enabled, apply the same filters when you build your Shopify report. Filters are configured per source — see [Filtering orders at ingestion](/sources/server-integrations/shopify#filtering-out-certain-orders-at-ingestion) for details.

### Step 2: Align the comparison window

Before assuming the data is off, make sure the comparison itself is fair:

* **Use the same date range** in both systems, in the **same timezone**.
* **Exclude refunds and post-order adjustments** on the Shopify side (the custom report below does this).
* **Add gift card sales back into Shopify revenue** if you're comparing revenue.
* **Match the metric granularity**: customer-level on both sides, or order-level on both sides.

### Step 3: Create a custom report in Shopify

To compare Shopify with Converge on revenue and orders, build a custom Shopify report that mirrors Converge's definitions:

1. Go to **Analytics** → **Reports**.
2. Click **New exploration**.
3. Replace the default query with:

```sql theme={null}
FROM sales
SHOW (gift_card_gross_sales + total_sales) AS revenue, orders
WHERE is_return_related = false AND excludes_post_order_adjustments = true
SINCE last_month
UNTIL last_month
ORDER BY revenue DESC
VISUALIZE revenue
```

4. Click **Run**.

This shows revenue and order count for the last month, matching what Converge would show for the same time range. Change the date in the top left to compare other periods.

### Step 4: Drill into specific orders

If steps 1–3 don't fully close the gap, build a per-order list in each system and diff them:

1. **In Converge**: go to <OutboundLink /> and click **Create new insight**. Add **Revenue**, **Placed Order** (aggregated by Count), and **New Customer Order** (aggregated by Count) as metrics. Click **Add breakdown** and select **id** (the Shopify Order ID). Enable **Show totals** under **Options** above the table. Set the date range you want to compare.
2. **In Shopify**: open the custom report from step 3. In the right pane, go to **Dimensions**, click the **plus sign**, find **Order ID**, and click **Apply**. If you're investigating a new customer gap, also add a **First-time customer** column or export your store's first-time customers list separately. Set the date range to match Converge.
3. **Diff the two lists.** Orders that appear in one system but not the other usually trace back to a filter, a post-order edit, or a refund. Orders flagged as new customer orders in one system but not the other typically map to one of the reasons in [Common reasons for New Customer Order discrepancies](#common-reasons-for-new-customer-order-discrepancies) — most often gift cards, email mismatches, POS-first customers, or repeat customers whose earlier orders pre-date your Converge install.

If you've worked through all four steps and still can't explain the gap, reach out to Converge support with the date range, the two numbers, and any specific order IDs that look wrong — that's enough to investigate from our side.


# Debugging stitching issues
Source: https://docs.runconverge.com/guides/debugging-stitching-issues

How to debug stitching issues in Converge

## Introduction

Stitching server-side tracked events to web sessions is a vital part of a healthy tracking setup. It enables Converge to optimize tracking for your destinations. That’s why it’s important to monitor your stitching rate and check if it falls below expected levels. A stitching rate of **95%+** is considered healthy.

You can review your stitching rate in the Data Quality report. It shows the percentage of server-side Placed Order events that Converge matched to a web session.

<Frame>
  <img alt="Debugging stitching issues - Healthy stitching rate" />
</Frame>

## How to review your stitching rate

If your stitching rate drops below 95%, the Data Quality report will show a warning. Start investigating by clicking on the event and navigating to the Stitching tab in the event details pane on the right.

<Frame>
  <img alt="Debugging stitching issues - Reviewing stitching rate" />
</Frame>

In this overview, you'll see:

| Field                    | Description                                      |
| :----------------------- | :----------------------------------------------- |
| **Sales channel type**   | Which sales channels were applied to your events |
| **Stitching rate graph** | Stitching rate over time                         |
| **Total server events**  | Total received server-side events                |
| **Unstitched events**    | Number of unstitched server-side events          |
| **Stitched rate**        | Percentage of stitched server-side events        |
| **Unstitched Events**    | List of individual unstitched events             |
| **Delayed Events**       | List of events stitched after being sent         |

To verify if there’s a real issue, select a time range covering a few weeks. If your stitching rate is above 95% on most days, it’s best to keep monitoring before digging deeper.

## Possible causes

There are many reasons why a session wasn’t stitched, but most issues fall into three categories.

### Web session wasn’t tracked

For stitching to happen, the web session must be tracked first. Common reasons it might not be:

1. **Ad blockers** could prevent Converge from tracking the session.
2. **Consent settings** could block tracking based on user preferences.
3. **Bad implementations** could prevent Converge from loading and tracking the session.

<Note>Although Converge works to avoid being blocked by ad blockers, it’s almost impossible to fully prevent. This is why we don’t aim for a 100% stitching rate.</Note>

If your site’s consent settings aren’t the cause, check your Converge implementation and make sure all pages are tracked correctly.

### Missing aliases

Converge uses aliases to stitch server-side events to web sessions. These are unique identifiers, like a **Cart Token**, **Email**, or **User ID**.

If a server-side event doesn’t contain an alias that matches a client-side tracked event, it won’t be stitched. You can check aliases for individual unstitched events by clicking the **\{ }** icon and going to the **Aliases** tab.

It’s best practice to add multiple aliases to your events. This gives Converge more options to stitch events and improves your stitching rate. Learn more about which aliases to pass [here](/sources/concepts/aliases#what-aliases-should-i-pass%3F).

### Delayed aliases

Sometimes a server-side event can’t be stitched immediately but gets stitched later.

For example, a server-side event might include only an email address. If the user didn’t enter their email during the web session (because they were already logged in), stitching can’t happen right away.

If the user later logs in again or subscribes to a newsletter and submits their email, Converge can stitch the past server-side event.

In this case:

* **Converge reports will update** based on the stitched event.
* But **events already sent to your destinations won’t retroactively include client-side identifiers**, which can impact conversion tracking.


# Implementing Consent Mode
Source: https://docs.runconverge.com/guides/implementing-consent-mode

How to implement Google and Microsoft Consent Mode for Converge

**Google** and **Microsoft** both introduced a framework called **Consent Mode**. It acts like a translator between your cookie banner and their tracking tools, adjusting what data gets collected based on the user's consent.

This guide shows how to implement Consent Mode when using Converge.

<Note>This guide describes how to implement Google and Microsoft Consent Mode. Converge has additional tools for handling consent for all your destinations that you can read about [here](/destinations/consent).</Note>

***

## Why implement Consent Mode?

Consent Mode allows you to respect users' privacy preferences while still collecting meaningful data for analytics and advertising. Without it, you risk either violating privacy laws or losing valuable insights and attribution information.

* <OutboundLink />
* <OutboundLink />

***

## Google vs Microsoft Consent Mode

Even though both frameworks are called "Consent Mode" and work similarly, they're separate. If you use products from both companies, you need to implement both frameworks.

### Consent Mode process

Google and Microsoft Consent Mode have the same basic requirements:

1. **Default**: Set a default consent status for all users before they interact with your cookie banner. You can customize defaults per country.
2. **Update**: When a user makes a choice on your cookie banner, update the Consent Mode status to match.

### Consent types

Consent Mode requires you to set statuses for different types of consent. These affect how tracking behaves.

| Consent type            | Description                                       | Required by Google | Required by Microsoft |
| :---------------------- | :------------------------------------------------ | :----------------: | :-------------------: |
| **ad\_storage**         | Allows storage (like cookies) for advertising     |         Yes        |          Yes          |
| **ad\_user\_data**      | Sets consent for sending user data related to ads |         Yes        |           No          |
| **ad\_personalization** | Sets consent for personalized ads                 |         Yes        |           No          |
| **analytics\_storage**  | Allows storage (like cookies) for analytics       |         Yes        |           No          |

Microsoft currently only requires **ad\_storage**. You can still set the others in case they expand support later.

<Info>You can extend Consent Types, but Google and Microsoft tracking tools won't use them. Examples: **functionality\_storage**, **personalization\_storage**, **security\_storage**. These add no value for tracking today.</Info>

### Consent mode behavior

When you've implemented Consent Mode correctly, the tracking products from Google and Microsoft will automatically adjust their tracking behavior based on the consent that has been given. A few examples are:

* **analytics\_storage granted**: GA4 web tracking will place *cookies* and process *IP addresses*.
* **analytics\_storage denied**: GA4 web tracking won't use *cookies* or process *IP addresses* but will send *cookieless pings* used in [behavioral modeling](https://support.google.com/analytics/answer/11161109?sjid=5719561030769842599-EU).
* **ad\_storage granted**: Google Ads web tracking will place *cookies* and process *click IDs* in the URL.
* **ad\_storage denied**: Google Ads web tracking won't use *cookies* or process *click IDs* in the URL but will send *cookieless pings* used in [conversion modeling](https://support.google.com/google-ads/answer/10548233?hl=en-GB).

For a full description of how Consent Mode impacts tracking behavior, you can read this documentation for <OutboundLink /> and this documentation about <OutboundLink />.

<Note>Since Google Consent Mode and Microsoft Consent Mode will impact behavior of their tracking based on the user's consent, **you don't have to set up additional consent settings in Converge**. It's best practice to always load Google and Microsoft destinations from Converge, regardless of consent given. Read more about it [here](#using-consent-mode-with-consent-settings-in-converge).</Note>

<Warning>If you implement Consent Mode after previously tracking users without it, you may see a drop in tracked users or conversions in your Google or Microsoft products.</Warning>

***

## Implementing Consent Mode

The Google and Microsoft destinations in Converge (like *GA4*, *Google Ads*, *Microsoft Ads*) respect Consent Mode settings automatically, but **Converge doesn't set them for you**. You have two options:

* **Consent Management Platform (CMP)**: Many CMPs (like Cookiebot, CookieYes, OneTrust) offer Consent Mode support out of the box.
* **Custom implementation**: You can implement Consent Mode manually with developer help.

### Key requirements

For Converge to work with your Consent Mode setup:

1. Set the **default** consent mode before the Converge JavaScript pixel loads.
2. Set the **update** consent mode (if the user already gave consent) after the **default** but still before the Converge pixel loads.

### Examples

You can use the following examples to implement Consent Mode for Converge.

<AccordionGroup>
  <Accordion title="Cookiebot">
    Cookiebot has built-in support for Consent Mode, but you need to set a default consent status yourself, prior to implementing Cookiebot and Converge.

    Add this code **before the Converge pixel** in the **\<head>** of your website. It:

    * Sets different default statuses for NL, EU, and non-EU countries for Google Consent Mode and Microsoft Consent Mode.
    * Adds the Cookiebot script to handle updates when a user gives consent or has done so previously.

    ```JavaScript theme={null}
    <script data-cookieconsent="ignore">
        //Set default Google Consent Mode status
        window.dataLayer = window.dataLayer || [];
        function gtag() {
            dataLayer.push(arguments);
        }
        gtag("consent", "default", {
            ad_personalization: "granted",
            ad_storage: "granted",
            ad_user_data: "granted",
            analytics_storage: "granted",
            functionality_storage: "granted",
            personalization_storage: "granted",
            security_storage: "granted",
            wait_for_update: 500,
        });
        gtag("consent", "default", {
            ad_personalization: "denied",
            ad_storage: "denied",
            ad_user_data: "denied",
            analytics_storage: "granted",
            functionality_storage: "granted",
            personalization_storage: "granted",
            security_storage: "granted",
            wait_for_update: 500,
            region: ['NL']
        });
        gtag("consent", "default", {
            ad_personalization: "denied",
            ad_storage: "denied",
            ad_user_data: "denied",
            analytics_storage: "denied",
            functionality_storage: "granted",
            personalization_storage: "granted",
            security_storage: "granted",
            wait_for_update: 500,
            region: ['AT','BE','BG','HR','CY','CZ','DK','EE','FI','FR','DE','GR','HU','IE','IT','LV','LT','LU','MT','PL','PT','RO','SK','SI','ES','SE','NO','IS','LI']
        });
        gtag("set", "ads_data_redaction", false);
        gtag("set", "url_passthrough", true);

        //Set default Microsoft Consent Mode status
        window.uetq = window.uetq || [];
        window.uetq.push('consent', 'default', {
            'ad_storage': 'denied',
            'wait_for_update': 500
        });
    </script>
    //Add Cookiebot script
    <script id="Cookiebot" src="https://consent.cookiebot.com/uc.js" data-cbid="[REPLACE WITH YOUR COOKIEBOT ID]"  type="text/javascript"></script>
    ```
  </Accordion>

  <Accordion title="CookieYes">
    CookieYes has built-in support for Consent Mode, but you need to set a default consent status yourself, prior to implementing CookieYes and Converge.

    Add this code **before the Converge pixel** in the **\<head>** of your website. It:

    * Sets different default statuses for NL, EU, and non-EU countries for Google Consent Mode and Microsoft Consent Mode.
    * Adds the CookieYes script to handle updates when a user gives consent or has done so previously.

    ```JavaScript theme={null}
    <script>
        //Set default Google Consent Mode status
        window.dataLayer = window.dataLayer || [];
        function gtag() {
            dataLayer.push(arguments);
        }
        gtag("consent", "default", {
            ad_personalization: "granted",
            ad_storage: "granted",
            ad_user_data: "granted",
            analytics_storage: "granted",
            functionality_storage: "granted",
            personalization_storage: "granted",
            security_storage: "granted",
            wait_for_update: 500,
        });
        gtag("consent", "default", {
            ad_personalization: "denied",
            ad_storage: "denied",
            ad_user_data: "denied",
            analytics_storage: "granted",
            functionality_storage: "granted",
            personalization_storage: "granted",
            security_storage: "granted",
            wait_for_update: 500,
            region: ['NL']
        });
        gtag("consent", "default", {
            ad_personalization: "denied",
            ad_storage: "denied",
            ad_user_data: "denied",
            analytics_storage: "denied",
            functionality_storage: "granted",
            personalization_storage: "granted",
            security_storage: "granted",
            wait_for_update: 500,
            region: ['AT','BE','BG','HR','CY','CZ','DK','EE','FI','FR','DE','GR','HU','IE','IT','LV','LT','LU','MT','PL','PT','RO','SK','SI','ES','SE','NO','IS','LI']
        });
        gtag("set", "ads_data_redaction", false);
        gtag("set", "url_passthrough", true);

        //Set default Microsoft Consent Mode status
        window.uetq = window.uetq || [];
        window.uetq.push('consent', 'default', {
            'ad_storage': 'denied',
            'wait_for_update': 500
        });
    </script>
    //Add CookieYes script
    <script id="cookieyes" type="text/javascript" src="https://cdn-cookieyes.com/client_data/[REPLACE WITH YOUR COOKIEYES WEBSITE KEY]/script.js" ></script>
    ```
  </Accordion>

  <Accordion title="Cookie Script">
    Cookie Script has built-in support for Consent Mode, but you need to set a default consent status yourself, prior to implementing Cookie Script and Converge.

    Add this code **before the Converge pixel** in the **\<head>** of your website. It:

    * Sets different default statuses for NL, EU, and non-EU countries for Google Consent Mode and Microsoft Consent Mode.
    * Adds the Cookie Script script to handle updates when a user gives consent or has done so previously.

    ```JavaScript theme={null}
    <script>
        //Set default Google Consent Mode status
        window.dataLayer = window.dataLayer || [];
        function gtag() {
            dataLayer.push(arguments);
        }
        gtag("consent", "default", {
            ad_personalization: "granted",
            ad_storage: "granted",
            ad_user_data: "granted",
            analytics_storage: "granted",
            functionality_storage: "granted",
            personalization_storage: "granted",
            security_storage: "granted",
            wait_for_update: 500,
        });
        gtag("consent", "default", {
            ad_personalization: "denied",
            ad_storage: "denied",
            ad_user_data: "denied",
            analytics_storage: "granted",
            functionality_storage: "granted",
            personalization_storage: "granted",
            security_storage: "granted",
            wait_for_update: 500,
            region: ['NL']
        });
        gtag("consent", "default", {
            ad_personalization: "denied",
            ad_storage: "denied",
            ad_user_data: "denied",
            analytics_storage: "denied",
            functionality_storage: "granted",
            personalization_storage: "granted",
            security_storage: "granted",
            wait_for_update: 500,
            region: ['AT','BE','BG','HR','CY','CZ','DK','EE','FI','FR','DE','GR','HU','IE','IT','LV','LT','LU','MT','PL','PT','RO','SK','SI','ES','SE','NO','IS','LI']
        });
        gtag("set", "ads_data_redaction", false);
        gtag("set", "url_passthrough", true);

        //Set default Microsoft Consent Mode status
        window.uetq = window.uetq || [];
        window.uetq.push('consent', 'default', {
            'ad_storage': 'denied',
            'wait_for_update': 500
        });
    </script>
    //Add Cookie Script script
    <script type="text/javascript" charset="UTF-8" src="//cdn.cookie-script.com/s/[REPLACE WITH YOUR COOKIE SCRIPT ID].js"></script>
    ```

    <Warning>Make sure that Google Consent Mode is enabled in Cookie Script by following the documentation [here](https://help.cookie-script.com/en/articles/30194-enable-google-consent-mode).</Warning>
  </Accordion>

  <Accordion title="Shopify Cookie Banner">
    You can use this code as a basis for your implementation in Shopify if you're using the Shopify Cookie banner.

    Add this code **before the Converge pixel** in the **\<head>** of your website and in your **Custom Pixel**. It:

    * Sets default consent statuses for Google Consent Mode and Microsoft Consent Mode.
    * Updates Google Consent Mode and Microsoft Consent Mode status after user gives consent.

    ```JavaScript theme={null}
    <script>
      document.addEventListener('DOMContentLoaded', function () {
      // Wait for Shopify object and customerPrivacy API
      if (window.Shopify && Shopify.customerPrivacy) {
        initializeConsent();
      } else {
        // Wait until it's available (retry approach)
        let retryCount = 0;
        const interval = setInterval(() => {
          if (window.Shopify && Shopify.customerPrivacy) {
            clearInterval(interval);
            initializeConsent();
          } else if (retryCount > 10) {
            clearInterval(interval);
          }
          retryCount++;
        }, 200);
      }
    });

    function initializeConsent() {
      var analytics_storage = window.Shopify.customerPrivacy.analyticsProcessingAllowed() ? 'granted' : 'denied';
      var ad_storage = window.Shopify.customerPrivacy.marketingAllowed() ? 'granted' : 'denied';

      //Set default Google Consent Mode status
      window.dataLayer = window.dataLayer || [];
      function gtag() {
          dataLayer.push(arguments);
      }
      gtag("consent", "default", {
          ad_personalization: ad_storage,
          ad_storage: ad_storage,
          ad_user_data: ad_storage,
          analytics_storage: analytics_storage,
          wait_for_update: 500
      });
      gtag("set", "ads_data_redaction", false);
      gtag("set", "url_passthrough", true);

      //Set default Microsoft Consent Mode status
      window.uetq = window.uetq || [];
      window.uetq.push('consent', 'default', {
          'ad_storage': ad_storage,
          'wait_for_update': 500
      });

      // React to consent changes
      document.addEventListener('visitorConsentCollected', function (event) {    
        gtag("consent", "update", {
            ad_personalization: event.detail.marketingAllowed ? "granted" : "denied",
            ad_storage: event.detail.marketingAllowed ? "granted" : "denied",
            ad_user_data: event.detail.marketingAllowed ? "granted" : "denied",
            analytics_storage: event.detail.analyticsAllowed ? "granted" : "denied"
        });
        
        window.uetq.push('consent', 'update', {
            'ad_storage': event.detail.analyticsAllowed ? "granted" : "denied"
        });

        cvg({
          "method": "consent",
          "analytics": event.detail.analyticsAllowed ? "granted" : "denied",
          "marketing": event.detail.analyticsAllowed ? "granted" : "denied"
        });
      });
    }

    </script> 
    ```
  </Accordion>

  <Accordion title="Custom implementation">
    You can use this code as a basis for your custom implementation. It doesn't integrate with any cookie banner and isn't set up to process an update with different values for the Consent Types.

    Add this code **before the Converge pixel** in the **\<head>** of your website. It:

    * Sets default consent statuses for Google Consent Mode and Microsoft Consent Mode.
    * Includes an `updateConsent` function to call when a user accepts all cookies or has done previously.

    ```JavaScript theme={null}
    <script data-cookieconsent="ignore">
        //Set default Google Consent Mode status
        window.dataLayer = window.dataLayer || [];
        function gtag() {
            dataLayer.push(arguments);
        }
        gtag("consent", "default", {
            ad_personalization: "granted",
            ad_storage: "granted",
            ad_user_data: "granted",
            analytics_storage: "granted",
            wait_for_update: 500,
        });
        gtag("consent", "default", {
            ad_personalization: "denied",
            ad_storage: "denied",
            ad_user_data: "denied",
            analytics_storage: "granted",
            wait_for_update: 500,
            region: ['NL']
        });
        gtag("consent", "default", {
            ad_personalization: "denied",
            ad_storage: "denied",
            ad_user_data: "denied",
            analytics_storage: "denied",
            wait_for_update: 500,
            region: ['AT','BE','BG','HR','CY','CZ','DK','EE','FI','FR','DE','GR','HU','IE','IT','LV','LT','LU','MT','PL','PT','RO','SK','SI','ES','SE','NO','IS','LI']
        });
        gtag("set", "ads_data_redaction", false);
        gtag("set", "url_passthrough", true);

        //Set default Microsoft Consent Mode status
        window.uetq = window.uetq || [];
        window.uetq.push('consent', 'default', {
            'ad_storage': 'denied',
            'wait_for_update': 500
        });

        function updateConsent(){
            gtag("consent", "update", {
                ad_personalization: "granted",
                ad_storage: "granted",
                ad_user_data: "granted",
                analytics_storage: "granted",
            });
            
            window.uetq.push('consent', 'update', {
                'ad_storage': 'granted'
            });
        }
    </script>
    ```
  </Accordion>

  <Accordion title="Custom implementation (granted by default)">
    If you want to always enable full tracking features in Google and Microsoft tracking, you can set a default consent status that sets all Consent Types to granted. Since all Consent Types are set to *granted* by **default**, you don't have to send an **update**.

    Add this code **before the Converge pixel** in the **\<head>** of your website. It:

    * Sets **default** consent statuses for Google Consent Mode and Microsoft Consent Mode with all Consent Types as **granted**.

    ```JavaScript theme={null}
    <script data-cookieconsent="ignore">
        //Set default Google Consent Mode status
        window.dataLayer = window.dataLayer || [];
        function gtag() {
            dataLayer.push(arguments);
        }
        gtag("consent", "default", {
            ad_personalization: "granted",
            ad_storage: "granted",
            ad_user_data: "granted",
            analytics_storage: "granted",
        });
        gtag("set", "ads_data_redaction", false);
        gtag("set", "url_passthrough", true);

        //Set default Microsoft Consent Mode status
        window.uetq = window.uetq || [];
        window.uetq.push('consent', 'default', {
            'ad_storage': 'granted',
            'wait_for_update': 500
        });
    </script>
    ```
  </Accordion>
</AccordionGroup>

***

## Using Consent Mode with Consent settings in Converge

You can also configure which destinations in Converge will load by using the **Consent settings** for each destination. Since Consent Mode is already handling how products from Google and Microsoft will behave based on consent given by the user, it's best practice to not enable any additional restrictions in Converge.

For the best results, configure consent as follows:

* Choose the **Analytics** or **Marketing** category based on the type of destination.
* Set the Consent mode setting to **Off**.

<Frame>
  <img alt="img" />
</Frame>

## Verify your implementation

You can validate your Google Consent Mode implementation by following [these docs](https://support.google.com/tagmanager/answer/14218557?hl=en).

You can validate your Microsoft Consent Mode implementation by following [these docs](https://help.ads.microsoft.com/#apex/ads/en/60119/1).

***

*Disclaimer: This guide provides general information. It is not intended as legal advice, and readers should consult with qualified counsel for advice regarding their specific circumstances. Converge disclaims any liability for actions taken based on the information provided in this post.*


# Measure Klaviyo revenue uplift
Source: https://docs.runconverge.com/guides/measure-klaviyo-revenue-uplift

How to measure the revenue uplift generated by Converge in Klaviyo.

## Introduction

If you're using Klaviyo as a destination with Converge, you can benefit from Converge's **re-identification** in your **abandoned browse**, **abandoned cart**, and **abandoned checkout** flows.

Where Klaviyo is only able to recognize returning users to your website by a **short-lived cookie**, Converge uses multiple identifiers that enable us to **recognize more users than Klaviyo**.

This enables us to enrich the server-side events sent to Klaviyo by Converge, which results in **more emails being sent** for event-based flows like abandoned browse, abandoned cart, and abandoned checkout, and will most likely **improve your overall sales**.

This guide shows you how to measure the uplift that's generated by the additional visitors that are identified by Converge.

## Set up uplift flow

<Steps>
  <Step icon="list" title="Add custom mapping in Converge">
    1. Set up a Klaviyo destination as described [here](/destinations/integrations/klaviyo).

    2. Go to your **Klaviyo destination** > **Configuration** > **Event mapping**.

    3. Select **Use custom mapping**.

    4. Disable the events for **Viewed Product**, **Added to Cart** and **Started Checkout** using the toggle.

    <Frame>
      <img alt="klaviyo disable events" />
    </Frame>

    5. Click **Add new mapping** at the bottom of the overview.

    6. Select **Viewed Product** in the **Source event** field.

    7. Enter **Viewed Product \[Converge]** in the **Forward as** field.

    8. Select **Server** as the **Forwarding mode**.

    9. Repeat steps 6-8 for **Added to Cart** → **Added to Cart \[Converge]** and **Started Checkout** → **Started Checkout \[Converge]**.

    <Frame>
      <img alt="klaviyo custom event mapping" />
    </Frame>

    10. Click **Save**.
  </Step>

  <Step icon="list" title="Create flows in Klaviyo">
    1. Go to your Klaviyo account.

    2. Go to your existing **abandoned browse**, **abandoned cart**, and **abandoned checkout** flow.

    3. Click the 3 vertical dots, click **Clone**, choose **Clone to this account**.

    4. Give your new flow a name (i.e., \[name of original flow] + Converge) and click **Continue**.

    5. Change the trigger to the equivalent Converge event (i.e., **Added To Cart** → **Added To Cart \[Converge]**).

    6. Click **Clone Flow**.

    7. Open the newly cloned flow and **select the Trigger**.

    8. Add filters excluding users that have tracked standard and Converge events after the triggered event:

       1. For an **abandoned browse** flow, filter users who have tracked:
          * **Added To Cart**
          * **Added To Cart \[Converge]**
          * **Started Checkout**
          * **Started Checkout \[Converge]**
          * **Placed Order**
       2. For an **abandoned cart** flow, filter users who have tracked:
          * **Started Checkout**
          * **Started Checkout \[Converge]**
          * **Placed Order**
       3. For an **abandoned checkout** flow, filter users who have tracked:
          * **Placed Order**

    <Frame>
      <img alt="klaviyo filters" />
    </Frame>

    9. Add any other Profile filter you want.

    10. Click **Save**.

    11. **Preview** and **test** the new flow and **enable** it when you are done.
  </Step>
</Steps>

## Measure results

Once the new flow is live, you'll start to see revenue attributed to it. All of that revenue is from users Converge recognized and Klaviyo didn't, proof that the extra events are working.

<Frame>
  <img alt="klaviyo results" />
</Frame>


# In-platform NC-Purchase
Source: https://docs.runconverge.com/guides/set-up-nc-purchase

An introduction guide to setting up a New Customer Purchase event in the Meta Ads Manager for in-platform CAC reporting and optimization

***

## Introduction

After this section, you will be able to see New Customer metrics such as New Customer ROAS (NC-ROAS), Cost per New Customer Purchase (CAC), etc. right in your Meta Ads Manager.

<Frame>
  <img alt="fb-9" />
</Frame>

### Why you should care about New Customer Events in your Meta Ads Manager

Even when you set up exclusions correctly, Meta usually does quite a lot of retargeting on existing customers.

Most performance marketers want to focus their Meta spend (almost) exclusively on acquiring **new** customers.

Sending a `NewCustomerPurchase` event to Meta that excludes all existing customer conversions, allows you to:

* **Report in-platform on CAC**: Brands often want to get a sense of how much they are paying for a new customer (CAC) and not (only) how much they are paying for a purchase.
* **Optimize towards New Customers**: You can force the Meta ad targeting algorithm to only be rewarded for New Customer conversions when using this as an optimization event.

### Step-by-step setup instructions

1. Go to your Meta Events Manager and click on **Custom Conversions** > **Create custom conversion**.
   <Frame>
     <img alt="fb-1" />
   </Frame>

2. Fill in `New Customer Purchase` in the **Name** field, and pick `NewCustomerPurchase` in the **Event** field.
    

   <Frame>
     <img alt="fb-2" />
   </Frame>

   <Note>
     If you do not see the `NewCustomerPurchase` event, go to the Meta Events Manager overview and verify this `NewCustomerPurchase` event before continuing.
   </Note>

3. In the **Choose a standard event for optimization** field, choose `Purchase`.
    

   <Frame>
     <img alt="fb-3" />
   </Frame>

4. In Rules, choose URL, **doesn't contain** and fill in `does_not_exist` in the form field. Press Enter after you fill in until you see your input become light gray. After that, press **Create**.
    
   <Frame>
     <img alt="fb-4" />
   </Frame>

5. Now that the Custom Conversion is created, share it with your Ad Account.
   Click on the dropdown on the right for the new conversion you just created, then click **Share**.
    
   <Frame>
     <img alt="fb-5" />
   </Frame>

6. Click **Share with an Ad Account**.
    
   <Frame>
     <img alt="fb-5" />
   </Frame>

7. Mark all the ad accounts you want to use this new Custom Conversion in.
    
   <Frame>
     <img alt="fb-5" />
   </Frame>

8. Click on **Share Custom Conversion**.
    
   <Frame>
     <img alt="fb-5" />
   </Frame>

9. The custom conversion is now created—time to show it in your Meta Ads Manager. Navigate to Meta Ads Manager and click on **Columns** > **Customize Columns**.
    
   <Frame>
     <img alt="fb-5" />
   </Frame>

10. Under **Custom Conversions** you'll find your NewCustomerPurchase. Choose **Total** and **Cost** to show total conversions and cost per New Customer Purchase.
     
    <Frame>
      <img alt="fb-4" />
    </Frame>

11. To add NC-ROAS, we need to create a custom metric. Click on **Create custom metric**.
     
    <Frame>
      <img alt="fb-5" />
    </Frame>

12. Call your custom metric `NC-ROAS` and for Formula choose: `NewCustomerPurchase Conversion Value` `÷` `Amount spent`. Click on **Create metric**. Be sure to mark *Everyone with access to this Business* if you want to share the metric.
     
    <Frame>
      <img alt="fb-6" />
    </Frame>

13. Also include `NC-ROAS` in your **Customize columns** if you want it to appear there.
     
    <Frame>
      <img alt="fb-7" />
    </Frame>

14. Done!
     

    <Note> Initially, it'll seem like no New Customer Purchase data is showing up in the Ads Manager because Meta doesn't support attributing custom conversions from the past. </Note>

    <Frame>
      <img alt="fb-8" />
    </Frame>


# Tracking influencer campaigns
Source: https://docs.runconverge.com/guides/tracking-influencer-campaigns

Set up tracking parameters to track influencer marketing campaigns in Converge

## Overview

Track influencer marketing campaigns in Converge using tracking parameters. This guide shows you how to structure your influencer links so that traffic and conversions are properly attributed to specific influencers and campaigns.

## Tracking parameter structure

Use the following tracking parameter structure for influencer links:

| Parameter      | Value                             | Maps to in Converge |
| -------------- | --------------------------------- | ------------------- |
| `utm_source`   | Platform name (e.g., `instagram`) | Channel             |
| `utm_medium`   | `influencer`                      | Channel Group       |
| `utm_campaign` | Influencer name                   | Campaign            |
| `utm_content`  | Campaign or post description      | Ad Set              |

### Why utm\_medium=influencer matters

Setting `utm_medium=influencer` is crucial because Converge uses this value to automatically classify traffic into the **Influencer** channel group. This ensures your influencer traffic is properly segmented in attribution reports.

## Examples

### Basic influencer link

```
https://yourbrand.com?utm_source=instagram&utm_medium=influencer&utm_campaign=Influencer-A&utm_content=Campaign-B
```

This will appear in Converge as:

* **Channel Group**: Influencer
* **Channel**: instagram
* **Campaign**: Influencer-A
* **Ad Set**: Campaign-B

### Tracking the same influencer across multiple platforms

Track the same influencer across different platforms by changing `utm_source`:

* **Instagram story:** `https://yourbrand.com?utm_source=instagram&utm_medium=influencer&utm_campaign=JohnDoe&utm_content=Summer2024`
* **TikTok video:** `https://yourbrand.com?utm_source=tiktok&utm_medium=influencer&utm_campaign=JohnDoe&utm_content=Summer2024`
* **YouTube:** `https://yourbrand.com?utm_source=youtube&utm_medium=influencer&utm_campaign=JohnDoe&utm_content=Summer2024`

### Different content from the same influencer

Use `utm_content` to distinguish between different posts or campaigns:

* **Story (Jan 15):** `https://yourbrand.com?utm_source=instagram&utm_medium=influencer&utm_campaign=JohnDoe&utm_content=Story-Jan15`
* **Reel (Jan 20):** `https://yourbrand.com?utm_source=instagram&utm_medium=influencer&utm_campaign=JohnDoe&utm_content=Reel-Jan20`
* **Feed post (Jan 25):** `https://yourbrand.com?utm_source=instagram&utm_medium=influencer&utm_campaign=JohnDoe&utm_content=Feed-Jan25`

## Best practices

### Consistent naming conventions

Establish a consistent naming convention for influencer identifiers:

* **By handle**: `@john_doe` or `john_doe`
* **By name**: `John-Doe`
* **By ID**: `influencer-001`

Pick one format and stick with it across all campaigns to ensure clean reporting.

## Viewing influencer data in Converge

Once set up, your influencer data will appear in Converge attribution reports:

1. Navigate to the Attribution section in Converge
2. Filter by **Channel Group = Influencer** to see all influencer traffic
3. Break down by **Channel** to see performance by platform (Instagram, TikTok, etc.)
4. Break down by **Campaign** to see performance by influencer or campaign name
5. Break down by **Ad Set** to see performance by specific content or posts

## Related resources

* [Channel classification](/attribution/channel-classification)
* [Tracking parameters](/attribution/tracking-parameters)
* [Session attribution](/attribution/session-attribution)


# Turn off your old tracking setup
Source: https://docs.runconverge.com/guides/turn-off-tracking

How to navigate your transition to Converge's tracking setup by removing old tracking setups

Instructions for turning off old tracking setups are now on each destination's page. Find the relevant destination below:

## Facebook / Meta

See [Meta Ads (Facebook Ads)](/destinations/integrations/facebook#turn-off-your-old-facebook-tracking) for instructions on turning off your old Facebook tracking.

***

## Google Ads

See [Google Ads - Conversion tracking (Browser)](/destinations/integrations/google-ads-conversions#turn-off-your-old-google-ads-tracking), [Google Ads - Conversion tracking (Server)](/destinations/integrations/google-ads-conversions-server-side#turn-off-your-old-google-ads-tracking), or [Google Ads - Remarketing](/destinations/integrations/google-ads-remarketing#turn-off-your-old-google-ads-tracking) for instructions on turning off your old Google Ads tracking.

***

## GA4

See [Google Analytics 4](/destinations/integrations/ga4#turn-off-your-old-ga4-tracking) for instructions on turning off your old GA4 tracking.

***

## TikTok

See [TikTok Ads](/destinations/integrations/tiktok#turn-off-your-old-tiktok-tracking) for instructions on turning off your old TikTok tracking.

***

## AWIN

See [AWIN](/destinations/integrations/awin#turn-off-your-old-awin-tracking) for instructions on uninstalling your old AWIN tracking.

***

## Snapchat Ads

See [Snapchat](/destinations/integrations/snapchat#turn-off-your-old-snapchat-tracking) for instructions on turning off your old Snapchat tracking.

***

## Pinterest Ads

See [Pinterest Ads](/destinations/integrations/pinterest#turn-off-your-old-pinterest-tracking) for instructions on turning off your old Pinterest tracking.


# Understanding attribution
Source: https://docs.runconverge.com/guides/understanding-attribution

An introductory guide to first-party vs. in-platform attribution and how to interpret these numbers

***

## What is first-party attribution

First-party attributed conversions are conversions based on your first-party data that's tracked in Converge. This is based on tracking parameters that are added to the links of your ads, like `cvg_source=facebook`, and our ability to create profiles of your users.

Because users can have multiple sessions before they purchase, the same purchase can be attributed to different channels based on the [attribution model](/attribution/channels#changing-the-attribution-model-of-your-first-party-conversions) you pick.

In the flowchart below, based on a **first-touch** model, the purchase should be attributed to Meta. Based on a **last-touch** model, the purchase should be attributed to Google.

```mermaid actions={false} theme={null}
flowchart LR
  id1("Person visits website with source **Meta**") -. 5 days later .-> id2("Person visits website with source **Google**") --- id3(["**Purchase**  ✓ "])
  style id3 color:#02b802,stroke:none
```

## What is in-platform attribution

In-platform conversions are conversions as calculated by the attribution model of the ad platform itself. For example, when you use the *"7-day click, 1-day view"* model in Meta and look at the Facebook Ads Manager, you see all conversions that Facebook believes came from a click on the ad in the last 7 days or a view of the ad in the last day.

This is typically the model that the ad platform will use itself to optimize its ad targeting.

## Which attribution method should I choose to make decisions?

You should typically include both numbers in your decision-making, as they both have their own strengths and weaknesses.
You can find a summary of both methods below.

| Attribution Model           | Strengths                                                                                                                                               | Weaknesses                                                                                                                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **First-party attribution** | **Great for relative comparisons**: First-party metrics allow you to compare all channels based on the same attribution model.                          | **May be less accurate**: First-party attribution can't account for view-through conversions or stitch sessions across devices.                                                                              |
| **In-platform attribution** | **Better accuracy**: In-platform metrics are usually more accurate because ad platforms have more data to attribute (they know which users viewed ads). | **Hard to compare across traffic sources**: Every ad platform employs different attribution models, making it hard to compare conversions. Some channels (e.g., Organic) don't have in-platform attribution. |

As a general rule of thumb, first-party attribution is better for relative comparisons **across traffic sources**, and in-platform-based metrics are better for checking performance **within a traffic source** (e.g., comparing the number of different Meta campaigns against each other).

## Known limitations of first-party attribution in relative comparisons

Although first-party attribution is better for relative comparisons, it comes with some known limitations.

**First-party attribution typically underreports top-of-funnel channels** (e.g., Meta and TikTok)

Because first-party tracking doesn't work across devices and doesn't have any information on view-through conversions, it tends to underreport top-of-funnel activity (sessions early in the customer funnel). The longer an average customer takes to convert, the more underreported these channels will be.

**First-party attribution typically overreports conversions to search and brand traffic**

Because first-party tracking might miss earlier sessions until conversion, it tends to overreport channels that are later in the customer journey, such as brand or search traffic.


# Quickstart
Source: https://docs.runconverge.com/implementation/quickstart

Set up customer data infrastructure in hours, not weeks

## Getting Started with Converge

Follow the instructions below to learn how to get your data into Converge, set up your first destination and power the dashboard with your ad platform data.

### 1. Get your customer data in Converge

To get started with Converge, you need to track the <OutboundLink />. Converge has pre-built integrations with most Shopping Platforms. Simply pick your platform below and follow the steps.

<Note> Most Converge installations only involve a storefront and store backend setup. If you leverage custom checkouts, subscriptions, or landing page builders, you will want to connect these as well. </Note>

<AccordionGroup>
  <Accordion icon="globe" title="Connect your storefront">
    <Tabs>
      <Tab title="Shopify">
        Install our prebuilt <OutboundLink /> to track all important storefront and checkout events.

        <Info> We support headless Shopify stores natively. You can find more information on that in the  <OutboundLink />  </Info>
      </Tab>

      <Tab title="WooCommerce">
        Install our prebuilt <OutboundLink />  to track all important storefront and checkout events.
      </Tab>

      <Tab title="Magento">
        Install our prebuilt <OutboundLink /> to track all important storefront and checkout events.
      </Tab>

      <Tab title="Custom">
        <Steps>
          <Step title="Install the Converge JS Pixel">
            You can find detailed instructions on installing the Converge JS Pixel on your storefront <OutboundLink />
          </Step>

          <Step title="Instrument Ecommerce Lifecycle events">
            Once installed, you should instrument your storefront with all <OutboundLink />.
          </Step>
        </Steps>

        <Note>If multitouch attribution or longer cookie lifetimes are important, consider implementing a <OutboundLink />. If you want to understand why this might be necessary, start by reading about cookie lifetimes <OutboundLink /> </Note>
      </Tab>

      <Tab title="BigCommerce">
        Install our prebuilt <OutboundLink />  to track all important storefront and checkout events.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion icon="store" title="Connect your Store Backend">
    <Tabs>
      <Tab title="Shopify">
        Install our prebuilt <OutboundLink /> to track all important server-side conversion events.
      </Tab>

      <Tab title="WooCommerce">
        Install our prebuilt <OutboundLink /> to track all important server-side conversion events.
      </Tab>

      <Tab title="Magento">
        Install our prebuilt <OutboundLink /> to track all important server-side conversion events.
      </Tab>

      <Tab title="Custom">
        <Steps>
          <Step title="Install the Converge Webhook Integration">
            You can find detailed instructions on installing the Converge Webhook Integration for server-side conversions <OutboundLink />.
          </Step>

          <Step title="Instrument Ecommerce Lifecycle events">
            Once installed, you should instrument your webhook integration with the appropriate server-side <OutboundLink />.
          </Step>
        </Steps>
      </Tab>

      <Tab title="BigCommerce">
        Install our prebuilt <OutboundLink /> to track all important server-side conversion events.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion icon="database" title="Connect other Datasources">
    <Tabs>
      <Tab title="Subscriptions">
        Use one of our pre-built connectors to get Subscription Lifecycle events in Converge.

        * <OutboundLink />
        * <OutboundLink />
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

### 2. Set up your Destinations

<Note>
  **Destinations send data from Converge** (e.g. `Purchase` events) to Destinations (e.g. Facebook Ads).
</Note>

<AccordionGroup>
  <Accordion icon="square-share-nodes" title="Set up destinations">
    <Tabs>
      <Tab title="Meta">
        Send your customer events to Meta using the <OutboundLink />.
      </Tab>

      <Tab title="Google Ads">
        Send your customer events to Google Ads using the <OutboundLink /> or <OutboundLink /> destinations.
      </Tab>

      <Tab title="Google Analytics 4">
        Send your customer events to Google Analytics 4 using the <OutboundLink />.
      </Tab>

      <Tab title="TikTok Ads">
        Send your customer events to TikTok Ads using the <OutboundLink />
      </Tab>

      <Tab title="Other">
        You can find a full list of destinations under the <OutboundLink /> section in the documentation.
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

### 3. Set up Ad Platform Integrations

<Note>
  **Ad Platform Integrations pull metrics** (e.g. Ad Spend) from Ad Platforms **into Converge** for dashboarding purposes.
</Note>

<AccordionGroup>
  <Accordion icon="rotate" title="Set up Ad Platform Integrations">
    <Tabs>
      <Tab title="Meta">
        Pull in Ad Platform metrics from Meta using the <OutboundLink />
      </Tab>

      <Tab title="Google Ads">
        Pull in Ad Platform metrics from Google Ads using the <OutboundLink />
      </Tab>

      <Tab title="TikTok Ads">
        Pull in Ad Platform metrics from TikTok Ads using the <OutboundLink />
      </Tab>

      <Tab title="Other">
        You can find a full list of Marketing Sources under the <OutboundLink /> section in the documentation.
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

### 4. Connect the Converge MCP

Connect the Converge MCP server to your AI assistant to query your analytics data in natural language. Follow the [MCP setup guide](/mcp/setup) to get started.


# Breakdowns
Source: https://docs.runconverge.com/insights-dashboards/breakdowns



Breakdowns allow you to compare metric values across a certain property.

They help you answer questions such as:

* How many Added To Cart events do I have *per country*
* How many Website visits do I have *per device type*
* How much Spend *per Ad Campaign*
* How much Purchases can be *first-party attributed per Channel*

## Applying a Breakdown

1. Click on <IconText name="plus" />.
   <Frame>
     <img alt="filter-icon" />
   </Frame>
2. Choose a property to break down, e.g. **Channel**
   <Frame>
     <img alt="filter-icon" />
   </Frame>
3. Done, your metric should be broken down across this dimension
   <Frame>
     <img alt="multiple metrics" />
   </Frame>


# Cohorts
Source: https://docs.runconverge.com/insights-dashboards/cohorts



Cohort Insights are a specific type of insight that allows you to visualize how certain metrics evolve on a per-cohort basis (e.g., LTV).

## How to create your first cohort insight

1. From the sidebar click on <IconText name="plus" /> and click on **Create new Insight**.
2. This will open the query builder, click on **Cohorts** from the top picker.
   <Frame>
     <img alt="Cohort picker" />
   </Frame>
3. Click on <IconText name="plus" />
4. Click on <IconText name="users" />
   <Frame>
     <img alt="Select metric" />
   </Frame>
5. Click on <IconText name="floppy-disk" /> in the top right corner.
6. You've created your first cohort insight.
   <Frame>
     <img alt="Cohort insight" />
   </Frame>

## Cohort Metrics

| Metric                    | Description                                             |
| ------------------------- | ------------------------------------------------------- |
| <IconText name="users" /> | LTV of the Cohort at Month y                            |
| <IconText name="users" /> | % of the Cohort who had a Placed Order event in Month y |


# Dashboards
Source: https://docs.runconverge.com/insights-dashboards/dashboards



## What is a dashboard

A dashboard is a collection of insights that can easily be shared.
Dashboards allow you to group and bring together related insights in one place.

## How to create your first dashboard

1. From the sidebar click on **Dashboards** and click on **Create new Dashboard**.

2. This will open the dashboard builder view, click on the <Icon name="pencil" />-icon next to "Unnamed dashboard" and give the dashboard a name, e.g. `Marketing KPIs`.
   <Frame>
     <img alt="Dashboard rename" />
   </Frame>

3. Click on the <Icon name="check" />-icon to save the new name.

4. Click on <IconText name="plus" />

5. Click on the **Add insight** button for the insights you'd like to add
   <Frame>
     <img alt="Add insight" />
   </Frame>

6. Click on **Edit layout (E)** in the top right corner, and move and resize the insights until you're happy with the dashboard.

7. Click on **Done editing** once you're happy.

8. You've created your first dashboard.
   <Frame>
     <img alt="Dashboard created" />
   </Frame>


# Examples
Source: https://docs.runconverge.com/insights-dashboards/examples



A glossary of Converge Insight Examples.

* [Non-Brand Google Spend and CPA over time](#non-brand-google-spend-and-cpa-over-time)
* [New Customers vs Target for the current month](#new-customers-vs-target-for-the-current-month)
* [AOV for Meta Conversions over time](#aov-for-meta-conversions-over-time)

***

## Non-Brand Google Spend and CPA over time

<CloudinaryVideo />

## New Customers vs Target for the current month

<CloudinaryVideo />

## AOV for Meta Conversions over time

<CloudinaryVideo />


# Export & share
Source: https://docs.runconverge.com/insights-dashboards/export



## Exporting Insights

1. Navigate to the Insights page and choose the Insight you want to export.
2. Click on the <Icon name="download" /> icon to download a `.csv` export.
   <Frame>
     <img alt="" />
   </Frame>
3. Done.

### Opening Converge Exports in Google Sheets

Some Google Sheets region configurations do not load Converge exports correctly.
Therefore, it's important to set your Sheets *Locale* to **United States**.

See the recording below for a step-by-step tutorial:

<CloudinaryVideo />


# Filters
Source: https://docs.runconverge.com/insights-dashboards/filters



Filters allow you to include or exclude certain values based on specific properties.

Filters allow you to answer questions such as:

* How many Added To Cart events do I have *in Canada*
* How many Website visits come *from mobile users*
* How much Spend comes from *my Summer Facebook campaign*
* How much Purchases can be *first-party attributed to TikTok*

## Applying a Filter

How you apply a filter to an insight depends on whether you want the filter to filter on a **Metric** level (applies to a single metric) or on an **Insight** level (applies to all metrics in the insight).

### Metric Filters

1. Click on the <Icon name="filter" />-icon next to the metric you want to filter.
   <Frame>
     <img alt="filter-icon" />
   </Frame>
2. Click on <IconText name="plus" />
3. Choose a property to filter on and a condition, e.g. **`total_price` greater than 50**
   <Frame>
     <img alt="filter-icon" />
   </Frame>
4. Done, your metric values should be filtered based on this condition.

### Insight Filters

1. Click on <IconText name="plus" /> in the <IconText name="bars-filter" /> section of the query builder.
   <Frame>
     <img alt="filter-icon" />
   </Frame>
2. Click on <IconText name="plus" />
3. Choose a property to filter on and a condition, e.g. **`total_price` greater than 50**
   <Frame>
     <img alt="filter-icon" />
   </Frame>
4. Done, all of your metric values should be filtered based on this condition.

   <Info>
     As an example of a filter that applies across a few metrics, notice the insight below that shows all:

     * `Placed Order` events with a `total_price` greater than 50
     * All sessions with a `Placed Order` event for which this event has a `total_price` greater than 50

     <Frame>
       <img alt="multiple metrics" />
     </Frame>
   </Info>


# Insight basics
Source: https://docs.runconverge.com/insights-dashboards/insights



This serves as a knowledge base for Insights. For a general overview of Insights & Dashboards, see the [Overview](./overview) section.

## What is an insight

Insights are the main building block of your custom marketing analytics.
They allow you to visualize customer events, ad platform metrics, and first-party attribution metrics, and analyze how you acquire customers.

## How to create your first insight

1. From the sidebar click on <IconText name="plus" /> and click on **Create new Insight**.

2. This will open the query builder, click on the <Icon name="pencil" />-icon next to "Unnamed insight" and give it a name, e.g. `Revenue over time`.
   <Frame>
     <img alt="Insight name" />
   </Frame>

3. Click on the <Icon name="check" />-icon to save the new name.

4. Click on <IconText name="plus" />

5. Click on <IconText name="dollar-sign" />
   <Frame>
     <img alt="Add metric" />
   </Frame>

6. Click on <IconText name="floppy-disk" /> in the top right corner.

7. You've created your first insight.
   <Frame>
     <img alt="Insight created" />
   </Frame>

## Insight Building Blocks

Insights are extremely flexible, you can configure the exact insight you want across these dimensions:

* [Metrics](./metrics): Choose which values you'd like to display
* [Visualization Types](./visualization-types): Insights can show up as tables, line charts, pie charts, etc.
* [Filters](./filters): You can flexibly filter in or out based on session, event, attribution, or ad platform properties
* [Breakdowns](./breakdowns): You can break down insights across session, event, attribution, or ad platform properties
* [Cohorts](./cohorts): We support specific cohort-based insights


# Metrics
Source: https://docs.runconverge.com/insights-dashboards/metrics



Insights consist of one or multiple metrics.
Metrics are based on Events, Ad Platforms, or a combination of both.

<Frame>
  <img alt="three-metrics" />
</Frame>

## Types of Metrics

When you click on **Add metric**, you have metrics in 4 categories.

### Popular

A small curated set of metrics from the other types that are often searched for.

<Frame>
  <img alt="img" />
</Frame>

### Events

Metrics based on the Events you track with the Converge [Sources](/sources/source-concepts)

<Frame>
  <img alt="img" />
</Frame>

### Ad platforms

Metrics based on the Marketing Sources you connected under [Marketing Sources](/ad-platforms/overview)

<Frame>
  <img alt="img" />
</Frame>

### Formula

A custom formula based on existing metrics.

<Frame>
  <img alt="img" />
</Frame>

## Aggregations

When you select Event Metrics such as **Added To Cart**, you might be looking for:

* The total number of **Added To Cart** events
* The total sessions with an **Added To Cart** event
* The **Added To Cart** conversion rate
* The Cost per **Added To Cart**
* etc.

Similarly, if you select Ad Platform Metrics such as **Clicks**, you might be looking for:

* The total number of **Clicks**
* The **CTR**
* The **CPM**
* etc.

These different ways of counting the underlying event or ad platform metric are called **Aggregations**.
Every time you pick a metric, you will need to choose an aggregation as well.

### Available Event Aggregations

<Frame>
  <img alt="event aggregations" />
</Frame>

| Aggregation                 | Description                                                                                                                               |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Events**                  | Total number of times an event occurred over the chosen period                                                                            |
| **Sessions**                | Total number of sessions with the specified event occurring at least once over the chosen period                                          |
| **Profiles**                | Total number of profiles who triggered the specified event at least once over the chosen period                                           |
| **Session conversion rate** | Total number of sessions with the specified event occurring at least once divided by total sessions over the chosen period                |
| **Profile conversion rate** | Total number of profiles with the specified event occurring at least once divided by total profiles with a Session over the chosen period |
| **CPA**                     | CPA of the chosen event. Without a specific Channel filter, this is equal to the **Blended CPA**                                          |
| **ROAS**                    | ROAS of the chosen event. Without a specific Channel filter, this is equal to the **Blended ROAS**                                        |
| **Event Properties**        | Allows you to do an aggregation of a specific event property                                                                              |

### Available Ad Platform Aggregations

<Frame>
  <img alt="ad platform aggregations" />
</Frame>

| Metric                              | Aggregation | Description                                |
| ----------------------------------- | ----------- | ------------------------------------------ |
| <IconText name="eye" />             | Sum         | Total number of impressions                |
|                                     | CPM         | Cost per impression                        |
| <IconText name="arrow-pointer" />   | Sum         | Total number of clicks                     |
|                                     | CTR         | Click-through rate                         |
|                                     | CPC         | Cost per click                             |
| <IconText name="coins" />           | Sum         | Total spend                                |
| <IconText name="basket-shopping" /> | Sum         | Total purchase conversions                 |
|                                     | CPA         | Cost per purchase conversion               |
|                                     | Revenue     | Conversion value of purchase conversions   |
|                                     | ROAS        | Return on ad spend of purchase conversions |
| <IconText name="basket-shopping" /> | Sum         | Total conversions                          |
|                                     | CPA         | Cost per conversion                        |
|                                     | Revenue     | Conversion value of conversions            |
|                                     | ROAS        | ROAS of conversions                        |

## Renaming a Metric

1. Click on the <Icon name="pencil" />-icon next to the metric you want to rename.
   <Frame>
     <img alt="" />
   </Frame>
2. Give your metric a new name and click on <Icon name="check" />
   <Frame>
     <img alt="" />
   </Frame>
3. Notice that in your insight, the metric is appropriately renamed
   <Frame>
     <img alt="" />
   </Frame>

## Hiding a Metric

You might want to combine some metrics in Formula Mode and only show a subset of the metrics you've used in the query.

For example, say that we want to show the **New Customer %**, which is defined as `100% * New Customers / Total Orders`.
The query would look something like this.

<Frame>
  <img alt="new customer formula" />
</Frame>

To make sure that the Insight only consists of Metric **C**, you can hide metrics A & B as follows:

1. Click on the <Icon name="eye" />-icon next to the metric you want to hide. In this example, this would be metrics A and B.
   <Frame>
     <img alt="" />
   </Frame>

2. The metrics should have disappeared from the insight.
   <Frame>
     <img alt="" />
   </Frame>


# Overview
Source: https://docs.runconverge.com/insights-dashboards/overview



<Note>
  This product is billed separately, ask your Converge rep for access.
</Note>

<CloudinaryVideo />

<DemoCard />

<br />

The Converge Insights and Dashboards Product allows you to create reports and dashboards that combine data from your:

* Store backend (e.g. Revenue by SKU)
* Converge Attribution Table (e.g. First Touch Purchases attributed to Facebook)
* Ad Platform (e.g. Facebook CPMs for my UK Campaigns)

And all of the above combined.

If you'd like to learn about how to use this product, start with [Insight Basics](./insights).
If you'd prefer a high-level set of video tutorials, check out [Video Tutorials](./video-tutorials).


# Video tutorials
Source: https://docs.runconverge.com/insights-dashboards/video-tutorials



A set of video tutorials covering Insights and Dashboards basics.

## Introduction to Insights and Dashboards

In this tutorial, we show you how to create an insight that shows **Revenue and Ad Spend over time** in less than 3 minutes.

<LoomVideo />

<br />

***

## Filters and Breakdowns

In this tutorial, we show you how to leverage Filters and Breakdowns to create the following insights:

* **Add To Carts by Device Type**
* **CPM across my Facebook UK Campaigns**

<LoomVideo />

<br />

***

## Conversion Rate Metrics

In this tutorial, we show you how to leverage conversion rate metrics for CRO research.
We create the following insights:

* **Add To Cart vs. New Customer Order Conversion Rate**
* **Mobile Add To Cart Conversion Rate vs Desktop New Customer Order Conversion Rate**
* **Conversion Rate of Facebook Traffic on Product Pages**

<LoomVideo />

<br />

***


# Visualization types
Source: https://docs.runconverge.com/insights-dashboards/visualization-types



Visualization Types allow you to showcase the same queries in different ways.
There are two categories of Visualization Types: **Time series** and **Total values**.

Within a certain visualization type, you can choose different Visualization Options.

## Visualization Types

### Changing the Visualization Type

You can change the Visualization Type using the Visualization Type Picker as per the screenshot below:

<Frame>
  <img alt="visualization-picker" />
</Frame>

### Time series visualization types

Time series Visualization types show you how metrics change over time.

#### Table

<Frame>
  <img alt="three-metrics" />
</Frame>

#### Line Chart

<Frame>
  <img alt="three-metrics" />
</Frame>

#### Bar Chart

<Frame>
  <img alt="three-metrics" />
</Frame>

#### Area Chart

<Frame>
  <img alt="three-metrics" />
</Frame>

### Totals visualization types

Totals visualization types show you the total value of metrics over a specific period.

#### Totals Number Chart

<Frame>
  <img alt="three-metrics" />
</Frame>

#### Totals Table

<Frame>
  <img alt="three-metrics" />
</Frame>

#### Totals Bar Chart

<Frame>
  <img alt="three-metrics" />
</Frame>

#### Totals Pie Chart

<Frame>
  <img alt="three-metrics" />
</Frame>

## Visualization Options

### Show values

The **Show values** visualization option allows you to add labels to each line-chart data point.
As an example, observe the following insight without any labels.

<Frame>
  <img alt="no labels example" />
</Frame>

With labels, this becomes:

<Frame>
  <img alt="no labels example" />
</Frame>

To configure **Show values**:

1. Click on <IconText name="sliders-simple" /> in the top right corner of your insight.
2. Tick on **Show values**
   <Frame>
     <img alt="labels instruction" />
   </Frame>
3. Done.

### Legend

You can choose to optionally **Hide** the legend or move it to the Top, Bottom, Left, or Right of the insight.

To configure:

1. Click on <IconText name="sliders-simple" /> in the top right corner of your insight.
2. Choose whether you want to show the legend and where.
3. Done.


# Privacy Policy
Source: https://docs.runconverge.com/legal/privacy-policy



Date: July 7, 2025

This Privacy Policy aims to inform you about how the entities under Converge collect, process, and use your personal data as controller, both generally (through use of our online and/or mobile services or our software) and when you visit our website. The processing of personal data of subjects in the European Union is always carried out in accordance with the General Data Protection Regulation (GDPR) and all other applicable privacy and data protection legislation.

Whenever Converge acts as a processor, the relevant information can be found in the Data Processing Agreement, which can be accessed here: [https://docs.runconverge.com/legal/terms#data-processing-agreement-dpa](https://docs.runconverge.com/legal/terms#data-processing-agreement-dpa).

## 1. Data Controller

The controller of your personal data is Converge Technologies, Inc., a Delaware corporation.

The controller as mentioned above may use your personal data for the purposes described in this Privacy Policy. With regards to certain processes, aforementioned controller will act as a joint controller together with Converge Ltd, with its registered office at Dalton House 60 Windsor Road, Merton Abbey, London, Greater London, United Kingdom, SW19 2RR.

If you have any questions or would like more information about this Privacy Policy and the processing of your personal data, you can contact us by email via [legal@runconverge.com](mailto:legal@runconverge.com).

## 2. Personal Data

**2.1. What are personal data?**

The personal data we generally collect and process about you always depends on your relationship with us (customer, supplier, website user, applicant, etc.).

The categories of information we collect can include:

* **Information you provide to us.** We may collect and store personal information you provide to us when purchasing our Services, communicating with us, or creating an account, including your name, email address, mobile phone number, user name, password, the organization you work for, and other credentials. We may also retain messages you send through the Service via helpchat.
* **Information we receive from other sites.** When you interact with our site through various other sites, we may receive information from such sites, including information posted or otherwise made available on your profile, user name, user ID, and any other information you permit the site to share with third-parties. The data we receive is dependent upon your privacy settings with the other site. You should always review, and if necessary, adjust your privacy settings on third-party websites and services before linking or connecting them to our website or Service.
* **Information we receive from other parties.** It is possible that we receive personal data from third parties (such as recommendations, or recruitment), such as your name, contact information or other credentials.
* **Metadata.** Converge may collect metadata associated with the User. Metadata typically consists of how, when, where, and by whom a piece of data was processed in the Services as well as how you use the Services. We use this information to operate, maintain, and provide to you the features and functionality of the Service, as well as to communicate directly with you, such as to send you email messages and push notifications, and permit you to share your creations on the Service with your contacts or social media sites. We may also send you Service-related emails or messages (e.g., account verification, order confirmations, change or updates to features of the Service, technical and security notices).

## 3. Processing Personal Data

We ensure that your personal data are processed in accordance with applicable legislation, in an adequate, relevant manner, and that this processing is limited to what is necessary for the purposes of the respective processing.

**3.1. Uses made of personal data**

We may use information collected from you for the following purposes:

* To ensure the functionality and security of the website.
* To conduct direct marketing campaigns, where permitted by law. You will always have the option to opt out of each commercial email we send.
* To provide you with information or services you request, or that we believe may be of interest to you, where you have given consent for such purposes.
* To customize the Services to your preferences.
* To deliver the Services for which you register.
* To register you for a conference or event and administer, operate, and secure such conferences and events.
* To develop and test new features of our Services, provided such efforts do not involve disclosure to third parties.
* To fulfill our contractual obligations to you.
* To inform you of updates or changes to our Services, including product announcements and improvements.
* To conduct internal business operations and administration.
* To comply with legal obligations, industry standards, and our policies.

**3.2. Retention period**

When determining the retention period, we take into account various criteria, such as the type of products and services requested by or provided to you, the nature and length of our relationship with you, possible re-enrollment with our products or services, the impact on the services we provide to you if we delete some information from or about you, mandatory retention periods provided by law, and the statute of limitations.

In any case, data will be retained only for as long as necessary to fulfil the purposes described above.

**3.3. Legal basis for processing**

If you are located in the European Economic Area, we may process your personal data for the above purposes when:

* You have consented to the processing of your personal data (for example, we may seek to obtain your consent for our use of cookies or similar technologies, or to send you marketing communications).
* We need your personal data to provide you with services and products requested by you, or to respond to your inquiries.
* We have a legal obligation to process your personal data.
* We have a legitimate interest in processing your personal data. In particular, we have a legitimate interest in processing it to ensure and improve the safety, security, and performance of our Services, to anonymize personal data and carry out data analyses, to manage our customers, receivables and suppliers and to keep our customers up to date.

## 4. With Whom Your Personal Data Are Shared

**4.1. General**

Within Converge: If necessary for the purposes for which your personal data are processed, it may happen that your data are shared with other entities within our group. These entities will only use your data for the purposes described in this Privacy Policy.

Outside Converge: In certain cases, we use service providers to process your data in connection with specific services we offer or to send you information about products and services. We ensure that these service providers only have access to your data to the extent necessary to perform their tasks.

**4.2. Transfers abroad**

Your data are stored in the United Kingdom. It is possible that we transfer your data to third parties who can process your data on our behalf abroad according to our instructions. We always do this in accordance with the conditions of this Privacy Policy and the applicable data protection regulations.

If you are a subject in the European Union and your personal data are transferred to a country outside the United Kingdom in which the level of protection is not equivalent to that in the European Union, we take appropriate measures to protect your personal data (usually in the form of the European Commission's standard contractual clauses).

Contact us if you would like more information about the specific mechanisms we use when transferring personal data outside the EEA.

A list of (sub)processors can be found here: [https://docs.runconverge.com/legal/subprocessors](https://docs.runconverge.com/legal/subprocessors).

## 5. Security Measures

We have implemented both technical and organizational security measures to prevent collected personal data from being destroyed, lost, falsified, altered, accessed without authorization, or accidentally provided to third parties, as well as to avoid any other form of unauthorized processing. We maintain a customized security policy that focuses on protecting your data.

We can in no way be held liable for any direct or indirect damage resulting from the incorrect or unlawful use of your personal data by third parties.

## 6. Your Rights and How to Exercise Them

If you have a complaint, question, or problem regarding the way we process your personal data, we ask you to contact us through the channels you can consult under chapter 1 of this Privacy Policy.

Converge acts as the contact point for handling your requests if you wish to exercise your rights.

If you are a subject in the European Union, you have the rights as mentioned below. When you contact us to exercise your rights, we will respond within one month. In exceptional cases, this period may be extended (up to a maximum of three months), but we will inform you within the first month of the reason for the delay. Whether or not you can exercise your rights depends on the nature of the processing and the legal basis.

Make sure to clearly indicate which right you wish to exercise and how you would like to receive the information (for example, by email, by post, orally, etc.). Note that in some cases we may ask you for additional information to verify that we are dealing with the right person.

Below you will find a schematic overview of which rights you have as a subject in the European Union, depending on the legal basis on which the processing is based:

| Legal obligation | Performance of a contract | Legitimate interest | Consent         |
| ---------------- | ------------------------- | ------------------- | --------------- |
| Access           | Access                    | Access              | Access          |
| Rectification    | Rectification             | Rectification       | Rectification   |
| Complaint        | Erasure                   | Erasure             | Erasure         |
|                  | Restriction               | Restriction         | Restriction     |
|                  | Dataportability           | Dataportability     | Dataportability |
|                  | Objection                 | Objection           | Complaint       |
|                  | Complaint                 | Complaint           |                 |

**6.1. Right of access**

You have the right to know whether or not your personal data are being processed. If your personal data are being processed, you have the right to access these data in all our files, along with additional information about the processing purposes, the categories of personal data, possible recipients of your data, the retention period, complaint procedure, etc.

If possible, especially when this does not affect the rights and freedoms of others, you can be provided with a free digital copy of these personal data. However, note that if you request multiple copies, we may charge a reasonable fee for this.

**6.2. Right to rectification**

As a data subject, you have the right to correct incomplete or inaccurate personal data relating to you. The term 'rectification' means that you have the option to modify or delete incorrect data. Ensuring the accuracy and integrity of your personal data is essential to achieving our goals.

**6.3. Right to restriction of processing**

As a data subject, you have the right to obtain the restriction of processing if one of the following elements applies:

* The accuracy of the personal data is contested by the data subject, for a period enabling the controller to verify the accuracy of the personal data;
* The processing is unlawful, and the data subject opposes the erasure of the personal data and requests the restriction of their use instead;
* The controller no longer needs the personal data for the processing purposes, but the data subject needs them for the establishment, exercise, or defense of legal claims;
* The data subject has objected to the processing, pending the verification of whether the legitimate grounds of the controller override those of the data subject.

**6.4. Right to object**

You have the right to object to the processing of your personal data. The legislation provides for a general right to object, as well as a specific right to object concerning direct marketing.

*a) General right to object*

You have the right to object to the processing of your personal data when these data (i) are incomplete concerning the processing purposes or have been provided incorrectly, or (ii) when the registration, communication, or storage of these data is prohibited, or (iii) when the data are retained longer than the specified retention period.

If your personal data are lawfully processed, you can still object to this processing based on legal provisions from the privacy legislation, for important and justified reasons related to your specific situation.

To prevent further processing, you must provide us with a motivated justification for your objection.

*b) Right to object to direct marketing*

You can object to the processing of your personal data for direct marketing purposes free of charge and without any motivation.

**6.5. Right to withdraw consent**

If the processing is based on your prior consent, you have the right to withdraw that consent at any time.

**6.6. Right to erasure**

Under the GDPR, you have the right to request the deletion of your personal data without undue delay in certain circumstances. These circumstances include, among others:

* The personal data are no longer necessary for the purposes for which they were collected or processed;
* You withdraw your consent for specific purposes;
* The personal data have been unlawfully processed;
* The personal data must be erased to comply with a legal obligation;

**6.7. Right to data portability**

In accordance with the GDPR, you have the right to request a copy of your personal data processed by us in a structured, commonly used, and machine-readable format. This can be requested for personal use or for transfer to a third party.

If technically feasible, you can request the electronic transfer of your personal data to a third party, after providing the correct contact details, including the transfer details, of this party.

**6.8. Right to lodge a complaint with the supervisory authority**

You always have the right to lodge a complaint with the supervisory authority, namely the Data Protection Commission:

6 Pembroke Row<br />
Dublin 2<br />
D02 X963<br />
Ireland<br />
[https://www.dataprotection.ie/](https://www.dataprotection.ie/)<br />
[https://forms.dataprotection.ie/contact](https://forms.dataprotection.ie/contact)

## 7. Hyperlinks

This website may contain links to websites operated by companies outside Converge. These other websites have their own privacy policies, which you should read carefully when you visit these websites. We are in no way responsible for the content of these websites or for the processing of personal data by these third parties.

## 8. Cookies

This website may use cookies to process information.

The processing of personal data collected in this way is based on our legitimate interest in the security and proper functioning of our website, and on your consent for analyzing the use of our website. For cookies other than those strictly necessary, we always ask for your consent first.

## 9. Changes

This Privacy Policy is regularly reviewed to accurately reflect how we handle data. You will not be notified in advance of any changes. However, adjustments will be clearly highlighted on our website. The date of the last change can be found at the top of this Privacy Policy.


# Standard Contractual Clauses
Source: https://docs.runconverge.com/legal/scc



**Module 2: Controller to Processor**

Version date: 2 July 2025

## SECTION I

**Clause 1 Purpose and scope**

(a)	These standard contractual clauses (hereinafter: ‘Clauses’) form an integral part of the Services Agreement including all order forms, schedules and exhibits connected thereto between Converge Technologies, Inc. (as data importer) and Customer (as data exporter) (hereinafter: ‘Agreement’). By entering into the Agreement, Converge Technologies, Inc. (as data importer) and Customer (as data exporter) are deemed to have acknowledged, approved to and executed these Clauses, without need for separate signature. These Clauses apply solely to the extent required under applicable data protection law.

(b)	The purpose of these Clauses is to ensure compliance with the requirements of Regulation (EU) 2016/679 of the European Parliament and of the Council of 27 April 2016 on the protection of natural persons with regard to the processing of personal data and on the free movement of such data (General Data Protection Regulation) for the transfer of personal data to a third country.

(c)	The Parties:

(i)	the natural or legal person(s), public authority/ies, agency/ies or other body/ies (hereinafter ‘entity/ies’) transferring the personal data, which for purposes of these Clauses shall mean the ‘Customer’, as defined in the Agreement, and further identified in Annex I.A (hereinafter the ‘data exporter’), and

(ii)	the entity/ies in a third country receiving the personal data from the data exporter, directly or indirectly via another entity also Party to these Clauses, which for purposes of these Clauses shall mean ‘Converge’, and further identified in Annex I.A (hereinafter the ‘data importer’),

have agreed to these Clauses.

(d)	These Clauses apply with respect to the transfer of personal data as specified in Annex I.B.

(e)	The Appendix to these Clauses containing the Annexes referred to therein forms an integral part of these Clauses.

**Clause 2 Effect and invariability of the Clauses**

(a)	These Clauses set out appropriate safeguards, including enforceable data subject rights and effective legal remedies, pursuant to Article 46(1) and Article 46(2)(c) of Regulation (EU) 2016/679 and, with respect to data transfers from controllers to processors and/or processors to processors, standard contractual clauses pursuant to Article 28(7) of Regulation (EU) 2016/679, provided they are not modified, except to select the appropriate Module(s) or to add or update information in the Appendix. This does not prevent the Parties from including the standard contractual clauses laid down in these Clauses in a wider contract and/or to add other clauses or additional safeguards, provided that they do not contradict, directly or indirectly, these Clauses or prejudice the fundamental rights or freedoms of data subjects.

(b)	These Clauses are without prejudice to obligations to which the data exporter is subject by virtue of Regulation (EU) 2016/679.

**Clause 3 Third-party beneficiaries**

(a)	Data subjects may invoke and enforce these Clauses, as third-party beneficiaries, against the data exporter and/or data importer, with the following exceptions:

(i)	Clause 1, Clause 2, Clause 3, Clause 6, Clause 7;

(ii)	Clause 8.1(b), 8.9(a), (c), (d) and (e);

(iii)	Clause 9(a), (c), (d) and (e);

(iv)	Clause 12(a), (d) and (f);

(v)	Clause 13;

(vi)	Clause 15.1(c), (d) and (e);

(vii)	Clause 16(e);

(viii)	Clause 18(a) and (b).

(b)	Paragraph (a) is without prejudice to rights of data subjects under Regulation (EU) 2016/679.

**Clause 4 Interpretation**

(a)	Where these Clauses use terms that are defined in Regulation (EU) 2016/679, those terms shall have the same meaning as in that Regulation.

(b)	These Clauses shall be read and interpreted in the light of the provisions of Regulation (EU) 2016/679.

(c)	These Clauses shall not be interpreted in a way that conflicts with rights and obligations provided for in Regulation (EU) 2016/679.

**Clause 5 Hierarchy**

In the event of a contradiction between these Clauses and the provisions of related agreements between the Parties, existing at the time these Clauses are agreed or entered into thereafter, these Clauses shall prevail.

**Clause 6 Description of the transfer(s)**

The details of the transfer(s), and in particular the categories of personal data that are transferred and the purpose(s) for which they are transferred, are specified in Annex I.B.

**Clause 7 Docking clause**

(a)	An entity that is not a Party to these Clauses may, with the agreement of the Parties, accede to these Clauses at any time, either as a data exporter or as a data importer, by completing the Appendix and signing Annex I.A.

(b)	Once it has completed the Appendix and signed Annex I.A, the acceding entity shall become a Party to these Clauses and have the rights and obligations of a data exporter or data importer in accordance with its designation in Annex I.A.

(c)	The acceding entity shall have no rights or obligations arising under these Clauses from the period prior to becoming a Party.

## SECTION II - OBLIGATIONS OF THE PARTIES

**Clause 8 Data protection safeguards**

The data exporter warrants that it has used reasonable efforts to determine that the data importer is able, through the implementation of appropriate technical and organisational measures, to satisfy its obligations under these Clauses.

**8.1   Instructions**

(a)	The data importer shall process the personal data only on documented instructions from the data exporter. The data exporter may give such instructions throughout the duration of the contract.

(b)	The data importer shall immediately inform the data exporter if it is unable to follow those instructions.

**8.2   Purpose limitation**

The data importer shall process the personal data only for the specific purpose(s) of the transfer, as set out in Annex I.B, unless on further instructions from the data exporter.

**8.3   Transparency**

On request, the data exporter shall make a copy of these Clauses, including the Appendix as completed by the Parties, available to the data subject free of charge. To the extent necessary to protect business secrets or other confidential information, including the measures described in Annex II and personal data, the data exporter may redact part of the text of the Appendix to these Clauses prior to sharing a copy, but shall provide a meaningful summary where the data subject would otherwise not be able to understand the its content or exercise his/her rights. On request, the Parties shall provide the data subject with the reasons for the redactions, to the extent possible without revealing the redacted information. This Clause is without prejudice to the obligations of the data exporter under Articles 13 and 14 of Regulation (EU) 2016/679.

**8.4   Accuracy**

If the data importer becomes aware that the personal data it has received is inaccurate, or has become outdated, it shall inform the data exporter without undue delay. In this case, the data importer shall cooperate with the data exporter to erase or rectify the data.

**8.5   Duration of processing and erasure or return of data**

Processing by the data importer shall only take place for the duration specified in Annex I.B. After the end of the provision of the processing services, the data importer shall, at the choice of the data exporter, delete all personal data processed on behalf of the data exporter and certify to the data exporter that it has done so, or return to the data exporter all personal data processed on its behalf and delete existing copies. Until the data is deleted or returned, the data importer shall continue to ensure compliance with these Clauses. In case of local laws applicable to the data importer that prohibit return or deletion of the personal data, the data importer warrants that it will continue to ensure compliance with these Clauses and will only process it to the extent and for as long as required under that local law. This is without prejudice to Clause 14, in particular the requirement for the data importer under Clause 14(e) to notify the data exporter throughout the duration of the contract if it has reason to believe that it is or has become subject to laws or practices not in line with the requirements under Clause 14(a).

**8.6   Security of processing**

(a)	The data importer and, during transmission, also the data exporter shall implement appropriate technical and organisational measures to ensure the security of the data, including protection against a breach of security leading to accidental or unlawful destruction, loss, alteration, unauthorised disclosure or access to that data (hereinafter ‘personal data breach’). In assessing the appropriate level of security, the Parties shall take due account of the state of the art, the costs of implementation, the nature, scope, context and purpose(s) of processing and the risks involved in the processing for the data subjects. The Parties shall in particular consider having recourse to encryption or pseudonymisation, including during transmission, where the purpose of processing can be fulfilled in that manner. In case of pseudonymisation, the additional information for attributing the personal data to a specific data subject shall, where possible, remain under the exclusive control of the data exporter. In complying with its obligations under this paragraph, the data importer shall at least implement the technical and organisational measures specified in Annex II. The data importer shall carry out regular checks to ensure that these measures continue to provide an appropriate level of security.

(b)	The data importer shall grant access to the personal data to members of its personnel only to the extent strictly necessary for the implementation, management and monitoring of the contract. It shall ensure that persons authorised to process the personal data have committed themselves to confidentiality or are under an appropriate statutory obligation of confidentiality.

(c)	In the event of a personal data breach concerning personal data processed by the data importer under these Clauses, the data importer shall take appropriate measures to address the breach, including measures to mitigate its adverse effects. The data importer shall also notify the data exporter without undue delay after having become aware of the breach. Such notification shall contain the details of a contact point where more information can be obtained, a description of the nature of the breach (including, where possible, categories and approximate number of data subjects and personal data records concerned), its likely consequences and the measures taken or proposed to address the breach including, where appropriate, measures to mitigate its possible adverse effects. Where, and in so far as, it is not possible to provide all information at the same time, the initial notification shall contain the information then available and further information shall, as it becomes available, subsequently be provided without undue delay.

(d)	The data importer shall cooperate with and assist the data exporter to enable the data exporter to comply with its obligations under Regulation (EU) 2016/679, in particular to notify the competent supervisory authority and the affected data subjects, taking into account the nature of processing and the information available to the data importer.

**8.7   Sensitive data**

Where the transfer involves personal data revealing racial or ethnic origin, political opinions, religious or philosophical beliefs, or trade union membership, genetic data, or biometric data for the purpose of uniquely identifying a natural person, data concerning health or a person’s sex life or sexual orientation, or data relating to criminal convictions and offences (hereinafter ‘sensitive data’), the data importer shall apply the specific restrictions and/or additional safeguards described in Annex I.B.

**8.8   Onward transfers**

The data importer shall only disclose the personal data to a third party on documented instructions from the data exporter. In addition, the data may only be disclosed to a third party located outside the European Union (in the same country as the data importer or in another third country, hereinafter ‘onward transfer’) if the third party is or agrees to be bound by these Clauses, under the appropriate Module, or if:

(i)	the onward transfer is to a country benefitting from an adequacy decision pursuant to Article 45 of Regulation (EU) 2016/679 that covers the onward transfer;

(ii)	the third party otherwise ensures appropriate safeguards pursuant to Articles 46 or 47 of Regulation (EU) 2016/679 with respect to the processing in question;

(iii)	the onward transfer is necessary for the establishment, exercise or defence of legal claims in the context of specific administrative, regulatory or judicial proceedings; or

(iv)	the onward transfer is necessary in order to protect the vital interests of the data subject or of another natural person.

Any onward transfer is subject to compliance by the data importer with all the other safeguards under these Clauses, in particular purpose limitation.

**8.9   Documentation and compliance**

(a)	The data importer shall promptly and adequately deal with enquiries from the data exporter that relate to the processing under these Clauses.

(b)	The Parties shall be able to demonstrate compliance with these Clauses. In particular, the data importer shall keep appropriate documentation on the processing activities carried out on behalf of the data exporter.

(c)	The data importer shall make available to the data exporter all information necessary to demonstrate compliance with the obligations set out in these Clauses and at the data exporter’s request, allow for and contribute to audits of the processing activities covered by these Clauses, at reasonable intervals or if there are indications of non-compliance. In deciding on a review or audit, the data exporter may take into account relevant certifications held by the data importer.

(d)	The data exporter may choose to conduct the audit by itself or mandate an independent auditor. Audits may include inspections at the premises or physical facilities of the data importer and shall, where appropriate, be carried out with reasonable notice.

(e)	The Parties shall make the information referred to in paragraphs (b) and (c), including the results of any audits, available to the competent supervisory authority on request.

**Clause 9 Use of sub-processors**

(a)	**OPTION 2: GENERAL WRITTEN AUTHORISATION** The data importer has the data exporter’s general authorisation for the engagement of sub-processor(s) from an agreed list. The data importer shall specifically inform the data exporter in writing of any intended changes to that list through the addition or replacement of sub-processors at least 7 days in advance, thereby giving the data exporter sufficient time to be able to object to such changes prior to the engagement of the sub-processor(s). The data importer shall provide the data exporter with the information necessary to enable the data exporter to exercise its right to object.

(b)	Where the data importer engages a sub-processor to carry out specific processing activities (on behalf of the data exporter), it shall do so by way of a written contract that provides for, in substance, the same data protection obligations as those binding the data importer under these Clauses, including in terms of third-party beneficiary rights for data subjects. The Parties agree that, by complying with this Clause, the data importer fulfils its obligations under Clause 8.8. The data importer shall ensure that the sub-processor complies with the obligations to which the data importer is subject pursuant to these Clauses.

(c)	The data importer shall provide, at the data exporter’s request, a copy of such a sub-processor agreement and any subsequent amendments to the data exporter. To the extent necessary to protect business secrets or other confidential information, including personal data, the data importer may redact the text of the agreement prior to sharing a copy.

(d)	The data importer shall remain fully responsible to the data exporter for the performance of the sub-processor’s obligations under its contract with the data importer. The data importer shall notify the data exporter of any failure by the sub-processor to fulfil its obligations under that contract.

(e)	The data importer shall agree a third-party beneficiary clause with the sub-processor whereby - in the event the data importer has factually disappeared, ceased to exist in law or has become insolvent - the data exporter shall have the right to terminate the sub-processor contract and to instruct the sub-processor to erase or return the personal data.

**Clause 10 Data subject rights**

(a)	The data importer shall promptly notify the data exporter of any request it has received from a data subject. It shall not respond to that request itself unless it has been authorised to do so by the data exporter.

(b)	The data importer shall assist the data exporter in fulfilling its obligations to respond to data subjects’ requests for the exercise of their rights under Regulation (EU) 2016/679. In this regard, the Parties shall set out in Annex II the appropriate technical and organisational measures, taking into account the nature of the processing, by which the assistance shall be provided, as well as the scope and the extent of the assistance required.

(c)	In fulfilling its obligations under paragraphs (a) and (b), the data importer shall comply with the instructions from the data exporter.

**Clause 11 Redress**

(a)	The data importer shall inform data subjects in a transparent and easily accessible format, through individual notice or on its website, of a contact point authorised to handle complaints. It shall deal promptly with any complaints it receives from a data subject.

(b)	In case of a dispute between a data subject and one of the Parties as regards compliance with these Clauses, that Party shall use its best efforts to resolve the issue amicably in a timely fashion. The Parties shall keep each other informed about such disputes and, where appropriate, cooperate in resolving them.

(c)	Where the data subject invokes a third-party beneficiary right pursuant to Clause 3, the data importer shall accept the decision of the data subject to:

(i)	lodge a complaint with the supervisory authority in the Member State of his/her habitual residence or place of work, or the competent supervisory authority pursuant to Clause 13;

(ii)	refer the dispute to the competent courts within the meaning of Clause 18.

(d)	The Parties accept that the data subject may be represented by a not-for-profit body, organisation or association under the conditions set out in Article 80(1) of Regulation (EU) 2016/679.

(e)	The data importer shall abide by a decision that is binding under the applicable EU or Member State law.

(f)	The data importer agrees that the choice made by the data subject will not prejudice his/her substantive and procedural rights to seek remedies in accordance with applicable laws.

**Clause 12 Liability**

(a)	Each Party shall be liable to the other Party/ies for any damages it causes the other Party/ies by any breach of these Clauses.

(b)	The data importer shall be liable to the data subject, and the data subject shall be entitled to receive compensation, for any material or non-material damages the data importer or its sub-processor causes the data subject by breaching the third-party beneficiary rights under these Clauses.

(c)	Notwithstanding paragraph (b), the data exporter shall be liable to the data subject, and the data subject shall be entitled to receive compensation, for any material or non-material damages the data exporter or the data importer (or its sub-processor) causes the data subject by breaching the third-party beneficiary rights under these Clauses. This is without prejudice to the liability of the data exporter and, where the data exporter is a processor acting on behalf of a controller, to the liability of the controller under Regulation (EU) 2016/679 or Regulation (EU) 2018/1725, as applicable.

(d)	The Parties agree that if the data exporter is held liable under paragraph (c) for damages caused by the data importer (or its sub-processor), it shall be entitled to claim back from the data importer that part of the compensation corresponding to the data importer’s responsibility for the damage.

(e)	Where more than one Party is responsible for any damage caused to the data subject as a result of a breach of these Clauses, all responsible Parties shall be jointly and severally liable and the data subject is entitled to bring an action in court against any of these Parties.

(f)	The Parties agree that if one Party is held liable under paragraph (e), it shall be entitled to claim back from the other Party/ies that part of the compensation corresponding to its/their responsibility for the damage.

(g)	The data importer may not invoke the conduct of a sub-processor to avoid its own liability.

**Clause 13 Supervision**

(a)	**Where the data exporter is established in an EU Member State:** The supervisory authority with responsibility for ensuring compliance by the data exporter with Regulation (EU) 2016/679 as regards the data transfer, as indicated in Annex I.C, shall act as competent supervisory authority.

**Where the data exporter is not established in an EU Member State, but falls within the territorial scope of application of Regulation (EU) 2016/679 in accordance with its Article 3(2) and has appointed a representative pursuant to Article 27(1) of Regulation (EU) 2016/679:** The supervisory authority of the Member State in which the representative within the meaning of Article 27(1) of Regulation (EU) 2016/679 is established, as indicated in Annex I.C, shall act as competent supervisory authority.

(b)	The data importer agrees to submit itself to the jurisdiction of and cooperate with the competent supervisory authority in any procedures aimed at ensuring compliance with these Clauses. In particular, the data importer agrees to respond to enquiries, submit to audits and comply with the measures adopted by the supervisory authority, including remedial and compensatory measures. It shall provide the supervisory authority with written confirmation that the necessary actions have been taken.

## SECTION III - LOCAL LAWS AND OBLIGATIONS IN CASE OF ACCESS BY PUBLIC AUTHORITIES

**Clause 14 Local laws and practices affecting compliance with the Clauses**

(a)	The Parties warrant that they have no reason to believe that the laws and practices in the third country of destination applicable to the processing of the personal data by the data importer, including any requirements to disclose personal data or measures authorising access by public authorities, prevent the data importer from fulfilling its obligations under these Clauses. This is based on the understanding that laws and practices that respect the essence of the fundamental rights and freedoms and do not exceed what is necessary and proportionate in a democratic society to safeguard one of the objectives listed in Article 23(1) of Regulation (EU) 2016/679, are not in contradiction with these Clauses.

(b)	The Parties declare that in providing the warranty in paragraph (a), they have taken due account in particular of the following elements:

(i)	the specific circumstances of the transfer, including the length of the processing chain, the number of actors involved and the transmission channels used; intended onward transfers; the type of recipient; the purpose of processing; the categories and format of the transferred personal data; the economic sector in which the transfer occurs; the storage location of the data transferred;

(ii)	the laws and practices of the third country of destination- including those requiring the disclosure of data to public authorities or authorising access by such authorities - relevant in light of the specific circumstances of the transfer, and the applicable limitations and safeguards;

(iii)	any relevant contractual, technical or organisational safeguards put in place to supplement the safeguards under these Clauses, including measures applied during transmission and to the processing of the personal data in the country of destination.

(c)	The data importer warrants that, in carrying out the assessment under paragraph (b), it has made its best efforts to provide the data exporter with relevant information and agrees that it will continue to cooperate with the data exporter in ensuring compliance with these Clauses.

(d)	The Parties agree to document the assessment under paragraph (b) and make it available to the competent supervisory authority on request.

(e)	The data importer agrees to notify the data exporter promptly if, after having agreed to these Clauses and for the duration of the contract, it has reason to believe that it is or has become subject to laws or practices not in line with the requirements under paragraph (a), including following a change in the laws of the third country or a measure (such as a disclosure request) indicating an application of such laws in practice that is not in line with the requirements in paragraph (a).

(f)	Following a notification pursuant to paragraph (e), or if the data exporter otherwise has reason to believe that the data importer can no longer fulfil its obligations under these Clauses, the data exporter shall promptly identify appropriate measures (e.g. technical or organisational measures to ensure security and confidentiality) to be adopted by the data exporter and/or data importer to address the situation. The data exporter shall suspend the data transfer if it considers that no appropriate safeguards for such transfer can be ensured, or if instructed the competent supervisory authority to do so. In this case, the data exporter shall be entitled to terminate the contract, insofar as it concerns the processing of personal data under these Clauses. If the contract involves more than two Parties, the data exporter may exercise this right to termination only with respect to the relevant Party, unless the Parties have agreed otherwise. Where the contract is terminated pursuant to this Clause, Clause 16(d) and (e) shall apply.

**Clause 15 Obligations of the data importer in case of access by public authorities**

**15.1   Notification**

(a)	The data importer agrees to notify the data exporter and, where possible, the data subject promptly (if necessary with the help of the data exporter) if it:

(i)	receives a legally binding request from a public authority, including judicial authorities, under the laws of the country of destination for the disclosure of personal data transferred pursuant to these Clauses; such notification shall include information about the personal data requested, the requesting authority, the legal basis for the request and the response provided; or

(ii)	becomes aware of any direct access by public authorities to personal data transferred pursuant to these Clauses in accordance with the laws of the country of destination; such notification shall include all information available to the importer.

(b)	If the data importer is prohibited from notifying the data exporter and/or the data subject under the laws of the country of destination, the data importer agrees to use its best efforts to obtain a waiver of the prohibition, with a view to communicating as much information as possible, as soon as possible. The data importer agrees to document its best efforts in order to be able to demonstrate them on request of the data exporter.

(c)	Where permissible under the laws of the country of destination, the data importer agrees to provide the data exporter, at regular intervals for the duration of the contract, with as much relevant information as possible on the requests received (in particular, number of requests, type of data requested, requesting authority/ies, whether requests have been challenged and the outcome of such challenges, etc.).

(d)	The data importer agrees to preserve the information pursuant to paragraphs (a) to (c) for the duration of the contract and make it available to the competent supervisory authority on request.

(e)	Paragraphs (a) to (c) are without prejudice to the obligation of the data importer pursuant to Clause 14(e) and Clause 16 to inform the data exporter promptly where it is unable to comply with these Clauses.

**15.2   Review of legality and data minimisation**

(a)	The data importer agrees to review the legality of the request for disclosure, in particular whether it remains within the powers granted to the requesting public authority, and to challenge the request if, after careful assessment, it concludes that there are reasonable grounds to consider that the request is unlawful under the laws of the country of destination, applicable obligations under international law and principles of international comity. The data importer shall, under the same conditions, pursue possibilities of appeal. When challenging a request, the data importer shall seek interim measures with a view to suspending the effects of the request until the competent judicial authority has decided on its merits. It shall not disclose the personal data requested until required to do so under the applicable procedural rules. These requirements are without prejudice to the obligations of the data importer under Clause 14(e).

(b)	The data importer agrees to document its legal assessment and any challenge to the request for disclosure and, to the extent permissible under the laws of the country of destination, make the documentation available to the data exporter. It shall also make it available to the competent supervisory authority on request.

(c)	The data importer agrees to provide the minimum amount of information permissible when responding to a request for disclosure, based on a reasonable interpretation of the request.

## SECTION IV - FINAL PROVISIONS

**Clause 16 Non-compliance with the Clauses and termination**

(a)	The data importer shall promptly inform the data exporter if it is unable to comply with these Clauses, for whatever reason.

(b)	In the event that the data importer is in breach of these Clauses or unable to comply with these Clauses, the data exporter shall suspend the transfer of personal data to the data importer until compliance is again ensured or the contract is terminated. This is without prejudice to Clause 14(f).

(c)	The data exporter shall be entitled to terminate the contract, insofar as it concerns the processing of personal data under these Clauses, where:

(i)	the data exporter has suspended the transfer of personal data to the data importer pursuant to paragraph (b) and compliance with these Clauses is not restored within a reasonable time and in any event within one month of suspension;

(ii)	the data importer is in substantial or persistent breach of these Clauses; or

(iii)	the data importer fails to comply with a binding decision of a competent court or supervisory authority regarding its obligations under these Clauses.

In these cases, it shall inform the competent supervisory authority of such non-compliance. Where the contract involves more than two Parties, the data exporter may exercise this right to termination only with respect to the relevant Party, unless the Parties have agreed otherwise.

(d)	Personal data that has been transferred prior to the termination of the contract pursuant to paragraph (c) shall at the choice of the data exporter immediately be returned to the data exporter or deleted in its entirety. The same shall apply to any copies of the data. The data importer shall certify the deletion of the data to the data exporter. Until the data is deleted or returned, the data importer shall continue to ensure compliance with these Clauses. In case of local laws applicable to the data importer that prohibit the return or deletion of the transferred personal data, the data importer warrants that it will continue to ensure compliance with these Clauses and will only process the data to the extent and for as long as required under that local law.

(e)	Either Party may revoke its agreement to be bound by these Clauses where (i) the European Commission adopts a decision pursuant to Article 45(3) of Regulation (EU) 2016/679 that covers the transfer of personal data to which these Clauses apply; or (ii) Regulation (EU) 2016/679 becomes part of the legal framework of the country to which the personal data is transferred. This is without prejudice to other obligations applying to the processing in question under Regulation (EU) 2016/679.

**Clause 17 Governing law**

**OPTION 1:** These Clauses shall be governed by the law of one of the EU Member States, provided such law allows for third-party beneficiary rights. The Parties agree that this shall be the law of Ireland.

**Clause 18 Choice of forum and jurisdiction**

(a)	Any dispute arising from these Clauses shall be resolved by the courts of an EU Member State.

(b)	The Parties agree that those shall be the courts of Ireland.

(c)	A data subject may also bring legal proceedings against the data exporter and/or data importer before the courts of the Member State in which he/she has his/her habitual residence.

(d)	The Parties agree to submit themselves to the jurisdiction of such courts.

**Clause 19 Execution**

These Clauses shall be deemed acknowledged, approved, executed, and binding upon the Parties by virtue of the execution of the Agreement. No separate execution or signature of these Clauses shall be required.

## ANNEX I

**A.   LIST OF PARTIES**

Data exporter(s):

* Name: the 'Customer', as defined in the Agreement
* Address: the Customer's address, as set out in the Agreement
* Contact person's name, position and contact details: as set out in the Agreement
* Activities relevant to the data transferred under these Clauses: Provision of software platform and services, carried out pursuant to, and subject to, the Agreement.
* Signature and date: date of the Agreement
* Role (controller/processor): **Controller**

Data importer(s):

* Name: Converge Technologies Inc.
* Address: Converge Technologies Inc.'s address, as set out in the Agreement
* Contact person's name, position and contact details: as set out in the Agreement
* Activities relevant to the data transferred under these Clauses: Provision of software platform and services, carried out pursuant to, and subject to, the Agreement
* Signature and date: date of the Agreement
* Role (controller/processor): **Processor**

**B.   DESCRIPTION OF TRANSFER**

* *Categories of data subjects whose personal data is transferred*<br />
  Customers and users of the Converge software platform, and website visitors and customers of Converge’s customers.

* *Categories of personal data transferred*<br />
  IP address, first name, last name, email address, telephone number, address data, user agent, cookie values, device identifiers, and any other personal data sent to Converge by Customer

* *Sensitive data transferred (if applicable) and applied restrictions or safeguards that fully take into consideration the nature of the data and the risks involved, such as for instance strict purpose limitation, access restrictions (including access only for staff having followed specialised training), keeping a record of access to the data, restrictions for onward transfers or additional security measures.*<br />
  None.

* *The frequency of the transfer (e.g. whether the data is transferred on a one-off or continuous basis).*<br />
  Continuous basis.

* *Nature of the processing*<br />
  Data is collected, forwarded, and made available for analytics.

* *Purpose(s) of the data transfer and further processing*<br />
  Enabling the use of Converge’s software platform.

* *The period for which the personal data will be retained, or, if that is not possible, the criteria used to determine that period*<br />
  As long is as it is necessary for the purpose of the processing.

* *For transfers to (sub-) processors, also specify subject matter, nature and duration of the processing*<br />
  The list of sub-processors and information can be found via: [https://docs.runconverge.com/legal/subprocessors](https://docs.runconverge.com/legal/subprocessors)

**C.   COMPETENT SUPERVISORY AUTHORITY**

Identify the competent supervisory authority/ies in accordance with Clause 13

**Data Protection Commission**

6 Pembroke Row<br />
Dublin 2<br />
D02 X963<br />
Ireland

## ANNEX II

**TECHNICAL AND ORGANISATIONAL MEASURES INCLUDING TECHNICAL AND ORGANISATIONAL MEASURES TO ENSURE THE SECURITY OF THE DATA**

**MODULE 2: Controller to Processor**

**General**<br />
The data importer implements reasonable measures to protect personal data from unauthorised access, use or disclosure.

**Program**<br />
The data importer maintains a comprehensive written information security program that includes administrative, technical, and organisational safeguards. These measures are designed to ensure the security, integrity, availability, resilience, and confidentiality of personal data, meet or exceed prevailing industry standards, and comply with applicable data protection law.

**Vulnerability Management**<br />
The data importer uses automated vulnerability scanning tools to scan its systems, logs scan reports, and conducts periodic reviews over time. A patch management and software update process is in place. Vulnerabilities are prioritised and remediated based on risk, and compensating controls are implemented where immediate remediation is not available.

**Encryption**<br />
The data importer uses industry-standard encryption tools to protect all personal data it (i) transmits wirelessly or across public networks or within its internal systems, (ii) stores on laptops or storage media, and (iii) stores on portable devices or internal systems. Secure key management procedures are in place to safeguard the confidentiality and integrity of encryption keys.

**Organisational Safeguards**<br />
Internal policies are in place to (i) limit the retention of personal data to the minimum period necessary to fulfil contractual obligations, and (ii) impose appropriate consequences for personnel who breach security obligations.

**Incident Response Plan**<br />
The data importer maintains a documented incident response plan addressing detection, reporting, evidence management, post-incident restoration, and incorporation of lessons learned. This plan is tested at least annually.

**Return or Destruction of Personal Data**<br />
Personal data is returned or securely destroyed at the end of the processing relationship, in accordance with internal data handling policies.


# Data Subprocessors
Source: https://docs.runconverge.com/legal/subprocessors

Up-to-date list of current Personal Data and Customer Data subprocessors of Converge.

Effective as of August 26, 2026.

These are the third parties that process customer data on your behalf.

| Entity                                | Corporate location | Purpose                                  |
| ------------------------------------- | ------------------ | ---------------------------------------- |
| Amazon Web Services, Inc.             | US                 | Cloud infrastructure                     |
| WorkOS, Inc.                          | US                 | Authentication                           |
| Modal Labs, Inc.                      | US                 | AI sandbox infrastructure                |
| Anthropic, PBC                        | US                 | AI inference                             |
| LangChain, Inc. (LangSmith)           | US                 | AI monitoring                            |
| Raintank Inc. (Grafana Labs)          | US                 | Monitoring and logging                   |
| Functional Software, Inc. (Sentry.io) | US                 | Error monitoring                         |
| PostHog, Inc.                         | US                 | Product analytics and session recordings |
| Astrodon Corp (Loops)                 | US                 | Email delivery                           |


# Terms and Conditions
Source: https://docs.runconverge.com/legal/terms



Converge Technologies, Inc. (“**Converge**” or “**we**” or “**us**”) owns and operates a proprietary marketing measurement platform (together with any future software products or services offered by Converge and accessed or used by you, the “**Services**”). These Terms and Conditions (the “**Terms**”, together with any Order Form(s) and the Data Processing Addendum attached as Schedule B, collectively, this “**Agreement**”) govern your access to and use of Converge’s Services. Capitalized terms used but not otherwise defined herein shall have the meanings given to them in Schedule A.

By accessing or using the Services, or by clicking a button or checking a box marked “I Agree” (or similar), you (a) confirm that you have read, understood, and agree to be bound by this Agreement, (b) confirm that you have read, understand, and acknowledge our [Privacy Policy](https://docs.runconverge.com/legal/privacy-policy), and (c) consent to entering into this Agreement electronically and agree that your electronic acceptance in the manner described herein satisfies any requirements under applicable law that such agreements be in writing or signed. If you do not agree to this Agreement, you may not access or use the Services.

We may update or otherwise modify this Agreement from time to time. If we make material changes, we will post the updated Terms on this page with a “Last Updated” effective date of the revisions. Your continued use of the Services after an update will constitute acceptance of the updated Terms. If you do not agree to the updated Terms, you must stop using the Services.

If you are entering into this Agreement on behalf of a company (such as your employer) or other legal entity, you represent and warrant that you are authorized to bind that entity to this Agreement, in which case “you” or “your” will refer to that entity (otherwise, such terms refer to you as an individual). If you do not have authority to bind your entity or do not agree with any provision of this Agreement, you must not accept this Agreement and may not use the Services.

UNLESS YOU OPT-OUT, THIS AGREEMENT CONTAINS A MANDATORY INDIVIDUAL ARBITRATION AND CLASS ACTION AND JURY TRIAL WAIVER PROVISION THAT, AS FURTHER SET FORTH BELOW, REQUIRES THE USE OF ARBITRATION ON AN INDIVIDUAL BASIS TO RESOLVE DISPUTES, RATHER THAN JURY TRIALS OR CLASS ACTIONS. YOU CAN OPT-OUT OF THE ARBITRATION AGREEMENT BY CONTACTING [LEGAL@RUNCONVERGE.COM](mailto:LEGAL@RUNCONVERGE.COM) WITHIN 30 DAYS OF ACCEPTING THESE TERMS.

## 1. Services.

**1.1. Services.** Subject to your compliance with this Agreement, Converge hereby grants you (i) a non-exclusive, non-sublicensable, revocable (only as expressly permitted hereunder), non-transferable (except as expressly permitted hereunder), right to access and use the Services during the Term, solely for your internal business purposes, in accordance with, and subject to, any other terms set forth in the then-current Order Form; and (ii) a non-exclusive, non-sublicensable, non-transferable license to use the Documentation during the Term, solely for your internal business purposes in connection with its use of the Services.

**1.2. Restrictions.** Except as expressly permitted by this Agreement, you will not, and will not permit any third party (including Authorized Users) to, use the Services in any manner beyond the scope of the rights expressly granted in this Agreement. Specifically, you will not at any time, directly or indirectly, and will not permit any third party to:<br />
(a) copy, modify or create derivative works of the Services or Documentation;<br />
(b) reverse engineer, disassemble, decompile, decode, or attempt to improperly access the software component of the Services;<br />
(c) share passwords or allow unauthorized access to the Services;<br />
(d) use the Services in any manner or for any purpose that infringes on third party IP or other rights or that violates any applicable law;<br />
(e) disrupt or interfere with the Services or its data;<br />
(f) use unauthorized tools to access or search the Services; or<br />
(g) use the Services, the Documentation or Confidential Information of Converge to develop competing products or copy ideas, features, functions or graphics of the Services.

**1.3. Authorized Users.** You will not permit any person or entity other than your Authorized Users to access, use or operate the Services. You are fully and directly responsible to Converge for: (a) any act or omission by each of your Authorized Users in connection with such Authorized User’s use of the Services; and (b) any use of the Services through your account, whether authorized or unauthorized. You will use, and will require all Authorized Users to use all reasonable means to secure usernames and passwords, hardware and software used to access the Services, and will promptly notify us if you or any Authorized User knows or reasonably suspects that any user name and password has been compromised. Each account for access to and use of the Services may only be accessed and used by the specific Authorized User for whom such account is created.

**1.4. Modification, Suspension, or Termination.** We may (i) modify, deprecate, or update the Services, in whole or in part, at any time during the Term; and (ii) without liability to you, immediately suspend, terminate, or limit your access to the Services at any time if we reasonably suspect that the Services are being used in violation of this Agreement. Without limitation, we will have no liability for any damages, liabilities, or losses as a result of any suspension, limitation or termination of your or any Authorized User’s right to use the Services in accordance with this subsection.

**1.5. Third-Party Services.**  The Services may allow you and your Authorized Users to interact with certain third-party services (collectively “**Third-Party Services**”). Converge does not provide or take responsibility for these Third-Party Services, including any compatibility issues or errors they may cause. You are solely responsible for your use of the Third-Party Services and obtaining any associated licenses and consents necessary to use the Third-Party Services.

## 2. Fees and Payment.

**2.1. Fees.** You will pay Converge the Fees as set forth on the relevant Order Form. All Fees are non-refundable and neither party will have the right to set off, discount or otherwise reduce or refuse to pay any amounts due to the other party under this Agreement. Unless otherwise set forth on the relevant Order Form, we reserve the right to change the Fees at the end of the relevant Order Form Term, upon 30 days’ prior written notice to you. If you have signed up for automatic billing, we will charge your selected payment method (such as a credit card or debit card) for any Fees on the applicable payment date, including any applicable taxes. If we cannot charge your selected payment method for any reason (such as expiration or insufficient funds), you remain responsible for any uncollected amounts, and we may attempt to charge the payment method again if you update your payment method information. In accordance with local law, we may update information regarding your selected payment method if provided such information by your financial institution. We may charge interest on late payments at a rate of 1.5% per month or the maximum rate permitted by applicable law for commercial transactions, whichever is higher, and we may suspend access to the Services until all payments are made in full.  You will reimburse Converge for all costs and expenses incurred (including attorneys’ fees) in collecting any late payments or interest.

**2.2. Taxes.** You are responsible for all sales, use, ad valorem or other taxes on any amount payable by you to Converge hereunder, other than any taxes imposed on Converge’s income.

## 3. Term and Termination.

**3.1. Term.** The term of each subscription shall be as specified in the applicable Order Form. Except as otherwise specified in an Order Form, subscriptions will automatically renew for additional periods equal to the expiring subscription term or one year (whichever is shorter), unless either party gives the other written notice (email acceptable) at least 30 days before the end of the relevant subscription term.

**3.2. Termination.** We reserve the right (a) to immediately and without notice suspend or terminate your access to or use of the Services if we reasonably believe that you have violated this Agreement and (b) to modify the Services or to suspend or stop providing all or portions of the Services at any time, to the extent permitted by law. You also have the right to stop using the Services at any time. We are not responsible for any loss or harm related to your inability to access or use the Services.

**3.3. Effect of Termination.** No expiration or termination of your access to the Services will affect your obligation to pay any amounts legitimately owed to Converge prior to the effective date of such expiration or termination. After the effective date of termination or expiration of your access to the Services, Converge will have no obligation to maintain or provide Your Content, and may, in our sole discretion, delete or destroy all copies of such Your Content in the Services or in our possession or control.

**3.4. Survival.** Sections related to Restrictions, Authorized Users, Fees and Payment, Effect of Termination, Survival, IP Rights, Confidentiality, Representations and Warranties, Indemnification, Limitation of Liability, General Provisions, and any other provisions that, by their nature, are intended to survive the Term, shall survive termination.

## 4. IP Rights.

**4.1. Converge.** Converge (and its licensors, where applicable) has and retains ownership of all rights in and to (including all IP Rights in and to) the Converge IP. No rights are granted to you hereunder (whether by implication, estoppel, exhaustion or otherwise) other than as expressly set forth herein.

**4.2. Customer.**

(a) You hereby grant Converge a non-exclusive, worldwide, sublicensable, royalty-free right and license to use, host, reproduce, publicly display, publicly perform, modify, transmit, and make derivative works of the Your Content: (i) during the applicable Term, solely for the purpose of hosting, operating, improving and providing the Services and Converge’s other current and future products, services and technologies; and (ii) on a perpetual basis, for purposes of developing and deriving Aggregate Data.

(b) You hereby grant Converge a limited, non-exclusive, royalty-free license to use and display your or your company’s name, designated trademarks, and associated logos (the “**Your Marks**”) with your prior written approval in each case, for Converge’s marketing and promotional efforts for its products and services, including by publicly naming you or your company as a client of Converge during or after the Term. All goodwill and improved reputation generated by our use of Your Marks inures to your or your company’s exclusive benefit.

**4.3. Feedback.** You grant Converge a perpetual, royalty-free license to use any feedback you or your representatives provide for Converge’s business purposes, including to improve the Services. The foregoing license includes the right to profit from such feedback without compensating or crediting you in any way. Feedback will not be considered your trade secret.

## 5. Confidentiality.

**5.1. Non-Disclosure of Confidential Information.** The parties will protect one another’s confidential information and not use or disclose it except as necessary to perform the Services. Confidential information includes all non-public information provided by a party under this Agreement that is designated as confidential at the time of disclosure or that, under the circumstances, a person exercising reasonable business judgment would understand to be confidential or proprietary. Converge’s Confidential Information includes, without limitation, all non-public elements of the Services.

**5.2. Exceptions.** The confidentiality obligation does not apply to information that is public, previously known to the receiving party, disclosed to the receiving party by a third without a breach of confidence, independently developed by a party without reference to the confidential information, or legally required to be disclosed.

## 6. Representations and Warranties.

**6.1. Representations and Warranties.** You represent and warrant that (i) you have obtained and will continue to have all necessary rights, authority, consents, and licenses for the access to and use of Your Content as contemplated by this Agreement, (ii) you will comply with all applicable laws in your use of the Services and performance of this Agreement, and (iii) our use of the Your Content in accordance with the Agreement will not cause a breach of any agreement or obligations between you and any third party.

**6.2. Disclaimer.** EXCEPT AS EXPRESSLY SET FORTH HEREIN, THE SERVICES AND OTHER CONVERGE IP ARE PROVIDED ON AN “AS IS” BASIS, AND CONVERGE MAKES NO WARRANTIES OR REPRESENTATIONS TO YOU, YOUR AUTHORIZED USERS OR TO ANY OTHER PARTY REGARDING THE CONVERGE IP, THE SERVICES OR ANY OTHER SERVICES OR MATERIALS PROVIDED HEREUNDER. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, CONVERGE HEREBY DISCLAIMS ALL WARRANTIES AND REPRESENTATIONS, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, COMMERCIAL RESULT, OR NON-INFRINGEMENT, AND ANY WARRANTIES ARISING OUT OF COURSE OF DEALING OR USAGE OF TRADE.  WITHOUT LIMITING THE FOREGOING, CONVERGE HEREBY DISCLAIMS ANY WARRANTY THAT USE OF THE SERVICES WILL BE ERROR-FREE, BUG-FREE OR UNINTERRUPTED. CONVERGE’S ONLY OBLIGATIONS WITH RESPECT TO THE SERVICES ARE EXPRESSLY STATED IN THIS AGREEMENT.

## 7. Indemnification.

You will defend Converge against any claim, demand, suit or proceeding made or brought against Converge by a third party arising from or relating to (a) Your Content (or our use thereof), (b) your use of any Services in violation of this Agreement, any third-party’s IP Rights, privacy or other rights, or applicable law, or (c) any of your products or services (collectively, a “**Claim**”), and will indemnify and hold harmless Converge from any damages, attorney fees and costs finally awarded against us as a result of, or for any amounts paid or payable by us under a settlement of, a Claim. We will: (i) promptly give you written notice of the Claim, (ii) give you sole control of the defense and settlement of the Claim (except that you must give us approval over any settlement), and (iii) give you all reasonable assistance, at your cost.

## 8. Limitation of Liability.

**8.1. Exclusion of Damages.** NEITHER PARTY WILL BE LIABLE FOR ANY LOSS OF REVENUE, ANTICIPATED PROFITS, LOST BUSINESS OR LOST SALES, OR FOR ANY INCIDENTAL, INDIRECT, PUNITIVE, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM OR RELATED TO THE AGREEMENT, THE CONVERGE IP, OR THE PROVISION OF THE SERVICES (INCLUDING WITHOUT LIMITATION, LOST PROFITS OR OTHER ECONOMIC LOSS, LOST REIMBURSEMENTS, LOST DATA, LOST SAVINGS OR REPUTATIONAL DAMAGES), WHETHER BASED IN CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, OR OTHERWISE, AND EVEN IF SUCH PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

**8.2. Total Liability.** CONVERGE’S AGGREGATE LIABILITY ARISING OUT OF OR RELATED TO THE SERVICES SHALL NOT EXCEED THE TOTAL OF THE AMOUNTS PAID BY YOU FOR THE SERVICES IN THE THREE (3) MONTH PERIOD PRECEDING THE EVENT GIVING RISE TO THE CLAIM, REGARDLESS OF THE LEGAL OR EQUITABLE THEORY ON WHICH THE CLAIM OR LIABILITY IS BASED, AND WHETHER OR NOT SUCH PARTY WAS ADVISED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE.

**8.3. Basis of the Bargain.**  THE PARTIES HEREBY ACKNOWLEDGE AND AGREE THAT THE LIMITATIONS OF LIABILITY IN THIS SECTION 8 ARE AN ESSENTIAL PART OF THE BASIS OF THE BARGAIN BETWEEN THEM, AND WILL APPLY EVEN IF THE REMEDIES AVAILABLE HEREUNDER ARE FOUND TO FAIL THEIR ESSENTIAL PURPOSE.

## 9. Arbitration; Class Action Waiver; Jury Trial Waiver.

PLEASE READ THIS SECTION CAREFULLY, AS IT DESCRIBES HOW DISPUTES BETWEEN US WILL BE RESOLVED.

**9.1. Arbitration Agreement.** For any dispute with Converge, you agree to first contact us at [legal@runconverge.com](mailto:legal@runconverge.com) and attempt to resolve the dispute with us informally.  In the unlikely event that our support team is unable to resolve a complaint you may have (or if we have not been able to resolve a dispute with you after attempting to do so informally), including, but not limited to, any alleged breach of this Agreement, you agree to resolve the dispute through binding arbitration. Arbitration, which is often less expensive, faster, and less formal than a lawsuit in court, uses a neutral arbitrator instead of a judge or jury. Arbitrators can award the same damages and relief that a court can award, and may, but do not have to, award legal fees, arbitrator’s fees and costs, and other costs incurred by the party that does not win the dispute. You agree that any dispute will be exclusively, fully, and finally resolved using binding arbitration through the American Arbitration Association  (“**AAA**”).

**9.2. Arbitration Procedure.**

(a) You and Converge agree to employ three (3) arbitrators (the “**Panel**”), where one (1) arbitrator is selected by you, one (1) arbitrator is selected by Converge, and the third (3rd) arbitrator is selected by mutual consent of you and Converge. If you and Converge cannot agree upon the third arbitrator, the first two (2) arbitrators chosen shall select the third arbitrator. The selection decision shall be binding.

(b) The arbitration shall be conducted by telephone, online, and/or be solely based on written submissions—the specific manner to be chosen by the party initiating the arbitration. The arbitration shall not involve any personal appearance by the parties or witnesses unless otherwise mutually agreed by the parties. Any judgment on the award rendered by the Panel may be entered in any court of competent jurisdiction.

(c) Any claim or dispute arising under this Agreement must be initiated by arbitration within two (2) years from its accrual date. Any claim or dispute initiated two (2) years or longer from its accrual date shall be time-barred and dismissed.

**9.3. Cost of Arbitration.**  Each party will pay the fees for its own attorneys, subject to any remedies to which that party may later be entitled under applicable law. In all cases where required by law, Converge will pay the arbitrator's and arbitration fees. If under applicable law Converge is not required to pay all of the arbitrator's and/or arbitration fees, such fee(s) will be apportioned between the parties in accordance with said applicable law. Any disputes regarding whether Converge is required to pay the arbitrator’s and arbitration fees and/or how those fees are to be apportioned between the parties will be resolved by the arbitrator.

**9.4. Exceptions to Agreement to Arbitrate.** Converge may bring a lawsuit solely for injunctive relief to stop unauthorized use or abuse of the Services or infringement of intellectual property rights (for example, trademark, trade secret, copyright, or patent rights) without first engaging in the informal dispute-resolution process described above.

**9.5.** YOU MAY ONLY RESOLVE DISPUTES WITH CONVERGE ON AN INDIVIDUAL BASIS, AND MAY NOT BRING A CLAIM AS A PLAINTIFF OR A CLASS MEMBER IN A CLASS, CONSOLIDATED, OR REPRESENTATIVE ACTION. CLASS ARBITRATIONS, CLASS ACTIONS, PRIVATE ATTORNEY GENERAL ACTIONS, AND CONSOLIDATION WITH OTHER ARBITRATIONS ARE NOT ALLOWED UNDER THESE TERMS. IF FOR ANY REASON A CLAIM PROCEEDS IN COURT RATHER THAN IN ARBITRATION, YOU AND CONVERGE EACH WAIVE ANY RIGHT TO A JURY TRIAL.

**9.6. Opt-Out of Alternative Dispute Resolution Process.** Notwithstanding the above, you can decline or “opt out” of the alternative dispute resolution process described above by contacting [legal@runconverge.com](mailto:legal@runconverge.com) within 30 days of first accepting these Terms and stating that you (first and last name) decline this dispute resolution process.

**9.7.** YOU UNDERSTAND AND AGREE THAT, BY NOT OPTING OUT OF THE ALTERNATIVE DISPUTE RESOLUTION PROCESS DESCRIBED, YOU WAIVE ANY RIGHT TO A JURY TRIAL TO WHICH YOU MAY OTHERWISE BE ENTITLED IN CONNECTION WITH ANY ACTION OR LITIGATION IN ANY WAY ARISING OUT OF OR RELATED TO THIS AGREEMENT.

**9.8.** If you opt out of the dispute resolution process described in this section or if this arbitration provision is found to be null and void, then all disputes arising under this Agreement between us will be subject to the jurisdiction of the state and federal courts located in New York, New York, and you and we hereby submit to the personal jurisdiction and venue of these courts. You and Converge agree that if for any reason a dispute proceeds in court rather than arbitration: (a) you and Converge waive any right to a jury trial; (b) the dispute will proceed solely on an individual, non-class, non-representative basis; and (c) neither you nor Converge may be a class representative or class member or otherwise participate in any class, representative, consolidated, or private attorney general proceeding.

## 10. General Provisions.

**10.1. Order of Precedence.** In the event of any conflict or inconsistency between the components of the Agreement, the following order of precedence shall govern: (1) the relevant Order Form, (2) the Data Processing Addendum, and (3) these Terms. The document higher in precedence shall control solely to the extent of such conflict or inconsistency.

**10.2. Governing Law.** This Agreement is governed by the laws of New York State without giving effect to any choice of law or conflict of law provisions.

**10.3. Force Majeure.** Neither party will be liable in damages or have the right to terminate this Agreement for any delay or default in performing hereunder (except for a failure to pay Fees) if such delay or default is caused by conditions beyond its reasonable control including acts of God, government restrictions (including, but not limited to, the denial or cancellation of any export or other necessary license and shelter-in-place or other similar orders), epidemics, acts of terrorism, wars, insurrections, or major disruptions affecting essential third-party infrastructure or service providers.

**10.4. Notices.** Except as may be otherwise set forth herein, all notices hereunder shall be in writing and shall be delivered by email (with confirmation of transmission). Email notifications to Converge shall be to [legal@runconverge.com](mailto:legal@runconverge.com). You further agree that we may send to you any privacy or other notices, disclosures, or communications regarding the Services (collectively, "**Communications**") through electronic means including but not limited to by email, using the email address that you provided to us related to your account or by posting the Communications on the Services. You agree that all agreements, notices, disclosures and other communications that we provide to you electronically satisfy any legal requirement that such communications be in writing. You further agree that any notices provided by us electronically are deemed to be given and received on the date we transmit any such electronic communication as described in this Agreement. The delivery of any Communications from us is effective when sent by us, regardless of whether you read the Communication when you receive it or whether you actually receive the delivery. You can withdraw your consent to receive Communications by deactivating your account.

**10.5. Export Control.** You will not export or re-export, either directly or indirectly, any technical data, software, process, product, service, or system obtained from Converge, without first complying with the United States and all other applicable government laws and regulations governing the export, re-export, and import of those items.

**10.6. Subcontracting.** We may use subcontractors, and other third-party providers (“**Subcontractors**”) in connection with the performance of our own obligations hereunder as we deem appropriate; provided that we remain responsible for the performance of each such Subcontractor.  Notwithstanding anything to the contrary in this Agreement, with respect to any third-party vendors including any hosting vendors, we will use commercially reasonable efforts to guard against any damages or issues arising in connection with such vendors, but will not be liable for the acts or omissions of such third-party vendors except to the extent that it has been finally adjudicated that such damages or issues are caused directly from the gross negligence or willful misconduct of Converge.

**10.7. Assignment.** You may not assign, delegate, or otherwise transfer your rights or obligations under this Agreement in whole or in part, except that you may assign this Agreement in connection with a merger, acquisition, sale of a majority of its equity, sale of substantially all of its assets to which this Agreement relates, or a similar transaction. This Agreement will be binding upon and will inure to the benefit of the parties and their permitted successors and assigns.

**10.8. Entire Agreement.** This Agreement constitutes the entire agreement, and supersedes any and all prior or contemporaneous representations, understandings and agreements, between the parties with respect to the subject matter of this Agreement, all of which are hereby merged into this Agreement. No amendment to this Agreement or waiver of any provision hereof will be valid or binding unless in a writing signed by the parties.

**10.9. No Waiver.** Failure to promptly enforce a provision of this Agreement will not be construed as a waiver of such provision.

**10.10. Relationship.** Nothing contained in this Agreement will be deemed to create, or be construed as creating, a joint venture or partnership between the parties. Neither party is, by virtue of this Agreement or otherwise, authorized as an agent or legal representative of the other party. Except as otherwise set forth in this Agreement, neither party is restricted from doing business with any other person, entity or organization by virtue of this Agreement. Neither party to this Agreement is granted any right or authority to assume or to create any obligation or responsibility, express or implied, on behalf or in the name of the other party, or to bind such other party in any manner. Nothing contained in this Agreement will be deemed to create any third-party beneficiary right upon any third party whatsoever.

**10.11. Enforceability.** If any one or more of the provisions of this Agreement should be ruled wholly or partly invalid or unenforceable, then the provisions held invalid or unenforceable will be deemed amended, and the court or other government body is authorized to reform the provision(s) to the minimum extent necessary to render them valid and enforceable in conformity with the parties’ intent as manifested herein.

**10.12. Counterparts.** This Agreement may be executed in counterparts, each of which will constitute the same instrument. Electronic signatures will be given the same effect and weight as originals.

## Schedule A - Definitions

“**Aggregate Data**” means any data that is derived or aggregated in deidentified form from (a) Your Content, or (b) your and/or your Authorized Users’ use of the Services, including, without limitation, any usage data or trends with respect to the Services. Subject to the foregoing, you have and retain ownership of Your Content, and any intellectual property rights therein.

“**Authorized User**” means any natural person who is your employee or contractor and who: (a) you authorize to use the Services; and (b) receives an account issued by Converge to use the Services.

“**Converge IP**” means the Services, the underlying software provided in conjunction with the Services, algorithms, interfaces, technology, databases, tools, know-how, processes and methods used to provide or deliver the Services, Documentation, and Aggregate Data, all improvements, modifications or enhancements to, or derivative works of, the foregoing (regardless of inventorship or authorship), whether of a general nature or specifically or individually conceived, created, or delivered by Converge alone or jointly with Customer, and all IP Rights in and to any of the foregoing.

“**Documentation**” means the operator and user manuals, training materials, specifications, and/or other similar materials in hard copy or electronic form if and as provided by Converge to you (including any revised versions thereof) relating to the Services, which may be updated from time to time.

“**IP Rights**” means patent rights (including, without limitation, patent applications and disclosures), inventions, copyrights, trade secrets, know-how, data and database rights, mask work rights, and any other intellectual property rights recognized in any country or jurisdiction in the world.

“**Order Form**” means any order form that has been mutually executed or otherwise been electronically accepted by you which references this Agreement.

“**Your Content**” means any nonpublic data captured through the Services, or otherwise made available to Converge, by or on behalf of you or your Authorized User, including visitor event data, attribution data, campaign metadata, and other custom configurations or reports created by you within the Services.

## Schedule B - Data Protection Addendum

This Data Processing Addendum (“**DPA**“) forms part of, and is subject to, the Software Services Terms & Conditions or other written or electronic terms of service or subscription agreement (the “**Agreement**”) between Converge Technologies, Inc. (“**Converge**,” “**we**” or “**us**”) and you (“**Customer**”). All capitalized terms not defined in this DPA shall have the meanings set forth in the Agreement.

In the event of any inconsistency or conflict between this DPA and the Agreement, this DPA will govern. Customer and Converge agree as follows:

**1. Definitions.**

“**Applicable Data Protection Law**” means all applicable data protection laws, rules, regulations, orders, ordinances, regulatory guidance, and industry self-regulations, including without limitation the EU General Data Protection Regulation (Regulation 2016/679), the United Kingdom Data Protection Act 2018, the California Consumer Privacy Act, as amended by the California Privacy Rights Act, the Swiss Federal Data Protection Act of 19 June 1992 (“FADP”), and any subsequent supplements, amendments, or replacements to the same.

“**Controller**” means an entity that, alone or jointly with others, determines the purposes for and means of Processing. “Controller” has the same meaning as “Business,” as that term is defined under Applicable Data Protection Law.

“**Data Subject**” means an identified or identifiable natural person.

“**De-Identified Data**” means data that cannot reasonably be used to infer information about, or otherwise be linked to, a Data Subject or as that term is otherwise defined under Applicable Data Protection Law. For the avoidance of doubt, De-Identified Data that has been aggregated will not be deemed Personal Data, subject to Converge’s compliance with restrictions on De-Identified Data under this DPA.

“**EU SCCs**” refers to the Standard Contractual Clauses promulgated by the EU Commission Implementing Decision (EU) 2021/914 dated 4 June 2021, as completed and supplemented by Converge, available at [https://docs.runconverge.com/legal/scc](https://docs.runconverge.com/legal/scc).

“**Personal Data**” means information that Converge Processes on Customer’s behalf in connection with its performance of the Services or otherwise pursuant to the Agreement or this DPA that identifies, relates to, describes, is reasonably capable of being associated with, or could reasonably be linked, directly or indirectly, to a Data Subject, or as that term or a similar term is defined under Applicable Data Protection Law.

“**Process**” or “**Processing**” means any operation or set of operations performed on Personal Data, whether or not by automated means, including, but not limited to, accessing, collecting, recording, organizing, structuring, using, storing, transferring, retaining, disclosing, selling, sharing, deleting, and destroying Personal Data.

“**Processor**” means a natural or legal person that Processes Personal Data on a Controller’s behalf. “Processor” has the same meaning as “Service Provider,” as that term is defined under Applicable Data Protection Law.

“**Converge Systems**” means the facilities, systems, equipment, hardware, and software Converge and Converge’s subprocessors use to Process Personal Data.

“**Security Breach**” means a breach of security leading to the accidental or unlawful destruction, loss, alteration, unauthorized disclosure of, or access to, Personal Data Processed by Converge.

“**UK Addendum**” refers to the UK’s International Data Transfer Addendum to the EU SCCs, available at [https://ico.org.uk/media2/migrated/4019539/international-data-transfer-addendum.pdf](https://ico.org.uk/media2/migrated/4019539/international-data-transfer-addendum.pdf).

**2. Roles of the Parties.** Converge will Process Personal Data on Customer’s behalf, as described in more detail in Annex 1. As between Customer and Converge, Customer will be the Controller and Converge will be the Processor.

**3. Customer Instructions.** The parties agree that the Agreement (including this DPA) sets out the exclusive and final instructions to Converge for all Processing of Personal Data. Any additional requested instructions must be mutually agreed by the parties in writing. Customer shall ensure its Processing instructions are lawful and that the Processing of Personal Data in accordance with such instructions will not violate Applicable Data Protection Law. Converge shall promptly notify Customer if, in Converge’s opinion, such instruction violates Applicable Data Protection Law. Converge may decide to suspend or cease such Processing of Customer Personal Data without owing Customer any compensation. Any lack of the aforementioned notification by Converge shall in no way affect Converge’s liability to the Customer.

If Customer fails to amend its instruction after being notified by Converge that such instruction is unlawful, Converge reserves the right to terminate the Agreement without liability for any damages or compensation arising from such termination.
Notwithstanding anything in the Agreement or DPA, Converge shall not be liable in any way for damages resulting from Customer’s instructions.

**4. Converge Responsibilities.** Converge agrees to:

(a) Process Personal Data solely in accordance with Customer’s documented instructions and for the specific business purposes and services specified in the Agreement and this DPA, which includes to prevent, detect, or investigate data security incidents, or protect against fraudulent activity to the extent authorized for Converge by Applicable Data Protection Law;

(b) except as expressly permitted by Applicable Data Protection Law, not retain, use, disclose, or otherwise Process Personal Data (i) for any purposes other than those specified in the Agreement and in Annex 1; (ii) for any commercial purpose other than the specific business purposes specified in the Agreement and the DPA, including to provide services to a different business; and (iii) outside the direct business relationship between Customer and Converge, including to combine or update Personal Data with information received from or on behalf of another source or collected from Converge’s own interactions with a Data Subject unless expressly instructed by Customer for a specific purpose, and for the sole benefit of Customer, in providing the Services;

(c) not “sell” or “share” Personal Data, as Applicable Data Protection Law defines those terms;

(d) ensure that persons who Process Personal Data on Converge’s behalf (such as employees) have undergone appropriate training and are bound by obligations of confidentiality;

(e) at Customer’s request, update, correct, delete, supplement, transfer, and provide Customer with access to Personal Data in Converge’s possession or control that has been lawfully provided by Customer and has been Processed on Customer’s behalf;

(f) cooperate with and provide reasonable assistance to Customer in complying with Applicable Data Protection Law including, but not limited to, assisting with legally-required data protection impact assessments, audits, and consultations with regulatory bodies. To the extent that the services referred to in the preceding paragraph are appropriate and possible, Customer and Converge shall agree on reasonable compensation to which Converge is entitled for these services based on Converge’s then-current rates; and

(g) upon Converge’s or a subprocessor’s receipt of a legally-binding request for access to Personal Data from a public authority and where permitted by applicable law: (i) attempt to redirect the request to Customer (and Converge is permitted to provide information to such public authority as reasonably necessary to redirect the request) and/or (ii) promptly notify Customer of the request for access to provide Customer the opportunity to comply with its notice and consent obligations with respect to affected Data Subjects or oppose the disclosure and obtain a protective order or seek other relief), unless providing such notice is prohibited by law, and (iii) where applicable, also comply with Converge’s obligations with respect to access by public authorities set forth in any applicable cross-border transfer mechanism.

**5. Provision of Personal Data.** Customer in its sole discretion determines what Personal Data is included in content Customer submits to the Services. Customer shall have sole responsibility for the accuracy, quality, and legal basis for collection of such Personal Data.

**6. Data Subject Requests.** Converge will not respond to direct requests from Data Subjects, and will refer such Data Subjects to Customer. As between Converge and Customer, Customer will be responsible for guaranteeing all Data Subjects' rights. Converge will cooperate with such requests and provide Customer with the reasonably necessary information.

**7. Subprocessors.** Subject to the requirements of this Section, Customer hereby grants general authorization to Converge to engage subprocessors to perform its obligations under this DPA and the Agreement. Converge will impose by way of contract on its subprocessors data protection obligations no less protective than those set out in this DPA and the Agreement, and Converge remains responsible for the Processing activities and omissions of its subprocessors.  Customer approves Converge’s current list of its subprocessors and the countries in which they are located listed at [https://docs.runconverge.com/legal/subprocessors](https://docs.runconverge.com/legal/subprocessors). In the event Converge intends to make changes to the list of approved subprocessors, Converge will provide Customer with at least seven (7) days’ prior written notice (email is sufficient). If Customer raises reasonable objections regarding a new subprocessor in writing during the seven (7) day period and Converge is unable to provide an alternate subprocessor, Customer, as its sole and exclusive remedy, may terminate the Agreement upon advance written notice with respect to those aspects of the Services which cannot be provided without use of the new subprocessor. Converge will refund any prepaid, unused fees for the terminated Services following the effective date of such termination.

**8. Cross-Border Data Transfers.**

The parties will not engage in cross-border transfers of Personal Data without taking steps to ensure such transfers comply with Applicable Data Protection Law. To the extent Customer transfers Personal Data to Converge about individuals in:

(a) the European Economic Area (EEA), the parties will conduct such transfers pursuant to Module 2 of the EU SCCs, which are hereby incorporated by reference and deemed executed by the parties as of the Effective Date, or by certifying to and participating in another lawful cross-border transfer mechanism. If Customer is not established in the EEA, Customer will have an appointed representative pursuant to article 27 of the GDPR.

(b) the United Kingdom, the parties will conduct such transfers pursuant to the EU SCCs in tandem with the UK Addendum, which are hereby incorporated by reference and deemed executed by the parties as of the Effective Date, or by certifying to and participating in another lawful cross-border transfer mechanism.

(c) Switzerland, the parties will conduct such transfers pursuant to the EU SCCs, which are hereby incorporated by reference and deemed executed by the parties as of the Effective Date, or by certifying to and participating in another lawful cross-border transfer mechanism. In relation to Personal Data that is protected by the FADP and transferred pursuant to the EU SCCs, the EU SCCs will be amended as follows:

i. references to “Regulation (EU) 2016/679” in the EU SCCs will be deemed to refer to the Swiss FADP;<br />
ii. references to specific articles of “Regulation (EU) 2016/679” will be deemed replaced with the equivalent article or section of the Swiss FADP;<br />
iii. references to “EU”, “Union” and “Member State” will be deemed replaced with ‘Switzerland’; <br />
iv. references to the “competent supervisory authority” and “competent courts” are replaced with the “Swiss Federal Data Protection Information Commissioner” and “applicable courts of Switzerland” (as applicable);<br />
v. in Clause 17, the EU SCCs will be governed by the laws of Switzerland; and<br />
vi. in Clause 18(b), disputes will be resolved before the competent courts of Switzerland.

(d) If the parties will engage in cross-border transfers of Personal Data subject to the EU SCCs and/or the UK Addendum, Converge will be the “data importer,” Customer will be the “data exporter,” and Annex 1 will provide the supplementary information required. If there is any conflict between this DPA and the EU SCCs and/or UK Addendum, respectively, the EU SCCs or UK Addendum will prevail.

(e) In the event Converge engages in cross-border or onward transfers of Personal Data with a subprocessor or other third-party recipient, Converge will conduct such transfers only after obtaining explicit consent from Customer and ensuring a lawful cross-border transfer mechanism is in place.

**9. Security Safeguards.** Converge will implement, maintain, and monitor a comprehensive written information security policy that contains appropriate administrative, technical, and organizational safeguards to ensure the confidentiality, integrity, and availability of Personal Data and prevent any unauthorized or unlawful Processing of such Personal Data, as detailed in Exhibit A hereto. The safeguards will be appropriate to the nature of the Personal Data and comply with Applicable Data Protection Law.

**10. Security Breach.**

(a) In the event Converge discovers a Security Breach, Converge will (i) without undue delay notify Customer in writing by email of the Security Breach; and (ii) promptly take appropriate steps to investigate, mitigate, and remedy the Security Breach.

(b) Any notification required under this Section must satisfy the requirements under Applicable Data Protection Law and include, where feasible: (i) the details of the Security Breach available to Converge at such time, which may include the number and categories of individuals affected, categories and number of records concerned, types of Personal Data affected, likely consequences of the Security Breach, and date and time of such incident; (ii) a summary of the incident that caused the Security Breach and any ongoing risks that the Security Breach poses; (iii) a description of the measures proposed or taken by Converge to address the Security Breach; (iv) any other information required under Applicable Data Protection Law. Following such initial notice, Converge will reasonably cooperate with Customer (including by  providing information reasonably requested by Customer) to enable Customer to comply with its legal obligations to notify supervisory authorities or Data Subjects of the Security Breach.

(c) Notwithstanding the foregoing, Converge’s maximum liability under this DPA will be limited pursuant to the limitations of liability set forth in the Agreement.

**11. Representations and Warranties.**

(a) Customer represents and warrants that it is and will remain in compliance with all Applicable Data Protection Laws in connection with the Agreement and Personal Data, and that the instructions given to Converge are in accordance with Applicable Data Protection Law.

(b) Customer represents and warrants that all Personal Data entrusted to Converge have been lawfully obtained and can be lawfully Processed throughout the duration of the Agreement. Customer shall, in this respect, assist and fully indemnify Converge against any complaint, action or claim by Data Subjects, third parties, public authorities and against Customer, if the latter acts as Processor, without prejudice to Converge's right to compensation from the Customer for the damages it has suffered.

(c) Taking into account the nature, scope, context and purpose of the Processing, as well as the risks to the rights and freedoms of natural persons which vary in their likelihood and seriousness, Customer represents and warrants that it has implemented and will maintain appropriate technical and organizational measures to ensure and be able to demonstrate that the Processing is carried out in accordance with Applicable Data Protection Law. These measures shall be reviewed at regular intervals and updated if necessary.

**12. Return or Destruction of Personal Data.** Upon Customer’s request, or promptly upon termination of the Agreement, Converge will cease all Processing of Personal Data and, at Customer’s election, either (a) return such data to Customer or (b) destroy such data and certify such destruction to Customer in writing. Converge is permitted to retain Personal Data where it has a legal requirement to do so, provided that Converge notified Customer of this in writing.
The parties hereby accept and agree to the terms of this Data Processing Addendum:

### Annex 1 to DPA: Scope of Processing

**1. Controller / Data Exporter:**

**Name:** Company named on the associated Order Form.<br />
**Address and Point of Contact:** The address and contact details associated with Customer's Converge account, or as otherwise specified in the Order Form or below.<br />
**Activities relevant to the data Processed under the DPA:** Use of the Converge platform and services.

**2. Processor / Data Importer:**

**Name:** Converge Technologies, Inc.<br />
**Address:** 169 Madison Avenue, Suite 15525, New York, NY 10016, United States<br />
**Activities relevant to the data Processed under the DPA:** Converge’s provision of customer event tracking services.<br />
**Point of Contact:** Thomas Holvoet, Data Protection Officer, [legal@runconverge.com](mailto:legal@runconverge.com)

**3. Subject Matter of Processing:**  The Processing is in relation to Converge’s provision of services under the Agreement.

**4. Duration of Processing:**  The Processing will begin after the Effective Date and will end upon expiration or termination of the Agreement.

**5. Nature and Purpose of Processing:**  Data is collected, forwarded, and made available for analytics, enabling the use of Converge’s software platform.

**6. Types of Personal Data include:**  IP address, first name, last name, email address, telephone number, address data, country code, state, zip code, user agent, device identifiers.

**7. Categories of Data Subjects:**  Customers and users of the Converge software platform, and website visitors and customers of Converge’s customers.

**8. Period of Data Retention by Converge:**  Converge will retain Personal Data until the termination of the Agreement, unless otherwise agreed to by the parties.

**9. Approved Subprocessors and Data Transfers:** [https://docs.runconverge.com/legal/subprocessors](https://docs.runconverge.com/legal/subprocessors)

## Exhibit A: Information Security Exhibit

**1. Definitions.** For purposes of this Information Security Exhibit (“Exhibit”), the following terms have the meanings set forth below. All capitalized terms not otherwise defined in this Exhibit will have the meaning given to them in the Data Processing Addendum (the “DPA”) between Customer and Converge.

**2. General.** Converge will use reasonable measures to protect Personal Data from unauthorized access, use or disclosure.

(a) **Program.** Converge will implement and maintain a comprehensive written information security program, which contains administrative, technical, and organizational safeguards that comply with this Exhibit, ensure the security, integrity, availability, resilience, and confidentiality of Customer Data, and meet or exceed prevailing industry standards and comply with Applicable Data Protection Law.

(b) **Vulnerability Management.** Converge will: (i) use automated vulnerability scanning tools to scan the Converge Systems; (ii) log vulnerability scan reports; (iii) conduct periodic reviews of vulnerability scan reports over time; (iv) use patch management and software update tools for the Converge Systems; (v) prioritize and remediate vulnerabilities by risk; and (vi) use compensating controls if no patch or remediation is immediately available.

(c) **Encryption.** Converge will encrypt, using industry standard encryption tools, all Personal Data that Converge: (i) transmits or sends wirelessly or across public networks or within the Converge Systems; (ii) stores on laptops or storage media, and (iii) stores on portable devices or within the Converge System. Converge will comply with secure key management policies and procedures and safeguard the security and confidentiality of all encryption keys associated with encrypted Personal Data.

(d) **Organizational Safeguards.** Converge will maintain and comply with internal policies to: (i) limit the retention of Personal Data to the minimum amount of time necessary to perform Converge’s obligations under the Agreement; and (ii) provide for meaningful consequences to personnel who breach the obligations set forth in this Exhibit.

(e) **Incident Response Plan.** Converge will maintain a documented incident response plan that addresses detection, reporting, evidence management, post-incident restoration and incorporation of lessons learned. The plan must be tested at least annually.

**3. Security Breach.** The security provisions relating to Personal Data are provided in the DPA.

**4. Return or Destruction of Customer Data.** Data return and destruction provisions relating to Personal Data are provided in the DPA.


# Ask Claude in Slack
Source: https://docs.runconverge.com/mcp/ask-claude-in-slack

Query your Converge analytics data from Slack by @mentioning Claude.

Ask analytics questions right from Slack. @mention Claude, and it calls the Converge MCP server behind the scenes to fetch your data and reply in-thread. No context switching, no dashboards to open. See the [overview](/mcp/overview) for the full list of available tools and authentication details.

<Frame>
  <img alt="Ask Claude in Slack" />
</Frame>

## Prerequisites

Before setting up Claude in Slack, connect the Converge MCP server to your Claude account first. Follow the [setup guide](/mcp/setup) to get started.

## Set up Claude in Slack

<Steps>
  <Step title="Install the Claude Slack app">
    A Slack workspace admin installs the Claude app from the [Slack Marketplace](https://slack.com/marketplace/A08SF47R6P4-claude).
  </Step>

  <Step title="Connect your Claude account">
    Open the Claude app in Slack and click **Connect Account**. Authorize with the
    same Claude account where you connected the Converge MCP server.
  </Step>

  <Step title="Enable Chat mode">
    In the Claude app home in Slack, find **Routing Mode** and select **Code + Chat**. This lets Claude route analytics questions through Chat, where MCP connectors live.

    The routing options are:

    * **Code**: Routes all messages to Claude Code (no MCP access).
    * **Code + Chat**: Claude decides which mode fits the message. Pick this one so analytics questions go through Chat (MCP connectors available) while code questions still work.

    <Frame>
      <img alt="Enable Chat mode" />
    </Frame>
  </Step>

  <Step title="Invite Claude to a channel">
    In the Slack channel where you want to use Claude, type `/invite @Claude`.
  </Step>

  <Step title="Verify the setup">
    @mention Claude with an analytics question to confirm everything works. For example:

    > @Claude what is revenue for Acme Corp for the last 7 days?

    Claude should call the Converge MCP server and reply with your data in the thread. Note that Claude keeps context within a Slack thread. Reply in the same thread and @mention Claude to ask follow-up questions without repeating yourself.
  </Step>
</Steps>


# Automate workflows
Source: https://docs.runconverge.com/mcp/automate-workflows

Schedule recurring analytics reports by connecting the Converge MCP server to workflow automation platforms.

The Converge MCP server lets you pull analytics data from Converge using any AI model that supports tool calling. Pair it with a workflow automation platform, or use the built-in schedulers of your AI assistant, and you can schedule recurring actions that run on autopilot, with no code required. See the [overview](/mcp/overview) for the full list of available tools and authentication details.

<Tip>
  For most recurring Slack or email reports, [routines](/mcp/routines) are the Converge-native way to do this, no external platform needed. Use the options on this page when you need custom triggers, multi-step workflows, or destinations beyond Slack and email.
</Tip>

Some examples of what you can automate:

* **Daily Slack digests** with yesterday's revenue, orders, and conversion rate.
* **Weekly channel breakdowns** comparing spend, ROAS, and CPA across ad platforms.
* **Google Sheets exports** that append a row of key metrics to a spreadsheet on a schedule.

## How it works

Every automated report follows a three-part pattern:

1. **Trigger**: A schedule fires at a set interval (daily, weekly, hourly).
2. **AI Agent + MCP**: The trigger invokes an AI Agent (e.g. ChatGPT, Claude) that calls the Converge MCP server to pull your analytics data.
3. **Output**: The AI Agent formats the results and sends them to a destination like Slack, or email.

Both n8n and Zapier support this pattern out of the box with their AI agent and MCP integrations. Claude Cowork is a simpler alternative where Claude itself is both the scheduler and the AI model, no separate platform needed.

## Set up automated reports

<Tip>
  We recommend **n8n** for automated reports: it gives you the most control and
  versatility, though it needs more setup time. **Zapier** also works, but its
  AI agent has limitations. **Claude Cowork** is the easiest to set up (no
  separate platform needed), but offers less control over the workflow.
</Tip>

<Tabs>
  <Tab title="n8n">
    [n8n](https://n8n.io) is an open-source workflow automation platform. It has built-in support for AI agents and MCP tool calling.

    <img alt="n8n workflow overview" />

    <Steps>
      <Step title="Create a new workflow with a Schedule Trigger">
        In n8n, create a new workflow. Add a **Schedule Trigger** node and set the interval (e.g., every day at 9:00 AM, every Monday at 8:00 AM, or every hour).

        In the node's **Settings** tab, optionally enable **Retry On Fail**. MCP calls can occasionally time out, and retries make sure your report still goes out.
      </Step>

      <Step title="Configure the AI Agent">
        Add an **AI Agent** node and connect it to the Schedule Trigger. Set *Source for Prompt* to *Define below*, then, add your desired prompt, or paste one of the [example prompts](#example-prompts) into the *Prompt* field.

        Then configure two sub-nodes:

        1. **Chat Model**: Choose OpenAI (GPT) or Anthropic (Claude) and connect it with your API key from that provider.
        2. **Tool**: Add an *MCP Client Tool* sub-node with the following settings:
           * **Endpoint**: `https://app.runconverge.com/api/mcp`
           * **Server Transport**: Streamable HTTP
           * **Authentication**: MCP OAuth2
           * **Credential for MCP OAuth2 API**: Click to create a new credential, n8n will open the Converge OAuth flow.
           * **Tools to include**: All
           * Under options, optionally set a timeout

        Before proceeding, we recommend testing this part of the workflow with *Execute step* (available on the AI agent node). You should see your report in the output panel.
      </Step>

      <Step title="Add an output node">
        Add an output action after the AI Agent: for example, **Slack** (send a channel message), **Gmail** (send an email), or **Google Sheets** (append a row). Map the AI agent's output to the message body using the expression `{{ $json.output }}`.

        See [output recommendations](#output-recommendations) below for tips on formatting per destination.
      </Step>

      <Step title="Test and activate">
        Click **Execute workflow** to run it once and verify the output. When everything looks good, publish your workflow to **Active**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Zapier">
    [Zapier](https://zapier.com) is a workflow automation platform that connects thousands of apps. Its [MCP Client](https://zapier.com/apps/mcp-client-by-zapier/integrations) integration lets you call tools on any MCP server (including Converge) directly from a Zap.

    <Frame>
      <img alt="Zapier workflow overview" />
    </Frame>

    <Steps>
      <Step title="Create a new Zap with a Schedule trigger">
        In Zapier, create a new Zap. Choose **Schedule by Zapier** as the trigger and set the frequency (e.g., every day, every week, or every hour).
      </Step>

      <Step title="Add the MCP Client action">
        Add a new action step and select **MCP Client by Zapier** as the app. Then configure it:

        1. **Account**: Connect the Converge MCP. Enter the server URL `https://app.runconverge.com/api/mcp`, set transport to *Streamable HTTP*, and choose *OAuth* for authentication. Zapier will open the Converge OAuth flow in your browser. Sign in with the same Google account you use for [Converge](/mcp/overview#authentication).
        2. **Tool**: Pick the [Converge tool](/mcp/overview#available-tools) you want to call (e.g., *Get Analytics View Data* or *Analytics Query*). Each MCP Client action is tied to one specific tool.
        3. **Options**: Fill in the tool's parameters (workspace ID, date range, metrics, etc.). The fields shown here depend on the tool you selected.

        Click **Test step** to verify the tool returns data.
      </Step>

      <Step title="Format the results with AI">
        The MCP Client returns unstructured data. To turn it into a readable report, add an AI step after the MCP step. Zapier supports several AI providers, pick whichever you prefer:

        * **AI by Zapier**: Built-in option that lets you pick from popular models (including Claude and GPT) without bringing your own API key. Includes a prompt generator and templates.
        * **Anthropic (Claude)** or **OpenAI (ChatGPT)**: Connect your own API key for more control over model selection and parameters.

        Set the action event to **Send Message** (or the equivalent for your chosen provider). Then fill in:

        * **User Message**: Write your formatting instructions, then click the **+** button to insert the MCP step's **Content Text** output. For example: *"Format the following data as a Slack message with bold metric names and bullet points. Keep it under 300 words. No code fences. Data:"* followed by the inserted MCP output.
        * **Model**: Pick the model you want to use (e.g., `claude opus 4.6`).
        * **System** (optional): Add a system prompt like *"You're a marketing analyst. Output only the formatted report, no extra commentary."*

        Leave **Memory Key** empty, it's not needed for one-off formatting tasks.

        Check [writing good prompts](#writing-good-prompts) and [output recommendations](#output-recommendations) for more tips on getting clean, destination-ready output.
      </Step>

      <Step title="Add an output action">
        Add a final action to send the formatted report somewhere: **Slack**, **Gmail**, **Google Sheets**, or any other Zapier-supported app. Map the AI step's output to the message body.

        For example, in a Gmail action: in the **Body** field, click the **+** button to insert data from the previous AI output step (for example, **Response Content Text**). Make sure **Body type** is set to **HTML** if your prompt asks the model to produce HTML output.

        See [output recommendations](#output-recommendations) for format tips per destination.
      </Step>

      <Step title="Test and publish">
        Test each step end-to-end by clicking **Test step** on every action in sequence. When everything looks good, click **Publish** to activate the Zap.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Cowork">
    Claude Cowork has a built-in scheduler ("scheduled tasks") with full MCP server access. There's no separate automation platform to set up: Claude acts as both the scheduler and the AI model.

    <Warning>
      Scheduled tasks only run while your computer is awake and Claude Cowork is
      open. If your machine is asleep when a task is due, Claude runs one catch-up
      execution when you wake it. For always-on automation, use n8n or Zapier
      instead.
    </Warning>

    <Steps>
      <Step title="Connect the Converge MCP server">
        If you haven't already, add the Converge MCP server to Claude. Follow the [setup guide](/mcp/setup) to get started.
      </Step>

      <Step title="Create a scheduled task">
        Open the **Scheduled** page from the Claude Cowork sidebar and click **New task**. This will open window to set up the local task. Configure:

        * **Name**: A short label (e.g. "daily-revenue-report").
        * **Description**: A short description of the task.
        * **Prompt**: A fully end-to-end prompt that tells Claude what to do, including which data to fetch from Converge, how to format it, and where to send it. The prompt must be fully self-contained: include workspace ID or name, metric names, and output format instructions, because the task runs without human input.
        * **Frequency**: Pick a schedule (e.g. daily at 9 AM, every Monday at 8 AM).

        You can also create a task by typing `/schedule` in any conversation.
      </Step>

      <Step title="Configure output via MCP connectors">
        To forward reports to Slack or another destination, add a connector in **Settings > Connectors** (e.g. Slack). Then include an output instruction in your prompt, like: *"Send the report to the #marketing channel in Slack."*

        If you skip this step, the report lives in your session history and you can review it anytime from the Schedule page.
      </Step>

      <Step title="Test and monitor">
        Click **Run now** on the task to verify the output. If everything looks good, keep the task enabled. Optionally, enable **Keep computer awake** in Claude Cowork settings to prevent sleep during scheduled windows.
      </Step>
    </Steps>

    <Info>
      **Claude Code** also has a scheduler with local and remote task options, but
      it's more designed for code-related tasks on a GitHub repo. You can connect the
      Converge MCP server to it, and the setup is very similar to Claude Cowork.
      See the [Claude Code scheduled tasks docs](https://code.claude.com/docs/en/scheduled-tasks) for more info.
    </Info>
  </Tab>
</Tabs>

## Output recommendations

The best output format depends on your destination. Tell the AI agent how to format its response in your prompt.

* **Email (Gmail, Outlook)**: Ask for **HTML** output. Email clients render HTML natively, so you get clean tables, color coding, and metric cards without any extra work. Some email clients require you to set the **Email Type** to **HTML**. Include a note in your prompt like: *"Output raw HTML only, no markdown fences and no prose."*
* **Slack**: Ask for **Markdown** output. Slack supports a subset of Markdown (bold, lists, code blocks) but doesn't render HTML. Keep reports concise, as long messages get truncated. Use bullet points and bold text for scanability.
* **Local file (Claude Cowork)**: Any format works: Markdown, HTML, CSV, JSON. Tell Claude Cowork to write results to a specific file path. Useful for reports you want to commit to a repo or process with scripts.

## Writing good prompts

Your prompt should be fully self-contained: include specific workspace IDs, view IDs (if needed), metric names, and output format instructions. The agent runs on a schedule without human input, so it can't ask follow-up questions.

A few tips:

* **Be specific about data.** If you want a specific view, use its exact ID (available in the URL of the view in Converge). Instead of *"pull my pacing sheet"*, say *"pull the Pacing data (view\_id: 12) for workspace ."*
* **Specify the output format.** Tell the agent exactly how to structure the result: HTML table, Markdown bullets, CSV, etc. Make clear that the output will be directly used in the next step, so it shouldn't include extra prose or commentary.
* **Be explicit about comparisons.** If you want week-over-week or month-over-month changes, spell it out. Don't leave it as optional, LLMs tend to skip anything that's framed as "nice to have."
* **Set formatting constraints.** If the output goes straight to email or Slack, add rules like *"no code fences,"* *"no markdown around the HTML,"* or *"keep it under 500 words."*
* **Include output instructions (Claude Cowork).** If you've connected a Slack or email connector, tell Claude where to send the result in your prompt. For example: *"Send the report to the #marketing channel in Slack."* Without this, the output stays in session history.

### Example prompts

<AccordionGroup>
  <Accordion title="Daily revenue summary (Slack)">
    ```text theme={null}
    Pull yesterday's data for workspace {your_workspace_id}. Include:
    revenue, total orders, average order value, and conversion rate.
    Compare each metric to the same day last week and show the percentage
    change in parentheses.

    Format as a Slack message using bold for metric names and bullet
    points. Keep it under 300 words. No code fences.
    ```

    A quick morning snapshot for your team, using the `analytics_query` tool.
  </Accordion>

  <Accordion title="Weekly channel breakdown (HTML email)">
    ```text theme={null}
    Pull last week's performance for workspace {your_workspace_id},
    broken down by channel. For each channel, include: spend, revenue,
    ROAS, and cost per acquisition. Sort by revenue descending. Compare
    each metric to the previous week and show the change as a percentage.

    Format as an HTML table with color-coded percentage changes (green
    for positive, red for negative). Output raw HTML only, no code
    fences, no markdown, no surrounding prose.
    ```

    Also uses the `analytics_query` tool. Great for a Monday morning channel review sent via email.
  </Accordion>

  <Accordion title="Export a saved analytics view">
    ```text theme={null}
    Fetch the Pacing data (view_id: {your_view_id}) for workspace
    {your_workspace_id}. Format the results as a clean HTML table with
    headers.

    Output raw HTML only, no code fences, no markdown, no extra text.
    ```

    Uses `get_analytics_view_data` to grab your Pacing view's data. Great if you want a little more control over the data than `analytics_query` provides.
  </Accordion>
</AccordionGroup>


# Overview
Source: https://docs.runconverge.com/mcp/overview

Query your Converge analytics data from any AI tool using the Converge MCP server.

<Frame>
  <iframe />
</Frame>

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that lets AI assistants connect to external data sources. The **Converge MCP server** gives any MCP-compatible client read access to your analytics data, with no code required.

## Applications and use cases

Pick a use case to get started. Each page walks you through the full setup.

<CardGroup>
  <Card title="Example prompts" href="/mcp/prompts" icon="robot">
    Ask analytics questions from Claude, ChatGPT, or any MCP-compatible
    assistant.
  </Card>

  <Card title="Automate workflows" href="/mcp/automate-workflows" icon="clock-rotate-left">
    Schedule recurring reports with n8n, Zapier, or Claude Cowork.
  </Card>

  <Card title="Ask Claude in Slack" href="/mcp/ask-claude-in-slack" icon="slack">
    Query your analytics data by @mentioning Claude in any Slack channel.
  </Card>
</CardGroup>

## Available tools

The Converge MCP server exposes the following tools:

| Tool                       | Description                                                                                                                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `analytics_query`          | Run custom queries with full flexibility over metrics, filters, breakdowns, date ranges, and attribution models.                                                                    |
| `cohort_analysis`          | Group customers by acquisition period and measure lifetime value (LTV) or retention rate across follow-up windows.                                                                  |
| `collect_feedback`         | Collects feedback about your experience. Fires automatically when issues arise, or ask your AI assistant to submit feedback anytime.                                                |
| `get_analytics_view_data`  | Export a saved analytics view's data. Useful for further analysis.                                                                                                                  |
| `get_insight_data`         | Export a saved insight's data.                                                                                                                                                      |
| `list_analytics_views`     | Lists your saved analytics views from within the app. The different types are: attribution, overview, pacing, landing page, product.                                                |
| `list_dashboards`          | Lists saved dashboards. Dashboards are collections of related insights.                                                                                                             |
| `list_insights`            | Lists saved insights. Each insight is a saved analytics query.                                                                                                                      |
| `list_metric_event_names`  | Lists metric event names tracked in a workspace. Use to discover valid `event_name` values for `analytics_query`. Optionally includes custom marketing events from ad platforms.    |
| `list_store_dimensions`    | List store dimensions available for a workspace. Store dimensions are user-defined groupings typically used for separating regions, brands, or sales channels.                      |
| `list_workspaces`          | Lists all workspaces you have access to.                                                                                                                                            |
| `search_touchpoint_values` | Search and validate touchpoint values (channel groups, channels, campaigns, ad sets, ads) before using them in filters. Returns IDs, names, and all parent levels in the hierarchy. |

Given these tools, there are two main ways to pull data:

* **Saved reports** (`get_analytics_view_data`): Pull data directly from a report you've already built in Converge. What you get back is exactly what you see in the app, no extra configuration needed. Use the `list_analytics_views` tool to see what reports are available.
* **Flexible queries** (`analytics_query`): Choose any combination of metrics, date ranges, attribution models, and breakdowns (channel, campaign, ad set, landing page). Far more versatile and powerful, and what you'll use most of the time.

## Workspaces

If your account has access to multiple workspaces, specify the one you want by name in your prompt (e.g. *"Show me last week's spend for **Acme US**"*). If you don't specify one, the AI assistant will fetch your list of available workspaces and ask you to pick one.

Once a workspace is selected, it stays active for the rest of the conversation. You can switch at any time by asking for a different workspace. New conversations start fresh — there's no workspace carried over between chats.

<Info>
  Instead of passing a workspace name, you can also define your workspace ID in
  the prompt, which skips the workspace-lookup step and is slightly faster. Find
  both your workspace name and ID in the Converge app:

  <Frame>
    <img alt="How to find your workspace name and ID" />
  </Frame>
</Info>

## Authentication

The Converge MCP server URL is:

```
https://app.runconverge.com/api/mcp
```

You can authenticate in two ways.

#### Google OAuth (recommended for interactive clients)

On your first interaction, a browser window opens automatically for Google sign-in. Use the same Google account you use to access Converge. This is the easiest option for clients like Claude, ChatGPT, or Cursor that handle the OAuth flow for you.

#### Personal API key (recommended for automations)

For MCP clients that don't support the interactive OAuth flow, authenticate with a personal API key instead. You can create one in the [API keys section](https://app.runconverge.com/-/settings/personal-api-keys) of your account settings.

<Frame>
  <img alt="Personal API keys" />
</Frame>

Each key:

* Starts with `cvg_` and is shown only once at creation, so copy it somewhere safe.
* Inherits your own access: it sees the same workspaces and data you do. Other accounts in your workspace will not be able to access this API key.
* Can be given an optional expiry (30 days, 90 days, 1 year, or never) and revoked at any time.

Pass the key as a standard bearer token in the `Authorization` header. For example:

```
Authorization: Bearer cvg_Q29udmVyZ2UgaXMgdGhlIGJlc3Q
```

Most MCP clients have a dedicated field for this. Paste the key there and skip the OAuth flow entirely.

## Example prompts

Anything you can query in Converge, you can ask in natural language. Your AI assistant translates your question into the right metrics, filters, breakdowns, and date ranges automatically.

* **Channel and campaign performance**: *"Break down yesterday's new customer orders, spend, and CPA by channel group."*
* **Ad-level creative analysis**: *"Show total spend and new customer first-touch ROAS for all ads with 'UGC Script' last quarter."*
* **Daily performance and revenue tracking**: *"Pull an MTD summary of spend, revenue, and new customer orders by channel."*
* **Country and market comparisons**: *"Break down monthly Facebook spend, new customer orders, and revenue per country from March 2024 to now."*
* **Landing page and funnel analysis**: *"Which landing pages drove the most new customer orders this month?"*

## FAQ

### Does Converge use my data to train AI models?

No. Converge does not train any AI models on your data, and our MCP server does not send your data to any AI provider on our behalf. The MCP server only responds to queries from the AI client *you* connect (Claude, ChatGPT, Claude Code, etc.), and data flows directly from Converge to that client over your authenticated session.

### Where does my data go when I use the MCP server?

When you ask a question in your AI assistant, two things happen:

1. The assistant calls the Converge MCP server at `app.runconverge.com/api/mcp` over an authenticated session (Google OAuth or a personal API key).
2. Converge returns the requested analytics data directly to the AI client running on your machine or in your AI provider's environment.
   Converge does not route your data through any third-party AI provider. The only AI provider involved is the one you've chosen to connect.

### Will my AI provider train on the data returned by Converge?

That depends on which AI assistant you connect and what plan you're on with that provider — not on Converge. Each AI vendor has its own data-handling and training policy which you should confirm with them.

### Where is my data processed?

Converge's application infrastructure runs on AWS in the US. The MCP server runs on the same infrastructure as the rest of the Converge platform. See [Data Subprocessors](/legal/subprocessors) for the full list.

Once data leaves the MCP server, it's processed by the AI provider you connected to, in whichever regions that provider operates.

### What data can the MCP server access?

The MCP server has read-only access to the same analytics data you can see in the Converge app: aggregated marketing performance, attribution, spend, orders, revenue, and the breakdowns and dimensions exposed by the tools listed under [Available tools](#available-tools). It does not read or send customer PII, and it cannot write back to your workspace.

### Can I revoke access?

Yes. Disconnect the connector in your AI assistant's settings, or revoke the personal API key from [Settings > Personal API Keys](https://app.runconverge.com/-/settings/personal-api-keys). For OAuth sessions, you can also revoke access from your Google Account's security settings.


# Example prompts
Source: https://docs.runconverge.com/mcp/prompts

Fetch analytics data and ask follow-up questions from Claude, Claude Code, ChatGPT, or any MCP-compatible assistant.

<Note>
  Haven't set up the MCP server yet? Follow the [setup guide](/mcp/setup) to get started.
</Note>

## Prompt templates

Copy these into your AI assistant for a deeper, multi-step analysis. Each prompt tells the AI exactly what data to pull, how to structure the output, and what recommendations to generate.

<Tip>
  We recommend using a frontier model (e.g. Claude Opus 4.6 or equivalent) for best results. Some prompts contain placeholders like `{time_period}` replace these with your own values before pasting. These reports make many tool calls, so expect the full analysis to take up to 5 minutes to complete.
</Tip>

<AccordionGroup>
  <Accordion title="Conversion rate analysis">
    ```text theme={null}
    Purpose: Perform a comprehensive conversion rate analysis for a DTC eCommerce business using Converge analytics data. Audience: Marketing, CRO, and leadership teams. Output must be data-driven, actionable, and tied to revenue impact.

    USER INPUTS:
    - Analysis Period: {time_period} [default: last 30 days]
    - Comparison Period: the same-length window immediately before {time_period}

    ---

    ## Expert knowledge you have

    * Converge is a multi-touch marketing attribution platform for DTC brands. It tracks conversion events from the website and pulls in aggregated marketing performance from ad platforms (Facebook Ads, Google Ads, TikTok, Pinterest, Bing, etc.). You can compare channels or campaigns by combining event and ad platform metrics with a touchpoint breakdown.
    * Key event metrics you can query:
        * `events` (count), `sessions`, `profiles`
        * `revenue` (total revenue for the event)
        * `session_conversion_rate`, `profile_conversion_rate`
        * `bounce_rate`, `session_duration`, `session_revenue`
        * `new_visitor_sessions`, `new_visitor_sessions_rate`
        * `cpa` (cost per acquisition = spend / events), `roas` (return on ad spend = revenue / spend), `acos` (ad cost of sales = spend / revenue)
    * Key ad platform metrics (platform-reported):
        * `spend`, `clicks`, `impressions`
        * `cpc`, `cpm`, `ctr`
        * `ad_conversions`, `ad_revenue`, `ad_roas`, `ad_cpa`, `ad_acos`
    * Standard conversion events (the funnel): `$page_load`, `Viewed Product`, `Added To Cart`, `Started Checkout`, `Placed Order`, `New Customer Order`.
    * `New Customer Order` fires on a profile's first-ever `Placed Order` -- use this for new customer acquisition metrics.
    * Multi-touch attribution (MTA) models available: `first_touch`, `last_touch`, `linear`, `first_touch_paid`, `last_touch_paid`, `top_of_funnel`, `time_decay`, `u_shaped`, `j_shaped`, and more. Default is `direct_session` (no MTA). Attribution `mode` can be `click_time` or `conversion_time`; click-time is better for evaluating spend efficiency (CPA, ROAS).
    * Available breakdowns: `touchpoint.channel_group`, `touchpoint.channel`, `touchpoint.campaign`, `touchpoint.adset`, `touchpoint.ad`, `session.landing_url`, and any `store_dimension.<id>` configured for the workspace.

    ---

    ## Process

    **Default attribution**: Unless the user specifies otherwise, use `top_of_funnel` model with a 30-day window and `click_time` mode for all `analytics_query` calls (`"attribution": {"model": "top_of_funnel", "window": 30, "mode": "click_time"}`).

    1. **Discover the workspace**: Call `list_workspaces` to find the workspace. Note the workspace's currency, timezone, and start_of_week -- pass these to all subsequent tool calls. Call `list_metric_event_names` to confirm which events are tracked and check for any custom events relevant to the funnel. Call `list_store_dimensions` to discover any region/brand/channel dimensions available for deeper segmentation.

    2. **Define the periods**: The analysis period is {time_period} (default: last 30 days). The comparison period is the same-length window immediately before. State both date ranges to the user.

    3. **Overall conversion performance** using `analytics_query`:

        - **Site-wide CVR**: Query `Placed Order` / `session_conversion_rate` and `Placed Order` / `events`, plus `sessions` (no event filter), `revenue` (`Placed Order` / `revenue`), and `session_revenue`. Run for both the analysis period and the comparison period.
        - **Trend over time**: Query the same metrics with `time_granularity: "week"` across the full analysis period to identify whether CVR is improving or declining. Characterise the direction ("improving", "declining", "flat") and magnitude.

    4. **Conversion by segment** -- run separate `analytics_query` calls with breakdowns:

        a. **By traffic source**: Breakdown by `touchpoint.channel_group`. Metrics: `Placed Order` / `session_conversion_rate`, `Placed Order` / `events`, `Placed Order` / `revenue`, `sessions`, `bounce_rate`, `cpa`, `roas`. Identify the highest- and lowest-converting channel groups.

        b. **By channel (granular)**: Breakdown by `touchpoint.channel`. Same metrics. Useful for separating e.g. Paid Social/facebook from Paid Social/tiktok.

        c. **By landing page**: Breakdown by `session.landing_url`. Metrics: `sessions`, `bounce_rate`, `session_duration`, `Placed Order` / `session_conversion_rate`, `Placed Order` / `revenue`. Sort by sessions descending, focus on top 10.

        d. **By day of week**: Query with `time_granularity: "day"` across the analysis period and group results by weekday to surface day-of-week patterns.

        e. **New vs returning visitors**: Query `new_visitor_sessions`, `new_visitor_sessions_rate`, alongside `Placed Order` / `session_conversion_rate`. Compare conversion behaviour of new visitor traffic vs overall.

        f. **By store dimension** (if available): For each store dimension discovered in step 1, breakdown by `store_dimension.<id>` to compare regions, brands, or sales channels.

    5. **Full funnel analysis**: For each funnel step, query `session_conversion_rate` with the analysis period. Calculate the step-to-step conversion rates:

        | Funnel Step | Event | Metric |
        |---|---|---|
        | Sessions | (no event filter) | `sessions` |
        | Product View | `Viewed Product` | `session_conversion_rate` |
        | Add to Cart | `Added To Cart` | `session_conversion_rate` |
        | Checkout Start | `Started Checkout` | `session_conversion_rate` |
        | Purchase | `Placed Order` | `session_conversion_rate` |

        Then derive step-to-step drop-off rates:
        - Session -> Product View rate
        - Product View -> Add to Cart rate
        - Add to Cart -> Checkout Start rate
        - Checkout Start -> Purchase rate

        Identify the **biggest leak** (lowest step-to-step conversion rate).

        Repeat the funnel analysis broken down by `touchpoint.channel_group` to see if certain channels have weaker funnel performance.

        Cross-reference funnel drop-offs with `bounce_rate` and `session_duration` to diagnose engagement issues.

    6. **New customer acquisition**: Query `New Customer Order` / `events`, `New Customer Order` / `cpa`, `New Customer Order` / `session_conversion_rate` for both periods. Break down by `touchpoint.channel_group` to find the most efficient acquisition channels.

    7. **Attribution comparison**: Run the top-line CVR and revenue query under two attribution models (e.g. `last_touch_paid` and `linear`) with `mode: "click_time"` to show how channel credit shifts under different models.

    8. **Synthesise findings and recommendations**: Using all data gathered, produce the report below.

    ---

    ## Report Structure

    ### Conversion Rate Analysis
    Period: [analysis period dates] vs [comparison period dates]


    #### 1. Executive Summary
    * 2--3 sentences summarising the headline CVR, direction of trend, and the single biggest opportunity. Example: "Session CVR is 2.1% over the last 60 days, up 0.3 pp vs the prior period. The biggest funnel leak is Checkout Start -> Purchase at 38% step conversion. Paid Social drives the most sessions but converts 40% below the site average."

    #### 2. Overall Conversion Performance (table)

    | Metric | Analysis Period | Comparison Period | Change |
    |---|---|---|---|
    | Sessions | | | 🟢/🟡/🔴 +X% |
    | Placed Orders | | | |
    | Session CVR | | | |
    | Revenue | | | |
    | Avg Revenue / Session | | | |
    | New Customer Orders | | | |
    | New Customer CVR | | | |

    *Weekly trend chart data included below.*

    #### 3. Weekly CVR Trend (table)
    * Session CVR and Orders by week across the analysis period. Flag any weeks with unusual spikes or drops, noting possible causes (promotions, seasonality, platform changes).

    #### 4. Conversion by Segment

    **a. By Landing Page (top 10)** -- sorted by sessions descending. Flag pages with high traffic but below-average CVR as optimisation targets.

    | Landing Page | Sessions | Bounce Rate | Avg Duration | CVR | Revenue |
    |---|---|---|---|---|---|

    **b. By Channel Group** -- highlight top 3 and bottom 3 by CVR.

    | Channel Group | Sessions | CVR | Orders | Revenue | Bounce Rate | CPA | ROAS |
    |---|---|---|---|---|---|---|---|

    **c. By Channel (granular)** -- top 10 by session volume. Flag any converting >50% above/below site average.

    **d. New vs Returning Visitors**

    | Segment | Sessions | Share | CVR | Revenue |
    |---|---|---|---|---|
    | New Visitors | | | | |
    | All Visitors | | | | |

    #### 5. Full Funnel Analysis

    | Step | Bar | Session Rate | Step-to-Step Rate | Drop-off |
    |---|---|---|---|---|
    | Product View | `██████████ X%` | | -- | -- |
    | Add to Cart | `███████░░░ X%` | | | |
    | Checkout Start | `█████░░░░░ X%` | | | |
    | Purchase | `███░░░░░░░ X%` | | | |

    Scale bars proportionally to the highest step. Use 🔴 on the step with the largest drop-off.

    **Biggest leak**: [step with lowest step-to-step rate]. Note if it correlates with high bounce rate or low session duration from specific sources. Show step-to-step rates for the top 3 channel groups by volume.

    #### 6. New Customer Acquisition

    | Channel Group | NC Orders | NC CPA | NC CVR | Share of NC Orders |
    |---|---|---|---|---|

    Identify the most cost-efficient acquisition channel.

    #### 7. Attribution View (if applicable)

    | Channel | Last Touch Paid Revenue | Linear Revenue | Shift |
    |---|---|---|---|

    Note channels that gain or lose significant credit under different models.

    #### 8. CRO Recommendations (10, prioritised)

    **Quick Wins (<1 week):** 1. Fix biggest funnel leak 2. Optimise highest-traffic, lowest-CVR landing page 3. Address worst-converting high-spend channel

    **Medium-term Tests (2--4 weeks):** 4. Checkout flow optimisation 5. Landing page A/B tests 6. New visitor experience improvements

    **Major Initiatives (1--3 months):** 7. Channel mix rebalancing 8. Attribution-informed budget reallocation 9. New customer acquisition strategy 10. Landing page optimisation for high-traffic, low-CVR pages

    *Each recommendation must cite the specific data point that justifies it.*

    #### 9. Revenue Impact Forecast

    Estimate monthly revenue lift for: fixing biggest funnel leak, lifting bottom 3 channels to site-average CVR, and improving new visitor CVR by 20%. Show arithmetic: `sessions x CVR x AOV = revenue`, then delta. State the total addressable opportunity.

    ---

    Based on data from Converge (runconverge.com), generated [today's date] at [current time].
    Analysis period: [dates]. Comparison period: [dates].
    Attribution basis: [model and window used, or "direct_session (no MTA)" if default].

    ---

    ## Style & Output Rules

    * Use tables for all quantitative sections; limit prose to summaries and anomaly callouts.
    * No placeholders -- every number must come from actual tool results.
    * Always label the attribution model and window for any metric that depends on attribution (CPA, ROAS, revenue by channel).
    * Double-check that percentage changes match the raw numbers shown.
    * Revenue impact forecasts must show the full arithmetic so the reader can verify.
    * Recommendations must cite specific data points from the analysis -- no generic advice.
    * If a breakdown is not available in Converge (e.g. device type, geography), state this clearly and suggest the user check Google Analytics or their analytics platform for that dimension.

    ### Visual formatting

    * **Traffic-light indicators**: In every table that has a Change or Direction column, prefix the value with 🟢 (positive / on-track), 🟡 (flat / marginal), or 🔴 (negative / needs attention). Example: `🟢 +12%`, `🔴 −8%`.
    * **Funnel visualization**: In the Full Funnel Analysis section, render a proportional bar next to each step using block characters (e.g. `████████░░ 82%`). Scale bars relative to the highest step so drop-offs are immediately visible.
    * **Bold key numbers**: In the Executive Summary and Anomalies sections, **bold** the 3--5 most important numbers so they stand out on a quick scan.
    * **Rank badges**: In channel and landing page tables, prefix the top 3 rows with 🥇 🥈 🥉 to highlight top performers at a glance.

    ---

    ## Converge MCP Tools Reference

    | Tool | When to use |
    |---|---|
    | `list_workspaces` | First call -- get workspace_id, currency, timezone, start_of_week |
    | `list_metric_event_names` | Discover valid event names for the workspace before querying |
    | `list_store_dimensions` | Discover region/brand/channel dimensions for segmentation |
    | `analytics_query` | All custom analytics queries (metrics, filters, breakdowns, attribution) |
    ```
  </Accordion>

  <Accordion title="Pacing report">
    ```text theme={null}
    Purpose: Generate a live pacing report of an eCommerce business using Converge analytics data with hourly granularity. Audience: Marketing and leadership team. Output must be professional, concise, and actionable.

    ---

    ## Expert knowledge you have

    * Converge is a multi-touch marketing attribution platform for DTC brands. It tracks conversion events from the website and pulls in aggregated marketing performance from ad platforms (Facebook Ads, Google Ads, TikTok, Pinterest, Bing, etc.). You can compare channels or campaigns by combining event and ad platform metrics with a touchpoint breakdown.
    * Key event metrics you can query:
        * `events` (count), `sessions`, `profiles`
        * `revenue` (total revenue for the event)
        * `session_conversion_rate`, `profile_conversion_rate`
        * `bounce_rate`, `session_duration`, `session_revenue`
        * `new_visitor_sessions`, `new_visitor_sessions_rate`
        * `cpa` (cost per acquisition = spend / events), `roas` (return on ad spend = revenue / spend), `acos` (ad cost of sales = spend / revenue)
    * Key ad platform metrics (platform-reported):
        * `spend`, `clicks`, `impressions`
        * `cpc`, `cpm`, `ctr`
        * `ad_conversions`, `ad_revenue`, `ad_roas`, `ad_cpa`, `ad_acos`
    * Standard conversion events: `$page_load`, `Viewed Product`, `Added To Cart`, `Started Checkout`, `Placed Order`, `New Customer Order`.
    * `New Customer Order` fires on a profile's first-ever `Placed Order` -- use this for new customer metrics.
    * Platform-reported data (`ad_conversions`, `ad_revenue`, `ad_roas`) can double-count conversions across platforms. Converge attribution uses multi-touch models to avoid this.
    * Recently launched campaigns may have unstable or insignificant performance if still in learning phase.
    * To analyse ad creative performance, use `analytics_query` with ad platform metrics broken down by `touchpoint.ad`.
    * Multi-touch attribution (MTA) models available: `first_touch`, `last_touch`, `linear`, `first_touch_paid`, `last_touch_paid`, `top_of_funnel`, `time_decay`, `u_shaped`, `j_shaped`, and more. Default is `direct_session` (no MTA).
    * Attribution `mode` can be `click_time` or `conversion_time`. Click-time is better for evaluating spend efficiency (CPA, ROAS).

    ---

    ## Process

    1. **Define the reporting periods**: Check the current date and time. Today is the reporting day (`since: 'dStart'`, `until: null`). Determine the current hour H. Query the full day for yesterday and same day last week, but only compare hours up to H for a fair comparison. State the date and current hour to the user.

    2. **Discover the workspace**: Call `list_workspaces` to find the workspace. Note the workspace's currency, timezone, and start_of_week -- pass these to all subsequent tool calls.

    3. **Gather today's data** using `analytics_query`:

        - **Topline with hourly trend**: Orders (`Placed Order` / `events`), Blended CVR (`Placed Order` / `session_conversion_rate`), NC-CPA (`New Customer Order` / `cpa`), Total Spend (`spend`). Also query `spend` filtered to Google (`touchpoint.channel` = `Paid Search/google`) and Facebook (`touchpoint.channel` = `Paid Social/facebook`). Use `time_granularity: "hour"` and `since: "dStart"` to get the hourly breakdown for today.

        - **Comparison windows**: Query the same metrics with `time_granularity: "hour"` for yesterday (`since: "1d"`, `until: "dStart"`) and same day last week (`since: "7d"`, `until: "6d"`). Then sum only the hours up to the current hour H so you compare the same partial window (midnight--H) across all three days.

    4. **Check for anomalies**: Compare today's totals through hour H against the same partial window for yesterday and same day last week. Flag any metric that deviates materially from both comparisons.

    ---

    ## Report Structure

    ### Pacing Report
    Date: [today's date], as of [current hour]

    #### 1. Headline
    * 1--2 sentences summarizing today so far. Example: "Revenue $14.2k through 2pm, +8% vs yesterday at the same hour. Spend tracking in line, blended ROAS at 3.1x."

    #### 2. Topline KPIs (table)

    | Metric | Today (to hour H) | Yesterday (to hour H) | Same Day Last Week (to hour H) | vs Yesterday | vs Last Week |
    |---|---|---|---|---|---|
    | Orders | | | | | |
    | Blended CVR | | | | | |
    | Blended NC-CPA | | | | | |
    | Total Spend | | | | | |
    | Google Spend | | | | | |
    | Facebook Spend | | | | | |

    *All comparisons use the same partial window (midnight to current hour H) for a fair hour-to-hour comparison.*

    #### 3. Hourly Trend (table)
    * Revenue and Orders by hour for today. Highlight any hours with unusual spikes or drops.

    #### 4. Anomalies & Action Items
    * Flag metrics pacing >15% above or below both yesterday and same day last week with a brief hypothesis.
    * 1--2 suggested actions if applicable. Example: "Facebook spend pacing 30% above yesterday with flat ROAS -- check if new campaign launched or budget cap was raised."

    ---

    Based on data from Converge (runconverge.com), generated [today's date] at [current time]
    Reporting day: [today], data through hour [H]. Comparison: same partial window (midnight--H) for yesterday and same day last week.
    Attribution basis: [model and window used, if applicable].

    ---

    ## Style & Output Rules

    * Keep the report to half a page -- this is a live check-in, not a deep dive.
    * Use tables for KPIs; limit commentary to anomalies and actions.
    * No placeholders -- every number must come from actual tool results.
    * Always label attribution basis for metrics.
    * Double-check that percentage changes match the raw numbers shown.

    ---

    ## Converge MCP Tools Reference

    | Tool | When to use |
    |---|---|
    | `list_workspaces` | First call -- get workspace_id, currency, timezone, start_of_week |
    | `analytics_query` | All custom analytics queries (metrics, filters, breakdowns, attribution) |
    ```
  </Accordion>
</AccordionGroup>


# Routines
Source: https://docs.runconverge.com/mcp/routines

Schedule recurring analytics reports delivered to Slack or email.

Routines let you run a prompt on a recurring basis and have the result delivered straight to Slack or your inbox. Behind the scenes, each routine uses the [Converge MCP](/mcp/overview) to pull live data from your workspace, so the output reflects the latest numbers every time it runs.

Use routines for things like:

* A daily performance snapshot with revenue, orders, ad spend, and blended ROAS broken down by channel group.
* A weekly "scale or kill" review of your top Meta ads, with NC ROAS and a recommended action per ad.
* A weekly head-to-head comparing Paid Social vs Paid Search efficiency on new customer acquisition.
* A weekly site health check covering visitors, session conversion rate, and AOV, flagging any day that fell off pace.

<Info>
  If you need an in-depth analysis, connect the [Converge MCP](/mcp/overview) to your AI of choice and chat with it directly.
</Info>

## How it works

A routine has three parts:

1. **Prompt**: Describes what data to pull and how to format the result. The MCP is invoked automatically to fetch the data from your Converge workspace.
2. **Schedule**: Daily or weekly, at a time you choose.
3. **Delivery**: A Slack channel or one or more email addresses.

Routines aim to run at the scheduled time, but delivery can lag by up to 10 minutes while we wait on the AI's response.

<Note>
  Routines always produce a response on every scheduled run. If you only want a notification when a metric crosses a specific threshold, you'll need to evaluate the output yourself. Native threshold-based alerting is not supported yet.
</Note>

## Connect Slack

Slack connects once for the whole workspace, not per routine. A workspace admin connects it under [Settings → Integrations](/settings/integrations/slack), and from then on every routine can deliver to it. See [Slack](/settings/integrations/slack) for setup and how to manage the connection.

## Create a routine

1. From the sidebar, open [**Routines**](https://app.runconverge.com/-/routines) and click **New routine**.
2. Give the routine a name, e.g. `Daily revenue summary`.
3. Write a **prompt** that describes the routine. Be specific about the metrics, time range, comparison period, and output format. See [writing good prompts](#writing-good-prompts) below.
4. Set the **schedule**: daily or weekly, and the time of day.
5. Choose a **delivery** method:

   * **Slack**: Pick a channel. Slack connects once for the whole workspace, see [Connect Slack](#connect-slack) above.
   * **Email**: Add one or more recipients.

   <Note>
     For Slack, add the converge bot to the channel before it can post. Type `@converge`, send the message, and click **Add to Channel**. Private channels won't appear in the channel dropdown until the bot's been added. See [add the bot to a channel](/settings/integrations/slack#add-the-bot-to-a-channel). Use **Send test message** to confirm it's working.
   </Note>
6. Click **Save**. You can run the routine once with **Run now** to verify the output before it goes live, this can take several minutes to finish.

## Writing good prompts

Routines are best for short, scannable updates that land in Slack or email, think snapshots and recaps, not deep dives. The prompt runs without any human in the loop, so it needs to be self-contained. A few tips:

* **Keep the scope tight.** Ask for a handful of metrics and one comparison, not a full-funnel analysis. *"Yesterday's revenue, orders, and conversion rate, compared to the same day last week."*
* **Specify the output format.** Tell the model how to structure the result. For Slack, ask for short Markdown with bullets and bold metric names. For email, ask for an HTML table.
* **Set length constraints.** Long messages get truncated in Slack and skimmed in email. *"Keep it under 300 words"* goes a long way.
* **Spell out comparisons.** If you want week-over-week or month-over-month changes, say so explicitly.

<Note>
  For more advanced setups, custom triggers, multi-step workflows, or destinations beyond Slack and email, see [automate workflows](/mcp/automate-workflows) for n8n, Zapier, and Claude Cowork patterns.
</Note>

## Related

* [Converge MCP overview](/mcp/overview): The full list of tools available to routines.
* [Automate workflows](/mcp/automate-workflows): Build more advanced automations with n8n, Zapier, or Claude Cowork.


# Setup
Source: https://docs.runconverge.com/mcp/setup

Connect the Converge MCP server to your AI assistant in under a minute.

Pull analytics data, compare performance, and ask follow-up questions without leaving the chat. See the [overview](/mcp/overview) for the full list of available tools and authentication details.

<Frame>
  <img alt="Chat with Converge data" />
</Frame>

## Prerequisites

* A [Converge](https://app.runconverge.com) account with access to at least one workspace.
* An MCP-compatible AI assistant: **Claude**, **Claude Code**, or **ChatGPT**.

## Install the Converge MCP server

<Tabs>
  <Tab title="Claude">
    Connect through Anthropic's web or desktop app at [claude.ai](https://claude.ai). Free accounts support only one custom connector; Pro or Team subscriptions allow adding more.

    <Steps>
      <Step title="Open Connectors settings">
        Open Claude and navigate to **Settings** > **Connectors**.
      </Step>

      <Step title="Add the Converge connector">
        Click **Add custom connector** and fill in:

        * **Name**: `Converge Analytics`
        * **URL**: `https://app.runconverge.com/api/mcp`
      </Step>

      <Step title="Authenticate">
        Start a new conversation and ask a question that triggers the Converge tools (e.g., *"List my Converge workspaces"*). A browser window opens for Google sign-in. Use the same Google account you use to access Converge.
      </Step>

      <Step title="Allow the Converge domain">
        Go to **Settings** > **Capabilities** and scroll to **Additional allowed domains**.
        Add `app.runconverge.com` to the list.

        <Frame>
          <img alt="Adding the Converge domain" />
        </Frame>

        <Note>
          This lets the AI agent download content directly from Converge servers, which saves tokens, uses less context, and makes queries faster.
        </Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    <Note>
      Claude Code is Anthropic's agentic coding tool that runs in your terminal or
      as an IDE extension. If you're using Claude at [claude.ai](https://claude.ai),
      use the **Claude** tab instead.
    </Note>

    <Steps>
      <Step title="Add the MCP server">
        Run the following in your terminal:

        ```bash theme={null}
        claude mcp add -t http -s user Converge "https://app.runconverge.com/api/mcp"
        ```
      </Step>

      <Step title="Start Claude Code">
        ```bash theme={null}
        claude
        ```
      </Step>

      <Step title="Authenticate">
        Inside the Claude Code session, run `/mcp` to trigger the authentication flow. A browser window opens for Google sign-in. Use the same Google account you use to access Converge.
      </Step>
    </Steps>
  </Tab>

  <Tab title="ChatGPT">
    Connect through OpenAI's web or desktop app at [chatgpt.com](https://chatgpt.com). Requires a Pro, Plus, or Team subscription.

    <Steps>
      <Step title="Enable Developer Mode">
        Open ChatGPT and navigate to **Settings** > **Advanced Settings** and toggle **Developer Mode** on. Requires a ChatGPT Pro, Plus, or Team subscription.
      </Step>

      <Step title="Add the Converge connector">
        Go to **Settings** > **Apps & Connectors** and click **Create**. Fill in:

        * **Connector name**: `Converge Analytics`
        * **Description**: `Query your Converge analytics data`
        * **Connector URL**: `https://app.runconverge.com/api/mcp`
      </Step>

      <Step title="Authenticate">
        Start a new conversation and ask a question that triggers the Converge tools (e.g., *"List my Converge workspaces"*). A browser window opens for Google sign-in. Use the same Google account you use to access Converge.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API Key">
    For MCP clients that don't support the interactive OAuth flow, authenticate with a personal API key instead.

    <Steps>
      <Step title="Create a personal API key">
        Go to [**Settings** > **Personal API Keys**](https://app.runconverge.com/-/settings/personal-api-keys) and click **Create personal API key**. Fill in a **Name**, pick an **Expiration**, then click **Create**.
      </Step>

      <Step title="Copy the key">
        Keys start with `cvg_` and are shown only once, so copy it somewhere safe right away. The key inherits your own access and sees the same workspaces and data you do.

        <Note>
          Treat it like a password and don't share it. You can revoke a key at any time from the same settings page.
        </Note>
      </Step>

      <Step title="Add the key to your MCP client">
        Pass the key as a bearer token in the `Authorization` header:

        ```
        Authorization: Bearer cvg_Q29udmVyZ2UgaXMgdGhlIGJlc3Q
        ```

        Most MCP clients have a dedicated field for this. Paste the key there and skip the OAuth flow entirely.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Verify the connection

Ask your AI assistant something like:

> *"List my Converge workspaces."*

You should see your workspace names returned. If your account has access to multiple workspaces, specify the one you want by name in your prompt (e.g., *"Show me last week's spend for **Acme US**"*).

## Try a query

Once connected, try one of these prompts:

* *"Break down this week's spend, new customer orders, and CPA by channel."*
* *"Show me campaign-level spend and ROAS for Facebook this week vs last week."*
* *"Which landing pages drove the most new customer orders this month?"*

See the [overview](/mcp/overview#available-tools) for the full list of available tools and query options.

## Next steps

<CardGroup>
  <Card title="Example prompts" href="/mcp/prompts" icon="circle-info">
    See example prompts and what you can ask your AI assistant.
  </Card>

  <Card title="Automate workflows" href="/mcp/automate-workflows" icon="clock-rotate-left">
    Schedule recurring reports with n8n, Zapier, or Claude Cowork.
  </Card>

  <Card title="Ask Claude in Slack" href="/mcp/ask-claude-in-slack" icon="slack">
    Query your analytics data by @mentioning Claude in any Slack channel.
  </Card>
</CardGroup>


# Slack
Source: https://docs.runconverge.com/settings/integrations/slack

Connect Slack once for your whole workspace so Converge can deliver reports to your channels.

Converge posts as the **converge** bot, never as you. Today, routines are the only feature that posts to Slack.

## How it works

The Slack connection is shared across your workspace. A workspace admin connects it once under [**Settings → Integrations**](https://app.runconverge.com/-/settings/workspace-integrations). After that, Converge can pick a channel and deliver through the same connection.

## Connect Slack

<Note>
  Only workspace admins can connect, reconnect, or disconnect Slack. If you're
  not an admin, ask one to set it up.
</Note>

<Steps>
  <Step title="Open the integration">
    Go to [**Settings →
    Integrations**](https://app.runconverge.com/-/settings/workspace-integrations),
    click **Add connection** and select **Slack**.
  </Step>

  <Step title="Add Converge to Slack">
    Click **Add to Slack** and authorize the app in your Slack workspace. Slack
    returns you to Converge once it's connected.
  </Step>
</Steps>

Slack bot tokens don't expire, so you connect once and the connection keeps working until it's revoked or disconnected.

## Add the bot to a channel

Connecting Slack installs the converge app in your workspace, but it can only post in channels it's a member of. After you connect, add the bot to each channel you want reports in.

1. Open the channel in Slack.
2. Type `@converge` and send the message.
3. Slack asks whether to add the bot. Depending on your Slack app, it shows a popup (like the one below) or prompts you right in the channel. Either way, choose **Add to Channel**.

<Frame>
  <img alt="Slack prompt to add the converge bot to a channel" />
</Frame>

Once the bot's a member, Converge can post there. Private channels won't appear until you've added the bot to it.

## What Converge can and can't do

When you connect, Converge asks Slack for permission to:

* **Post messages as the converge bot.** Deliver reports to the channels you pick. Messages come from Converge, not from you.
* **See your list of channels.** So Converge can choose where to post.
* **Read basic profile info.** To @mention the right teammates in a report.

Converge can't read your messages, files, or conversation history, and it only posts when a routine runs.

## Related

* [Routines](/mcp/routines): schedule reports and deliver them to Slack or email.


# Roles
Source: https://docs.runconverge.com/settings/roles

Learn about the available roles and their permissions

## Overview

Roles determine what actions users can perform within the platform. Each role has specific permissions that control access to features and settings.

## Available Roles

The platform offers four roles with different permission levels:

### Admin

**Description**: Full access to all features and settings.

Admins can:

* Manage workspace settings
* Access all data and analytics
* Configure sources and destinations
* Add and remove team members

### Editor

**Description**: Access to all features and settings, except removing members.

Editors can:

* Manage workspace settings
* Access all data and analytics
* Configure sources and destinations
* Invite new members with Editor role or lower
* Cannot remove team members

### Analyst

**Description**: Can only create insights and dashboards.

Analysts can:

* View all data and analytics
* Create and edit insights and dashboards
* Invite new members with Analyst role or lower
* Cannot modify workspace settings, sources or destinations

### Viewer

**Description**: Read-only access to features and settings without ability to make changes.

Viewers can:

* View data and dashboards
* Invite new members with Viewer role
* Cannot make changes to any settings or configurations

***

## Changing a User's Role

1. Navigate to the **Members** page using the sidebar.
2. Find the user whose role you want to change.
3. Click on the Edit icon for the user row.
4. Select the new role from the dropdown.
5. Click on **Save**.

***

## Best Practices

* Assign the Admin role only to users who need full administrative access
* Use Editor roles for team members who need to configure the platform but shouldn't manage users
* Assign Analyst roles to team members who work primarily with data and reports
* Use Viewer roles for stakeholders who only need to see results without making changes


# Workspace
Source: https://docs.runconverge.com/settings/workspace

Modify your workspace settings

## Timezone

<Note> Typically, you will want to pick the timezone of your Facebook Ads Manager or your local timezone. </Note>

1. Click on the **Settings**-button at the bottom of the sidebar.
2. Navigate to the **General**-subtab.
3. Click on the switch next to the **Timezone** form field.
4. Fill in the Timezone of your choice, e.g. `EST`.
5. Click on **Save**.
   <img alt="workspace timezone" />

***

## Currency

### How to modify your Workspace Currency

1. Click on the **Settings**-button at the bottom of the sidebar.
2. Navigate to the **General**-subtab.
3. Click on the **Currency** form field
4. Fill in the Currency of your choice, e.g. `United States dollar`.
5. Click on **Save**.
6. Navigate to the **Attribution** tab, you should see that the **Overview** tab now uses your desired currency.
   <img alt="workspace currency" />

<Note>Currency rates update every hour. If your events or ad platforms use a different currency than Converge, your results might be slightly off. </Note>

***

## Access

### How do I invite someone to my Workspace

<Note> Invitation links expire after 3 days and can only be used once. </Note>

1. Click on the **Members**-button at the bottom of the sidebar (under Settings).
2. Navigate to the **Invites**-subtab.
   <Frame>
     <img alt="invites-img" />
   </Frame>
3. Click on **Invite** to generate a new invite link
4. Send this link to the person who you want to give access to, they will receive access to your Workspace after logging in to Converge.

<br />

### How do I remove someone from my Workspace

1. Click on the **Members**-button at the bottom of the sidebar. You can now see everyone who has access.
   <Frame>
     <img alt="members-img" />
   </Frame>
2. Click on the <Icon name="trash" />-icon next to the user you want to remove.
3. Done.


# Aliases
Source: https://docs.runconverge.com/sources/concepts/aliases

Introduction to Aliases

## Introduction to Aliases

### Server-side tracking and stitching challenges

A common challenge with server-side tracking is **linking server-side conversions with their corresponding browser sessions**.

If conversions can't be tied to browser sessions, it results in several downstream issues:

* **Missing browser-side data** (e.g., cookies, IP addresses), leading to reduced ad performance and lower matching rates for [Destinations](/destinations/integrations/overview).
* **Inability to attribute conversions** properly.

```mermaid actions={false} theme={null}
flowchart LR
  id1("*Browser*<br/>Viewed Page") --> id2("*Browser*<br/>Started Checkout") -..- id3("*Server*<br/>Placed Order") ~~~ id4(["**Unstitched** ⚠️ "])
  style id4 stroke:none
```

Converge resolves this issue through the use of **aliases**.

<Warning>If your website uses caching, make sure your aliases aren’t cached. Cached aliases can cause stitching issues that seriously impact your analytics and tracking in Converge.</Warning>

### What are aliases?

An **alias** is a unique identifier for a profile across different data sources.

To address the stitching issue, you can pass a `checkout_token` alias in both the browser-side **Started Checkout** event and the server-side **Placed Order** event. This enables Converge to recognize that both events belong to the same profile and session.

```mermaid actions={false} theme={null}
flowchart LR
  id1("*Browser*<br/>Viewed Page") --> id2("*Browser*<br/>Started Checkout<br/>**alias=checkout_token_xyz**") --> id3("*Server*<br/>Placed Order<br/>**alias=checkout_token_xyz**") ~~~ id4(["**Stitched** ✓ "])
  style id4 stroke:none
```

Aliases are primarily used to **link server-side conversions with browser sessions**, but they can also merge profiles across different websites, browsers, or devices.

In [Converge JS](/sources/website-integrations/converge-pixel), the customer's browser session cookie is used as the default alias. Additionally, Converge provides a set of default aliases for its integrations.

<Accordion title="Code Examples" icon="code">
  <CodeGroup>
    ```javascript Converge Pixel - Javascript theme={null}
    cvg({
      method: "track",
      eventName: "Subscribed To Newsletter",
      properties: {},
      profileProperties: {},
      aliases: ["urn:email:john.smith@apple.com"],
    });
    ```

    ```python Converge Webhook - Python theme={null}
    resp = requests.post(
        "{YOUR_POSTBACK_ENDPOINT}",
        json=
            {
            "event_name": "Subscribed To Newsletter",
            "properties": {},
            "profile_properties": {},
            "aliases": ["urn:email:john.smith@apple.com"],
        }
    )
    ```

    ```javascript Converge Pixel - Shopify Cart Token theme={null}
    cvg({
      method: "track",
      eventName: "Added To Cart",
      properties: {
        product_id: "123456",
        variant_id: "78910",
        sku: "MY_SKU",
        name: "My Product",
        variant_name: "Vanilla",
        price: 42,
        currency: "USD",
        quantity: 1,
        vendor: "My Store",
      },
      aliases: ["urn:shopify:cart_token:Z2NwLWV1cm9wZS13..."]
    });
    ```
  </CodeGroup>
</Accordion>

### What aliases should I pass?

The exact aliases you choose depend on your specific customer journey. Commonly used aliases are:

* **Cart Token** (e.g., `urn:cart_token:123xyz`): can be used to stitch a checkout on a different domain with the storefront session, or to stitch a server-side purchase to a website session.
* **Checkout Token** (e.g., `urn:checkout_token:456abc`): can be used to stitch a checkout on a different domain with the storefront session, or to stitch a server-side purchase to a website session.
* **Email** (e.g., `urn:email:john.smith@apple.com`): can be used to stitch a server-side order to a checkout session.
* **User ID** (e.g., `urn:user_id:123456`): can be used to stitch a server-side order to a website session.

There are two main guidelines for choosing aliases:

1. **Aim for redundancy**: Client-side events have no guarantee of being tracked, meaning that if the stitching of your customer journey depends on a single browser event and this browser event is missed, your server-side conversion won't be stitched correctly.
2. **As early in the customer journey as possible**: If your stitching alias is too late in the journey, then you run the risk that the server-side `Placed Order` event is received in Converge before the client-side event with the stitching alias has been received. As such, a `cart_token` you can pick up early in the journey is a much more reliable alias than an `email` property you receive very late in the journey.

#### Example

If you have a customer journey that looks like this:

```mermaid actions={false} theme={null}
flowchart LR
  id1("*Browser*<br/>Viewed Page") --> id2("*Browser*<br/>Added To Cart") --> id3("*Browser*<br/>Started Checkout") --> id4("*Browser*<br/>Added Payment Info") --> id5("*Server*<br/>Placed Order")
```

Then an optimal stitching setup would look something like:

```mermaid actions={false} theme={null}
flowchart LR
  id1("*Browser*<br/>Viewed Page") --> id2("*Browser*<br/>Added To Cart<br/>**alias=cart_token_xyz**") --> id3("*Browser*<br/>Started Checkout<br/>**alias=checkout_token_123**") --> id4("*Browser*<br/>Added Payment Info<br/>**alias=john&#64;smith.com**") --> id5("*Server*<br/>Placed Order<br/>**alias=cart_token_xyz**<br/>**alias=checkout_token_123**<br/>**alias=john&#64;smith.com**")
```

Note that:

1. There are multiple stitching identifiers on the browser events in the customer journey to stitch the server-side `Placed Order` to the corresponding website session.
2. Stitching identifiers are available early in the customer journey, ensuring that client-side events with relevant aliases will arrive before the server-side `Placed Order` event.

### Aliases vs Profile Properties

Note that [aliases](/sources/concepts/aliases) and [profile properties](/sources/concepts/profile-properties) are two different things.

Profile properties persist across events but **aren't necessarily unique** across profiles.

As an example, `$first_name` is a clear profile property (it persists across events) yet it doesn't uniquely define this profile so it wouldn't be a correct alias.

***

## Aliases for re-identification

### Default cookie behavior

Many browsers wipe all third-party cookies and all cookies that are set browser-side through JavaScript.
For example, **Safari will wipe all of those cookies after 7 days**.

This significantly impacts the accuracy of multitouch attribution.
Observe in the graph below how a customer who comes to your site in an interval longer than 8 days can't be re-identified.

```mermaid actions={false} theme={null}
flowchart LR
  id1("*User* visits website<br/>with cookie **X**") -. 5 days later .-> id2("*User* visits website<br/>with cookie **X**") ~~~ id3(["**Re-identified**  ✓ "])
  style id3 stroke:none


  id4("*User* visits website<br/>with cookie **X**") -. 8 days later (cookie is lost).-> id5("*User* visits website<br/>with cookie **Y**") ~~~ id6(["**Not re-identified** ✖ "])
  style id6 stroke:none

```

For a full list of browsers and their cookie lifetimes, see <OutboundLink />

### Server-side first-party cookies

The reliable way to re-identify users over longer periods of time is through **server-side first-party cookies**.
As illustrated in the graph below, these do reliably re-identify users.

```mermaid actions={false} theme={null}
flowchart LR
  id1("*User* visits website<br/>with server-side cookie **X**") -. up to 365 days later .-> id2("*User* visits website<br/>with server-side cookie **X**") ~~~ id3(["**Re-identified**  ✓ "])
  style id3 color:#02b802,stroke:none

```

### Leveraging server-side first-party cookies within Converge

By using a server-side first-party cookie as an **alias**, Converge can:

1. **Reliably re-identify your customers for multitouch attribution**. This is especially important for brands where the buying cycle is longer than the cookie lifetime of 7 days.
2. **Extend the lifetime of third-party cookies**: Converge stores third-party cookies that are relevant for your destinations in its <OutboundLink />. Converge can then retrieve these third-party cookies when it recognizes a customer after the 7-day period.

***

## Setting up a server-side first-party cookie

If you are using one of the Converge prebuilt integrations (e.g. for Shopify) then you are likely already using a server-side first-party cookie.
Check out your specific integration documentation to verify.

If you are integrating [Converge JS](/sources/website-integrations/converge-pixel) on your website, then you will need to implement this directly yourself.

### Installation instructions

<AccordionGroup>
  <Accordion title="Set up a first-party server-side cookie" icon="server">
    We provide a minimal code example below for Node.js, but any server web framework should be able to handle server-side cookies.

    <CodeGroup>
      ```js Node.JS Server theme={null}
       // server.js

       const express = require('express');
       const cookieParser = require('cookie-parser');
       const uuid = require('uuid');

       const app = express();
       const PORT = 3000;

       app.use(cookieParser());

       // Middleware to generate and set unique visitor cookie if not already set
       app.use((req, res, next) => {
       if (!req.cookies.visitorId) {
           const visitorId = uuid.v4(); // Generate a unique visitor ID
           res.cookie('mystore_uid', visitorId, { maxAge: 365 * 24 * 60 * 60 * 1000, httpOnly: true });
       }
       next();
       });

       // Route to serve Next.js application
       app.use('/', require('./frontend'));

       app.listen(PORT, () => {
       console.log(`Server is running on port ${PORT}`);
       });
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Pass the cookie as an alias in all of your client-side ConvergeJS calls" icon="cookie">
    Modify the code where you set up the `page_load` to include the cookie you set up above as an `alias`.
    We provide an example for Next.js, but this should be straightforwardly implemented in any framework.

    ```js NextJS theme={null}
    import { useEffect } from "react";
    import Cookies from 'js-cookie';

    const MyApp = ({ Component, pageProps, router }) => {
    useEffect(() => {
        const visitorId = Cookies.get('mystore_uid');
        const handleRouteChange = (url) => {
        cvg({method: "track", eventName: "$page_load", aliases: [`urn:mystore_uid:${visitorId}`]})
        };
        router.events.on("routeChangeComplete", handleRouteChange);
        return () => {
        router.events.off("routeChangeComplete", handleRouteChange);
        };
    }, []);
    return <Component {...pageProps} />;
    };
    export default MyApp;
    ```
  </Accordion>
</AccordionGroup>

***


# Deduplication
Source: https://docs.runconverge.com/sources/concepts/deduplication

Introduction to Deduplication

Converge supports deduplication natively. You can deduplicate events with an optional `eventID` parameter. This is especially important for events that are used as conversions. Converge will deduplicate events with the same `eventID` at ingestion time.

The `eventID` will also be forwarded to your destinations for in-platform deduplication.

### Limitations of deduplication

Converge only supports deduplication within a single data source, for now.
If you track the same event across multiple data sources, these won't be deduplicated.


# New customer status
Source: https://docs.runconverge.com/sources/concepts/new-customer-status

How Converge determines whether a Placed Order is a first-time purchase, and how to instrument $is_new_customer correctly

The `$is_new_customer` property on the `Placed Order` event tells Converge whether the order is a customer's first purchase. It powers the `New Customer Order` [derived event](/sources/extending-the-spec/derived-events), the `NewCustomerPurchase` events forwarded to Meta, TikTok, and Reddit, and the `customer_type` (`NEW` vs. `RETURNING`) field on server-side Google Ads conversions.

## What "new customer" means

A new customer is a profile whose **current `Placed Order` is their first completed purchase from your store**. It isn't about whether the customer just registered an account, signed up for a newsletter, or is visiting for the first time. The only question is: have they bought from you before?

That definition lives on the order, not the profile. A profile that was created last year but only places its first order today is a new customer on today's order. From the next order onward, it isn't.

## Who sets the value

There are two paths, and they behave differently.

### Prebuilt integrations: Converge sets it for you

If your `Placed Order` events come in through a prebuilt source like Shopify, BigCommerce, WooCommerce, or Firmhouse, Converge sets `$is_new_customer` automatically using the platform's native new-customer signal.

### Custom integrations: you set it

If you send `Placed Order` from a custom server-side webhook, a custom mobile app, or any source Converge doesn't have a native integration for, **you're the one responsible for setting `$is_new_customer`**. Your backend has authoritative order history.

## How Converge fills it in if you don't

If a `Placed Order` arrives without `$is_new_customer`, Converge falls back to its own history. It looks for prior `Placed Order` events on the same profile, matched on email. If a prior order exists, the customer is marked as returning. If not, they're marked as new.

This fallback is only as accurate as the history Converge has on file. Two situations can commonly come up:

* **Short historical sync windows.** If your prebuilt source was created with a start date that doesn't cover the customer's first order, that first order isn't in Converge. A customer who bought in 2023 from a source synced from 2024 onward will look new on their next order.
* **Identity changes.** The fallback matches on email. A returning customer who places an order with a different email, a typo, or a separate account looks new to Converge, even though they aren't to you.

For these reasons, passing the value explicitly is always more reliable than relying on the fallback.

## Is the property required?

The spec marks `$is_new_customer` as required for the `Placed Order` event because passing it explicitly is the only way to get a reliable result. In practice, Converge won't reject a `Placed Order` event that omits it — the fallback above kicks in instead.

## Override rules

The rules for who wins between an explicit value and the fallback are simple:

* **If you pass a value, Converge uses it.** Passing `true` creates a `New Customer Order` event, even if Converge has seen that email before. Passing `false` doesn't, even if Converge has no prior history for that customer.
* **If you don't pass a value, Converge uses the fallback.**
* **Converge never overwrites a value you explicitly passed.** A common misconception, sometimes repeated by AI assistants, is that Converge recalculates `$is_new_customer` based on its own history regardless of what you send. It doesn't. The explicit value wins.

## A note on idempotency

Converge's tracking API is idempotent on `event_id`. The first request to land for a given `event_id` is the one Converge persists; any later request with the same `event_id` is treated as a duplicate and dropped. That means if you send a `Placed Order` with `$is_new_customer: false` and then a few seconds later send a corrected event with `$is_new_customer: true` using the same `event_id`, the corrected value is dropped. Make sure the first event you send for an order has the right value, or use a new `event_id` if you genuinely need to record a new event.

See [deduplication](/sources/concepts/deduplication) for the full picture.

## Quick reference

| Situation                                              | What happens                                                                          |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| Prebuilt source (Shopify, BigCommerce, WooCommerce, …) | Converge sets `$is_new_customer` from the platform's native signal.                   |
| Custom source, value passed                            | Converge uses your value as-is. Always.                                               |
| Custom source, value omitted                           | Converge falls back to its own order history, matched on email and other identifiers. |
| Same `event_id` resent with a corrected value          | Dropped as a duplicate. The first event wins.                                         |

## Related

* [Placed Order spec](/sources/converge-spec#placed-order)
* [Derived events](/sources/extending-the-spec/derived-events)
* [Aliases](/sources/concepts/aliases)
* [Deduplication](/sources/concepts/deduplication)


# Overview
Source: https://docs.runconverge.com/sources/concepts/overview

Introduction to the Converge Source concepts

A handful of concepts shape how Converge turns raw events into clean, unified data. This section introduces each one. You don't have to configure most of them, but understanding them makes it much easier to reason about your setup and debug it.

## An introductory example

Imagine an ecommerce store that has the following minimal customer journey:

1. **Viewed Page**: User visits the storefront
2. **Added To Cart**: User adds an item to cart
3. **Placed Order**: User places an order

For the optimal setup, they will want to track `Viewed Page` and `Added To Cart` on the browser, but `Placed Order` events on <Tooltip> the server</Tooltip>.

### Challenges with server-side tracking

Tracking the `Placed Order` on the server is more reliable, but it introduces three challenges, each of which maps to a core Converge concept.

* <OutboundLink />: to recognize which browser-side events and which server-side events come from the same user.
* <OutboundLink />: to store browser-side information about a user so it's available later.
* <OutboundLink />: to make sure that the same order doesn't get processed twice.

## The concepts

### Aliases

An <OutboundLink /> is a unique identifier for a profile across data sources. Aliases are how Converge stitches a server-side order back to the browser session it came from, and how it re-identifies returning customers over time.

### Profile properties

<OutboundLink /> are characteristics of a user, like email or user agent, that persist across events rather than belonging to a single event.

### Server-side enrichment

<OutboundLink /> is how Converge automatically adds stored profile data to a stitched server-side event, so a sparse order event inherits the browser context destinations need to match it.

### Deduplication

<OutboundLink /> ensures an event tracked in more than one place, such as a `Placed Order` seen on both the browser and the server, is only counted once.

### Sales channels

<OutboundLink /> classify each event by its tracking context, such as web, subscription, or POS. This keeps stitching and deduplication rates accurate by only applying them where they make sense.

### New customer status

<OutboundLink /> determines whether a `Placed Order` is a customer's first purchase, via the `$is_new_customer` property. It powers the `New Customer Order` event and new-customer reporting at your destinations.


# Profile Properties
Source: https://docs.runconverge.com/sources/concepts/profile-properties

Introduction to Profile Properties

It is possible to include **profile properties** in an event. These properties are characteristic of the user. These properties are **persisted across events**, whereas the event properties are only available and relevant to the event itself.

Profile Properties allow you to store information on a user that you might need later.
For example, the Converge Pixel will [auto-track](/sources/converge-spec#page-load) several browser session information, so this is available for your server-side events (e.g., the `Placed Order` event).

However, profile properties are also useful for storing information across events *within* a single source.
Imagine a user that triggers a `Subscribed To Newsletter` event with an `$email` parameter. Afterward, that same user triggers an `Added To Cart` event.
Storing the `$email` as a profile property ensures that you have this information available at the moment of the `Added To Cart` event without you as a developer having to pass it again.

<Accordion title="Code Examples" icon="code">
  <CodeGroup>
    ```javascript Converge Pixel - Javascript theme={null}
    cvg({
      method: "track",
      eventName: "Subscribed To Newsletter",
      properties: {
        formId: "your-form-id",
      },
      profileProperties: {
        $email: "john.smith@apple.com",
        $first_name: "John",
        $last_name: "Smith",
        $phone_number: "+199999999",
      },
    });
    ```

    ```python Converge Webhook - Python theme={null}
    resp = requests.post(
        "{YOUR_POSTBACK_ENDPOINT}",
        json=
            {
            "event_name": "Subscribed To Newsletter",
            "properties": {
              "formId": "your-form-id",
            },
            "profile_properties": {
                "$email": "john.smith@apple.com",
                "$first_name": "John",
                "$last_name": "Smith",
                "$phone_number": "+199999999",

            }
        }
    )

    ```
  </CodeGroup>
</Accordion>


# Sales Channels
Source: https://docs.runconverge.com/sources/concepts/sales-channels

Introduction to sales channels

Sales channels categorize individual events based on their specific tracking context, such as browser, mobile application, or POS.
This classification doesn't impact how [stitching](/sources/concepts/aliases) or [deduplication](/sources/concepts/deduplication) are performed but rather ensures that any insights and warnings are increasingly accurate and aligned with the nature of each event.
By distinguishing these events through sales channel types, Converge can provide more precise insights into a healthy Converge setup and highlight any areas of concern.

#### Example 1: Browser and Server "Placed Order" Event

```mermaid actions={false} theme={null}
flowchart LR
  A("*Browser*<br/>Viewed Page") --> B("*Browser*<br/>Started Checkout") --> C("*Browser*<br/>Placed Order") -..- D("*Server*<br/>Placed Order") ~~~ E["Deduplication and stitching<br/>applicable here"]
  style E stroke:none
```

In this example, a "Placed Order" event is initiated on the browser with a corresponding "Placed Order" event being received from a server-side data source.
We want concepts like deduplication and session stitching to be applicable and relevant here.
By categorizing both as "web," Converge can ensure that calculations and insights reflect a true picture of the setup without introducing irrelevant discrepancies from non-web sources where deduplication or stitching may not make sense.

#### Example 2: Subscriptions

```mermaid actions={false} theme={null}
flowchart LR
  A("*Browser*<br/>Started Subscription") -..-  B("*Server*<br/>Placed Order") -. 30 days later .-> C("*Server*<br/>Placed Recurring Subscription Order") ~~~ D["Deduplication and stitching<br/>**not** applicable here"]
  style D stroke:none
```

For this example, a "Started Subscription" event is captured on the browser, followed by a "Placed Order" event from the server side, indicating a successful subscription start. These events will be categorized as a "web" sales channel given the user web journey. However, thirty days later, the server sends Converge a "Placed Recurring Subscription Order." This event is categorized as a "subscription\_contract" sales channel because it's an automated event rather than a user-initiated event.

Since there are no corresponding browser interactions for the recurring subscription order, concepts like deduplication and session stitching aren't applicable or necessary in this scenario. By using a different sales channel from "web," such events aren't mistakenly associated with user actions, and deduplication and session stitching rates remain accurate.

## Supported sales channels

We support a number of sales channel types:

| Name           | Property Value         | Description                                                          |
| -------------- | ---------------------- | -------------------------------------------------------------------- |
| Web            | web                    | Events occurring via browser-based interactions and actions          |
| Subscriptions  | subscription\_contract | Automated events related to subscription renewals or contracts.      |
| SMS            | sms                    | Events or interactions triggered via SMS/Text communication.         |
| Mobile App     | mobile\_app            | User interactions occurring within mobile applications.              |
| POS            | pos                    | Point of Sale transactions taking place in physical stores.          |
| Marketplace    | marketplace            | Sales and interactions through third-party marketplaces like Amazon. |
| Offline        | offline                | Offline events such as amended orders, manual orders, or calls.      |
| Facebook Shop  | facebook\_shop         | Purchases and interactions through the Facebook Shop channels.       |
| Pinterest Shop | pinterest\_shop        | Sales and activity through the Pinterest Shop channels.              |
| TikTok Shop    | tiktok\_shop           | Orders and interactions made via the TikTok Shop channels.           |

## Implementation

Sales channels are introduced via an event's event properties using the `$sales_channel_type` property.
All events sent from the Converge pixel are categorized as a "web" sales channel type.
If an event is received by Converge from a server-side integration like Shopify, BigCommerce, Firmhouse, or WooCommerce, a mapping occurs.
Custom integrations like webhooks require manual instrumentation of the property.

<Note> By default, if `$sales_channel_type` isn't passed (e.g., custom integration), or a mapping can't be found (server integration), Converge defaults to "web". </Note>

<Warning> Make sure that the `$sales_channel_type` is the same for the web events and server-side event you are using for stitching. If not, the stitching rate in the Data Quality report won't be accurate. </Warning>

<CodeGroup>
  ```python Python - Server-side theme={null}
  resp = requests.post(
      "{YOUR_POSTBACK_ENDPOINT}",
      json=
          {
          "event_name": "Placed Order",
          "event_id": "order-1", # your order id, necessary for deduplication
          "properties": {
              # event properties
              "$sales_channel_type": "web",  # important, see supported sales channels
          },
          "profile_properties": {
              # Pass as many as possible
              "$first_name": "John",
              "$last_name": "Smith",
              "$email": "john.smith@apple.com",
              "$phone_number": "+199999999",
              "$city": "San Francisco",
              "$country_code": "US",
              "$state": "California",
              "$zip_code": "94103",
          },
          # important, this will be used for stitching backend orders to website sessions
          "aliases": ["urn:email:john.smith@apple.com"],
      }
  )
  ```
</CodeGroup>


# Server-side enrichment
Source: https://docs.runconverge.com/sources/concepts/server-side-enrichment

How Converge enriches server-side events with profile data

## What is server-side enrichment?

Server-side events are reliable but sparse. A `Placed Order` sent from your backend is guaranteed to fire for every purchase, but it arrives with almost none of the browser context that ad platforms and analytics tools need to match a conversion to a click.

**Enrichment** is how Converge fills that gap. Once a server-side event is stitched to a profile, Converge automatically adds everything it already knows about that profile to the event. A bare order event inherits the user's browser identifiers, click IDs, and attribution context, so the data you forward looks as if it had been tracked on the browser all along.

```mermaid actions={false} theme={null} theme={null}
flowchart LR
  id1("*Server*<br/>Placed Order<br/>order_id, value, email") --> id2{{"Converge<br/>enrichment"}} --> id3("*Enriched*<br/>Placed Order<br/>+ $fbp, $fbc<br/>+ IP, user agent<br/>+ landing page, UTMs")
  style id2 stroke:none
```

## Why it matters

A server-side conversion that can't be matched to a browser session causes the same downstream problems as an unstitched event:

* **Lower match rates** at your [destinations](/destinations/overview). Meta, Google, and others rely on identifiers like `fbp`, `fbc`, IP address, and user agent to attribute a conversion. Without them, the event is forwarded but poorly matched, which weakens optimization.
* **Missing attribution**. The order can't be tied to the campaign, landing page, or channel that drove it.

Enrichment solves both. Because the enriched event already carries browser-side identifiers, Converge can forward a high-quality conversion to every destination, even though the order itself was tracked on the server.

## How it works

Enrichment happens automatically at ingestion. There's nothing to configure, but it does depend on two other concepts: <OutboundLink /> (which stitch the event to a profile) and <OutboundLink /> (which supply the browser context that gets merged in).

<Steps>
  <Step title="The event is stitched to a profile">
    Converge uses the event's <OutboundLink /> to resolve which profile it belongs to. This is the prerequisite for enrichment: an event that can't be stitched has no profile to draw context from.
  </Step>

  <Step title="Stored profile data is merged in">
    Converge looks up the <OutboundLink /> collected earlier in the journey, mostly from browser events, and merges them onto the event.
  </Step>

  <Step title="The enriched event is forwarded">
    Each destination reads the identifiers it needs from the enriched event. For example, the Meta destination picks up `$fbp` and `$fbc` to raise its match quality.
  </Step>
</Steps>

This is why a `cart_token` or `checkout_token` alias passed early in the journey matters so much: it's what links the eventual server-side order back to the browser session that holds all the useful context. For more on choosing reliable aliases, see <OutboundLink />

## What gets enriched

When the Converge Pixel runs on the browser, it stores a set of profile properties automatically. After stitching, these become available on your server-side events:

| Property             | Description                                |
| -------------------- | ------------------------------------------ |
| `$user_agent`        | The browser's user agent                   |
| `$cookie_id`         | The Converge first-party cookie identifier |
| `$screen_resolution` | The device's screen resolution             |
| `$is_mobile`         | Whether the session was on a mobile device |
| `$timezone`          | The browser's timezone                     |
| `$language`          | The browser's language                     |

On top of these, Converge stores destination-specific click identifiers when they're present in the landing URL or set by a destination's own script, such as `$fbp` and `$fbc` for Meta, and `$gbraid` and `$wbraid` for Google. Any profile properties you pass yourself, like `$email`, `$first_name`, or `$phone_number`, are enriched the same way.

<Note>Enrichment only adds data that's missing. Properties already present on the incoming server-side event are kept as-is, so an explicit value you send always wins over a stored one.</Note>

## Enrichment and re-identification

Enrichment is also what makes Converge's longer cookie lifetime useful. Browsers like Safari wipe browser-set cookies after 7 days, but a <OutboundLink /> reliably re-identifies a returning customer for up to a year. When Converge recognizes a returning profile, enrichment restores the third-party cookies stored against it, so destinations can still match the conversion well after the browser would have forgotten the user.

## Related concepts

Enrichment ties the other source concepts together:

* <OutboundLink /> determine which profile an event belongs to. No stitching, no enrichment.
* <OutboundLink /> are the data that gets merged in.
* <OutboundLink /> makes sure an enriched conversion isn't counted twice.


# Consent
Source: https://docs.runconverge.com/sources/consent

Track visitor consent to Converge

## Overview

You can configure how the Converge destinations should behave based on the visitor's consent preferences.
To set this up, you need to send the consent to Converge.

You still need a CMP, cookie banner provider, or your own solution to collect the preference.

While this allows you to configure how destinations handle consent,
regardless of the configured consent, events will still be sent to Converge.

<Warning>This documentation describes implementing Consent for Converge. It does not implement Google or Microsoft Consent Mode. Read [this](/guides/implementing-consent-mode) guide for implementing Google and Microsoft Consent Mode.</Warning>

## The consent method

The `cvg` object has a `consent` method that you can use to send the visitor's consent preferences to Converge.
It takes two arguments. We recommend always sending both.

* `analytics`:
  Preference for analytics tracking. Possible values are `granted`, and `denied`.
  If not set, Converge will assume that the visitor has `denied` consent.
* `marketing`:
  Preference for marketing tracking. Possible values are `granted`, and `denied`.
  If not set, Converge will assume that the visitor has `denied` consent.

See the examples below.

<AccordionGroup>
  <Accordion icon="chart-simple" title="The visitor has granted consent for only analytics tracking">
    ```javascript theme={null}
    cvg({ 
        "method": "consent",
        "analytics": "granted",
    })
    ```
  </Accordion>

  <Accordion icon="chart-simple" title="Equivalent to granting consent for only analytics tracking">
    ```javascript theme={null}
    cvg({
        "method": "consent",
        "analytics": "granted",
        "marketing": "denied",
    })
    ```
  </Accordion>

  <Accordion icon="envelopes-bulk" title="The visitor has granted consent for both analytics and marketing tracking">
    ```javascript theme={null}
    cvg({
        "method": "consent",
        "analytics": "granted",
        "marketing": "granted",
    })
    ```
  </Accordion>

  <Accordion icon="radiation" title="The visitor has denied consent for both analytics and marketing tracking">
    ```javascript theme={null}
    cvg({
        "method": "consent",
        "analytics": "denied",
        "marketing": "denied",
    })
    ```
  </Accordion>
</AccordionGroup>

<Note>
  You need to make sure the `cvg` object is available before you call the `consent` method.
  If this is not the case, include the following snippet before calling `cvg`.

  ```javascript theme={null}
  window.cvg||(cvg=function(){cvg.process?cvg.process.apply(cvg,arguments):cvg.queue.push(arguments)},cvg.queue=[]);
  ```
</Note>

## Storing consent

Consent should be sent every time the user visits the page.
Typically, you will rely on your CMP or own cookie banner implementation to retrieve the visitor's consent and send it to Converge.

Converge stores the consent preferences in the visitor's browser as a backup.
But, to make sure that it is up-to-date, you should still specify it every time the converge snippet loads.

The preferences are also stored on the Converge **profile**, under the `profile_properties`.
This is used to filter events when forwarding server-side.

<Accordion title="Inspect the consent parameters for a profile">
  The consent preferences are stored in the **profile properties**, under the `$consent` key. This object is used to filter the server-side events.

  ```json profile_properties theme={null}
  {
      ...
      "$consent": {
          "analytics": "granted",
          "marketing": "denied"
      }
  }
  ```
</Accordion>

## Automatic CMP integrations

Converge automatically detects and integrates with popular Consent Management Platforms (CMPs). When one of these CMPs is present on your page, Converge will automatically read the visitor's consent preferences and apply them—no additional code required.

<Note>
  This integration handles Converge's consent tracking. If you're using Google Ads, GA4, or Microsoft Ads, you'll also need to implement Google and Microsoft Consent Mode. Read the [Implementing Consent Mode guide](/guides/implementing-consent-mode) to learn how to set this up with your CMP.
</Note>

### Supported CMPs

The following CMPs are automatically detected and integrated:

<AccordionGroup>
  <Accordion title="Avada (Shopify)">
    Converge automatically integrates with Avada's cookie consent banner on Shopify stores. The integration:

    * Detects Avada's consent banner using the Shopify Customer Privacy API
    * Maps analytics and marketing consent from Shopify's consent framework
    * Updates automatically when visitors change their consent preferences

    No additional configuration is needed if you're using Avada on Shopify.

    <Info>
      For Google Ads and GA4, you'll also need to implement Google Consent Mode. See the [Shopify Cookie Banner implementation example](/guides/implementing-consent-mode#examples) in the Consent Mode guide.
    </Info>
  </Accordion>

  <Accordion title="Consentmo">
    Converge automatically integrates with Consentmo's consent banner. The integration:

    * Detects Consentmo's banner script on the page
    * Reads the `analytics` and `marketing` preferences directly, since Consentmo already uses these category names
    * Listens for the `consentmoSignal` event to capture consent changes made during the session, and `consentmoSignal_onLoad` to pick up a returning visitor's stored choice

    No additional configuration is needed if you're using Consentmo.

    <Info>
      For Google Ads and GA4, you'll also need to implement Google Consent Mode. See the [custom implementation examples](/guides/implementing-consent-mode#examples) in the Consent Mode guide for help integrating Consentmo with Google Consent Mode.
    </Info>
  </Accordion>

  <Accordion title="Cookiebot">
    Converge automatically integrates with Cookiebot's consent framework. The integration:

    * Maps Cookiebot's `statistics` category to Converge's `analytics` consent
    * Maps Cookiebot's `marketing` category to Converge's `marketing` consent
    * Listens for the `CookiebotOnConsentReady` event to capture consent updates

    No additional configuration is needed if you're using Cookiebot.

    <Info>
      For Google Ads and GA4, you'll also need to implement Google Consent Mode. See the [Cookiebot implementation example](/guides/implementing-consent-mode#examples) in the Consent Mode guide.
    </Info>
  </Accordion>

  <Accordion title="CookieFirst">
    Converge automatically integrates with CookieFirst's consent banner. The integration:

    * Maps CookieFirst's `performance` category to Converge's `analytics` consent
    * Maps CookieFirst's `advertising` category to Converge's `marketing` consent
    * Listens for the `cf_consent` event to capture consent updates
    * Waits for the CookieFirst banner to load before reading consent

    No additional configuration is needed if you're using CookieFirst.

    <Info>
      For Google Ads and GA4, you'll also need to implement Google Consent Mode. See the [custom implementation examples](/guides/implementing-consent-mode#examples) in the Consent Mode guide for help integrating CookieFirst with Google Consent Mode.
    </Info>
  </Accordion>

  <Accordion title="Cookie Information">
    Converge automatically integrates with Cookie Information's consent platform. The integration:

    * Maps Cookie Information's `cookie_cat_statistic` category to Converge's `analytics` consent
    * Maps Cookie Information's `cookie_cat_marketing` category to Converge's `marketing` consent
    * Listens for the `CookieInformationConsentGiven` event to capture consent updates

    No additional configuration is needed if you're using Cookie Information.

    <Info>
      For Google Ads and GA4, you'll also need to implement Google Consent Mode. See the [custom implementation examples](/guides/implementing-consent-mode#examples) in the Consent Mode guide for help integrating Cookie Information with Google Consent Mode.
    </Info>
  </Accordion>

  <Accordion title="CookieYes">
    Converge automatically integrates with CookieYes's consent banner. The integration:

    * Maps CookieYes's `analytics` category to Converge's `analytics` consent
    * Maps CookieYes's `advertisement` category to Converge's `marketing` consent
    * Listens for the `cookieyes_consent_update` event to capture consent changes
    * Waits for the CookieYes banner to load before reading consent

    No additional configuration is needed if you're using CookieYes.

    <Info>
      For Google Ads and GA4, you'll also need to implement Google Consent Mode. See the [CookieYes implementation example](/guides/implementing-consent-mode#examples) in the Consent Mode guide.
    </Info>
  </Accordion>

  <Accordion title="OneTrust">
    Converge automatically integrates with OneTrust's consent framework. The integration:

    * Maps OneTrust's category C0002 (Performance) to Converge's `analytics` consent
    * Maps OneTrust's categories C0004 (Targeting) and C0005 (Social Media) to Converge's `marketing` consent
    * Integrates with the `OptanonWrapper` callback to capture consent updates

    No additional configuration is needed if you're using OneTrust.

    <Info>
      For Google Ads and GA4, you'll also need to implement Google Consent Mode. See the [custom implementation examples](/guides/implementing-consent-mode#examples) in the Consent Mode guide for help integrating OneTrust with Google Consent Mode.
    </Info>
  </Accordion>

  <Accordion title="Usercentrics">
    Converge automatically integrates with Usercentrics's consent platform. The integration:

    * Maps Usercentrics's `functional` category to Converge's `analytics` consent
    * Maps Usercentrics's `marketing` category to Converge's `marketing` consent
    * Listens for the `UC_CONSENT` event to capture consent updates
    * Waits for the Usercentrics CMP to load before reading consent

    No additional configuration is needed if you're using Usercentrics.

    <Info>
      For Google Ads and GA4, you'll also need to implement Google Consent Mode. See the [custom implementation examples](/guides/implementing-consent-mode#examples) in the Consent Mode guide for help integrating Usercentrics with Google Consent Mode.
    </Info>
  </Accordion>
</AccordionGroup>

<Note>
  If you're using one of these CMPs, you don't need to manually call the `cvg` consent method. Converge will automatically detect the CMP and sync consent preferences. However, you can still manually call the consent method if you need to override or supplement the automatic integration.
</Note>

### Limitations

The automatic CMP integrations have a few limitations to be aware of:

* **Loading order**: The CMP must load and initialize before Converge can read consent preferences. Most integrations include timeout logic (typically 5 seconds) to wait for the CMP to load.
* **Category mapping**: Converge only tracks two consent categories (`analytics` and `marketing`). Additional categories from your CMP are not captured.
* **Custom configurations**: If you've customized your CMP category names or structure, the automatic integration may not work correctly. Use the manual consent method instead.

## Sending consent

When Converge has not received any consent preferences, we will default to `denied` consent.
For that reason, we recommend calling the consent method before the Converge snippet.

```html Configuring consent before the tracking theme={null}
<script src="https://static.runconverge.com/pixels/xxxxxx.js" async></script>
<script>
    window.cvg||(cvg=function(){cvg.process?cvg.process.apply(cvg,arguments):cvg.queue.push(arguments)},cvg.queue=[]);
    cvg({
        "method": "consent",
        "analytics": "granted",
        "marketing": "granted",
    })
    cvg({method:"track", eventName:"$page_load"});
</script>

```

## Default consent

The Converge consent can be updated while the visitor is browsing the page.
To set a default consent, you can simply call the `consent` method with the static default preferences -- and later on, update them as follows.

```javascript Default to granted consent until the visitor denies marketing theme={null}
cvg({ 
    "method": "consent",
    "analytics": "granted",
    "marketing": "granted",
})

// When the visitor denies marketing
function denyMarketing() {
    cvg({ 
        "method": "consent",
        "analytics": "granted",
        "marketing": "denied",
    })
}
```

## Identifiers

The Converge pixel leverages the following identifiers in every setup.

| Name            | Method | Description                                                                                                                                                                          |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `__cvg_uid`     | Cookie | Unique identifier for the user                                                                                                                                                       |
| `__cvg_sid`     | Cookie | Unique identifier for the current session                                                                                                                                            |
| `__cvg_session` | Cookie | Information about the current session. It's used to ensure consistency of the session properties sent to Converge and to trigger new sessions based on changing tracking parameters. |

The following identifiers are only used for specific destinations.

| Name                | Destination | Method | Description            |
| ------------------- | ----------- | ------ | ---------------------- |
| `__cvg_tblcid`      | Taboola     | Cookie | Click ID from Taboola  |
| `__cvg_mgidcid`     | MGID        | Cookie | Click ID from MGID     |
| `__cvg_sccid`       | Snapchat    | Cookie | Click ID from SnapChat |
| `__cvg_awc`         | AWIN        | Cookie | Click ID from AWIN     |
| `__cvg_outbraincid` | Outbrain    | Cookie | Click ID from Outbrain |

The following identifiers are only used when Converge consent integration is active.

| Name                      | Method        | Description                         |
| ------------------------- | ------------- | ----------------------------------- |
| `__cvg_consent_analytics` | Local Storage | User consent for analytics purposes |
| `__cvg_consent_marketing` | Local Storage | User consent for marketing purposes |


# Event Spec
Source: https://docs.runconverge.com/sources/converge-spec



#### Why the Converge Spec?

Most CDPs are not very strict about *which* events you track, *where* you track them (client or server) and with *which properties*.
This usually leads to problems with destinations downstream as each destination does have very specific integration requirements to operate optimally.

#### Advantages of a strict spec

Converge, therefore, works with a strict Converge event spec.
Because we have a semantic understanding of what you are tracking, we can:

1. Automatically map your source events to destinations in an optimal way through our <OutboundLink />
2. Surface your meaningful analytics through our <OutboundLink /> product.
3. Monitor and flag when you are wrongly tracking events or properties negatively affecting your destinations or analytics through <OutboundLink />.

Of course, you can still extend the Converge Spec with your own events, properties, etc.

***

## Auto-tracking

These events, event properties, profile properties and aliases will be auto-tracked by the [Converge Pixel](/sources/website-integrations/converge-pixel).

### \$page\_load

When a user views a page.

<AccordionGroup>
  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({ method: "track", eventName: "$page_load" });
      ```
    </CodeGroup>
  </Accordion>

  <Tip>
    You do not need to manually implement any of the below properties, they will be automatically tracked for all client-side events.
  </Tip>

  <Accordion title="Auto-tracked Event Properties" icon="list">
    <ParamField type="string">
      IP address of the user.
    </ParamField>

    <ParamField type="string">
      URL of the pageview.
    </ParamField>

    <ParamField type="string">
      URL referrer of the pageview.
    </ParamField>

    <ParamField type="string">
      Browser timezone, as an IANA time zone name, e.g. `"America/New_York"`.
    </ParamField>

    <ParamField type="string">
      Screen resolution of the user's device, as `"<width>x<height>"` in CSS pixels, e.g. `"440x956"`.
    </ParamField>

    <ParamField type="boolean">
      Whether the event was tracked on a mobile device.
    </ParamField>

    <ParamField type="string">
      The sales channel where the event occurred. For client-side events tracked through the Converge Pixel, this will **always be "web" by default**. More on supported sales channels can be found [here](/sources/concepts/sales-channels).
    </ParamField>
  </Accordion>

  <Accordion title="Auto-tracked Profile Properties" icon="address-card">
    <ParamField type="string">
      IP address of the user.
    </ParamField>

    <ParamField type="string">
      Converge cookie ID.
    </ParamField>

    <ParamField type="string">
      User Agent of the last browser session of the user.
    </ParamField>
  </Accordion>

  <Accordion title="Auto-tracked Aliases" icon="passport">
    <ParamField>
      Alias based on the Converge cookie ID.
    </ParamField>
  </Accordion>
</AccordionGroup>

[//]: # "TODO: This list of event properties and profile properties is WIP"

***

## Ecommerce events

These events and properties should be passed for Ecommerce brands.
All of these events will contain additional prepopulated properties through [auto-tracking](#auto-tracking).

### Viewed Product

When a user views a product detail page.

<AccordionGroup>
  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="string">
      Product ID of the item that is being viewed.
    </ParamField>

    <ParamField type="string">
      Variant ID of the product variant that is being viewed
    </ParamField>

    <ParamField type="string">
      SKU of the product and variant that is being viewed
    </ParamField>

    <ParamField type="string">
      Product Name of the item that is being viewed
    </ParamField>

    <ParamField type="string">
      Variant name of the product variant that is being viewed
    </ParamField>

    <ParamField type="float">
      Unit price of the item that is being viewed
    </ParamField>

    <ParamField type="string">
      Currency of the product that is being viewed, as per [ISO
      4217](https://en.wikipedia.org/wiki/ISO_4217)
    </ParamField>

    <ParamField type="string">
      Name of the vendor of the product that is being viewed.
    </ParamField>

    <ParamField type="string">
      URL to the product page of the item that is being viewed.
    </ParamField>

    <ParamField type="string">
      URL of a product image of the item that is being viewed.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Viewed Product",
        properties: {
          product_id: "123456",
          variant_id: "78910", // if available
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla", // if available
          price: 42,
          currency: "USD",
          vendor: "My Store",
        },
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### Viewed Collection

When a user views a collection detail page that includes multiple products.

<AccordionGroup>
  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="string">
      Collection ID of the collection that is being viewed.
    </ParamField>

    <ParamField type="string">
      Name of the collection that is being viewed.
    </ParamField>

    <ParamField type="string">
      Description of the collection that is being viewed.
    </ParamField>

    <ParamField type="list of Item">
      <Expandable title="Item">
        <ParamField type="string">
          Product ID of the item that is being viewed.
        </ParamField>

        <ParamField type="string">
          Variant ID of the product variant that is being viewed
        </ParamField>

        <ParamField type="string">
          SKU of the product and variant that is being viewed
        </ParamField>

        <ParamField type="string">
          Product Name of the item that is being viewed
        </ParamField>

        <ParamField type="string">
          Variant name of the product variant that is being viewed
        </ParamField>

        <ParamField type="float">
          Unit price of the item that is being viewed
        </ParamField>

        <ParamField type="string">
          Currency of the product that is being viewed, as per [ISO
          4217](https://en.wikipedia.org/wiki/ISO_4217)
        </ParamField>

        <ParamField type="string">
          Name of the vendor of the product that is being viewed.
        </ParamField>

        <ParamField type="string">
          URL to the product page of the item that is being viewed.
        </ParamField>

        <ParamField type="string">
          URL of a product image of the item that is being viewed.
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Viewed Collection",
        properties: {
          id: "123456", // Collection ID
          name: "My Collection Name",
          description: "My Collection Description",
          items: [
            {
              product_id: "123456",
              variant_id: "78910", // if available
              sku: "MY_SKU",
              name: "My Product",
              variant_name: "Vanilla", // if available
              price: 42,
              currency: "USD",
              vendor: "My Store",
            },
          ],
        },
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### Added To Cart

When a user adds a product to cart.

<AccordionGroup>
  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="string">
      Product ID of the item that is being added to cart.
    </ParamField>

    <ParamField type="string">
      Variant ID of the product variant that is being added to cart.
    </ParamField>

    <ParamField type="string">
      SKU of the product and variant that is being added to cart.
    </ParamField>

    <ParamField type="string">
      Product Name of the item that is being added to cart.
    </ParamField>

    <ParamField type="string">
      Variant name of the product variant that is being added to cart.
    </ParamField>

    <ParamField type="float">
      Unit price of the item that is being added to cart.
    </ParamField>

    <ParamField type="string">
      Currency of the product that is being viewed, as per [ISO
      4217](https://en.wikipedia.org/wiki/ISO_4217)
    </ParamField>

    <ParamField type="int">
      Amount of times the item is being added to cart.
    </ParamField>

    <ParamField type="string">
      Name of the vendor of the product that is being added to cart.
    </ParamField>

    <ParamField type="string">
      URL to the product page of the item that is being added to cart.
    </ParamField>

    <ParamField type="string">
      URL of a product image of the product that is being added to cart.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Added To Cart",
        properties: {
          product_id: "123456",
          variant_id: "78910",
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla",
          price: 42,
          currency: "USD",
          quantity: 1,
          vendor: "My Store",
        },
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### Removed From Cart

When a user removes a product from cart.

<AccordionGroup>
  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="string">
      Product ID of the item that is being removed from cart.
    </ParamField>

    <ParamField type="string">
      Variant ID of the product variant that is being removed from cart.
    </ParamField>

    <ParamField type="string">
      SKU of the product and variant that is being removed from cart.
    </ParamField>

    <ParamField type="string">
      Product Name of the item that is being removed from cart.
    </ParamField>

    <ParamField type="string">
      Variant name of the product variant that is being removed from cart.
    </ParamField>

    <ParamField type="float">
      Unit price of the item that is being removed from cart.
    </ParamField>

    <ParamField type="string">
      Currency of the product that is being viewed, as per [ISO
      4217](https://en.wikipedia.org/wiki/ISO_4217)
    </ParamField>

    <ParamField type="int">
      Amount of times the item is being removed from cart.
    </ParamField>

    <ParamField type="string">
      Name of the vendor of the product that is being removed from cart.
    </ParamField>

    <ParamField type="string">
      URL to the product page of the item that is being removed from cart.
    </ParamField>

    <ParamField type="string">
      URL of a product image of the product that is being removed from cart.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Removed From Cart",
        properties: {
          product_id: "123456",
          variant_id: "78910",
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla",
          price: 42,
          currency: "USD",
          quantity: 1,
          vendor: "My Store",
        },
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### Started Checkout

When a user starts the checkout process.

<AccordionGroup>
  <Note> This event typically is used for stitching website sessions to server-side orders, make sure to add appropriate [aliases](/sources/concepts/aliases)</Note>

  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="float">
      Total value of the cart at checkout with tax and shipping.
    </ParamField>

    <ParamField type="float">
      Total tax of the cart at checkout.
    </ParamField>

    <ParamField type="float">
      Total shipping cost of the cart at checkout.
    </ParamField>

    <ParamField type="float">
      Total discount of the cart at checkout.
    </ParamField>

    <ParamField type="string | list of string">
      The coupon or list of coupons used at checkout
    </ParamField>

    <ParamField type="string">
      Currency of the cart that is being checked out, as per [ISO
      4217](https://en.wikipedia.org/wiki/ISO_4217)
    </ParamField>

    <ParamField type="list of CheckoutItem">
      <Expandable title="CheckoutItem">
        <ParamField type="string">
          Product ID of the item.
        </ParamField>

        <ParamField type="string">
          Variant ID of the product variant
        </ParamField>

        <ParamField type="string">
          SKU of the product and variant
        </ParamField>

        <ParamField type="string">
          Product Name of the item
        </ParamField>

        <ParamField type="string">
          Variant name of the product variant
        </ParamField>

        <ParamField type="float">
          Unit price of the item
        </ParamField>

        <ParamField type="string">
          Currency of the product, as per [ISO
          4217](https://en.wikipedia.org/wiki/ISO_4217)
        </ParamField>

        <ParamField type="string">
          Name of the vendor of the product.
        </ParamField>

        <ParamField type="int">
          Amount of times the item is present in the cart at checkout.
        </ParamField>

        <ParamField type="string">
          URL to the product page of the item
        </ParamField>

        <ParamField type="string">
          URL of a product image of the item
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Started Checkout",
        properties: {
          total_price: 42,
          total_tax: 3.5,
          total_shipping: 2.4,
          currency: "USD",
          coupon: 'COUPON123',
          items: [
            // Notice that this is a list of items
            {
              product_id: "123456",
              variant_id: "78910",
              sku: "MY_SKU",
              name: "My Product",
              variant_name: "Vanilla",
              price: 42,
              currency: "USD",
              quantity: 1,
              vendor: "My Store",
            },
          ],
        },
        aliases: ["urn:cart_token:xyz123"]
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### Added Payment Info

When a user adds their payment info.

<AccordionGroup>
  <Note> This event typically is used for stitching website sessions to server-side orders, make sure to add appropriate [aliases](/sources/concepts/aliases)</Note>

  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="float">
      Total value of the cart at checkout with tax and shipping.
    </ParamField>

    <ParamField type="float">
      Total tax of the cart at checkout.
    </ParamField>

    <ParamField type="float">
      Total shipping cost of the cart at checkout.
    </ParamField>

    <ParamField type="float">
      Total discount of the cart at checkout.
    </ParamField>

    <ParamField type="string | list of string">
      The coupon or list of coupons used at checkout
    </ParamField>

    <ParamField type="string">
      Currency of the cart that is being checked out, as per [ISO
      4217](https://en.wikipedia.org/wiki/ISO_4217)
    </ParamField>

    <ParamField type="list of CheckoutItem">
      <Expandable title="CheckoutItem">
        <ParamField type="string">
          Product ID of the item.
        </ParamField>

        <ParamField type="string">
          Variant ID of the product variant
        </ParamField>

        <ParamField type="string">
          SKU of the product and variant
        </ParamField>

        <ParamField type="string">
          Product Name of the item
        </ParamField>

        <ParamField type="string">
          Variant name of the product variant
        </ParamField>

        <ParamField type="float">
          Unit price of the item
        </ParamField>

        <ParamField type="string">
          Currency of the product, as per [ISO
          4217](https://en.wikipedia.org/wiki/ISO_4217)
        </ParamField>

        <ParamField type="string">
          Name of the vendor of the product.
        </ParamField>

        <ParamField type="int">
          Amount of times the item is present in the cart at checkout.
        </ParamField>

        <ParamField type="string">
          URL to the product page of the item
        </ParamField>

        <ParamField type="string">
          URL of a product image of the item
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Profile Properties" icon="address-card">
    <ParamField type="string">
      Email Address of the user.
    </ParamField>

    <ParamField type="string">
      Phone Number of the user including the `+` sign and country code. For example: `"+1 (917) 123-4567"` or `"+3295123456"`.
    </ParamField>

    <ParamField type="string">
      City of the user's address.
    </ParamField>

    <ParamField type="string">
      Country code of the user's address as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, e.g. `"US"`. Three-letter alpha-3 codes such as `"USA"` are not supported.
    </ParamField>

    <ParamField type="string">
      State of the user's address.
    </ParamField>

    <ParamField type="string">
      Zip code of the user's address.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Added Payment Info",
        properties: {
          total_price: 42,
          total_tax: 3.5,
          total_shipping: 2.4,
          currency: "USD",
          coupon: 'COUPON123',
          items: [
            {
              product_id: "123456",
              variant_id: "78910",
              sku: "MY_SKU",
              name: "My Product",
              variant_name: "Vanilla",
              price: 42,
              currency: "USD",
              quantity: 1,
              vendor: "My Store",
            },
          ],
        },
        profileProperties: {
          // Pass if available
          $email: "john.smith@apple.com",
          $phone_number: "+199999999",
          $city: "San Francisco",
          $country_code: "US",
          $state: "California",
          $zip_code: "94103",
        },
        
        // important, this will be used for stitching backend orders to website sessions
        aliases: ["urn:email:john.smith@apple.com"],
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### Placed Order

When a user places an order.

<AccordionGroup>
  <Note>
    **Conversion event**: you should adhere to the **Where To Track**,
    **Deduplication** and **Session Stitching** guidelines.
  </Note>

  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on **both** the client and the server.
  </Accordion>

  <Accordion title="Deduplication" icon="check-double">
    You should pass a unique `eventID` so client-side and server-side copies of
    the same order can be deduplicated.
  </Accordion>

  <Accordion title="Session Stitching" icon="code-merge">
    You should make sure that the conversion can be stitched to the corresponding website session by including the right set of **aliases** on this event and corresponding web events.

    Common **aliases** are:

    * Email: `urn:email:john.smith@apple.com`
    * Checkout Token: `urn:checkout_token:xyz_123`
    * Customer ID: `urn:customer_id:123456`

    Which alias you use depends on your exact setup and which identifiers are available both on the browser and the server in a user journey.

    Learn more about session stitching and aliases [here](/sources/concepts/aliases#server-side-tracking-and-stitching-problems).
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="string">
      Order ID.
    </ParamField>

    <ParamField type="float">
      Total value of the order with tax and shipping.
    </ParamField>

    <ParamField type="float">
      Total tax of the order.
    </ParamField>

    <ParamField type="float">
      Total shipping cost of the order.
    </ParamField>

    <ParamField type="float">
      Total discount on the order.
    </ParamField>

    <ParamField type="string | list of string">
      The coupon or list of coupons used in the order.
    </ParamField>

    <ParamField type="string">
      Currency of the order, as per [ISO
      4217](https://en.wikipedia.org/wiki/ISO_4217)
    </ParamField>

    <ParamField type="list of CheckoutItem">
      <Expandable title="CheckoutItem">
        <ParamField type="string">
          Product ID of the item in the order.
        </ParamField>

        <ParamField type="string">
          Variant ID of the item in the order
        </ParamField>

        <ParamField type="string">
          SKU of the item in the order
        </ParamField>

        <ParamField type="string">
          Product Name of the item in the order
        </ParamField>

        <ParamField type="string">
          Variant name of the product variant
        </ParamField>

        <ParamField type="float">
          Unit price of the item in the order
        </ParamField>

        <ParamField type="string">
          Currency of the item in the order, as per [ISO
          4217](https://en.wikipedia.org/wiki/ISO_4217)
        </ParamField>

        <ParamField type="string">
          Name of the vendor of the item in the order.
        </ParamField>

        <ParamField type="int">
          Amount of times the item is present in the order.
        </ParamField>

        <ParamField type="string">
          URL to the product page of the item
        </ParamField>

        <ParamField type="string">
          URL of a product image of the item
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="boolean">
      Whether this order is the customer's first completed purchase. If omitted, Converge falls back to its own order history. See [New customer status](/sources/concepts/new-customer-status) for more details, including override behavior and common pitfalls.
    </ParamField>

    <ParamField type="string">
      The sales channel of the event. If no sales channel type is provided then Converge fallback to "web". More on supported sales channels values can be found [here](/sources/concepts/sales-channels). The sales channel type provided entirely depends on the context of the event, integration, and where the event originates from. Client-side Placed Order events should always be "web".
    </ParamField>

    <ParamField type="string">
      The URL of the page where the event occurred. This will be automatically tracked for all client-side events.
    </ParamField>
  </Accordion>

  <Accordion title="Profile Properties" icon="address-card">
    <Info> Some fields are required for both the Event Properties **and** the Profile Properties. The reason is that Event Properties are static and Profile Properties are dynamic. A customer might move address between two orders for example.</Info>

    <ParamField type="string">
      Email Address of the user.
    </ParamField>

    <ParamField type="string">
      Phone Number of the user including the `+` sign and country code. For example: `"+1 (917) 123-4567"` or `"+3295123456"`.
    </ParamField>

    <ParamField type="string">
      City of the user's address.
    </ParamField>

    <ParamField type="string">
      Country code of the user's address as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, e.g. `"US"`. Three-letter alpha-3 codes such as `"USA"` are not supported.
    </ParamField>

    <ParamField type="string">
      State of the user's address.
    </ParamField>

    <ParamField type="string">
      Zip code of the user's address.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <Warning>
      If you track conversions both server-side and client-side, you should make sure you use the `"forward"` method for the client-side event.
      See the client-side code example.

      Make sure you include the **same eventID** on the client-side and server-side event.
    </Warning>

    <Warning>
      Note that client-side calls use camelCase (e.g. `eventName`) and server-side calls use snake\_case (e.g. `event_name`).
    </Warning>

    <CodeGroup>
      ```javascript JavaScript - Client-side theme={null}
      cvg({
        method: "forward", 
        eventName: "Placed Order",
        eventID: "order-1", // used for deduplicating, should be unique
        properties: {
          id: "order-1",
          total_price: 42,
          total_tax: 3.5,
          total_shipping: 2.4,
          currency: "USD",
          coupon: 'COUPON123',
          items: [
            {
              product_id: "123456",
              variant_id: "654321",
              sku: "MY_SKU",
              name: "My Product",
              variant_name: "Vanilla",
              price: 42,
              currency: "USD",
              quantity: 1,
              vendor: "My Store",
            },
          ],
        },
        profileProperties: {
          // Pass if available
          $email: "john.smith@apple.com",
          $phone_number: "+199999999",
          $city: "San Francisco",
          $country_code: "US",
          $state: "California",
          $zip_code: "94103",
      },
        aliases: ["urn:email:john.smith@apple.com"],
      });
      ```

      ```python Python - Server-side theme={null}
      resp = requests.post(
          "https://app.runconverge.com/api/webhooks",
          header={
            "Content-Type": "application/json", 
            "X-Webhook-Token": "{YOUR_WEBHOOK_TOKEN}"
          },
          json=
              {
              "event_name": "Placed Order",
              "event_id": "order-1", # your order id, necessary for deduplication
              "properties": {
                  "id" : "order-1", # will be shown in the UI
                  "total_price": 42,
                  "total_tax": 3.5,
                  "total_shipping": 2.4,
                  "currency": "USD",
                  "items": [
                      {
                          "product_id": "123456",
                          "variant_id": "654321", # important for Shopify stores
                          "sku": "MY_SKU",
                          "name": "My Product",
                          "variant_name": "Vanilla",
                          "price": 42,
                          "currency": "USD",
                          "quantity": 1,
                          "vendor": "My Store",
                      },
                  ],
                  "$is_new_customer": False, # important
                  "$sales_channel_type": "web",  # important, see supported sales channels
                  "$url": "https://my-store.com/checkout"
              },
              "profile_properties": {
                  # Pass as many as possible
                  "$first_name": "John",
                  "$last_name": "Smith",
                  "$email": "john.smith@apple.com",
                  "$phone_number": "+199999999",
                  "$city": "San Francisco",
                  "$country_code": "US",
                  "$state": "California",
                  "$zip_code": "94103",
              },
              # important, this will be used for stitching backend orders to website sessions
              "aliases": ["urn:email:john.smith@apple.com"],
          }
      )
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

[//]: # "TODO: Should add a set of recommended aliases to Placed Order events"

### Viewed Cart

When a user views their cart.

<AccordionGroup>
  <Info>
    This is an optional event
  </Info>

  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="float">
      Total value of the cart with tax and shipping.
    </ParamField>

    <ParamField type="float">
      Total tax of the cart.
    </ParamField>

    <ParamField type="float">
      Total shipping cost of the cart.
    </ParamField>

    <ParamField type="float">
      Total discount of the cart.
    </ParamField>

    <ParamField type="string | list of string">
      The coupon or list of coupons used in the cart.
    </ParamField>

    <ParamField type="string">
      Currency of the cart that is being checked out, as per [ISO
      4217](https://en.wikipedia.org/wiki/ISO_4217)
    </ParamField>

    <ParamField type="list of CartItem">
      <Expandable title="CartItem">
        <ParamField type="string">
          Product ID of the item.
        </ParamField>

        <ParamField type="string">
          Variant ID of the product variant
        </ParamField>

        <ParamField type="string">
          SKU of the product and variant
        </ParamField>

        <ParamField type="string">
          Product Name of the item
        </ParamField>

        <ParamField type="string">
          Variant name of the product variant
        </ParamField>

        <ParamField type="float">
          Unit price of the item
        </ParamField>

        <ParamField type="string">
          Currency of the product, as per [ISO
          4217](https://en.wikipedia.org/wiki/ISO_4217)
        </ParamField>

        <ParamField type="string">
          Name of the vendor of the product.
        </ParamField>

        <ParamField type="int">
          Amount of times the item is present in the cart at checkout.
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Viewed Cart",
        properties: {
          total_price: 42,
          total_tax: 3.5,
          total_shipping: 2.4,
          currency: "USD",
          coupon: 'COUPON123',
          items: [
            // Notice that this is a list of items
            {
              product_id: "123456",
              variant_id: "78910",
              sku: "MY_SKU",
              name: "My Product",
              variant_name: "Vanilla",
              price: 42,
              currency: "USD",
              quantity: 1,
              vendor: "My Store",
            },
          ],
        },
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

## Subscription lifecycle events

These events and properties should be passed by companies who operate on subscriptions.

### Started Subscription

When a user starts a subscription.

<AccordionGroup>
  <Note>
    **Conversion event**: you should adhere to the **Where To Track**, **Deduplication** and **Session Stitching** guidelines.
  </Note>

  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on **both** the client and the server.
  </Accordion>

  <Accordion title="Deduplication" icon="check-double">
    You should pass a unique `eventID` so client-side and server-side copies of
    the same order can be deduplicated.
  </Accordion>

  <Accordion title="Session Stitching" icon="code-merge">
    You should make sure that the conversion can be stitched to the corresponding website session by including the right set of **aliases** on this event and corresponding web events.

    Common **aliases** are:

    * Email: `urn:email:john.smith@apple.com`
    * Checkout Token: `urn:checkout_token:xyz_123`
    * Customer ID: `urn:customer_id:123456`

    Which alias you use depends on your exact setup and which identifiers are available both on the browser and the server in a user journey.

    Learn more about session stitching and aliases [here](/sources/concepts/aliases#server-side-tracking-and-stitching-problems).
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="float">
      Total value of the subscription with tax and shipping.
    </ParamField>

    <ParamField type="float">
      Total tax of the subscription.
    </ParamField>

    <ParamField type="float">
      Total shipping cost of the subscription.
    </ParamField>

    <ParamField type="float">
      Total discount on the subscription.
    </ParamField>

    <ParamField type="string | list of string">
      The coupon or list of coupons used in the subscription.
    </ParamField>

    <ParamField type="string">
      Currency of the subscription, as per [ISO
      4217](https://en.wikipedia.org/wiki/ISO_4217)
    </ParamField>

    <ParamField type="list of CheckoutItem">
      <Expandable title="CheckoutItem">
        <ParamField type="string">
          Product ID of the item in the subscription.
        </ParamField>

        <ParamField type="string">
          Variant ID of the item in the subscription
        </ParamField>

        <ParamField type="string">
          SKU of the item in the subscription
        </ParamField>

        <ParamField type="string">
          Product Name of the item in the subscription
        </ParamField>

        <ParamField type="string">
          Variant name of the item in the subscription
        </ParamField>

        <ParamField type="float">
          Unit price of the item in the subscription
        </ParamField>

        <ParamField type="string">
          Currency of the item in the subscription, as per [ISO
          4217](https://en.wikipedia.org/wiki/ISO_4217)
        </ParamField>

        <ParamField type="string">
          Name of the vendor of the item in the subscription.
        </ParamField>

        <ParamField type="int">
          Amount of times the item is present in the subscription.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      The sales channel where the event occurred. For client-side events tracked through the Converge Pixel, this will **always be "web" by default**. More on supported sales channels can be found [here](/sources/concepts/sales-channels).
    </ParamField>
  </Accordion>

  <Accordion title="Profile Properties" icon="address-card">
    <Info> Some fields are required for both the Event Properties **and** the Profile Properties. The reason is that Event Properties are static and Profile Properties are dynamic. A customer might move address between two orders for example.</Info>

    <ParamField type="string">
      Email Address of the subscriber.
    </ParamField>

    <ParamField type="string">
      Phone Number of the subscriber including the `+` sign and country code. For example: `"+1 (917) 123-4567"` or `"+3295123456"`.
    </ParamField>

    <ParamField type="string">
      City of the subscriber's address.
    </ParamField>

    <ParamField type="string">
      Country code of the subscriber's address as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, e.g. `"US"`. Three-letter alpha-3 codes such as `"USA"` are not supported.
    </ParamField>

    <ParamField type="string">
      State of the subscriber's address.
    </ParamField>

    <ParamField type="string">
      Zip code of the subscriber's address.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <Note>
      If you track conversions both server-side and client-side, you should make sure you use the `"forward"` method for the client-side event.
      See the client-side code example.
    </Note>

    <CodeGroup>
      ```javascript JavaScript - Client-side theme={null}
      cvg({
        method: "forward", 
        eventName: "Started Subscription",
        eventID: "order-1", // should be the subscription id or order id of the first purchase
        properties: {
          id: "order-1",
          total_price: 42,
          total_tax: 3.5,
          total_shipping: 2.4,
          currency: "USD",
          coupon: 'COUPON123',
          items: [
            {
              product_id: "123456",
              variant_id: "654321",
              sku: "MY_SKU",
              name: "My Product",
              variant_name: "Vanilla",
              price: 42,
              currency: "USD",
              quantity: 1,
              vendor: "My Store",
            },
          ],
        },
        profileProperties: {
          // Pass if available
          $email: "john.smith@apple.com",
          $phone_number: "+199999999",
          $city: "San Francisco",
          $country_code: "US",
          $state: "California",
          $zip_code: "94103",
        },
        // important, this will be used for stitching backend orders to website sessions
        aliases: ["urn:email:john.smith@apple.com"],
      });
      ```

      ```python Python - Server-side theme={null}
      resp = requests.post(
          "{YOUR_POSTBACK_ENDPOINT}",
          json=
              {
              "event_name": "Started Subscription",
              "event_id": "order-1",  # should be the subscription id or order id of the first purchase
              "properties": {
                  "id" : "order-1", # will be shown in the UI
                  "total_price": 42,
                  "total_tax": 3.5,
                  "total_shipping": 2.4,
                  "currency": "USD",
                  "items": [
                      {
                          "product_id": "123456",
                          "variant_id": "654321", # important for Shopify stores
                          "sku": "MY_SKU",
                          "name": "My Product",
                          "variant_name": "Vanilla",
                          "price": 42,
                          "currency": "USD",
                          "quantity": 1,
                          "vendor": "My Store",
                      },
                  ],
                  "$sales_channel_type": "web",
              },
              "profile_properties": {
                  # Pass as many as possible
                  "$first_name": "John",
                  "$last_name": "Smith",
                  "$email": "john.smith@apple.com",
                  "$phone_number": "+199999999",
                  "$city": "San Francisco",
                  "$country_code": "US",
                  "$state": "California",
                  "$zip_code": "94103",
              },   
              # important, this will be used for stitching backend orders to website sessions
              "aliases": ["urn:email:john.smith@apple.com"],
          }
      )
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

[//]: # "TODO: Should add a set of recommended aliases to Started Subscription events"

[//]: # "TODO: Should decide whether people should also track this client-side"

### Cancelled Subscription

When a user cancels a subscription.

<AccordionGroup>
  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the server.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="float">
      Total value of the subscription with tax and shipping.
    </ParamField>

    <ParamField type="float">
      Total tax of the subscription.
    </ParamField>

    <ParamField type="float">
      Total shipping cost of the subscription.
    </ParamField>

    <ParamField type="float">
      Total discount on the subscription.
    </ParamField>

    <ParamField type="string | list of string">
      The coupon or list of coupons used in the subscription.
    </ParamField>

    <ParamField type="string">
      Currency of the subscription, as per [ISO
      4217](https://en.wikipedia.org/wiki/ISO_4217)
    </ParamField>

    <ParamField type="list of CheckoutItem">
      <Expandable title="CheckoutItem">
        <ParamField type="string">
          Product ID of the item in the subscription.
        </ParamField>

        <ParamField type="string">
          Variant ID of the item in the subscription
        </ParamField>

        <ParamField type="string">
          SKU of the item in the subscription
        </ParamField>

        <ParamField type="string">
          Product Name of the item in the subscription
        </ParamField>

        <ParamField type="string">
          Variant name of the item in the subscription
        </ParamField>

        <ParamField type="float">
          Unit price of the item in the subscription
        </ParamField>

        <ParamField type="string">
          Currency of the item in the subscription, as per [ISO
          4217](https://en.wikipedia.org/wiki/ISO_4217)
        </ParamField>

        <ParamField type="string">
          Name of the vendor of the item in the subscription.
        </ParamField>

        <ParamField type="int">
          Amount of times the item is present in the subscription.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      The sales channel where the event occurred. Due to this event typically being server side, the sales channel type should be **"offline"**. More on supported sales channels can be found [here](/sources/concepts/sales-channels).
    </ParamField>
  </Accordion>

  <Accordion title="Profile Properties" icon="address-card">
    <Info> Some fields are required for both the Event Properties **and** the Profile Properties. The reason is that Event Properties are static and Profile Properties are dynamic. A customer might move address between two orders for example.</Info>

    <ParamField type="string">
      Email Address of the subscriber.
    </ParamField>

    <ParamField type="string">
      Phone Number of the subscriber including the `+` sign and country code. For example: `"+1 (917) 123-4567"` or `"+3295123456"`.
    </ParamField>

    <ParamField type="string">
      City of the subscriber's address.
    </ParamField>

    <ParamField type="string">
      Country code of the subscriber's address as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, e.g. `"US"`. Three-letter alpha-3 codes such as `"USA"` are not supported.
    </ParamField>

    <ParamField type="string">
      State of the subscriber's address.
    </ParamField>

    <ParamField type="string">
      Zip code of the subscriber's address.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```python Python - Server-side theme={null}
      resp = requests.post(
          "{YOUR_POSTBACK_ENDPOINT}",
          json=
              {
              "event_name": "Cancelled Subscription",
              "properties": {
                  "id": "4001920", # the subscription id
                  "total_price": 42,
                  "total_tax": 3.5,
                  "total_shipping": 2.4,
                  "currency": "USD",
                  "items": [
                      {
                          "product_id": "123456",
                          "variant_id": "654321", # important for Shopify stores
                          "sku": "MY_SKU",
                          "name": "My Product",
                          "variant_name": "Vanilla",
                          "price": 42,
                          "currency": "USD",
                          "quantity": 1,
                          "vendor": "My Store",
                      },
                  ],
                  "$sales_channel_type": "offline",
              },
              "profile_properties": {
                  # Pass as many as possible
                  "$first_name": "John",
                  "$last_name": "Smith",
                  "$email": "john.smith@apple.com",
                  "$phone_number": "+199999999",
                  "$city": "San Francisco",
                  "$country_code": "US",
                  "$state": "California",
                  "$zip_code": "94103",
              },
              "aliases": ["urn:email:john.smith@apple.com"],
          }
      )

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

[//]: # "TODO: Should add a set of recommended aliases to Started Subscription events"

[//]: # "TODO: Should decide whether people should also track this client-side"

### Placed Recurring Subscription Order

When a user places a recurring subscription order.

<AccordionGroup>
  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the server.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="float">
      Total value of the subscription with tax and shipping.
    </ParamField>

    <ParamField type="float">
      Total tax of the subscription.
    </ParamField>

    <ParamField type="float">
      Total shipping cost of the subscription.
    </ParamField>

    <ParamField type="float">
      Total discount on the subscription.
    </ParamField>

    <ParamField type="string | list of string">
      The coupon or list of coupons used in the subscription.
    </ParamField>

    <ParamField type="string">
      Currency of the subscription, as per [ISO
      4217](https://en.wikipedia.org/wiki/ISO_4217)
    </ParamField>

    <ParamField type="list of CheckoutItem">
      <Expandable title="CheckoutItem">
        <ParamField type="string">
          Product ID of the item in the subscription.
        </ParamField>

        <ParamField type="string">
          Variant ID of the item in the subscription
        </ParamField>

        <ParamField type="string">
          SKU of the item in the subscription
        </ParamField>

        <ParamField type="string">
          Product Name of the item in the subscription
        </ParamField>

        <ParamField type="string">
          Variant name of the item in the subscription
        </ParamField>

        <ParamField type="float">
          Unit price of the item in the subscription
        </ParamField>

        <ParamField type="string">
          Currency of the item in the subscription, as per [ISO
          4217](https://en.wikipedia.org/wiki/ISO_4217)
        </ParamField>

        <ParamField type="string">
          Name of the vendor of the item in the subscription.
        </ParamField>

        <ParamField type="int">
          Amount of times the item is present in the subscription.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      The sales channel where the event occurred. Due to this event typically being server side, the sales channel type should be **"subscription\_contract"**. More on supported sales channels can be found [here](/sources/concepts/sales-channels).
    </ParamField>
  </Accordion>

  <Accordion title="Profile Properties" icon="address-card">
    <Info> Some fields are required for both the Event Properties **and** the Profile Properties. The reason is that Event Properties are static and Profile Properties are dynamic. A customer might move address between two orders for example.</Info>

    <ParamField type="string">
      Email Address of the subscriber.
    </ParamField>

    <ParamField type="string">
      Phone Number of the subscriber including the `+` sign and country code. For example: `"+1 (917) 123-4567"` or `"+3295123456"`.
    </ParamField>

    <ParamField type="string">
      City of the subscriber's address.
    </ParamField>

    <ParamField type="string">
      Country code of the subscriber's address as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, e.g. `"US"`. Three-letter alpha-3 codes such as `"USA"` are not supported.
    </ParamField>

    <ParamField type="string">
      State of the subscriber's address.
    </ParamField>

    <ParamField type="string">
      Zip code of the subscriber's address.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```python Python - Server-side theme={null}
      resp = requests.post(
          "{YOUR_POSTBACK_ENDPOINT}",
          json=
              {
              "event_name": "Placed Recurring Subscription Order",
              "properties": {
                  "id": "4001920", # the subscription id
                  "total_price": 42,
                  "total_tax": 3.5,
                  "total_shipping": 2.4,
                  "currency": "USD",
                  "items": [
                      {
                          "product_id": "123456",
                          "variant_id": "654321", # important for Shopify stores
                          "sku": "MY_SKU",
                          "name": "My Product",
                          "variant_name": "Vanilla",
                          "price": 42,
                          "currency": "USD",
                          "quantity": 1,
                          "vendor": "My Store",
                      },
                  ],
                  "$sales_channel_type": "subscription_contract",
              },
              "profile_properties": {
                  # Pass as many as possible
                  "$first_name": "John",
                  "$last_name": "Smith",
                  "$email": "john.smith@apple.com",
                  "$phone_number": "+199999999",
                  "$city": "San Francisco",
                  "$country_code": "US",
                  "$state": "California",
                  "$zip_code": "94103",
              },
              "aliases": ["urn:email:john.smith@apple.com"],
          }
      )
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

## Useful additional events

Most ad platforms rely on the `email` parameter being available on customer events.
For that reason, you will want to capture events that pick up this parameter.

### Logged In

When a user logs in.

<AccordionGroup>
  <Note> This event typically is used for stitching website sessions to server-side orders, make sure to add appropriate [aliases](/sources/concepts/aliases)</Note>

  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    This event does not require any event properties.
  </Accordion>

  <Accordion title="Profile Properties" icon="address-card">
    <ParamField type="string">
      Email Address of the user.
    </ParamField>

    <ParamField type="string">
      Phone Number of the user including the `+` sign and country code. For example: `"+1 (917) 123-4567"` or `"+3295123456"`.
    </ParamField>

    <ParamField type="string">
      City of the user's address.
    </ParamField>

    <ParamField type="string">
      Country code of the user's address as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, e.g. `"US"`. Three-letter alpha-3 codes such as `"USA"` are not supported.
    </ParamField>

    <ParamField type="string">
      State of the user's address.
    </ParamField>

    <ParamField type="string">
      Zip code of the user's address.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Logged In",
        profileProperties: {
          $email: "john.smith@apple.com",
          $phone_number: "+199999999",
          $city: "San Francisco",
          $country_code: "US",
          $state: "California",
          $zip_code: "94103",
        },
        
        // important, this will be used for stitching backend orders to website sessions
        aliases: ["urn:email:john.smith@apple.com"],
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### Searched

When a user performs a search on your website.

<AccordionGroup>
  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    <ParamField type="string">
      The search query entered by the user.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Searched",
        properties: {
          query: "running shoes",
        },
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

### Signed Up

When a user signs up.

<AccordionGroup>
  <Note> This event typically is used for stitching website sessions to server-side orders, make sure to add appropriate [aliases](/sources/concepts/aliases)</Note>

  <Accordion title="Where To Track" icon="map-pin">
    This event should be tracked on the client.
  </Accordion>

  <Accordion title="Event Properties" icon="list">
    This event does not require any event properties.
  </Accordion>

  <Accordion title="Profile Properties" icon="address-card">
    <ParamField type="string">
      Email Address of the user.
    </ParamField>

    <ParamField type="string">
      Phone Number of the user including the `+` sign and country code. For example: `"+1 (917) 123-4567"` or `"+3295123456"`.
    </ParamField>

    <ParamField type="string">
      City of the user's address.
    </ParamField>

    <ParamField type="string">
      Country code of the user's address as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, e.g. `"US"`. Three-letter alpha-3 codes such as `"USA"` are not supported.
    </ParamField>

    <ParamField type="string">
      State of the user's address.
    </ParamField>

    <ParamField type="string">
      Zip code of the user's address.
    </ParamField>
  </Accordion>

  <Accordion title="Code Example" icon="code">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      cvg({
        method: "track",
        eventName: "Signed Up",
        profileProperties: {
          $email: "john.smith@apple.com",
          $phone_number: "+199999999",
          $city: "San Francisco",
          $country_code: "US",
          $state: "California",
          $zip_code: "94103",
        },
        
        // important, this will be used for stitching backend orders to website sessions
        aliases: ["urn:email:john.smith@apple.com"],
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>


# Custom Event Properties
Source: https://docs.runconverge.com/sources/extending-the-spec/custom-event-properties

Add custom properties to the auto-tracked events

### Tracking custom event properties for auto-tracked events

If you're using one of our prebuilt source integrations, and you want to include custom properties (or modify existing properties) on these events, then you can do so using the `set` method.

Imagine, for example, that I want to send a custom property with my `Added To Cart` event.
I would then call the following function *before* the `Added To Cart` event is fired.

```js theme={null}
cvg({method: "set", eventProperties: {hello:"world"}})
```

When my `Added To Cart` event fires, it will now include the custom `hello -> world` property mapping.

You can modify profile properties in the same way, a full example of the function would be:

```js theme={null}
cvg({method: "set", properties: {...profileProperties}, eventProperties: {...eventProperties}})
```


# Custom Events
Source: https://docs.runconverge.com/sources/extending-the-spec/custom-events

Trigger custom events from your Website

## Overview

Although Converge will automatically track the essential events on your website, there are sometimes user actions that you may want to track that aren't tracked by default.
Converge allows you to do this either [with code](#track-custom-events-with-code) or [no-code](#track-custom-events-no-code)

***

## Track custom events with code

You can track custom events through code either on the client-side or on the server-side.

* <OutboundLink /> or <Tooltip> other client-side sources </Tooltip>.
* <OutboundLink />

***

## Track custom events no-code

Converge allows you to track arbitrary events with your client-side sources based on user actions with **no code changes**.

### Set up custom events for a source

Converge allows you to configure custom events for client-side sources.

<Accordion icon="location-dot" title="How to set up custom events for your Source">
  1. Navigate to the <OutboundLink /> page in your Converge dashboard
  2. Click on the client-side Source for which you want to configure a custom event.
  3. Click on the **Custom events** tab.
  4. Click on **Add custom event** to start configuring a new custom event.
  5. Fill in the **Event name**.
  6. Click on **Add trigger** to start configuring a trigger.
  7. Select the **Trigger type**.
  8. Click on **Add condition** to start configuring a condition.
  9. Select the **Condition variable**, **Condition operation** and **Condition value**.
  10. Repeat the above for every custom event, trigger and condition as needed.
  11. Click on **Save** to persist the custom events.
</Accordion>

### Definitions

#### Custom event

A custom event is any event you may want to track in the browser that is triggered by a particular user action. For example, you may want to track a `Joined wait list` event when the user clicks a link on your website, or a `Watched welcome video` when the user started watching an embedded video.

#### Trigger

Triggers are used to define which user actions will fire the events. When a trigger is defined, the Converge pixel will start listening to the specific events. Once a corresponding event has occurred, the custom event will be fired.

For example, you may want to fire a `Subscribed To Newsletter` event when a particular link is clicked. An **All Links Click** trigger may be used to fire the event.

<Note>
  A custom event can have one or more triggers configured. If multiple triggers are present, the custom event will be triggered when **ANY** of the triggers is fired.

  For example, you may want to fire the same `Subscribed To Newsletter` event when another link is pressed. A possible implementation would be to have two separate triggers (one for each link). As soon as any of the links are pressed, the event will be fired. There is no need for the user to perform both actions.
</Note>

All the supported triggers are listed in [Trigger types](#trigger-types).

#### Conditions

Conditions are used to limit the effect of individual triggers. When an event corresponding to a trigger is detected, the conditions linked to the trigger will be checked before firing the associated custom event.

For example, you may want to fire a `Subscribed To Newsletter` event when a link containing the text `Subscribe` is clicked. If the `All Elements Click` trigger is used without any conditions, the event will be fired as soon as any link is clicked. A condition may be added to limit the trigger to only fire if the clicked text contains the text `Subscribe`, for example.

<Note>
  A trigger can have zero or more conditions configured. If no conditions are present, the trigger will fire for any events. If multiple conditions are present, the trigger will only fire when **ALL** conditions are met.

  For example, you may want to fire a `Subscribed To Newsletter` event when a link containing the text `Subscribe` on the homepage of your website is clicked. A possible implementation would be to have an `All Elements Click` trigger containing two conditions: one for the `Click Text` and another for the `Page URL`.
</Note>

A condition consists of three parts:

* **Condition variable**: a variable to be compared, it can either be globally available (e.g. `Page URL`, `Referrer`, etc.) or trigger specific (e.g. `Click Element`, `Video Duration`, etc.). All supported values are listed in [Condition variables](#condition-variables).

* **Condition operator**: a condition to be applied to the variable.

* **Condition value**: the value to be compared against the variable.

***

## Trigger types

### All Elements Click

Tracks clicking on any element (e.g. links, images, buttons, etc.) in the page.

<Warning>
  If no conditions are applied to this trigger, it will fire every time a user clicks anything. Make sure to limit the scope of this trigger by being as specific as possible with its conditions, for example by applying filters on `Page URL`, `Click Element`, etc.
</Warning>

### All Links Click

Tracks clicking only on HTML links `<a>` and its descendants.

<Warning>
  If no conditions are applied to this trigger, it will fire every time a user clicks any link. Make sure to limit the scope of this trigger by being as specific as possible with its conditions, for example by applying filters on `Page URL`, `Click Element`, etc.
</Warning>

### Form Submission

Tracks the submission of HTML `<form>` elements in the page.

<Warning>
  If no conditions are applied to this trigger, it will fire every time a user submits any form. Make sure to limit the scope of this trigger by being as specific as possible with its conditions, for example by applying filters on `Page URL`, `Form Element`, etc.
</Warning>

### Page View

Tracks page view. It's triggered immediately upon page load.

### Timer

Tracks the elapsed time. It can be used to trigger events at regular intervals (e.g. every 5 seconds) or after a delay (e.g. after the user stays on the page for more than 10 seconds).

The timer trigger can be configured with the following settings:

* **Interval**: The interval (in milliseconds) between each trigger.

* **Limit**: The maximum number of times the trigger will fire.

### Video

Tracks interactions with HTML `<video>` elements.

The video trigger can be configured to capture one or multiple events:

* **Play**: triggers when the video begins to play

* **Paused**: triggers when the video is paused

* **Ended**: triggers when the video has ended

***

## Condition variables

### Click conditions

* **Click Element**: a reference to the DOM element that was clicked.
* **Click Classes**: the classes attribute of the clicked element as a string.
* **Click ID**: the ID attribute of the clicked element.
* **Click Target**: the target attribute of the clicked link.
* **Click URL**: the HREF attribute of the clicked link.
* **Click Text**: the text content of the clicked element.

### Form conditions

* **Form Element**: a reference to the DOM `<form>` element that was submitted.
* **Form Action**: the action URL of the submitted form.
* **Form Classes**: the classes attribute of the submitted form as a string.
* **Form ID**: the ID attribute of the submitted form.
* **Form Method**: the method attribute of the submitted form.
* **Form Target**: the target attribute of the submitted form.
* **Form Text**: the text content of the submitted form.

### Pages conditions

* **Page URL**: the full URL of the current page.
* **Page Hostname**: the hostname part of the URL of the current page.
* **Page Path**: the path part of the URL of the current page.
* **Referrer:** the full referrer URL for the current page.

### Video conditions

* **Video Element**: a reference to the DOM `<video>` element that was triggered.
* **Video URL**: the full URL of the video.
* **Video Duration**: the duration (in seconds) of the video.
* **Video Current Time**: the current time (in seconds) of the video when the event occurred.
* **Video Percent**: the percentage (as an integer between 0 and 100) of the video when the event occurred.
* **Video Status**: the video status (`playing`, `paused`, `ended` or `seeking`) of the video when the event occurred.

***

## Condition operators

In addition to common numeric (e.g. **lower than**, **greater than or equal to**, etc.) and string operators (e.g. **contains**, **starts with**, etc.), some condition variables also support additional more advanced operators:

* **matches RegEx**, **matches RegEx (ignore case)**, **does not match RegEx**, **does not match RegEx (ignore case)**

The **matches RegEx** and its related operators allow you to use [regular expressions](https://en.wikipedia.org/wiki/Regular_expression) for matching text patterns.

* **matches CSS selector**, **does not match CSS selector**

The **matches CSS selector** and its related operator allows you to use [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to filter HTML elements in the page. When used in combination with supported variables (e.g. **Click Element**, **Video Element**) it enables you to target specific HTML elements.

For example, if you want to target a particular `<a>` element that has a particular class that is an immediate child of an element with a known ID, you could use:

```
#some-known-id > a.some-class
```


# Derived Events
Source: https://docs.runconverge.com/sources/extending-the-spec/derived-events

Create new events from existing events

## Overview

Converge lets you automatically create new events based on the properties of existing ones, without writing any code.

***

## Set up derived events

<Accordion icon="location-dot" title="How to set up derived events">
  1. Navigate to the <OutboundLink /> page in your Converge dashboard.
  2. Click **Create new derived event** to start creating a new derived event.
  3. Fill in the **Derived Event Name**. This will be the name assigned to all new derived events matching your filter conditions.
  4. Under the filters, select a source event you want to trigger the creation of a derived event.
  5. Select the **Condition property**, **Condition operation**, and **Condition value** that the selected event's properties must match to create the derived event.
  6. Repeat for each condition as needed by clicking **Add condition**.
  7. Click **Save** to persist the derived event.
</Accordion>

Once configured, derived events will automatically be created whenever an event matches your specified filters. To forward these derived events to a destination, configure an [event mapping](/destinations/event-mapping#event-mapping) using the derived event name as the source event.

***

## Definitions

### Derived event

A derived event is any event you want to create that's triggered by an existing event's properties matching your desired filters. For example, you may want to track a `Subscription Purchase` event when a `Placed Order` event comes in that has a field `tag` containing the text `subscription`.

### Filters

Filters are used to define the conditions when a derived event should be created. They should include the name of the source event as well as conditions for each matching event property.

<Note>
  The `New Customer Order` derived event is created on setup for all users by default. It's not editable. It fires whenever a `Placed Order` event has `$is_new_customer` set to `true`. Prebuilt integrations like Shopify set this property automatically. Custom integrations should set it themselves, since Converge's fallback depends on the order history it already has on file. See [New customer status](/sources/concepts/new-customer-status) for the full rules.
</Note>

A condition consists of three parts:

* **Condition variable**: a variable to be compared. It can be any of the event's available properties (e.g. `Product names`, `coupons`, etc.).

* **Condition operator**: a condition to be applied to the variable.

* **Condition value**: the value to be compared against the variable.

<Note>
  The filters only work on the event's properties. Currently, it doesn't allow filtering on attribution, profile properties, session properties, or sources.

  For example, if you want to create derived events matching a certain condition from a particular source, you can't do this at the moment.
</Note>


# Overview
Source: https://docs.runconverge.com/sources/extending-the-spec/overview

Extend the Converge Spec with your own custom events, custom properties, and derived events

Converge allows you to extend each part of the Converge Spec.

* [Custom Events](../extending-the-spec/custom-events)
* [Custom Event Properties](../extending-the-spec/custom-event-properties)
* [Derived Events](../extending-the-spec/derived-events)


# GDPR Removal Request
Source: https://docs.runconverge.com/sources/gdpr-removal

Delete users data from Converge

If a user requests to delete their data under GDPR, contact support through the chat in your workspace or by email. Include one of the following identifiers:

* **Email address**
* **Converge Profile ID**

We’ll delete all associated data, including events. **This may affect reporting**.

We process removal requests within **30 days** of receiving them.


# Monitoring
Source: https://docs.runconverge.com/sources/monitoring

Test and monitor your Converge Integration

## Overview

Converge provides the following tools to monitor and debug whether your Sources are working correctly:

* [Source Logs](#source-logs)
* [Source Warnings](#source-warnings)
* [Pixel Monitor](#pixel-monitor)

***

## Source Logs

Converge stores detailed logs of every event that gets sent to Converge including [event properties](/sources/converge-spec), [profile properties](/sources/source-concepts#profile-properties) and [aliases](/sources/source-concepts#aliases).

### Where to find Source Logs

1. Navigate to the [Sources Tab](https://app.runconverge.com/-/sources) in your Converge dashboard
2. Click on the Source you want to debug

<Frame>
  <img alt="pick a source" />
</Frame>

3. Click on the **Logs** tab to see the logs

<Frame>
  <img alt="pick logs" />
</Frame>

4. Click on any of the Log Lines to inspect the **event properties**, **profile properties**, **aliases**, etc.

### Filter through the logs

* **By Event Name**: You can select a subset of events to show in the log by clicking on **Select events** and then ticking the relevant events.
* **By Date**: You can use the date picker in the right top corner to select log lines from a particular date range.

### Exporting logs

1. Navigate to the [Sources Tab](https://app.runconverge.com/-/sources) in your Converge dashboard
2. Click on the Source you want to debug

<Frame>
  <img alt="pick a source" />
</Frame>

3. Click on the **Logs** tab to see the logs

<Frame>
  <img alt="pick logs" />
</Frame>

4. You can export your log selection to CSV using the <IconText name="arrow-up-from-bracket" />-button in the right top corner.

<Note>
  Log entries are limited to 10,000 lines.
</Note>

***

## Source Warnings

Converge will automatically flag when events do not conform with the [Converge event spec](/sources/converge-spec) and give you pointers as to how to modify your events to be compliant with the spec.

### Where to find Source Warnings

1. Navigate to the [Sources Tab](https://app.runconverge.com/-/sources) in your Converge dashboard
2. Click on the Source you want to see logs from
   <img alt="pick a source" />
3. Click on the **Warnings** tab to see the appropriate warnings. Each warning includes information as to what `property` is malformed, as well as detailed log lines to inspect.
   <img alt="see warning info" />

***

## Pixel Monitor

### What is a Pixel Monitor

The Pixel Monitor verifies that your Converge tracking pixel is installed and working on your websites. It loads your site in a browser and checks for the Converge tracking script.

The monitor will display one of two statuses:

* **Pixel Installed**: The Converge pixel was successfully detected on your website
* **Pixel Not Found**: The monitor was unable to detect the Converge pixel

<Warning>
  The monitor loads your site through a **US-based browser**. It may not verify sites that use **geographic redirects** or require **user consent** before loading tracking scripts.
</Warning>

### Where to find the Pixel Monitor

1. Navigate to the [Sources Tab](https://app.runconverge.com/-/sources) in your Converge dashboard
2. Check the **Pixel Monitor** tab for the status of each source. Note that pixel monitor checks can only be performed on client-side sources.

<Frame>
  <img alt="pick a source" />
</Frame>

3. Click on the Source for which you would like to view monitoring details.
4. Access the **Monitors** tab to view pixel monitoring status. Each monitor performs automated checks every 24 hours to verify proper client-side pixel implementation.

<Frame>
  <img alt="see monitors" />
</Frame>

### How to create a Pixel Monitor

1. Click **Create Monitor** to add a new website monitoring configuration.

<Frame>
  <img alt="click create a monitor" />
</Frame>

2. Configure individual monitors for each website where the client-side pixel is deployed.

<Frame>
  <img alt="input website url" />
</Frame>


# Set up a proxy
Source: https://docs.runconverge.com/sources/proxy

Set up first-party tracking by passing Converge requests through your own domain

## Overview

By proxying requests to Converge through your own domain, Converge is no longer treated as a third-party script.
This has the following advantages:

* **First-party cookies**: When Converge runs on your main domain, we automatically set a first-party cookie.
  First-party cookies are not restricted by browser privacy features like Apple ITP. They are longer-lasting, allowing you to track longer user journeys.
* **Bypassing ad blockers**: Converge's domain can be blocked by ad blockers based on our domain name. Using your own domain lets you bypass these ad blockers.

## Installation instructions

There are two parts to proxying requests to Converge:

* **Hosting the script on your own domain** By proxying requests to `https://static.runconverge.com/pixels/*.js` the Converge script is loaded through your domain.
* **Proxying the tracking requests** By proxying requests to `https://app.runconverge.com/api/tr/*` the tracking requests are sent through your domain.

<Note>
  Ensure that the proxy sets the `X-Forwarded-For` header to the original IP address of the request.
</Note>

<Note>
  Ensure that the proxy sets the `X-Forwarded-Host` header to the domain name of your proxy.
</Note>

To let Converge know your proxied domain, update your Converge pixel snippet as follows:

<Steps>
  <Step>
    Update the `src` of the Converge script to point to your domain. Replace `xxxxxx` with your Converge pixel public token.

    ```html theme={null}
    <script src="https://yourdomain.com/cvg/static/pixels/xxxxxx.js" async></script>
    ```
  </Step>

  <Step>
    Include the `proxy` call to configure your proxied endpoints for static and tracking requests.

    ```javascript theme={null}
    cvg({method: "proxy", tracking: "https://yourdomain.com/cvg", static: "https://yourdomain.com/cvg/static"});
    ```

    This should happen before any tracking calls.
  </Step>
</Steps>

This would yield the following updated snippet:

```html theme={null}
<script src="https://yourdomain.com/cvg/static/pixels/xxxxxx.js" async></script>
<script>
window.cvg||(cvg=function(){cvg.process?cvg.process.apply(cvg,arguments):cvg.queue.push(arguments)},cvg.queue=[]);
cvg({method: "proxy", tracking: "https://yourdomain.com/cvg", static: "https://yourdomain.com/cvg/static"});
cvg({method:"track",eventName:"$page_load"});
</script>
```

### Setting up a proxy through Nginx

If you're using Nginx as your web server or reverse proxy, you can configure it to proxy requests to Converge. Below is a complete working configuration example.

```nginx theme={null}
server {
    listen 80;
    server_name cvg.yourdomain.com;

    # DNS resolver needed for proxy_pass to HTTPS upstreams
    resolver 8.8.8.8 ipv6=off valid=300s;

    # Forward original client information
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host  $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP         $remote_addr;

    # Use HTTP/1.1 to keep upstream connections open
    proxy_http_version 1.1;
    proxy_set_header Connection "";

    # =========================
    # 1) STATIC PIXELS
    #    Proxy /pixels/ to static.runconverge.com
    # =========================
    location ^~ /pixels/ {
        proxy_pass https://static.runconverge.com/pixels/;
        proxy_set_header Host static.runconverge.com;
        proxy_ssl_server_name on;
        proxy_ssl_name static.runconverge.com;

        # CORS headers for pixel JavaScript
        add_header Access-Control-Allow-Origin * always;
        add_header Access-Control-Allow-Methods "GET, OPTIONS" always;

        # Handle preflight requests
        if ($request_method = OPTIONS) {
            return 204;
        }
    }

    # =========================
    # 2) TRACKING REQUESTS
    #    Proxy /api/tr/ to app.runconverge.com
    # =========================
    location ^~ /api/tr/ {
        # Handle CORS preflight requests
        if ($request_method = OPTIONS) {
            add_header Access-Control-Allow-Origin  $http_origin always;
            add_header Access-Control-Allow-Credentials true always;
            add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
            add_header Access-Control-Allow-Headers $http_access_control_request_headers always;
            add_header Access-Control-Max-Age 86400 always;
            add_header Vary "Origin, Access-Control-Request-Headers, Access-Control-Request-Method" always;
            return 204;
        }

        # Hide CORS headers from upstream to avoid conflicts
        proxy_hide_header Access-Control-Allow-Origin;
        proxy_hide_header Access-Control-Allow-Credentials;
        proxy_hide_header Access-Control-Allow-Methods;
        proxy_hide_header Access-Control-Allow-Headers;

        proxy_pass https://app.runconverge.com/api/tr/;
        proxy_set_header Host app.runconverge.com;
        proxy_ssl_server_name on;
        proxy_ssl_name app.runconverge.com;

        # CORS headers for actual responses
        add_header Access-Control-Allow-Origin $http_origin always;
        add_header Access-Control-Allow-Credentials true always;
        add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
        add_header Vary "Origin, Access-Control-Request-Headers, Access-Control-Request-Method" always;
    }

    # Everything else returns 404
    location / {
        return 404;
    }
}
```

After setting up your Nginx configuration:

1. Test the configuration: `nginx -t`
2. Reload Nginx: `systemctl reload nginx` or `nginx -s reload`
3. Update your Converge pixel snippet to use your proxy domain:

```html theme={null}
<script src="https://cvg.yourdomain.com/pixels/xxxxxx.js" async></script>
<script>
window.cvg||(cvg=function(){cvg.process?cvg.process.apply(cvg,arguments):cvg.queue=[]);
cvg({method: "proxy", tracking: "https://cvg.yourdomain.com", static: "https://cvg.yourdomain.com"});
cvg({method:"track",eventName:"$page_load"});
</script>
```

#### FAQ

<Accordion title="I am getting 404/410 errors when making requests?">
  If you're getting 404 or 410 errors and don't see traffic reaching Converge's servers, this is typically caused by a missing DNS resolver directive.
  Add `resolver 8.8.8.8 ipv6=off valid=300s;` to your server block.
</Accordion>

### Setting up a proxy through Vercel rewrites

If your site is hosted on Vercel, you can use the vercel.json configuration file to easily set up a proxy to Converge.

```json theme={null}
{
  "rewrites": [
    {
      "source": "/cvg/static/:path*",
      "destination": "https://static.runconverge.com/:path*"
    },
    {
      "source": "/cvg/:path*",
      "destination": "https://app.runconverge.com/api/tr/:path*"
    }
  ]
}
```

<Accordion title="Advanced implementation">
  If you want to make sure that your proxy is only used for the pixels in your Converge workspace you can add some extra conditions to the configuration file.

  Replace `xxxxxx` with your Converge pixel public token and YY-YYYYYYY with the GTAG ID from Google Analytics 4 or Google Ads.

  ```json theme={null}
  {
    "rewrites": [
      {
        "source": "/cvg/static/pixels/xxxxxx.js",
        "destination": "https://static.runconverge.com/pixels/xxxxxx.js"
      },
      {
        "source": "/cvg/static/js",
        "has": [
          { "type": "query", "key": "tid", "value": "YY-YYYYYYY" }
        ],
        "destination": "https://static.runconverge.com/js"
      },
      {
        "source": "/cvg/sgtm",
        "has": [
          { "type": "query", "key": "ep.cvg_public_token", "value": "xxxxxx" }
        ],
        "destination": "https://app.runconverge.com/api/tr/sgtm"
      },
      {
        "source": "/cvg/:method",
        "has": [
          { "type": "query", "key": "public_token", "value": "xxxxxx" }
        ],
        "destination": "https://app.runconverge.com/api/tr/:method"
      }
    ]
  }
  ```
</Accordion>

Update your Converge pixel snippet to the following:

```html theme={null}
<script src="/cvg/static/pixels/xxxxxx.js" async></script>
<script>
window.cvg||(cvg=function(){cvg.process?cvg.process.apply(cvg,arguments):cvg.queue.push(arguments)},cvg.queue=[]);
cvg({method: "proxy", tracking: "https://yourdomain.com/cvg", static: "https://yourdomain.com/cvg/static"});
cvg({method:"track",eventName:"$page_load"});
</script>
```

After deploying the changes, verify that

* static scripts like the Converge pixel and GTAG's load from your own domain
* tracking requests to `/tr/*` are proxied through your domain
* the response headers from the `/tr/track` call include the `Set-Cookie` header which sets a `__cvg_1p_uid` cookie


# Amazon
Source: https://docs.runconverge.com/sources/server-integrations/amazon

Connect your Amazon account to Converge

## Installation instructions

<Steps>
  <Step title="Create a new Server-side source in Converge">
    1. In Converge, go to Event sources
    2. Click on **Create a new source**
    3. Pick *Server-side* from the modal
    4. Choose **Amazon**
    5. Name your source: e.g. `Amazon Orders`
  </Step>

  <Step title="Connect your Amazon account">
    6. Click on **Connect Amazon**
    7. You'll be redirected to Amazon to authorize the connection
    8. Sign in with your Amazon account credentials
    9. Review and approve the permissions requested by Converge
    10. You'll be redirected back to Converge
    11. Select your Amazon region from the dropdown
  </Step>

  <Step title="Complete setup">
    12. Once you've selected your region, click on **Create Source**
  </Step>
</Steps>

<Note>You should see the Source syncing all historical order data. No need to wait before it's fully synced to create destinations—we'll automatically check which orders are historic and new and forward only the new ones if a destination is active while historically syncing.</Note>

<Note>We'll only sync orders once they leave the **pending** state. Orders stay in pending while waiting for payment authorization, which typically takes a day or two but can take longer.</Note>

<Warning>This integration currently only works for third-party (3P) sellers. If you are a first-party seller and would like support, please reach out to us.</Warning>

***

## Event spec

This integration auto-tracks the following events on the server with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                          | Event Description                |
| --------------------------------------------------- | -------------------------------- |
| [Placed Order](/sources/converge-spec#placed-order) | When a customer places an order. |

### Sales channels

Events received by Converge from Amazon are automatically mapped to Converge's [sales channels types](/sources/concepts/sales-channels).

All orders from Amazon are mapped to the **amazon** sales channel type.

More on sales channels can be found [here](/sources/concepts/sales-channels).

| Amazon     | Converge | Description                    |
| ---------- | -------- | ------------------------------ |
| All orders | amazon   | Orders from Amazon marketplace |


# BigCommerce
Source: https://docs.runconverge.com/sources/server-integrations/bigcommerce

Connect your BigCommerce store backend to Converge

<Note> This is a webhook-based source, meaning that it does not sync historical data. </Note>

## Installation instructions

<Steps>
  <Step title="Navigate to your Store-level API Tokens">
    1. Go to <OutboundLink />  and click <IconText name="plus" />.
  </Step>

  <Step title="Configure your API Token">
    2. Select **V2/V3 API token** as your **Token type**.
    3. Enter `Converge` in the **Name**-field
    4. Keep note of the API path, you will need it later.
    5. Under **OAuth Scopes**, grant Converge **read-only** access to all available scopes.
    6. Click **Save**. You will be prompted to download a `.txt` file containing the credentials you will need to set up your Converge source.
  </Step>

  <Step title="Create a new Server-side source in Converge">
    7. In Converge, click on **Create a new source**
    8. Pick *Server-side* from the modal
    9. Name your source: e.g. `{Storename} Store Backend`
    10. Choose the **BigCommerce** app from the dropdown menu.
  </Step>

  <Step title="Connect the Source to BigCommerce">
    11. Enter the hash parameter from the API path retrieved in *Step 4*.
        <Info> If your API path is `https://api.bigcommerce.com/stores/xxxxxx/`, the hash is `xxxxxx`. </Info>
    12. Paste the Access Token from the `.txt` file in *Step 6* in the **Access Token** field.
    13. Unless you have a good reason not to, you should leave **Storefronts** and **Start Date** blank. Click on **Create Source**.
        <Info> You might have multiple storefronts of which only one is relevant for Converge. In that case, you can pass the specific storefront name under **Storefronts** and Converge will only sync orders belonging to that Storefront.</Info>
  </Step>
</Steps>

***

## Event spec

This integration auto-tracks the following events on the server with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                          | Event Description                |
| --------------------------------------------------- | -------------------------------- |
| [Placed Order](/sources/converge-spec#placed-order) | When a customer places an order. |

### Sales channels

Events received by Converge from BigCommerce are automatically mapped to Converge's [sales channels types](/sources/concepts/sales-channels) whenever possible.

More on sales channels can be found [here](/sources/concepts/sales-channels).

<Note> Converge falls back to "web" if a mapping cannot be found. This is typically the case with third-party integrations with BigCommerce. </Note>

An example of how Converge maps BigCommerce sales channels:

| Bigcommerce         | Converge       | Description                                                     |
| ------------------- | -------------- | --------------------------------------------------------------- |
| www                 | web            | Browser                                                         |
| iphone              | web            | iPhone web                                                      |
| ipad                | web            | iPad web                                                        |
| android             | web            | Android web                                                     |
| mobile              | web            | mobile browser                                                  |
| external            | -              | Orders API - depends on third party integration (e.g. Recharge) |
| manual              | offline        | Manual Order                                                    |
| checkout\_api       | web            | Checkout API                                                    |
| buybutton           | web            | Buy Button                                                      |
| amazon              | marketplace    | Amazon integration                                              |
| ebay                | marketplace    | Ebay integration                                                |
| facebookcheckout    | facebook\_shop | Facebook Checkout                                               |
| facebookshop        | facebook\_shop | Facebook Shop                                                   |
| facebookmarketplace | facebook\_shop | Facebook Marketplace                                            |
| pinterest           | facebook\_shop | Pinterest                                                       |
| socialshop          | marketplace    | Social Shop                                                     |


# Firmhouse
Source: https://docs.runconverge.com/sources/server-integrations/firmhouse

Connect your Firmhouse subscription events to Converge

## Installation instructions

Firmhouse is primarily used as a subscription backend and checkout that is run in parallel with an ecommerce platform such as Shopify, but some merchants choose to run Firmhouse standalone without a shopping backend.
Your Converge configuration will depend on your specific Firmhouse setup.

<Steps>
  <Step title="Navigate to the Firmhouse Admin Dashboard">
    1. Navigate to your <OutboundLink />
  </Step>

  <Step title="Create your API token">
    2. Click on **Integrations** in the side panel
       <Frame>
         <img alt="integrations" />
       </Frame>
    3. Click on **Generate new token**, choose **No expiration** and choose **Write** as your Access Type, click on **Create project access token**.
    4. Copy the token you just created, you will need it later.
  </Step>

  <Step title="Create a new Server-side source in Converge">
    5. In Converge, click on **Create a new source**
    6. Pick *Server-side* from the modal
    7. Name your source: e.g. `{Storename} Subscriptions`
  </Step>

  <Step title="Connect and configure the Source">
    8. Choose **Firmhouse** as the app you want to connect.

    9. Enter the Firmhouse access token you created in *Step 4*.

    10. Review the options and pick how the subscription value of the `Started Subscription` event in Converge should be calculated. If you are unsure, ask your contact at Firmhouse for a recommendation.
        <Frame>
          <img alt="subscription value" />
        </Frame>

    11. The next step depends on whether you are running Firmhouse side-by-side Shopify, or standalone.

        <Tabs>
          <Tab title="Shopify and Firmhouse">
            Choose **Shopify** as your **Product and variant ID** and make sure **Track Firmhouse invoices as Placed Order events** is turned **off**.

            <Frame>
              <img alt="" />
            </Frame>
          </Tab>

          <Tab title="Only Firmhouse">
            Choose **Firmhouse** as your **Product and variant ID** and make sure **Track Firmhouse invoices as Placed Order events** is turned **on**.

            <Frame>
              <img alt="" />
            </Frame>
          </Tab>
        </Tabs>

    12. You can ignore shipment date and leave Start Date blank and click on **Create Source**.
  </Step>
</Steps>

***

## Event spec

This integration auto-tracks the following events on the server with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                                          | Event Description                      |
| ------------------------------------------------------------------- | -------------------------------------- |
| [Started Subscription](/sources/converge-spec#started-subscription) | When a customer starts a subscription. |
| [Placed Order](/sources/converge-spec#started-subscription)\*       | When a customer places and order.      |

\*Only when configured in the Source configuration.

### Sales channels

More on sales channels can be found [here](/sources/concepts/sales-channels).

An example of how Converge map Firmhouse events:

| Firmhouse             | Converge Mapping              | Description                                                                                                                      |
| --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Started Subscription  | web                           | New subscription triggered                                                                                                       |
| Placed Order          | web or subscription\_contract | Recurring placed order events are mapped to "subscription\_contract" while first time and one time purchases are mapped to "web" |
| Placed Shipment Order | offline                       | Placed shipment orders                                                                                                           |


# Magento 2
Source: https://docs.runconverge.com/sources/server-integrations/magento

Connect your Magento 2 store backend to Converge

## Installation instructions

<Steps>
  <Step title="Set the Configuration">
    1. Open your terminal or command prompt and navigate to the root directory of your Magento 2 installation.
    2. Execute the following command to set the `oauth/consumer/enable_integration_as_bearer` configuration option to `1`.

    ```bash bash theme={null}
    bin/magento config:set oauth/consumer/enable_integration_as_bearer 1
    ```
  </Step>

  <Step title="Verify the Configuration">
    3. To ensure that the configuration has been set correctly, you can check the value using the following command:

    ```bash bash theme={null}
    bin/magento config:show oauth/consumer/enable_integration_as_bearer
    ```

    4. The output should confirm that the value is set to `1`.
  </Step>

  <Step title="Navigate to your Magento Integration Settings">
    5. Navigate to your Magento Admin Dashboard.
    6. From the Menu Sidebar, navigate to the **System** > **Extensions** > **Integrations** submenu.
  </Step>

  <Step title="Generate your Magento Admin Access Token">
    7. Choose to generate a new key, and choose `Sales/Operations/Orders/Actions/View` as your scope.
    8. Copy the generated access token, you will need it in the next step.
  </Step>

  <Step title="Create a new Server-side source in Converge">
    9. In Converge, click on **Create a new source**
    10. Pick *Server-side* from the modal
    11. Name your source: e.g. `{Storename} Store Backend`
    12. Choose the **Magento v2** app from the dropdown menu.
  </Step>

  <Step title="Connect the Source to Magento">
    13. Enter the full URL of the REST API of your Magento 2 store in the  **API URL**-field, including `https://`, e.g. `https://myshop.com/rest`
    14. If your storefront is hosted on a different domain than your API, please provide the domain in the **Storefront domain**.
        This domain should match the domain on which the Magento Storefront Module was installed. For example, `myshop.com`.
        Feel free to leave this blank if your store is hosted on the same domain.
    15. Paste in the Admin Access Token you retrieved in the previous section in the **Admin Access Token**.
    16. Optionally, filter out orders by store view or modify the start date. You should leave these fields blank if you do not have a good reason to use them.
  </Step>
</Steps>

<Note> You should see the Source syncing all historical order data, you should wait until it's fully synced to create destinations </Note>

## Configuration

### Storefront domain

If your storefront is hosted on a different domain than your API, please provide the domain in the **Storefront domain**.
This domain should match the domain on which the Magento Storefront Module was installed.
For example, `www.example.com`.

<Note>
  Pay attention to provide the full domain here. Depending on your setup, it might be necessary to include `www.`, or not.
  You can inspect the full domain in the browser's address bar when you visit your storefront. Click on the address bar to see the full URL.
</Note>

### Filter by store view name

You can scope your Magento integration to only include orders from a specific store view.
This may be useful if you have multiple store views in your Magento installation and want to separate them out in Converge.

### Only track orders once they reach a status

You can customize where in the order lifecycle Converge starts tracking orders.
This can be useful if you want to exclude unconfirmed orders or only track orders that have been paid for.

The default order status lifecycle is documented by Magento <OutboundLink />.

<Accordion title="Default lifecycle example">
  For the default order lifecycle, you could specify `processing` to only track orders that have been paid for.

  The order reaches the `processing` status after the payment has been confirmed, before it is shipped.
</Accordion>

<Note>
  Converge will track the order whenever it reaches any of the specified status. The order may still go through multiple transitions after this point.
</Note>

<Warning>
  Depending on your Magento installation, the order lifecycle may have been customized.
  Make sure to consult on any changes with your Magento developer.
</Warning>

***

## Event spec

This integration auto-tracks the following events on the server with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                          | Event Description                |
| --------------------------------------------------- | -------------------------------- |
| [Placed Order](/sources/converge-spec#placed-order) | When a customer places an order. |


# Recharge
Source: https://docs.runconverge.com/sources/server-integrations/recharge

Connect your Recharge subscription events to Converge

## Installation instructions

<Steps>
  <Step title="Navigate to the Recharge Admin Dashboard">
    1. In your Shopify Admin Dashboard, navigate to `Apps` > `Recharge`.
    2. Verify in the menu bar that you have access to the **API Tokens** submenu.
       <Note>Only Storeowners can view and access API tokens by default. If you do not see the option for API tokens, you will have to ask your storeowners to update your account permissions. </Note>
  </Step>

  <Step title="Create your token">
    3. Click on **Create an API Token**.
    4. For each of the scopes, provide `Read access`.
    5. Click on **Save** and copy your token.
  </Step>

  <Step title="Create a new Server-side source in Converge">
    6. In Converge, click on **Create a new source**
    7. Pick *Server-side* from the modal
    8. Name your source: e.g. `{Storename} Subscriptions`
  </Step>

  <Step title="Connect the Source">
    9. Enter the Recharge API Token.
    10. Click on **Create Source**.
  </Step>
</Steps>

<Note>This source is webhook-based, meaning historical data won't be synced in.</Note>

***

## Event spec

This integration auto-tracks the following events on the server with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                                              | Event Description                           |
| ----------------------------------------------------------------------- | ------------------------------------------- |
| [Started Subscription](/sources/converge-spec#started-subscription)     | When a customer starts a subscription.      |
| [Cancelled Subscription](/sources/converge-spec#cancelled-subscription) | When a customer cancels their subscription. |

[//]: # "TODO: The RecurringSubscriptionPayment event and Skipped Subscription should be included"

### Sales channels

More on sales channels can be found [here](/sources/concepts/sales-channels).

The following events are mapped to the following sales channel types:

| Recharge                            | Converge Mapping       | Description                                                     |
| ----------------------------------- | ---------------------- | --------------------------------------------------------------- |
| Started Subscription                | web                    | Browser-based interactions and actions                          |
| Placed Recurring Subscription Order | subscription\_contract | Automated events related to subscription renewals or contracts. |
| Cancelled Subscription              | subscription\_contract |                                                                 |
| Activated Subscription              | subscription\_contract |                                                                 |
| Paused Subscription                 | subscription\_contract |                                                                 |
| Skipped Subscription                | subscription\_contract |                                                                 |
| Unskipped Subscription              | subscription\_contract |                                                                 |


# Shopify
Source: https://docs.runconverge.com/sources/server-integrations/shopify

Connect your Shopify store backend to Converge

## Installation instructions

<Note>
  If you have access to the Shopify store as a **User**, please follow the steps below in the **Store Account**-tab.
  If you have access to the Shopify store as a **Partner**, please follow the steps in the **Partner Account**-tab.
</Note>

<Tabs>
  <Tab title="Store Account">
    <Steps>
      <Step title="Create a custom Shopify app">
        1. Go to the [Shopify Developer Portal](https://dev.shopify.com/dashboard)
        2. From the Dev Dashboard, be sure you're on Apps in the left-panel navigation and select **Create app** in the top, right corner of the screen.

        <Frame>
          <img alt="create-app" />
        </Frame>

        3. Select **Start from Dev Dashboard**.

        <Frame>
          <img alt="start-from-dev-dashboard" />
        </Frame>

        4. Name your app, e.g. `Converge Server-side Integration`, then select **Create**.
           You don't need to configure anything else on this page for now.
      </Step>

      <Step title="Configure your app access">
        5. Click on **Versions** in the left-panel navigation and **Create a version**.

        <Frame>
          <img alt="create-version" />
        </Frame>

        9. Under **App URL**, enter `https://app.runconverge.com`.

        <Frame>
          <img alt="app-url" />
        </Frame>

        10. Untick the "Embed app in Shopify admin" checkbox.
        11. In the textbox, under **Access > Scopes**, paste the following text:

        ```text theme={null}
        read_customer_events, read_customers, read_orders, read_products, read_all_orders
        ```

        <Frame>
          <img alt="scopes" />
        </Frame>

        <Warning>
          If you get a warning that the `read_all_orders`-scope does not exist, then you are most likely a **Partner Account** and you should **follow the steps in the "Partner Account"-tab** instead.
        </Warning>

        12. In the textbox, under **Access > Redirect URLs**, paste the following text:

        ```text theme={null}
        https://app.runconverge.com/api/datasources/shopify/partner/auth
        ```

        <Frame>
          <img alt="redirect-urls" />
        </Frame>

        13. In the bottom right corner, click **Release** and then click **Release** again to confirm. You don't need to provide a version name.

        <Frame>
          <img alt="scopes-release" />
        </Frame>

        <Frame>
          <img alt="release-confirmation" />
        </Frame>

        14. In the left-panel navigation, click on **Settings** for the app you just created.
            Note down the **Client ID** and **Secret**, you'll need to enter them in Converge later.

        <Frame>
          <img alt="settings-credentials" />
        </Frame>
      </Step>

      <Step title="Install the app in your Shopify store">
        15. In the left-panel navigation, click on **Home** and click on "Install app".

        <Frame>
          <img alt="manage-custom-install-link" />
        </Frame>

        16. Select the store you want to install the app, and click "Install". You'll then be redirected to Converge.

        <Frame>
          <img alt="manage-custom-install-link" />
        </Frame>
      </Step>

      <Step title="Create the Shopify source in Converge">
        17. In Converge, go to Event sources and click on **Create a new source**.
        18. Name your source: e.g. `{Storename} Store Backend`
        19. Pick *Server-side* from the modal and choose the **Shopify** app from the dropdown menu.
        20. Enter the **Store domain** of the Shopify store you want to use Converge for, this is the string before `myshopify.com` in the Shopify URL.
        21. Paste the **Client ID** and **Secret** from the Dev Dashboard in the respective fields.
        22. Click **Authorize Shopify Custom App**.
        23. Click on **Create Source**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Partner Account">
    <Steps>
      <Step title="Create a custom Shopify app">
        1. Go to the [Shopify Developer Portal](https://dev.shopify.com/dashboard)
        2. From the Dev Dashboard, be sure you're on Apps in the left-panel navigation and select **Create app** in the top, right corner of the screen.

        <Frame>
          <img alt="create-app" />
        </Frame>

        3. Select **Start from Dev Dashboard**.

        <Frame>
          <img alt="start-from-dev-dashboard" />
        </Frame>

        4. Name your app, e.g. `Converge Server-side Integration`, then select **Create**.
           You don't need to configure anything else on this page for now.
      </Step>

      <Step title="Configure your app access">
        5. In the left-panel navigation, click on **Home**.
           In the **Distribution** section, click on **Select distribution method**.
           This will open a new modal in the Partners Dashboard.

        <Frame>
          <img alt="home-distribution" />
        </Frame>

        6. Select **Custom distribution** and confirm your selection in the popup.

        <Frame>
          <img alt="custom-distribution" />
        </Frame>

        <Frame>
          <img alt="confirm-custom-distribution" />
        </Frame>

        7. In the left-panel navigation, now navigate to **API access requests** and click on **Request access** under the **Read all orders scope** section.
           You can copy the explanation below and click on submit, it will get approved automatically.

        ```text theme={null}
        Historical order analytics.
        ```

        <Frame>
          <img alt="api-access-requests" />
        </Frame>

        <Frame>
          <img alt="request-access-form" />
        </Frame>

        8. Go back to your previous tab in the Dev Dashboard. Click on **Versions** in the left-panel navigation and **Create a version**.

        <Frame>
          <img alt="create-version" />
        </Frame>

        9. Under **App URL**, enter `https://app.runconverge.com`.

        <Frame>
          <img alt="app-url" />
        </Frame>

        10. Untick the "Embed app in Shopify admin" checkbox.
        11. In the textbox, under **Access > Scopes**, paste the following text:

        ```text theme={null}
        read_customer_events, read_customers, read_orders, read_products, read_all_orders, read_reports
        ```

        <Frame>
          <img alt="scopes" />
        </Frame>

        12. In the textbox, under **Access > Redirect URLs**, paste the following text:

        ```text theme={null}
        https://app.runconverge.com/api/datasources/shopify/partner/auth
        ```

        <Frame>
          <img alt="redirect-urls" />
        </Frame>

        13. In the bottom right corner, click **Release** and then click **Release** again to confirm. You don't need to provide a version name.

        <Frame>
          <img alt="scopes-release" />
        </Frame>

        <Frame>
          <img alt="release-confirmation" />
        </Frame>

        14. In the left-panel navigation, click on **Settings** for the app you just created.
            Note down the **Client ID** and **Secret**, you'll need to enter them in Converge later.

        <Frame>
          <img alt="settings-credentials" />
        </Frame>
      </Step>

      <Step title="Install the app in your Shopify store">
        15. In the left-panel navigation, click on **Home** and navigate to the "Manage custom install link" in the "Distribution" section.

        <Frame>
          <img alt="manage-custom-install-link" />
        </Frame>

        16. Enter the **Store domain** of the Shopify store you want to use Converge for and click **Generate link**.

        <Frame>
          <img alt="store-domain-generate" />
        </Frame>

        <Frame>
          <img alt="generate-link-confirm" />
        </Frame>

        17. Copy the link and paste it in a new tab. Complete the installation flow.

        <Frame>
          <img alt="copy-install-link" />
        </Frame>

        <Frame>
          <img alt="shopify-partners-page" />
        </Frame>
      </Step>

      <Step title="Create the Shopify source in Converge">
        18. In Converge, go to Event sources and click on **Create a new source**.
        19. Name your source: e.g. `{Storename} Store Backend`
        20. Pick *Server-side* from the modal and choose the **Shopify** app from the dropdown menu.
        21. Enter the **Store domain** of the Shopify store you want to use Converge for, this is the string before `myshopify.com` in the Shopify URL.
        22. Paste the **Client ID** and **Secret** from the Dev Dashboard in the respective fields.
        23. Click **Authorize Shopify Custom App**.
        24. Click on **Create Source**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Warning>
  The installation instructions previously relied on creating a **custom Shopify app through the admin panel**.
  This is **no longer supported** by Shopify and is now replaced by the Developer Portal.
  Please follow the new installation instructions above for any new installations.

  If you already have a custom app for Converge from **before Jan 1st, 2026**, you can still use the **legacy** instructions below.

  <Accordion icon="store" title="Legacy installation instructions">
    <Steps>
      <Step title="Create a custom Shopify app">
        1. Navigate to the Shopify Admin dashboard, and click on **Settings**
        2. Click on **Apps and sales channels** in the Settings modal.
        3. Click on **Develop apps**, you might have to choose **allow custom app development** in a pop-up
        4. Click on **Create an app**, give the app the name `Converge` and choose your own email address as the developer.
      </Step>

      <Step title="Configure the correct scopes">
        5. Choose **Configure Admin API scopes** and mark the following 4 scopes (i) `read_customer_events`, (ii) `read_customers`, (iii) `read_orders` (iv) `read_products`
      </Step>

      <Step title="Install the custom app to get the token">
        6. Click on **Save** and then **Install app**. Reveal and copy the **Admin API access token**
      </Step>

      <Step title="Create a new Server-side source in Converge">
        7. In Converge, go to Event sources
        8. Click on **Create a new source**
        9. Pick *Server-side* from the modal
        10. Name your source: e.g. `{Storename} Store Backend`
      </Step>

      <Step title="Connect the Source">
        11. Enter the store name, this is the string before `myshopify.com` in the Shopify URL. E.g. For `convergestore.myshopify.com` the store name would be `convergestore`
        12. Paste the Shopify Access Token in the Converge web app under **Shopify API Password**. Do not fill in a starting date, just click on **Create source**
        13. Click on **Create Source**.
      </Step>
    </Steps>
  </Accordion>
</Warning>

<Note> You should see the Source syncing all historical order data. No need to wait before it's fully synced to create destinations—we'll automatically check which orders are historic and new and forward only the new ones in case a destination is active while historically syncing. </Note>

***

## Post-Purchase Upsells

Many Shopify stores use post-purchase upsells such as <OutboundLink />.
After placing an order, the customer will be prompted to add a new item to the order.

If the customer accepts the upsell, **the original order will be modified by the upsell app**.
For this reason, the only way to track these post-purchase upsells reliably is server-side (as the order is modified server-side).

The Shopify Server Integration supports upsell tracking by introducing an optional delay in the integration settings.
If you turn on this delay, Converge will wait 10 minutes for the upsell to come in before forwarding it to destinations.

You can turn this option on in the configuration of the integration:

<Frame>
  <img alt="upsell app intro" />
</Frame>

<Warning>Please contact Converge support before enabling this feature.</Warning>

<Note> This will only work with Destinations that support server-side events. Client-side destinations will not track the upsell. </Note>

***

## Filtering out certain orders at ingestion

You might want to make sure certain order types never make it into Converge (e.g. test orders).

The Converge Shopify source allows you to configure order exclusions based on their channel or applied tag.
E.g. You can filter out all `pos` orders or filter out all orders with an `Exclude` tag.

To configure, navigate to <OutboundLink /> and click on your Shopify source.
Then, under configuration mark the exact criteria by which you want to exclude orders from arriving in Converge.

<Frame>
  <img alt="source-filters" />
</Frame>

***

## Event spec

This integration auto-tracks the following events on the server with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                          | Event Description                |
| --------------------------------------------------- | -------------------------------- |
| [Placed Order](/sources/converge-spec#placed-order) | When a customer places an order. |

This integration also auto-tracks some additional events that are not part of the Converge event spec.

| Event Name      | Event Description                 |
| --------------- | --------------------------------- |
| Received Refund | When a customer refunds an order. |

### Sales channels

Events received by Converge from Shopify are automatically mapped to Converge’s [sales channels types](/sources/concepts/sales-channels) whenever possible.
Shopify's various sales channels, such as the web, shop app, and marketplace integrations, are translated into Converge’s standardized sales channels types based on the context and source of each event.

For example, events originating from Shopify checkout are mapped to the web sales channel, while those from POS systems or third-party marketplaces (like Amazon) are categorized as pos and marketplace, respectively.

More on sales channels can be found [here](/sources/concepts/sales-channels).

<Note> Due to the extensive nature of Shopify's sales channels and tight integration with third-party apps, it may be difficult to get an accurate sales channels mapping. As such, Converge falls back to "web" if a mapping cannot be found. </Note>

An example of how Converge maps Shopify sales channels:

| Shopify                | Converge               | Description                                                      |
| ---------------------- | ---------------------- | ---------------------------------------------------------------- |
| web                    | web                    | Shopify checkout                                                 |
| subscription\_contract | subscription\_contract | Recurring placed order events, and third party subscription apps |
| shopify\_draft\_order  | offline                | Manual orders                                                    |
| pos                    | pos                    | Point of sales orders                                            |
| 12875497473            | web                    | Shopify headless                                                 |
| Edit Order             | offline                | Orders that are manually edited                                  |
| 3890849                | marketplace            | Shopify Shop App                                                 |
| 2329312                | facebook\_shop         | Meta/Facebook Checkout                                           |
| 4383523                | tiktok\_shop           | Tiktok Checkout integration                                      |
| 3009811                | pinterest\_shop        | Pinterest Checkout                                               |
| amazon                 | marketplace            | Amazon integration                                               |


# Skio
Source: https://docs.runconverge.com/sources/server-integrations/skio

Connect your Skio subscription events to Converge

## Installation instructions

<Steps>
  <Step title="Navigate to the Skio Admin Dashboard">
    1. Navigate to your Skio Admin Dashboard.
  </Step>

  <Step title="Create your token">
    2. Click on **Account** > **API**
    3. Give your token a name: e.g. `Converge`
    4. Click on **Generate API Key** and copy the key, you will need it later.
  </Step>

  <Step title="Create a new Server-side source in Converge">
    5. In Converge, click on **Create a new source**
    6. Pick *Server-side* from the modal
    7. Name your source: e.g. `{Storename} Subscriptions`
  </Step>

  <Step title="Connect the Source">
    8. Choose **Skio** as your app.
    9. Enter the Skio API Token.
    10. Fill in your Store Name.
    11. Click on **Create Source**.
  </Step>
</Steps>

***

## Event spec

This integration auto-tracks the following events on the server with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                                          | Event Description                      |
| ------------------------------------------------------------------- | -------------------------------------- |
| [Started Subscription](/sources/converge-spec#started-subscription) | When a customer starts a subscription. |

### Sales channels

Currently all 'Started Subscription' events are categorized as "web" sales channel type, given this event corresponds to a web user journey.

More on sales channels can be found [here](/sources/concepts/sales-channels).


# Converge Webhook
Source: https://docs.runconverge.com/sources/server-integrations/webhook

Connect your Server-side data to Converge

## Installation instructions

<Steps>
  <Step title="Create a new Webhook Source in Converge">
    1. In Converge, click on **Create a new source**
    2. Pick *Server-side* from the modal
    3. Name your server-side source: e.g. `{Storename} Store Backend`
    4. Click on **Create Source**.
  </Step>

  <Step title="Send a test event">
    4. Click on your newly created source. You'll see a webhook endpoint URL and webhook token under the source configuration tab.
       <img alt="webhook_config" />

    <Note>
      The webhook token was added recently to improve error messaging for easier issue diagnosis. Existing integrations that don't use a webhook token remain unaffected.
    </Note>

    5. The webhook endpoint is the URL where you'll send the events.
    6. Ensure the webhook token is included as a header using the header key `X-Webhook-Token`.
    7. Verify that your webhook source is working by sending a test [Placed Order](/sources/converge-spec#placed-order) event request. Ensure the request meets the parameters outlined in [Manually instrumenting events](/sources/server-integrations/webhook#manually-instrumenting-events).

    <Accordion icon="code" title="Code example">
      <Note>Include the webhook token from the Converge UI in the code example below.</Note>

      <CodeGroup>
        ```cURL cURL theme={null}
        curl -X POST \
        "https://app.runconverge.com/api/webhooks" \
        -H "Content-Type: application/json" \
        -H "X-Webhook-Token: {YOUR_WEBHOOK_TOKEN}" \
        -d '{
         "event_name": "Placed Order",
         "event_id": "order-1",
         "properties": {
             "id" : "order-1",
             "total_price": 42,
             "total_tax": 3.5,
             "total_shipping": 2.4,
             "currency": "USD",
             "items": [
                 {
                     "product_id": "123456",
                     "variant_id": "654321",
                     "sku": "MY_SKU",
                     "name": "My Product",
                     "price": 42,
                     "currency": "USD",
                     "quantity": 1,
                     "vendor": "My Store"
                 }
             ],
             "$is_new_customer": false,
             "$sales_channel_type": "web"  # important, see supported sales channels
         },
         "profile_properties": {
             "$first_name": "John",
             "$last_name": "Smith",
             "$email": "john.smith@apple.com",
             "$phone_number": "+199999999",
             "$city": "San Francisco",
             "$country_code": "US",
             "$state": "California",
             "$zip_code": "94103"
         },
         "aliases": ["urn:email:john.smith@apple.com"]
        }'

        ```
      </CodeGroup>
    </Accordion>
  </Step>

  <Step title="Verify that your event arrived in Converge">
    8. Click on your newly created source and choose the **Logs** tab. You should see the event you just sent there.
  </Step>
</Steps>

***

## Manually instrumenting events

If the pre-built server integrations do not cover the applicable conversions from the [Converge event spec](/sources/converge-spec); or if you want to add custom events from your website then you will need to manually instrument these using the Converge Pixel.
You can use the Webhook source to manually instrument these events.

<Info> As a general rule, you should always **aim to pass as many `properties`, `profile_properties`, and `aliases` as possible** </Info>

The webhook body has the following parameters:

| Parameter            | Type            |            | Description                                                                                                                                                                                                                                                                                |
| :------------------- | :-------------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_name`         | `string`        | *Required* | The name of the event                                                                                                                                                                                                                                                                      |
| `event_id`           | `string`        | *Required* | The ID of the event, used for [deduplication](/sources/source-concepts#deduplication)                                                                                                                                                                                                      |
| `properties`         | `object`        | *Required* | The event properties you want to pass, covering the [Converge Spec](/sources/server-integrations/webhook#event-spec) and possibly your own custom properties.                                                                                                                              |
| `profile_properties` | `object`        | *Required* | The [profile properties](/sources/source-concepts#profile-properties)                                                                                                                                                                                                                      |
| `aliases`            | `array[string]` | *Required* | Any [aliases](/sources/source-concepts#aliases). Must contain at least one alias, with a maximum of 10 aliases allowed.                                                                                                                                                                    |
| `timestamp`          | `datetime`      | *Optional* | The date and time when the event occurred. If not provided, the current time will be used. The timestamp can be expressed as a string in ISO 8601 format (e.g., `"2024-09-02T12:34:56+00:00"`) or a UTC timestamp (e.g., `1725312229`). The string representation must specify a timezone. |

***

## Event spec

This integration does not auto-track any events by default.
All events should be instrumented manually according to the Converge event spec.

<Note> You should typically implement [Placed Order](/sources/converge-spec#placed-order) and [Started Subscription](/sources/converge-spec#started-subscription) events server-side. You can find a full list in the [Converge Spec here](/sources/converge-spec) </Note>

### Sales channels

Due to the events being instrumented manually, particular importance is placed on sales channels because of concepts like deduplication and session stitching.
When choosing a sales channel type for an event, if you expect a conversion (e.g., Placed Order) to have a corresponding web journey, then you'll want to typically categorize them as "web".
If the event is automated, say, a recurring subscription order, then you'll want to use "subscription\_contract".
If you're selling your products on a marketplace like Amazon, for example, and you intend to forward these Placed Order events to Converge via the webhook, you'll want to categorize them as "marketplace".

More on sales channels can be found [here](/sources/concepts/sales-channels).

<Note>If no sales channel type is provided, Converge falls back to "web".</Note>

The following supported sales channel types are:

| Name           | Property Value         | Description                                                          |
| -------------- | ---------------------- | -------------------------------------------------------------------- |
| Web            | web                    | Events occurring via browser-based interactions and actions          |
| Subscriptions  | subscription\_contract | Automated events related to subscription renewals or contracts.      |
| SMS            | sms                    | Events or interactions triggered via SMS/Text communication.         |
| Mobile App     | mobile\_app            | User interactions occurring within mobile applications.              |
| POS            | pos                    | Point of Sale transactions taking place in physical stores.          |
| Marketplace    | marketplace            | Sales and interactions through third-party marketplaces like Amazon. |
| Offline        | offline                | Offline events such as amended orders, manual orders, or calls.      |
| Facebook Shop  | facebook\_shop         | Purchases and interactions through the Facebook Shop channel.        |
| Pinterest Shop | pinterest\_shop        | Sales and activity through the Pinterest Shop channel.               |
| TikTok Shop    | tiktok\_shop           | Orders and interactions made via the TikTok Shop channel.            |


# WooCommerce
Source: https://docs.runconverge.com/sources/server-integrations/woocommerce

Connect your WooCommerce store backend to Converge

## Installation instructions

<Steps>
  <Step title="Navigate to your WooCommerce REST API Settings">
    1. Navigate to your WordPress Admin Dashboard.
    2. From the Menu Sidebar, navigate to the **WooCommerce** > **Settings** submenu.
    3. On the WooCommerce Settings Page, click on the **Advanced** tab in the top bar.
    4. In the **Advanced Tab**, click on the **REST API** link on the top of the page.
  </Step>

  <Step title="Generate your WooCommerce Consumer Key and Consumer Secret">
    5. On the **REST API** page, click on the **Add key** button, this will open a menu to create a new key.
    6. Choose `Converge` for the **Description**-form field, your own account as the **User**, and choose `Read` as the **Permissions**.
    7. Click on **Generate API Key**.
    8. Copy the **Consumer key** and **Consumer secret**, you will need them to set up the Converge Source.
  </Step>

  <Step title="Create a new Server-side source in Converge">
    9. In Converge, click on **Create a new source**
    10. Pick *Server-side* from the modal
    11. Name your source: e.g. `{Storename} Store Backend`
    12. Choose the **WooCommerce** app from the dropdown menu.
  </Step>

  <Step title="Connect the Source to WooCommerce">
    13. Enter your Store URL in the **URL of your WooCommerce store**-field, including `https://`, e.g. `https://myshop.com`
    14. Paste the **Consumer key** and **Consumer secret** from your previous step.
    15. Click on **Create Source**.
  </Step>
</Steps>

<Note> You should see the Source syncing all historical order data, you should wait until it's fully synced to create destinations </Note>

***

## Event spec

This integration auto-tracks the following events on the server with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                          | Event Description                |
| --------------------------------------------------- | -------------------------------- |
| [Placed Order](/sources/converge-spec#placed-order) | When a customer places an order. |

### Sales channels

Events received by Converge from a WooCommerce integration are automatically mapped to Converge's [sales channels types](/sources/concepts/sales-channels) whenever possible.

More on sales channels can be found [here](/sources/concepts/sales-channels).

<Note> Converge falls back to "web" if a mapping cannot be found. This is typically the case with third-party integrations with WooCommerce. </Note>

An example of how Converge maps WooCommerce sales channels:

| Woocommerce  | Converge               | Description                                                                        |
| ------------ | ---------------------- | ---------------------------------------------------------------------------------- |
| checkout     | web                    | Browser                                                                            |
| subscription | subscription\_contract | Subscription events                                                                |
| admin        | offline                | Manual orders                                                                      |
| rest-api     | -                      | Depends on third party integration, defaults to "web" if no valid mapping is found |

#### Third party integrations

For third-party integrations, Converge provides support for a metadata field that can be used to specify the sales channel type directly.
This is particularly useful for custom implementations or when working with external systems that use the WooCommerce API to create or update orders.

Converge reads the metadata field called `sales_channel_type` to determine the appropriate sales channel type for the event. This metadata can be set in WooCommerce orders to override the default channel mapping.
If this field is present and has a valid sales channel type value, Converge uses it to categorize the sales channel.


# Tracking snippets
Source: https://docs.runconverge.com/sources/tracking-snippets

Add custom JavaScript to your tracking snippets that gets loaded with your pixel.

## What are tracking snippets?

Tracking snippets let you add small pieces of JavaScript that load right after your pixel but before any destinations. This is useful when you want to run code before events are tracked in Converge or sent to your destinations. Common uses include:

* Setting an event property that should be sent with every event.
* Tracking a custom event in Converge that requires JavaScript.
* Adding a default Google or Microsoft Consent Mode status.

<Note>Tracking snippets can only be added to a client-side pixel.</Note>

## How to add a tracking snippet

1. Go to **Event sources** under **Data management** in the main navigation.
2. Select a **client-side pixel** that's loaded on your website where you want to add the snippet.
3. Open the **Custom tracking** tab.
4. In the **Tracking snippets** section, click **Add snippet**.
5. Add the **JavaScript code** you want to include.
6. Click **Save**.

<Note>You can only add JavaScript code directly. You can't load a JavaScript file through a `<script>` tag.</Note>


# BigCommerce Web
Source: https://docs.runconverge.com/sources/website-integrations/bigcommerce

Install the BigCommerce Storefront Script

The BigCommerce Website Integration consists of a script that tracks your storefront and checkout events.

***

## Installation instructions

The Converge Website installation for a BigCommerce store consists of:

<Steps>
  <Step title="Create a new Client Source in Converge">
    1. In Converge, click on **Create a new source**
    2. Pick *Client-side* from the modal
    3. Name your pixel: e.g. `{Storename} Storefront`
  </Step>

  <Step title="Configure the storefront script">
    4. Navigate to **Channel Manager** in the BigCommerce Dashboard.

    5. Under Storefronts, click on the <Icon name="ellipsis" />-icon next to the Storefront for which you want to install tracking. Click on **Edit Settings**.

    6. In the storefront settings, click on **Script manager** in the sidebar and then click on **Create a script**.

    7. Choose **Converge** as your script name, choose **Footer** as your Placement and **All pages** as your Location. Make sure the Script category is **Essential** and Script type is **Script**.

    8. Copy the script below
       <Accordion title="Click to see script to copy" icon="clipboard">
         ```html theme={null}
         <script>
         !function(){"use strict";!function(e,t,c,n,s,o,r){e.cvg||(s=e.cvg=function(){s.process?s.process.apply(s,arguments):s.queue.push(arguments)},s.queue=[],(o=t.createElement(c)).async=1,o.src="https://static.runconverge.com/pixels/YOUR_PUBLIC_TOKEN.js",(r=t.getElementsByTagName(c)[0]).parentNode.insertBefore(o,r))}(window,document,"script")}();
         </script>

         <script>
             (function(){
                 const cartId = "{{cart_id}}";
                 let aliases = [];
                 let profileProperties = {};

                 if (cartId) {
                     aliases.push(`urn:bigcommerce:cart:${cartId}`);
                 }


                 const getCookie = (name) => {
                     const value = `; ${document.cookie}`;
                     const parts = value.split(`; ${name}=`);
                     if (parts.length === 2) {
                         return parts.pop().split(';').shift();
                     }
                     return '';
                 }

                 const setCookie = (name, value) => {
                     document.cookie = `${name}=${value}; path=/;`;
                 }
                 
                 const setupCheckoutEvent = (eventName) => {
                     return fetch('/api/storefront/checkout/{{cart_id}}')
                         .then((response) => response.json())
                         .then((checkout) => {
                             const cart = checkout.cart;
                             if (cart.email) {
                                 aliases.push(`urn:email:${cart.email}`);
                                 profileProperties['$email'] = cart.email;
                             }
                             if (cart.customerId) {
                                 aliases.push(`urn:bigcommerce:customer:{{settings.store_hash}}:${cart.customerId}`);
                             }
                             const address = checkout.billingAddress
                             profileProperties = {
                                 ...profileProperties,
                                 $first_name: address.firstName,
                                 $last_name: address.lastName,
                                 $phone_number: address.phone,
                                 $city: address.city,
                                 $state: address.stateOrProvince,
                                 $zip_code: address.postalCode,
                                 $country_code: address.countryCode,
                             }
                             
                             cvg({
                                 method: 'track',
                                 eventName: eventName,
                                 properties: {
                                     id: cart.id,
                                     total_price: cart.cartAmount,
                                     total_discount: cart.discountAmount,
                                     total_tax: checkout.taxes.map(t => t.amount).reduce((a, b) => a + b, 0),
                                     coupon: cart.coupons.map(c => c.code),
                                     currency: cart.currency.code,
                                     items: cart.lineItems.physicalItems.map(
                                         l => ({
                                             product_id: l.productId,
                                             variant_id: l.variantId,
                                             name: l.name,
                                             variant_name: l.variantId,
                                             sku: l.sku,
                                             price: l.salePrice,
                                             discount: l.discountAmount,
                                             vendor: l.brand.name,
                                             quantity: l.quantity,
                                             currency: cart.currency.code
                                         })
                                     ),
                                     ...profileProperties
                                 },
                                 aliases,
                                 profileProperties
                             })
                         }
                     )
                 }

                 cvg({method: "track", eventName: "$page_load", aliases, profileProperties});

                 const pageType = "{{page_type}}";
                 if (pageType === "product") {
                     const product = {
                         product_id: "{{product.id}}",
                         name: "{{product.title}}",
                         sku: "{{product.sku}}",
                         price: +("{{product.price.with_tax.value}}" || "{{product.price.without_tax.value}}"),
                         currency: "{{product.price.with_tax.currency}}" || "{{product.price.without_tax.currency}}",
                         vendor: "{{product.brand.name}}"
                     };
                     cvg({
                         method: "track",
                         eventName: "Viewed Product",
                         properties: product,
                         aliases,
                         profileProperties
                     });
                     const btn = document.getElementById("form-action-addToCart");
                     if (btn) {
                         btn.addEventListener('click', function (){
                                 cvg({
                                     method: "track",
                                     eventName: "Added To Cart",
                                     properties: {
                                         ...product,
                                         quantity: 1
                                     },
                                     aliases
                                 });
                         });
                     }
                 } else if (pageType === "category") {
                     cvg({
                         method: "track",
                         eventName: "Viewed Collection",
                         properties: {
                             id: "{{category.id}}",
                             name: "{{category.name}}",
                             description: "{{category.description}}",
                             items: [
                                 {{#each category.products}}
                                     {
                                         product_id: "{{this.id}}",
                                         name: "{{this.name}}",
                                         sku: "{{this.sku}}",
                                         price: +("{{this.price.with_tax.value}}" || "{{this.price.without_tax.value}}"),
                                         currency: "{{this.price.with_tax.currency}}" || "{{this.price.without_tax.currency}}",
                                         vendor: "{{this.brand.name}}"
                                     },
                                 {{/each}}
                             ].slice(0, 20)
                         },
                         aliases,
                         profileProperties
                     });

                 } else if (pageType === 'cart') {
                     const coupons = {{#if cart.coupons}} {{{json cart.coupons}}} {{else}} [] {{/if}};
                     const codes = coupons.map(c => c.code);
                     const discount = -1 * coupons.map(c => c.discount.value).reduce((a, b) => a + b, 0);
                     cvg({
                         method: "track",
                         eventName: "Viewed Cart",
                         properties: {
                             total_price: +"{{cart.grand_total.value}}",
                             total_tax: +"{{cart.taxes.cost.value}}",
                             total_discount: discount,
                             currency: "{{cart.grand_total.currency}}",
                             coupon: codes,
                             items: [
                                 {{#each cart.items}}
                                     {
                                         product_id: "{{this.product_id}}",
                                         name: "{{this.name}}",
                                         sku: "{{this.sku}}",
                                         price: +"{{this.price.value}}",
                                         currency: "{{this.price.currency}}",
                                         vendor: "{{this.brand.name}}",
                                         quantity: +"{{this.quantity}}"
                                     },
                                 {{/each}}
                             ]
                         },
                         aliases,
                         profileProperties
                     });

                 } else if (pageType === 'checkout') {
                     if (getCookie('__cvg_started_checkout') !== "{{cart_id}}") {
                         setupCheckoutEvent('Started Checkout');
                         setCookie('__cvg_started_checkout', "{{cart_id}}");
                     }
                     window.addEventListener("click", function(event){ 
                         var id = event.target.id;
                         if (id === 'checkout-customer-continue' ) {
                             setupCheckoutEvent('Added Contact Info');
                         }
                         if (id === 'checkout-shipping-continue') {
                             setupCheckoutEvent("Added Shipping Info")
                         }
                         if (id === 'checkout-payment-continue') {
                             setupCheckoutEvent("Added Payment Info")
                         }
                     });
                 } 
             })();  
         </script>
         ```
       </Accordion>

    9. Navigate to your Converge dashboard and find the Client-side source you created for BigCommerce. Click on the pixel and copy the tracking token as per the screenshot below.
       <Frame>
         <img alt="funnelish-14" />
       </Frame>

    10. Replace the `YOUR-TRACKING-TOKEN` field in the script pasted with your personal Converge token.
        <Frame>
          <img alt="funnelish-15" />
        </Frame>

    11. Once that is done, click on **Save**.
  </Step>

  <Step title="Verify that the integration is working correctly">
    12. Check that the plugin is working correctly by generating some `$page_load`, `Added To Cart`, `Started Checkout` events by visiting the store and seeing that these events arrive in the Source Log.

    <Info>Set up a [Pixel Monitor](/sources/monitoring#pixel-monitor) to automatically verify your pixel stays installed.</Info>
  </Step>
</Steps>

***

## Event spec

This integration auto-tracks the following events on the browser with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                                  | Event Description                               | Integration |
| ----------------------------------------------------------- | ----------------------------------------------- | ----------- |
| [PageView](/sources/converge-spec#page-view)                | When a customer views a page.                   | Storefront  |
| [Viewed Product](/sources/converge-spec#viewed-product)     | When a customer views a product.                | Storefront  |
| [Added To Cart](/sources/converge-spec#added-to-cart)       | When a customer adds an item to cart            | Checkout    |
| [Started Checkout](/sources/converge-spec#started-checkout) | When a customer initiates the checkout process. | Checkout    |


# Converge JS
Source: https://docs.runconverge.com/sources/website-integrations/converge-pixel

Connect your Website to Converge

## Installation instructions

<Steps>
  <Step title="Create a new Client Source in Converge">
    1. In Converge, click on **Create a new source**
    2. Pick *Client-side* from the modal
    3. Name your pixel: e.g. `{Storename} Storefront`
  </Step>

  <Step title="Install the Converge HTML snippet in your storefront">
    4. Click on your newly created Source and from the modal pick `HTML`, and copy that snippet.

    <Accordion icon="code" title="Code example">
      ```html theme={null}
      <script
        src="<https://static.runconverge.com/pixels/{YOUR_PUBLIC_TOKEN}.js>"
        async
      ></script>
      <script>
        window.cvg||(c=window.cvg=function(){c.process?c.process.apply(c,arguments):c.queue.push(arguments)},c.queue=[]);
        cvg({method:"track",eventName:"$page_load"});
      </script>
      ```
    </Accordion>

    5. Copy the HTML snippet and include it in the header of your website, right above the closing `</head>` tag.
  </Step>

  <Step title="Verify that the integration is working correctly">
    6. Check that your pixel is working correctly by generating some `$page_load` events by visiting the website and seeing that these events arrive in the Source Log.

    <Info>Set up a [Pixel Monitor](/sources/monitoring#pixel-monitor) to automatically verify your pixel stays installed.</Info>
  </Step>
</Steps>

<Warning>
  Implement Converge directly in your site's `<head>` whenever possible. We do not recommend using Google Tag Manager (GTM) or other tag managers as your permanent setup.

  GTM installation is technically possible - however, GTM can delay pixel loading, and ad blockers that block GTM containers can also silently block the Converge JS Pixel.
</Warning>

### Note for Single-page applications

<Warning>If you are using a single-page application, you should hook the `$page_load` tracking call into your router to re-fire the event. </Warning>

<Tabs>
  <Tab title="NextJS App Router">
    ```javascript theme={null}
      // app/ConvergePageView.jsx
      'use client'
      import { usePathname } from "next/navigation";
      import { useEffect } from "react";

      export default function ConvergePageView() {
        const pathname = usePathname();

        useEffect(() => {
          cvg({ method: "track", eventName: "$page_load" });
        }, [pathname])
        
        return null
      }

      // app/layout.js
      import ConvergePageView from "./ConvergePageView";

      export default function RootLayout({ children }) {
        return (
          <html lang="en">
            <body>
              <ConvergePageView /> 
              {children}
            </body>
          </html>
        )
      }
    ```
  </Tab>

  <Tab title="NextJS Page Router">
    ```javascript theme={null}
      import { useEffect } from "react";
      const MyApp = ({ Component, pageProps, router }) => {
        useEffect(() => {
          const handleRouteChange = (url) => {
            cvg({ method: "track", eventName: "$page_load" });
          };
          router.events.on("routeChangeComplete", handleRouteChange);
          return () => {
            router.events.off("routeChangeComplete", handleRouteChange);
          };
        }, []);
        return <Component {...pageProps} />;
      };
      export default MyApp;
    ```
  </Tab>
</Tabs>

***

## Cross-domain tracking

Converge supports cross-domain tracking through the methods below. We can stitch sessions across different domains and make sure that cookie information, first-party attribution, etc. will work correctly.

Note that you do **not** need to do anything for tracking across subdomains.
i.e. if the pixel snippet is installed on `myfirstdomain.com` and on `checkout.myfirstdomain.com`, the sessions should be stitched across both domains automatically.

If you want to stitch a session from `myfirstdomain.com` to `myotherdomain.com` then you will want to make sure to implement it as per the instructions below.

### How does cross-domain tracking work

Converge allows for cross-domain tracking through the `__cvg_uid` and `__cvg_sid` parameters and cookies.
If Converge recognizes the same `__cvg_uid` and `__cvg_sid` identifiers for pageviews on `myfirstdomain.com` and pageviews on `myotherdomain.com` then it will stitch those sessions under the same profile and session.

To stitch, we need to be able to pass the cookie between different websites as the cookie is only generated if the `__cvg_uid` and `__cvg_sid` are not set in the URL.
If there is a `__cvg_uid` set in the URL as a parameter, the cookie will be set to this value.

<Frame>
  ```mermaid actions={false} theme={null}
  flowchart TB
    id1("*User* visits **myfirstdomain.com** and gets assigned **__cvg_uid=1234** and **__cvg_sid=ABCD**") -. "Clicks on link myotherdomain.com/?__cvg_uid=1234&__cvg_sid=ABCD" .-> id2("*User* visits **myotherdomain.com** and Converge reads the id from the URL") ~~~ id3(["**Session stitched**  ✓ "])
    style id3 color:#02b802,stroke:none
  ```
</Frame>

### The `link_domain` method

The Converge Pixel exposes the `link_domain` method to automatically add the `?__cvg_uid={CVG_ID_VALUE}&__cvg_sid={CVG_SID_VALUE}` suffix to every outbound link that leads to `myotherdomain.com`.
Include the following method together with the basic Converge pixel snippet on the `myfirstdomain.com` website to enable it on every page.

```js theme={null}
cvg({ method: "link_domain", domain: "myotherdomain.com" });
```

<Note>
  Always validate that both `__cvg_uid` and `__cvg_sid` are present after navigating to another domain. If those are missing, Converge has no way of stitching the events correctly. This will potentially lead to sessions being attributed as organic referrals from your other domain.
</Note>

<Warning>
  If the redirect to `myotherdomain.com` doesn't happen directly through a link click but through JavaScript code, the parameter won't be added automatically.

  Follow [Manually setting up cross-domain tracking](#manually-setting-up-cross-domain-tracking) to manually instrument the links.
</Warning>

### Manually setting up cross-domain tracking

If the `link_domain` cannot be used in your case, you will need to manually instrument the links by adding the `__cvg_uid` and `__cvg_sid` URL parameters and their corresponding cookie values for each outbound link in that case.

The procedure for this will vary depending on your specific requirements. But in general, it consists of fetching the necessary cookie values and appending them to the URL before redirecting.

For example, assuming you are navigating to another domain using a click event on a button, one possible approach is the following:

```js theme={null}
document.getElementById('some-button').addEventListener('click', () => {
    // use your preferred way of reading cookie values
    let uid = getCookie('__cvg_uid')
    let sid = getCookie('__cvg_sid')

    window.location.href = `https://myotherdomain.com?__cvg_uid=${uid}&__cvg_sid=${sid}`
})
```

<Note>
  Always validate that both `__cvg_uid` and `__cvg_sid` are present after navigating to another domain. If those are missing, Converge has no way of stitching the events correctly. This will potentially lead to sessions being attributed as organic referrals from your other domain.
</Note>

***

## Manually instrumenting events

If the pre-built website integrations do not cover the entire [Converge event spec](/sources/converge-spec); or if you want to add custom events from your website then you will need to manually instrument these using the Converge Pixel.
You can use the `track` method in the Converge Pixel for this purpose.

<Note> As a general rule, you should always **aim to pass as many `properties`, `profileProperties` and `aliases` as possible** </Note>

The track method has the following parameters:

* `eventName`: The name of the event
* `properties`: The event properties you want to pass, covering the Converge Spec and possibly your own custom properties.
* `profileProperties`: The [profile properties](/sources/source-concepts#profile-properties)
* `aliases`: Any [aliases](/sources/source-concepts#aliases)

<AccordionGroup>
  <Info> You can find Converge JS examples for the entire [Converge Spec here](/sources/converge-spec) </Info>

  <Accordion title="Code Examples" icon="code">
    <CodeGroup>
      ```javascript Added To Cart theme={null}
      cvg({
        method: "track",
        eventName: "Added To Cart",
        properties: {
          product_id: "123456",
          variant_id: "78910",
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla",
          price: 42,
          currency: "USD",
          quantity: 1,
          vendor: "My Store",
        },
      });
      ```

      ```javascript Added Payment Info theme={null}
      cvg({
        method: "track",
        eventName: "Added Payment Info",
        properties: {
          total_price: 42,
          total_tax: 3.5,
          total_shipping: 2.4,
          currency: "USD",
          items: [
            {
              product_id: "123456",
              sku: "MY_SKU",
              name: "My Product",
              price: 42,
              currency: "USD",
              quantity: 1,
              vendor: "My Store",
            },
          ],
        },
        profileProperties: {
          // Pass if available
          $email: "john.smith@apple.com",
          $phone_number: "+199999999",
          $city: "San Francisco",
          $country_code: "US",
          $state: "California",
          $zip_code: "94103",
        },
        aliases: ["urn:email:john.smith@apple.com"],
      });

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Turning off tracking for internal users

By appending the `internalUser=1` query parameter to the URL of the page you're visiting, you can prevent the Converge pixel from executing.
As a consequence, no events or sessions will be tracked. For example:

* `https://mywebsite.com?internalUser=1`
* `https://mywebsite.com/product-1?internalUser=1`
* `https://mywebsite.com/product-1?utm_source=test&internalUser=1`

<Note>
  This flag is stored under the `__cvg_internal_user` cookie and will persist for this browser, for as long as the cookie is present (up to 2 years).

  When conducting internal testing, it is advised to regularly add the `internalUser=1` query parameter to the URL to prevent tracking.
</Note>

***

## Event spec

This integration auto-tracks the following events with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                       | Event Description             |
| ------------------------------------------------ | ----------------------------- |
| [\$page\_load](/sources/converge-spec#page-load) | When a customer views a page. |


# Firmhouse
Source: https://docs.runconverge.com/sources/website-integrations/firmhouse

Install the Converge Pixel on your Firmhouse Checkout

Converge supports tracking Checkout events on the Firmhouse Checkout.

***

## Installation instructions

The Converge Website installation for a Firmhouse Checkout consists of:

<Steps>
  <Step title="Create a new Client Source in Converge">
    1. In Converge, click on **Create a new source**
    2. Pick *Client-side* from the modal
    3. Name your pixel: e.g. `{Storename} Firmhouse Checkout`
    4. Click on your newly created source and copy your public token per the screenshot below:
       <Frame>
         <img alt="funnelish-14" />
       </Frame>
  </Step>

  <Step title="Create your Storefront token">
    5. Navigate to your <OutboundLink />
    6. Click on **Integrations** in the side panel
       <Frame>
         <img alt="integrations" />
       </Frame>
    7. Click on **Generate new token**, choose **No expiration** and choose **Storefront** as your Access Type, click on **Create project access token**.
    8. Copy the token you just created, you will need it later.
  </Step>

  <Step title="Set up website tracking for your Firmhouse checkout">
    9. Click on **Checkout** > **Preferences**.

    10. Copy the following script in the **Body**, paste it above other scripts that might be already there.

        <Accordion title="Click to see tracking script" icon="code">
          <Note> You will need to do a few modifications to the script as described in the following steps</Note>

          ```html theme={null}
              <script src="https://static.runconverge.com/pixels/{YOUR-PUBLIC-TOKEN}" async></script>
              <script>
              window.cvg||(cvg=function(){cvg.process?cvg.process.apply(cvg,arguments):cvg.queue.push(arguments)},cvg.queue=[]);
              cvg({method:"track",eventName:"$page_load"});
              </script>

              <script>
                  /**************************************************************************
                  * Firmhouse Converge Pixel configuration
                  * storefrontToken: In the firmhouse portal, go to Settings > Integrations > Generate new token > Access type: Storefront
                  * currency: The currency of your store
                  *************************************************************************/
                  const storefrontToken = '{YOUR-STOREFRONT-TOKEN}';
                  const currency = 'EUR';


                  /******************************** Globals ********************************/
                  const aliases = [];
                  let profileProperties = {};
                  /* --------------------------------------------------------------------- */


                  /******************************** Helpers ********************************/
                  const getCookie = (name) => {
                      const value = `; ${document.cookie}`;
                      const parts = value.split(`; ${name}=`);
                      if (parts.length === 2) {
                          return parts.pop().split(';').shift();
                      }
                      return '';
                  }

                  const setCookie = (name, value) => {
                      document.cookie = `${name}=${value}; path=/;`;
                  }

                  const isValidEmail = (email) => 
                      email && /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/.test(email);


                  const collectProfileProperties = () => {
                      const $email = document.querySelector('[name="subscription[email]"]')?.value;
                      
                      const phoneCountry = document.querySelector('#country-listbox li.active')?.getAttribute('data-dial-code');
                      const phone = document.querySelector('[name="subscription[phone_number]"]')?.value;
                      
                      const $phone_number = phoneCountry && phone ? `+${phoneCountry} ${phone}` : undefined;
                      const $first_name = document.querySelector('[name="subscription[name]"]')?.value;
                      const $last_name = document.querySelector('[name="subscription[last_name]"]')?.value;
                      const $zip_code = document.querySelector('[name="subscription[zipcode]"]')?.value;
                      const $city = document.querySelector('[name="subscription[city]"]')?.value;

                      const $country_code = document.querySelector('[name="subscription[country]"] option:checked')?.value;

                      profileProperties = {
                          ...profileProperties,
                          $email,
                          $phone_number,
                          $first_name,
                          $last_name,
                          $zip_code,
                          $city,
                          $country_code,
                      };
                      if (isValidEmail($email)) {
                          aliases.push(`urn:email:${$email}`);
                      }
                  }

                  const getCart = () => fetch(
                      'https://portal.firmhouse.com/graphql',
                      {
                          method: 'POST',
                          headers: {
                              'Content-Type': 'application/json',
                              'Accept': 'application/json',
                              'X-Subscription-Token': cartToken,
                              'X-Project-Access-Token': storefrontToken
                          },
                          body: JSON.stringify({
                              query: `
                                  {
                                      currentCart {
                                          token

                                          orderedProducts {
                                              quantity
                                              product {
                                                  title
                                                  priceCents
                                                  shopifyProductId
                                                  shopifyVariantId
                                                  sku
                                              }
                                          }
                                      }
                                  }
                              `,
                          }),
                      }
                  )
                  .then((response) => response.json())
                  .then((body) => body.data.currentCart)
                  .then((cart) => ({
                      id: cart.token,
                      currency,
                      total_price: cart.orderedProducts.reduce((acc, l) => acc + l.product.priceCents * l.quantity, 0) / 100,
                      items: cart.orderedProducts.map((l) => ({
                          product_id: l.product.shopifyProductId.split('/').pop(),
                          variant_id: l.product.shopifyVariantId.split('/').pop(),
                          sku: l.product.sku,
                          name: l.product.title,
                          variant_name: l.product.shopifyVariantId.split('/').pop(),
                          price: l.product.priceCents / 100,
                          quantity: l.quantity,
                          currency
                      }))
                  }));


                  const setupStartedCheckout = (cartPromise, cartToken) => {
                      if (getCookie('__cvg_started_checkout') !== cartToken) {
                          cartPromise.then((cart) => {
                              cvg({method: 'event', event: 'Started Checkout', properties: cart, aliases, profileProperties});
                          });
                          setCookie('__cvg_started_checkout', cartToken);
                      }
                  }

                  const setupAddedPaymentInfo = (cartPromise, cartToken) => {
                      const subscriptionSubmit = document.querySelector('[data-role="subscription-submit"]');
                      if (subscriptionSubmit) {

                          subscriptionSubmit.addEventListener('click', () => {
                              collectProfileProperties();
                              aliases.push(`urn:email:${profileProperties["$email"]}`);
                              cartPromise.then((cart) => {
                                  cvg({method: 'event', event: 'Added Payment Info', properties: cart, aliases, profileProperties});
                              });
                          });
                      }
                  }
                  /* --------------------------------------------------------------------- */


                  /******************************** Setup **********************************/
                  // Get the cart_token from URL or localStorage
                  const cartToken = (
                      new URLSearchParams(window.location.search).get('cart_token')
                      || localStorage.getItem('Firmhouse.cartToken')
                      || getCookie('__cvg_cart_token')
                  );
                  
                  // Ensure that no 'dummy' subscription tokens are used for identification (e.g. 'new')
                  if (cartToken && cartToken.length >= 10) {
                      aliases.push(`urn:firmhouse:token:${cartToken}`);
                      setCookie('__cvg_cart_token', cartToken);
                  } else {
                      const path = window.location.pathname;
                      const matches = path.match(/\/subscriptions\/([a-zA-Z0-9]+)/);
                      const subscriptionToken = matches && matches[1];
                      if (subscriptionToken && subscriptionToken.length >= 10) {
                          aliases.push(`urn:firmhouse:token:${subscriptionToken}`);
                      }
                  }
                  /* --------------------------------------------------------------------- */

                  
                  /******************************** Events **********************************/
                  cvg({method: 'event', event: '$page_load', aliases, profileProperties});

                  if (cartToken) {
                      const cartPromise = getCart();
                      setupStartedCheckout(cartPromise, cartToken);
                      setupAddedPaymentInfo(cartPromise, cartToken);
                  }
                  /* --------------------------------------------------------------------- */
          </script>
          ```
        </Accordion>

    11. Replace the `{YOUR-PUBLIC-TOKEN}` with the public token you retrieved in *Step 4*.

    12. Replace the `{YOUR-STOREFRONT-TOKEN}` with the API token you retrieved in *Step 7*.

    13. Click on **Update project**

    <Info>Set up a [Pixel Monitor](/sources/monitoring#pixel-monitor) to automatically verify your pixel stays installed.</Info>
  </Step>
</Steps>

***

## Event spec

This integration auto-tracks the following events on the browser with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                                      | Event Description                               |
| --------------------------------------------------------------- | ----------------------------------------------- |
| [PageView](/sources/converge-spec#page-view)                    | When a customer views a page.                   |
| [Started Checkout](/sources/converge-spec#started-checkout)     | When a customer initiates the checkout process. |
| [Added Payment Info](/sources/converge-spec#added-payment-info) | When a customer adds their payment info.        |


# Funnelish
Source: https://docs.runconverge.com/sources/website-integrations/funnelish

Install the Converge Pixel on your Funnelish funnels

Converge supports tracking Storefront and Checkout events on Funnelish natively.

***

## Installation instructions

The Converge Website installation for a Funnelish storefront consists of:

<Steps>
  <Step title="Create a new Webhook Source in Converge">
    1. In Converge, navigate to **Sources** and click on <IconText name="circle-plus" />
    2. Pick *Server-side* from the modal
    3. Name your source: e.g. `{Storename} Funnelish Storefront` and pick the **Funnelish**-app from the dropdown.
       <Frame>
         <img alt="funnelish-2" />
       </Frame>
    4. If you already have a Shopify source and Funnelish syncs all of the orders to Shopify, then you should **not enable** the "Track Funnelish orders as Placed Order conversions" option. If you will be using Funnelish as your order backend instead, then you should turn on the switch.
       <Frame>
         <img alt="funnelish-18" />
       </Frame>
       <Warning>If left **disabled**, our Funnelish Webhook integration tracks a custom event called "Placed Funnelish Order" which stitches the web session to the Shopify Placed Order. It also means the actual Funnelish event will not be forwarded to any destinations using Funnelish as a source. However, if you are using Funnelish as your order backend instead, then this option should be enabled. This means Funnelish orders will be forwarded as Placed Order events.</Warning>
    5. Click on **Create Source**.
    6. Copy the link that is displayed under *Postback Endpoint*, you will need it later.
       <Frame>
         <img alt="funnelish-4" />
       </Frame>
  </Step>

  <Step title="Create a Funnelish Automation to send events to the webhook">
    7. Open your Funnelish dashboard, and click on **Automations** in the top bar and then **Create a new automation**.
       <Frame>
         <img alt="funnelish-4" />
       </Frame>

    8. Choose **Start from scratch** in the modal that pops up and click **Create**.
       <Frame>
         <img alt="funnelish-5" />
       </Frame>

    9. Give your automation the name *Converge* and click on **New trigger**.
       <Frame>
         <img alt="funnelish-6" />
       </Frame>

    10. Choose **On purchase** under triggers and click on **Create**.
        <Frame>
          <img alt="funnelish-7" />
        </Frame>

    11. Choose **Add an action**.
        <Frame>
          <img alt="funnelish-8" />
        </Frame>

    12. Choose **Add new webhook** and fill in the webhook from *Step 3*.
        <Frame>
          <img alt="funnelish-9" />
        </Frame>

    13. Activate the Funnel in the top right corner.
        <Frame>
          <img alt="funnelish-11" />
        </Frame>

    <Warning> Make sure the Facebook App in Funnelish is turned off completely, as you will suffer from duplicate tracking if this is not the case. Make sure the Facebook app is turned off both on a general level, **and** on a per-funnel basis. </Warning>
  </Step>

  <Step title="Set up website tracking for your funnels">
    <Note> You need to do the following steps for **every new and existing funnel you set up**. </Note>

    14. Navigate to your new funnel in **Funnels** and click on the Funnel you want to install Converge tracking for. When in the funnel, click on **Funnel settings**.
        <Frame>
          <img alt="funnelish-12" />
        </Frame>

    15. Navigate to **Custom codes** and click on **New tracking code**.

    16. Give the new tracking code a name you can remember and turn *Lazy load* **off**.
        <Frame>
          <img alt="funnelish-13" />
        </Frame>

    17. Now you will want to copy-paste the script below.

        <Accordion title="Click to see tracking script" icon="code">
          ```html theme={null}
          <script
          src="https://static.runconverge.com/pixels/YOUR-TRACKING-TOKEN.js"
          async
          ></script>
          <script>
          window.cvg ||
          ((c = window.cvg =
              function () {
              c.process ? c.process.apply(c, arguments) : c.queue.push(arguments);
              }),
          (c.queue = []));
          cvg({ method: "track", eventName: "$page_load" });
          </script>

          <script>
          let ViewContentURLIdentifier = "YOUR-VIEWCONTENT-IDENTIFIER";
          let AddToCartURLIdentifier = "YOUR-ADDTOCART-IDENTIFIER";
          let InitiateCheckoutURLIdentifier = "YOUR-CHECKOUT-IDENTIFIER";

          if (window.location.href.includes(AddToCartURLIdentifier)) {
          cvg({
              method: "track",
              eventName: "Added To Cart",
              properties: {
              product_id: "1",
              variant_id: "1",
              name: "Product Name",
              variant_name: "Variant Name",
              price: 0,
              currency: "EUR",
              quantity: 1,
              },
          });
          }

          if (window.location.href.includes(ViewContentURLIdentifier)) {
          cvg({
              method: "track",
              eventName: "Viewed Product",
              properties: {
              product_id: "1",
              variant_id: "1",
              name: "Product Name",
              variant_name: "Variant Name",
              price: 0,
              currency: "EUR",
              },
          });
          }

          // InitiateCheckout and Added To Cart can be on the same URL
          if (window.location.href.includes(InitiateCheckoutURLIdentifier)) {
          cvg({
              method: "track",
              eventName: "Started Checkout",
              properties: {
                  total_price: 0,
                  total_tax: 0,
                  total_shipping: 0,
                  currency: "USD",
                  items: [
                  // Notice that this is a list of items
                      {
                      product_id: "1",
                      variant_id: "1",
                      name: "Product Name",
                      variant_name: "Variant Name",
                      price: 0,
                      currency: "EUR",
                      },
                  ],
              }
              });
          }
          </script>
          ```
        </Accordion>

        <Note> You will need to do a few modifications described in *Steps 5-7* to the script. </Note>

    18. Navigate to your Converge dashboard and find the pixel you are using for Funnelish. Click on the pixel and copy the tracking token as per the screenshot below.

    <Frame>
      <img alt="funnelish-14" />
    </Frame>

    19. Replace the `YOUR-TRACKING-TOKEN` field in the script pasted with your personal Converge token.

    <Frame>
      <img alt="funnelish-15" />
    </Frame>

    20. Replace the `YOUR-ADDTOCART-IDENTIFIER` and `YOUR-CHECKOUT-IDENTIFIER` values with values that uniquely identify a URL in the funnel where you want to trigger this event.

        <Info> As an example, if you want to trigger an AddToCart event on the `myfunnelishstore.com/cart` page, then you will want to replace `YOUR-ADDTOCART-IDENTIFIER` with `cart`. **These identifiers might be different values for different funnels**, so double-check when implementing a new funnel.</Info>

    21. Click on **Create code** and on **Save changes**.

    <Frame>
      <img alt="funnelish-16" />
    </Frame>

    <Info>Set up a [Pixel Monitor](/sources/monitoring#pixel-monitor) to automatically verify your pixel stays installed.</Info>
  </Step>
</Steps>

***

## Event spec

This integration auto-tracks the following events on the browser with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                                  | Event Description                               | Integration |
| ----------------------------------------------------------- | ----------------------------------------------- | ----------- |
| [PageView](/sources/converge-spec#page-view)                | When a customer views a page.                   | Pixel       |
| [Viewed Product](/sources/converge-spec#viewed-product)     | When a customer views a product.                | Pixel       |
| [Added To Cart](/sources/converge-spec#added-to-cart)       | When a customer adds an item to cart            | Pixel       |
| [Started Checkout](/sources/converge-spec#started-checkout) | When a customer initiates the checkout process. | Pixel       |
| [Placed Order](/sources/converge-spec#placed-order)         | When a customer places an order                 | Webhook     |

This integration also auto-tracks some additional events that are not part of the Converge event spec.

| Event Name             | Event Description                                                           | Integration |
| ---------------------- | --------------------------------------------------------------------------- | ----------- |
| Placed Funnelish Order | Event that stitches Funnelish website sessions with Shopify backend orders. | Webhook     |


# Magento Web
Source: https://docs.runconverge.com/sources/website-integrations/magento

Install the Magento Storefront Module

The Magento Website Integration consists of a Magento module that tracks your storefront and checkout events.

***

## Installation instructions

The Converge Website installation for a Magento store consists of:

<Steps>
  <Step title="Create a new Client Source in Converge">
    1. In Converge, click on **Create a new source**
    2. Pick *Client-side* from the modal
    3. Name your pixel: e.g. `{Storename} Storefront`
  </Step>

  <Step title="Install the Magento Plugin">
    4. Add the Converge repository to your Magento 2 project's `composer.json` file:

       ```bash bash theme={null}
       composer config repositories.repo-name vcs https://github.com/run-converge/converge-magento2
       ```
    5. Run the following command to install the Converge Magento 2 module:
       ```bash bash theme={null}
       composer require run-converge/converge-magento2:0.2.0
       ```
    6. Enable the Converge module using the Magento CLI:
       ```bash bash theme={null}
       bin/magento module:enable Converge_Converge
       ```
    7. Upgrade your Magento setup to ensure the Converge module is integrated properly:
       ```bash bash theme={null}
       bin/magento setup:upgrade
       ```
    8. Deploy static content to your Magento store for the Converge module:
       ```bash bash theme={null}
       bin/magento setup:static-content:deploy
       ```
  </Step>

  <Step title="Configure the Converge Magento Plugin with your public token">
    9. In the Converge web app, click on the source you created in *Step 1* and copy the **Public Token**. The code consists of 6 characters and can be retrieved from the HTML snippet. If your script `src` looks like `https://static.runconverge.com/pixels/AYU51m.js`, then your public token is `AYU51m`.
    10. Go to `Stores` > `Settings` > `Configuration` > `Converge` > `Converge` and add the public token you just retrieved.
  </Step>

  <Step title="Verify that the integration is working correctly">
    11. Check that the plugin is working correctly by generating some `$page_load`, `Added To Cart`, and `Started Checkout` events by visiting the store and seeing that these events arrive in the Source Log.

    <Info>Set up a [Pixel Monitor](/sources/monitoring#pixel-monitor) to automatically verify your pixel stays installed.</Info>
  </Step>
</Steps>

***

## Event spec

This integration auto-tracks the following events on the browser with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                                  | Event Description                               | Integration |
| ----------------------------------------------------------- | ----------------------------------------------- | ----------- |
| [PageView](/sources/converge-spec#page-view)                | When a customer views a page.                   | Storefront  |
| [Viewed Product](/sources/converge-spec#viewed-product)     | When a customer views a product.                | Storefront  |
| [Added To Cart](/sources/converge-spec#added-to-cart)       | When a customer adds an item to cart            | Checkout    |
| [Started Checkout](/sources/converge-spec#started-checkout) | When a customer initiates the checkout process. | Checkout    |


# Shopify Web
Source: https://docs.runconverge.com/sources/website-integrations/shopify

Install the Shopify Website Pixel

The Shopify Website Integration consists of two integrations covering the full tracking spec.

1. The Shopify Storefront Integration
2. The Shopify Checkout Integration

***

## Installation instructions

The installation process of Converge is slightly different based on whether you have a **Shopify Liquid** storefront; or whether you are running a **Shopify Headless** Storefront.

<Tabs>
  <Tab title="Shopify Liquid">
    The Converge Website installation for a Shopify Liquid store consists of:

    <Steps>
      <Step title="Create a new Client Source in Converge">
        1. In Converge, go to **Event sources**
        2. Click on **Create a new source**
        3. Pick *Client-side* from the modal
        4. Name your pixel: e.g. `{Storename} Storefront`
      </Step>

      <Step title="Install the Converge Liquid snippet in your storefront">
        4. Click on your newly created Source, make sure you pick `Shopify Liquid`, and then copy that snippet.
        5. In the Shopify admin dashboard, navigate to **Sales Channels** > **Online Store**.
        6. Click on "**...**" next to the **Edit Theme** button, and click **Edit code**.
        7. In the left sidebar, open the **Layouts** folder and click on *theme.liquid*. Insert the snippet right above the closing `</head>` tag. Click **Save**.
      </Step>

      <Step title="Verify that the integration is working correctly">
        8. Always double-check that you did not break anything on the site after inserting the snippet.
           <Info>It's good practice to **add the snippet to other themes in development as well** and to add this snippet to your version control, so a theme switch does not kill website tracking </Info>
        9. Check that your pixel is working correctly by generating some `$page_load`, `Viewed Product` and `Viewed Collection` events by visiting the store and seeing that these events arrive in the Source Log.

        <Info>Set up a [Pixel Monitor](/sources/monitoring#pixel-monitor) to automatically verify your pixel stays installed.</Info>
      </Step>

      <Step title="Create a new Client Source in Converge">
        10. In Converge, go to **Event sources**
        11. Click on **Create a new source**
        12. Pick *Client-side* from the modal
        13. Name your pixel: e.g. `{Storename} Checkout`
      </Step>

      <Step title="Install the Converge Checkout as an extension in Shopify Customer Events">
        14. Click on your newly created Source and pick `Shopify Custom Pixel`, and copy that snippet.
        15. In the Shopify Admin dashboard, navigate to **Settings** > **Customer Events**
        16. Click on **Add custom pixel**.
        17. Name your pixel, e.g. `Converge Pixel`
        18. Paste the script from the web app here.
        19. Click on **Save Pixel**
            <Frame>
              <img alt="save pixel" />
            </Frame>
        20. Under **Customer Privacy**, set the **Permission** flag to **Not required**.
            <Frame>
              <img alt="img" />
            </Frame>
        21. Also make sure that **Data sale** is set to **Data collected does not qualify as a data sale**.
            <Frame>
              <img alt="img" />
            </Frame>
        22. Click on **Connect Pixel**
            <Frame>
              <img alt="save pixel 1" />
            </Frame>

        <Info> Shopify might throw a warning that the pixel is not subscribed to any events. You can safely ignore this warning. </Info>
      </Step>

      <Step title="Verify that the integration is working correctly">
        23. Check that your pixel is working correctly by generating some `Added To Cart`, `Started Checkout` and `Added Payment Info` events by visiting the store and seeing that these events arrive in the Source Log.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Shopify Headless">
    The Converge Website installation for a Shopify Headless store consists of:

    <Steps>
      <Step title="Create a new Client Source in Converge">
        1. In Converge, click on **Create a new source**
        2. Pick *Client-side* from the modal
        3. Name your pixel: e.g. `{Storename} Storefront`
      </Step>

      <Step title="Install the Converge JS Base Snippet">
        4. Install the Converge JS Base Snippet in your storefront following the steps [here](/sources/website-integrations/converge-pixel#installation-instructions)
      </Step>

      <Step title="Verify that the integration is working correctly">
        5. Double-check that `$page_load` events are coming in correctly in the Source Logs.
      </Step>

      <Step title="Create a new Client Source in Converge">
        6. In Converge, go to **Event sources**
        7. Click on **Create a new source**
        8. Pick *Client-side* from the modal
        9. Name your pixel: e.g. `{Storename} Checkout`
      </Step>

      <Step title="Install the Converge Checkout as an extension in Shopify Customer Events">
        10. Click on your newly created Source and pick `Shopify Custom Pixel`, and copy that snippet.
        11. In the Shopify Admin dashboard, navigate to **Settings** > **Customer Events**
        12. Click on **Add custom pixel**.
        13. Name your pixel, e.g. `Converge Pixel`
        14. Paste the script from the web app here.
        15. Click on **Save Pixel**
            <Frame>
              <img alt="save pixel" />
            </Frame>
        16. Under **Customer Privacy**, set the **Permission** flag to **Not required**.
            <Frame>
              <img alt="img" />
            </Frame>
        17. Also make sure that **Data sale** is set to **Data collected does not qualify as a data sale**.
            <Frame>
              <img alt="img" />
            </Frame>
        18. Click on **Connect Pixel**
            <Frame>
              <img alt="save pixel 1" />
            </Frame>

        <Info> Shopify might throw a warning that the pixel is not subscribed to any events. You can safely ignore this warning. </Info>
      </Step>

      <Step title="Track the remaining Converge Spec">
        19. The Converge JS pixel only picks up [\$page\_load](/sources/converge-spec#page-load)-events by default for a headless store.
            You will typically have to supplement the following events using Converge JS for all Destinations to work optimally.

            * [Viewed Product](/sources/converge-spec#viewed-product)
            * [Viewed Collection](/sources/converge-spec#viewed-collection)
            * [Added To Cart](/sources/converge-spec#added-to-cart)

            For more information on manually instrumenting events, read [here](/sources/website-integrations/converge-pixel#manually-instrumenting-events).
      </Step>

      <Step title="Add appropriate aliases to stitch the session across all sources">
        20. At this point, you should be tracking the entire Converge Ecommerce Spec.
            However, for a Headless setup, it is paramount that you set the `checkout_token` as an alias **before** redirecting the user to the Shopify Checkout to make sure that the storefront session and the checkout session can be linked to the same user.
            You can read more about aliases [here](/sources/source-concepts#aliases).
      </Step>

      <Step title="Verify that the integration is working correctly">
        21. Check that your setup is working by doing an entire user journey from `$page_load` to `Placed Order` and verifying that all events are properly tracked without any [Source Warnings](/sources/monitoring#source-warnings).
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  The integration relies on Shopify Standard Events (see <OutboundLink /> for reference).

  If you are using custom code to handle, for example, cart, checkout, or payment, it's possible that the standard Shopify events will not be triggered or will have missing data. In those cases, you may need to implement the affected tracking events manually. See [Manually instrumenting events](/sources/website-integrations/converge-pixel#manually-instrumenting-events) for reference.
</Note>

***

## FAQ

<AccordionGroup>
  <Accordion title="Why do I need both a Shopify Liquid and a Shopify Checkout Pixel?">
    When you install the Shopify Web integration, you'll install both the Shopify Storefront integration (which lives in the `theme.liquid`) and a Checkout integration, which leverages Shopify App Pixels.
    You can check which integration tracks which events in the [Integration event spec](#event-spec).

    The difference between the Liquid Pixel and the Checkout Pixel is that the Checkout Pixel is completely sandboxed by Shopify and loads with a large delay, see more info [here](https://help.shopify.com/en/manual/promoting-marketing/pixels/overview) on the limitations of App Pixels.
    This is undesirable for events such as `$page_load`, where a user may browse away before the Converge pixel is loaded and before this event can be tracked.

    For that reason, you would want to track all events in the `theme.liquid`. However, **Shopify does not allow you to track reliably on the Checkout using this approach**.
  </Accordion>

  <Accordion title="Why do I have too few client-side events tracked on the Shopify Checkout">
    #### 1. Verify that Custom Pixel Privacy Settings are set up correctly

    You might have Custom Pixel Privacy settings set up in Shopify that limit us from tracking the Checkout.

    1. Navigate to the Shopify Admin dashboard, navigate to **Settings** > **Customer Events** and find the `Converge Pixel`.
    2. Click on it to open the settings.
    3. Verify in your Custom Pixel settings whether you have set the **Permission** flag to **Not required**.

       <Frame>
         <img alt="img" />
       </Frame>
    4. Also make sure that **Data sale** is set to **Data collected does not qualify as a data sale**.
       <Frame>
         <img alt="img" />
       </Frame>

    #### 2. Verify that a broken cookiebanner integration is not blocking the Converge Pixel

    If you are using a custom cookie banner that is not properly integrated with Shopify, then Shopify might block our pixel from loading on their checkout.
    To verify, go through the following steps:

    1. Navigate to the Shopify Admin dashboard, navigate to **Settings** > **Customer privacy** and verify whether **Regions** is set up:
       <Frame>
         <img alt="img" />
       </Frame>
    2. If **Regions** is set up, and you have a custom cookie banner, then Shopify might be blocking our pixel. Click on **Edit** and unselect all countries, then press **Save**.
       <Frame>
         <img alt="img" />
       </Frame>
    3. Verify over the coming hours that more checkout events are coming in.
  </Accordion>
</AccordionGroup>

***

## Event spec

This integration auto-tracks the following events on the browser with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                                                  | Event Description                                        | Integration |
| --------------------------------------------------------------------------- | -------------------------------------------------------- | ----------- |
| [PageView](/sources/converge-spec#page-load)                                | When a customer views a page.                            | Storefront  |
| [Viewed Product](/sources/converge-spec#viewed-product)                     | When a customer views a product.                         | Storefront  |
| [Viewed Collection](/sources/converge-spec#viewed-collection)               | When a customer views a collection of products.          | Storefront  |
| [Added To Cart](/sources/converge-spec#added-to-cart)                       | When a customer adds an item to cart                     | Checkout    |
| [Removed From Cart](/sources/converge-spec#removed-from-cart)               | When a customer removes an item from cart                | Checkout    |
| [Started Checkout](/sources/converge-spec#started-checkout)                 | When a customer initiates the checkout process.          | Checkout    |
| [Added Payment Info](/sources/converge-spec#added-payment-info)             | When a customer adds their payment info on the checkout. | Checkout    |
| [Subscribed To Newsletter](/sources/converge-spec#subscribed-to-newsletter) | When a customer subscribes to your newsletter.           | Checkout    |
| [Placed Order](/sources/converge-spec#placed-order)                         | When a customer places an order.                         | Checkout    |

This integration also auto-tracks some additional events that are not part of the Converge event spec.

| Event Name          | Event Description                                                | Integration |
| ------------------- | ---------------------------------------------------------------- | ----------- |
| Added Contact Info  | When a customer fills in the contact information in the checkout | Checkout    |
| Added Shipping Info | When a customer fills in their shipping info in the checkout     | Checkout    |

***

## Utility Object

<Note> Note that this utility object is not available on the Shopify Checkout. </Note>

Converge exposes a utility object called `__cvg_shopify_info` that picks up useful event properties and profile properties automatically.

We give an example below of requesting this object and what it looks like in the code example below.

<Accordion icon="code" title="Example of the utility object on a Product Page">
  ```js theme={null}
  window['__cvg_shopify_info']

  >>> {
      "product": {
          "id": 7104622526660,
          "title": "ADIDAS | CLASSIC BACKPACK",
          "handle": "adidas-classic-backpack",
          "description": "This women's backpack has a glam look, thanks to a faux-leather build with an allover fur print. The front zip pocket keeps small things within reach, while an interior divider reins in potential chaos.",
          "published_at": "2022-04-05T12:53:37+02:00",
          "created_at": "2022-04-05T12:53:37+02:00",
          "vendor": "ADIDAS",
          "type": "ACCESSORIES",
          "tags": [
              "adidas",
              "backpack",
              "egnition-sample-data"
          ],
          "price": 7000,
          "price_min": 7000,
          "price_max": 7000,
          "available": false,
          "price_varies": false,
          "compare_at_price": null,
          "compare_at_price_min": 0,
          "compare_at_price_max": 0,
          "compare_at_price_varies": false,
          "variants": [
              {
                  "id": 41374006870212,
                  "title": "OS / black",
                  "option1": "OS",
                  "option2": "black",
                  "option3": null,
                  "sku": "AD-03-black-OS",
                  "requires_shipping": true,
                  "taxable": true,
                  "featured_image": null,
                  "available": false,
                  "name": "ADIDAS | CLASSIC BACKPACK - OS / black",
                  "public_title": "OS / black",
                  "options": [
                      "OS",
                      "black"
                  ],
                  "price": 7000,
                  "weight": 0,
                  "compare_at_price": null,
                  "inventory_management": "shopify",
                  "barcode": null,
                  "requires_selling_plan": false,
                  "selling_plan_allocations": [
                      {
                          "price_adjustments": [
                              {
                                  "position": 1,
                                  "price": 7000
                              }
                          ],
                          "price": 7000,
                          "compare_at_price": 7000,
                          "per_delivery_price": 7000,
                          "selling_plan_id": 1961754820,
                          "selling_plan_group_id": "adc3b0fe7ea2b6a111dff9a6fb88114ceab61eec"
                      }
                  ],
                  "quantity_rule": {
                      "min": 1,
                      "max": null,
                      "increment": 1
                  }
              }
          ],
          "images": [
              "//converge-dev.myshopify.com/cdn/shop/products/85cc58608bf138a50036bcfe86a3a362.jpg?v=1649156017",
              "//converge-dev.myshopify.com/cdn/shop/products/8a029d2035bfb80e473361dfc08449be.jpg?v=1649156017",
              "//converge-dev.myshopify.com/cdn/shop/products/ad50775123e20f3d1af2bd07046b777d.jpg?v=1649156017"
          ],
          "featured_image": "//converge-dev.myshopify.com/cdn/shop/products/85cc58608bf138a50036bcfe86a3a362.jpg?v=1649156017",
          "options": [
              "Size",
              "Color"
          ],
          "media": [
              {
                  "alt": null,
                  "id": 23867923562692,
                  "position": 1,
                  "preview_image": {
                      "aspect_ratio": 1.134,
                      "height": 560,
                      "width": 635,
                      "src": "//converge-dev.myshopify.com/cdn/shop/products/85cc58608bf138a50036bcfe86a3a362.jpg?v=1649156017"
                  },
                  "aspect_ratio": 1.134,
                  "height": 560,
                  "media_type": "image",
                  "src": "//converge-dev.myshopify.com/cdn/shop/products/85cc58608bf138a50036bcfe86a3a362.jpg?v=1649156017",
                  "width": 635
              },
              {
                  "alt": null,
                  "id": 23867923595460,
                  "position": 2,
                  "preview_image": {
                      "aspect_ratio": 1.134,
                      "height": 560,
                      "width": 635,
                      "src": "//converge-dev.myshopify.com/cdn/shop/products/8a029d2035bfb80e473361dfc08449be.jpg?v=1649156017"
                  },
                  "aspect_ratio": 1.134,
                  "height": 560,
                  "media_type": "image",
                  "src": "//converge-dev.myshopify.com/cdn/shop/products/8a029d2035bfb80e473361dfc08449be.jpg?v=1649156017",
                  "width": 635
              },
              {
                  "alt": null,
                  "id": 23867923628228,
                  "position": 3,
                  "preview_image": {
                      "aspect_ratio": 1.134,
                      "height": 560,
                      "width": 635,
                      "src": "//converge-dev.myshopify.com/cdn/shop/products/ad50775123e20f3d1af2bd07046b777d.jpg?v=1649156017"
                  },
                  "aspect_ratio": 1.134,
                  "height": 560,
                  "media_type": "image",
                  "src": "//converge-dev.myshopify.com/cdn/shop/products/ad50775123e20f3d1af2bd07046b777d.jpg?v=1649156017",
                  "width": 635
              }
          ],
          "requires_selling_plan": false,
          "selling_plan_groups": [
              {
                  "id": "adc3b0fe7ea2b6a111dff9a6fb88114ceab61eec",
                  "name": "Test Plan",
                  "options": [
                      {
                          "name": "Frequency",
                          "position": 1,
                          "values": [
                              "Deliver every month"
                          ]
                      }
                  ],
                  "selling_plans": [
                      {
                          "id": 1961754820,
                          "name": "Deliver every month",
                          "description": "",
                          "options": [
                              {
                                  "name": "Frequency",
                                  "position": 1,
                                  "value": "Deliver every month"
                              }
                          ],
                          "recurring_deliveries": true,
                          "price_adjustments": [
                              {
                                  "order_count": null,
                                  "position": 1,
                                  "value_type": "fixed_amount",
                                  "value": 0
                              }
                          ],
                          "checkout_charge": {
                              "value_type": "percentage",
                              "value": 100
                          }
                      }
                  ],
                  "app_id": "5284869"
              }
          ],
          "content": "This women's backpack has a glam look, thanks to a faux-leather build with an allover fur print. The front zip pocket keeps small things within reach, while an interior divider reins in potential chaos."
      },
      "variant": {
          "id": 41374006870212,
          "title": "OS / black",
          "option1": "OS",
          "option2": "black",
          "option3": null,
          "sku": "AD-03-black-OS",
          "requires_shipping": true,
          "taxable": true,
          "featured_image": null,
          "available": false,
          "name": "ADIDAS | CLASSIC BACKPACK - OS / black",
          "public_title": "OS / black",
          "options": [
              "OS",
              "black"
          ],
          "price": 7000,
          "weight": 0,
          "compare_at_price": null,
          "inventory_management": "shopify",
          "barcode": null,
          "requires_selling_plan": false,
          "selling_plan_allocations": [
              {
                  "price_adjustments": [
                      {
                          "position": 1,
                          "price": 7000
                      }
                  ],
                  "price": 7000,
                  "compare_at_price": 7000,
                  "per_delivery_price": 7000,
                  "selling_plan_id": 1961754820,
                  "selling_plan_group_id": "adc3b0fe7ea2b6a111dff9a6fb88114ceab61eec"
              }
          ],
          "quantity_rule": {
              "min": 1,
              "max": null,
              "increment": 1
          }
      },
      "currency": "GBP",
      "collection": {
          "products": null
      },
      "customer_id": null,
      "email": null,
      "address": null,
      "phone": null,
      "search": null
  }
  ```
</Accordion>


# TypeScript SDK
Source: https://docs.runconverge.com/sources/website-integrations/typescript-sdk

Implement Converge JS Pixel with the TypeScript SDK

## Installation instructions

<Steps>
  <Step title="Create a new Client Source in Converge">
    1. In Converge, click on **Create a new source**
    2. Pick *Client-side* from the modal
    3. Name your pixel: e.g. `{Storename} Storefront`
  </Step>

  <Step title="Install the Converge HTML snippet in your storefront">
    4. Click on your newly created Source and from the modal pick `HTML`, and copy the first `<script>` tag from the snippet.

    <Accordion icon="code" title="Code example">
      ```javascript theme={null}
      <script
        src="<https://static.runconverge.com/pixels/{YOUR_PUBLIC_TOKEN}.js>"
        async
      ></script>
      ```
    </Accordion>

    5. Copy the HTML snippet and include it in the header of your website, right above the closing `</head>` tag.
  </Step>

  <Step title="Add the Converge Typescript SDK">
    6. Install the package using your package manager.

    ```shell-session theme={null}
    # npm
    npm install @runconverge/browser

    # yarn
    yarn add @runconverge/browser
    ```

    6. Import the package and use it.

    ```typescript theme={null}
    import { Converge } from '@runconverge/browser'
    ```

    7. Track your events.

    <CodeGroup>
      ```typescript $page_load theme={null}
      Converge.track({
        eventName: "$page_load"
      });
      ```

      ```typescript Added To Cart theme={null}
      Converge.track({
        eventName: "Added To Cart",
        properties: {
          product_id: "123456",
          variant_id: "78910",
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla",
          price: 42,
          currency: "USD",
          quantity: 1,
          vendor: "My Store",
        }
      });
      ```

      ```typescript Added Payment Info theme={null}
      Converge.track({
        eventName: "Added Payment Info",
        properties: {
          total_price: 42,
          total_tax: 3.5,
          total_shipping: 2.4,
          currency: "USD",
          items: [
            {
              product_id: "123456",
              sku: "MY_SKU",
              name: "My Product",
              price: 42,
              currency: "USD",
              quantity: 1,
              vendor: "My Store",
            },
          ],
        },
        profileProperties: {
          // Pass if available
          $email: "john.smith@apple.com",
          $phone_number: "+199999999",
          $city: "San Francisco",
          $country_code: "US",
          $state: "California",
          $zip_code: "94103",
        },
        aliases: ["urn:email:john.smith@apple.com"]
      });
      ```

      ```typescript Placed Order theme={null}
      Converge.forward({
          eventName: "Placed Order",
          eventID: "order-1", // used for deduplicating, should be unique
          properties: {
            id: "order-1",
            total_price: 42,
            total_tax: 3.5,
            total_shipping: 2.4,
            currency: "USD",
            coupon: 'COUPON123',
            items: [
              {
                product_id: "123456",
                variant_id: "654321",
                sku: "MY_SKU",
                name: "My Product",
                variant_name: "Vanilla",
                price: 42,
                currency: "USD",
                quantity: 1,
                vendor: "My Store",
              },
            ],
            $is_new_customer: false
          },
          profileProperties: {
            // Pass if available
            $email: "john.smith@apple.com",
            $phone_number: "+199999999",
            $city: "San Francisco",
            $country_code: "US",
            $state: "California",
            $zip_code: "94103",
          },
          aliases: ["urn:email:john.smith@apple.com"]
        });
      ```

      ```typescript Custom Event theme={null}
      Converge.track({
          eventName: 'Custom Event',
          // ... extra props
      })
      ```
    </CodeGroup>

    <Note>Find the package on NPM [here](https://www.npmjs.com/package/@runconverge/browser).</Note>
  </Step>

  <Step title="Verify that the integration is working correctly">
    6. Check that your pixel is working correctly by generating some `$page_load` events by visiting the website and seeing that these events arrive in the Source Log.

    <Info>Set up a [Pixel Monitor](/sources/monitoring#pixel-monitor) to automatically verify your pixel stays installed.</Info>
  </Step>
</Steps>

***

## Cross-domain tracking

Converge supports cross-domain tracking through the methods below. We can stitch sessions across different domains and make sure that cookie information, first-party attribution, etc. will work correctly.

Note that you do **not** need to do anything for tracking across subdomains.
i.e. if the pixel snippet is installed on `myfirstdomain.com` and on `checkout.myfirstdomain.com`, the sessions should be stitched across both domains automatically.

If you want to stitch a session from `myfirstdomain.com` to `myotherdomain.com` then you will want to make sure to implement it as per the instructions below.

### How does cross-domain tracking work

Converge allows for cross-domain tracking through the `__cvg_uid` and `__cvg_sid` parameters and cookies.
If Converge recognizes the same `__cvg_uid` and `__cvg_sid` identifiers for pageviews on `myfirstdomain.com` and pageviews on `myotherdomain.com` then it will stitch those sessions under the same profile and session.

To stitch, we need to be able to pass the cookie between different websites as the cookie is only generated if the `__cvg_uid` and `__cvg_sid` are not set in the URL.
If there is a `__cvg_uid` set in the URL as a parameter, the cookie will be set to this value.

<Frame>
  ```mermaid actions={false} theme={null}
  flowchart TB
    id1("*User* visits **myfirstdomain.com** and gets assigned **__cvg_uid=1234** and **__cvg_sid=ABCD**") -. "Clicks on link myotherdomain.com/?__cvg_uid=1234&__cvg_sid=ABCD" .-> id2("*User* visits **myotherdomain.com** and Converge reads the id from the URL") ~~~ id3(["**Session stitched**  ✓ "])
    style id3 color:#02b802,stroke:none
  ```
</Frame>

### The `link_domain` method

The Converge Pixel exposes the `link_domain` method to automatically add the `?__cvg_uid={CVG_ID_VALUE}&__cvg_sid={CVG_SID_VALUE}` suffix to every outbound link that leads to `myotherdomain.com`.
Include the following method together with the basic Converge pixel snippet on the `myfirstdomain.com` website to enable it on every page.

```typescript theme={null}
Converge.linkDomain({
    domain: 'myotherdomain.com'
})
```

<Note>
  Always validate that both `__cvg_uid` and `__cvg_sid` are present after navigating to another domain. If those are missing, Converge has no way of stitching the events correctly. This will potentially lead to sessions being attributed as organic referrals from your other domain.
</Note>

<Warning>
  If the redirect to `myotherdomain.com` does not happen directly through a link click, but for example, through JS code, the parameter won't be added automatically.

  You should follow [Manually setting up cross-domain tracking](#manually-setting-up-cross-domain-tracking), to manually instrument the links.
</Warning>

### Manually setting up cross-domain tracking

If the `link_domain` cannot be used in your case, you will need to manually instrument the links by adding the `__cvg_uid` and `__cvg_sid` URL parameters and their corresponding cookie values for each outbound link in that case.

The procedure for this will vary depending on your specific requirements. But in general, it consists of fetching the necessary cookie values and appending them to the URL before redirecting.

For example, assuming you are navigating to another domain using a click event on a button, one possible approach is the following:

```js theme={null}
document.getElementById('some-button').addEventListener('click', () => {
    // use your preferred way of reading cookie values
    let uid = getCookie('__cvg_uid')
    let sid = getCookie('__cvg_sid')

    window.location.href = `https://myotherdomain.com?__cvg_uid=${uid}&__cvg_sid=${sid}`
})
```

<Note>
  Always validate that both `__cvg_uid` and `__cvg_sid` are present after navigating to another domain. If those are missing, Converge has no way of stitching the events correctly. This will potentially lead to sessions being attributed as organic referrals from your other domain.
</Note>

***

## Manually instrumenting events

If the pre-built website integrations do not cover the entire [Converge event spec](/sources/converge-spec); or if you want to add custom events from your website then you will need to manually instrument these using the Converge Pixel.
You can use the `track` method in the Converge Pixel for this purpose.

<Note> As a general rule, you should always **aim to pass as many `properties`, `profileProperties` and `aliases` as possible** </Note>

The track method has the following parameters:

* `eventName`: The name of the event
* `properties`: The event properties you want to pass, covering the Converge Spec and possibly your own custom properties.
* `profileProperties`: The [profile properties](/sources/source-concepts#profile-properties)
* `aliases`: Any [aliases](/sources/source-concepts#aliases)

<AccordionGroup>
  <Info> You can find Converge JS examples for the entire [Converge Spec here](/sources/converge-spec) </Info>

  <Accordion title="Code Examples" icon="code">
    <CodeGroup>
      ```typescript Added To Cart theme={null}
      Converge.track({
        eventName: "Added To Cart",
        properties: {
          product_id: "123456",
          variant_id: "78910",
          sku: "MY_SKU",
          name: "My Product",
          variant_name: "Vanilla",
          price: 42,
          currency: "USD",
          quantity: 1,
          vendor: "My Store",
        },
      });
      ```

      ```typescript Added Payment Info theme={null}
      Converge.track({
        eventName: "Added Payment Info",
        properties: {
          total_price: 42,
          total_tax: 3.5,
          total_shipping: 2.4,
          currency: "USD",
          items: [
            {
              product_id: "123456",
              sku: "MY_SKU",
              name: "My Product",
              price: 42,
              currency: "USD",
              quantity: 1,
              vendor: "My Store",
            },
          ],
        },
        profileProperties: {
          // Pass if available
          $email: "john.smith@apple.com",
          $phone_number: "+199999999",
          $city: "San Francisco",
          $country_code: "US",
          $state: "California",
          $zip_code: "94103",
        },
        aliases: ["urn:email:john.smith@apple.com"],
      });

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Turning off tracking for internal users

By appending the `internalUser=1` query parameter to the URL of the page you're visiting, you can prevent the Converge pixel from executing.
As a consequence, no events or sessions will be tracked. For example:

* `https://mywebsite.com?internalUser=1`
* `https://mywebsite.com/product-1?internalUser=1`
* `https://mywebsite.com/product-1?utm_source=test&internalUser=1`

<Note>
  This flag is stored under the `__cvg_internal_user` cookie and will persist for this browser, for as long as the cookie is present (up to 2 years).

  When conducting internal testing, it is advised to regularly add the `internalUser=1` query parameter to the URL to prevent tracking.
</Note>


# WooCommerce Web
Source: https://docs.runconverge.com/sources/website-integrations/woocommerce

Install the WooCommerce Storefront Plugin

The WooCommerce Website Integration consists of a WooCommerce plugin that tracks your storefront and checkout events.

***

## Installation instructions

The Converge Website installation for a WooCommerce store consists of:

<Steps>
  <Step title="Create a new Client Source in Converge">
    1. In Converge, click on **Create a new source**
    2. Pick *Client-side* from the modal
    3. Name your pixel: e.g. `{Storename} Storefront`
  </Step>

  <Step title="Install the WooCommerce Plugin">
    4. Download the WooCommerce Plugin by clicking on the following link: <DownloadLink />

    5. In the WordPress admin dashboard, navigate to **Plugins** in the sidebar and click on **Upload Plugin**.

    6. Choose the .zip file that you just downloaded as the file to upload.

    7. Click on **Install Plugin** and after that on **Activate Plugin**
  </Step>

  <Step title="Configure the WooCommerce Plugin">
    8. In the Converge web app, click on the source you created in *Step 1* and copy the **Public Token**.
       <Info> The code consists of 6 characters and can be retrieved from the HTML snippet. If your script `src` looks like `https://static.runconverge.com/pixels/AYU51m.js`, then your public token is `AYU51m`. </Info>
    9. Navigate to **Tools** > **Converge** in the WooCommerce dashboard.
    10. Fill in the **Public Token** and save the configuration.
  </Step>

  <Step title="Verify that the integration is working correctly">
    11. Check that the plugin is working correctly by generating some `$page_load`, `Added To Cart`, `Started Checkout` events by visiting the store and seeing that these events arrive in the Source Log.

    <Info>Set up a [Pixel Monitor](/sources/monitoring#pixel-monitor) to automatically verify your pixel stays installed.</Info>
  </Step>
</Steps>

***

## Event spec

This integration auto-tracks the following events on the browser with all properties available according to the [Converge event spec](/sources/converge-spec).

| Event Name                                                  | Event Description                               | Integration |
| ----------------------------------------------------------- | ----------------------------------------------- | ----------- |
| [PageView](/sources/converge-spec#page-view)                | When a customer views a page.                   | Storefront  |
| [Viewed Product](/sources/converge-spec#viewed-product)     | When a customer views a product.                | Storefront  |
| [Added To Cart](/sources/converge-spec#added-to-cart)       | When a customer adds an item to cart            | Checkout    |
| [Started Checkout](/sources/converge-spec#started-checkout) | When a customer initiates the checkout process. | Checkout    |
| [Placed Order](/sources/converge-spec#placed-order)         | When a customer places an order.                | Checkout    |