​
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 that snippet.
  1. Copy the HTML snippet and include it in the header of your website, right above the closing </head> tag.
3

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.

​
Note for Single-page applications

If you are using a single-page application, you should hook the $page_load tracking call into your router to re-fire the event.
NextJS
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;

​
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, UTM 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_uuid parameter and cookie. If Converge recognizes the same __cvg_uid identifier 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 is not set in the URL. If there is a __cvg_uid set in the URL as a hyperparam, 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} 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.

cvg({ method: "link_domain", domain: "myotherdomain.com" });

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. So it is important to always test whether the __cvg_uid parameter is present on the new URL.

You will need to manually instrument the link by adding the ?__cvg_uid URL parameter and its corresponding cookie value for each outbound link in that case.

​
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

​
Event Spec

This integration auto-tracks the following events with all properties available according to the Converge Event Spec.

Event NameEvent Description
$page_loadWhen a customer views a page.
Custom Event PropertiesShopify Web