Converge JS

​

Installation Instructions

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

​

Note for Single-page applications

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

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

​

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

​

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.

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

​

Event Spec

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