​
Installation Instructions

1

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
2

Install the Converge HTML snippet in your storefront

  1. Click on your newly created Source and from the modal pick HTML, and copy the first <script> tag from the snippet.
  1. Copy the HTML snippet and include it in the header of your website, right above the closing </head> tag.
3

Add the Converge Typescript SDK

  1. Install the package using your package manager.
# npm
npm install @runconverge/browser

# yarn
yarn add @runconverge/browser
  1. Import the package and use it.
import { Converge } from '@runconverge/browser'
  1. Track your events.
Converge.track({
  eventName: "$page_load"
});
Find the package on NPM here.
4

Verify that the integration is working correctly

  1. 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.

​
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.

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.

Converge.linkDomain({
    domain: 'myotherdomain.com'
})

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.

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, to manually instrument the links.

​
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:

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}`
})

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.

​
Manually instrumenting events

If the pre-built website integrations do not cover the entire Converge Event 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.

As a general rule, you should always aim to pass as many properties, profileProperties and aliases as possible

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
  • aliases: Any aliases
You can find Converge JS examples for the entire Converge Spec here

​
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

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.