Converge Pixel

This section explains how to install the plain Converge JS Pixel for a custom or headless storefront. If you are not using a custom setup, then have a look at our prebuilt integrations.

Quickstart
Implementing Basic Ecommerce Events
Cross-domain tracking
Tracking Custom Events
Tracking Landing Page Builders

1. Quickstart

This guide helps you install the basic Converge Pixel which tracks $page_load-events by default.

Log in to the Converge webapp on app.runconverge.com and click on the Sources tab in the left side-bar.
Click on Create a new source and pick Client-side from the modal
Name your pixel: e.g. {Storename} Storefront

After creating the pixel, click on your pixel and from the modal pick HTML, it should look something like this.

<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,argum
  ents):c.queue.push(arguments)},c.queue=[]);
  cvg({method:"track",eventName:"$page_load"});
</script>

Copy the HTML snippet and include it in the header of your website.
Check that your pixel is working correctly by refreshing the page and seeing $page_load events arrive in Converge at the Profiles tab.

📌 Note for single-page applications

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

2. Implementing Basic Ecommerce Events

Converge has a predefined spec with regards to Ecommerce Events. Once the basic pixel is installed, you should set up as many as possible of the following events for all destinations to work optimally.

You might decide to set up some events through the server integration. You can find some more info as to what you should track through the pixel versus on the server here.

a) Viewed Product

b) Description

When a user views a product detail page.

Code example:

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",
  },
});

b) Viewed Collection

Description

When a user views a collection detail page that includes multiple products.

Code example:

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",
      },
    ],
  },
});

c) Added To Cart

Description

When a user adds an item to cart.

Code example:

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",
  },
});

d) Started Checkout

Description

When a user views a product detail page.

Code example:

cvg({
  method: "track",
  eventName: "Started Checkout",
  properties: {
    total_price: 42,
    total_tax: 3.5,
    total_shipping: 2.4,
    currency: "USD",
    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",
      },
    ],
  },
});

e) Added Payment Info

Description

When a user views a product detail page.

Code example:

📌 Make sure you pass as many profile properties and appropriate aliases as possible. You can read more about profile properties here, and about aliases here.

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"],
});

f) Placed Order

Description

When a user places an order.

Code example:

📌 Make sure you pass as many profile properties and appropriate aliases as possible. You can read more about profile properties here, and about aliases here.

📌 Typically, you would want to set up Placed Order tracking using the server-side integration.

cvg({
  method: "track",
  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",
    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"],
});

Description

When a user subscribes to the newsletter.

Code example:

📌 Make sure you pass as many profile properties and appropriate aliases as possible. You can read more about profile properties here, and about aliases here.

cvg({
  method: "track",
  eventName: "Subscribed To Newsletter",
  properties: {
    formId: "your-form-id",
  },
  profileProperties: {
    // Only pass the relevant parameters
    $email: "john.smith@apple.com",
    $first_name: "John",
    $last_name: "Smith",
    $phone_number: "+199999999",
  },
  // for more info, see the section on aliases
  aliases: ["urn:email:john.smith@apple.com"],
});

h) Logged In

Description

When a user logs in.

Code example:

📌 Make sure you pass as many profile properties and appropriate aliases as possible. You can read more about profile properties here, and about aliases here.

cvg({
  method: "track",
  eventName: "Logged In",
  properties: {},
  profileProperties: {
    // Pass if available
    $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"],
});

3. Cross-domain tracking

Converge supports cross-domain tracking out-of-the box. To enable cross-domain tracking from myfirstdomain.com to myotherdomain.com, include the following method together with the basic Converge pixel snippet.

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

📌 Note that you do not need this snippet 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 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.

4. Tracking Custom Events

Sometimes you want to go beyond the basic ecommerce events and track custom events. All of these examples below presume that you have already installed the Converge JS/Liquid snippet on your website.

a) Tracking a Custom PageView

The Converge Pixel already auto-tracks $page_load-events for every PageView. However, sometimes you might want to track a specific PageView as a custom event – for example, you could track a PageView of the Thank you page as a Viewed Thank You Page-event.

To do this, you will just want to embed the following one-liner in the <head> tags of the specific page.

<script>
  cvg({ method: "event", event: "Viewed Thank You Page" });
</script>

b) Tracking a Custom Button Click

We already discussed how to trigger a custom event when a page is viewed, but what if you want to trigger a Converge custom event based on a click of an element (e.g. a button).

To do that, you will want to add an EventListener to the HTMLElement in question, that fires the Custom Converge event once someone clicks on the HTMLElement.

Step-by-step

Right-click on the item in question you want to track, click on “Inspect Element”. In this example, this is the BigCommerce button on the Converge Integrations Page.

Right-click on the item in the HTML code, click on “Copy > Copy Selector”. In this example, the selector is: #main > div > a. You will need this selector for the code-snippet, so keep it.
Insert the following code in the <head>-tags.

<script>
  // Identify the Button
  // Replace the selector, with your selector in step 2.
  var bigCommerceButton = document.querySelector("#main > div > a");

  // Add Event Listener to Button that sends Converge Event once clicked
  bigCommerceButton.addEventListener(
    "click",
    function () {
      cvg({ method: "event", event: "Clicked BigCommerce Integration" });
    },
    false
  );
</script>

d) Tracking an Email Form Submission

Sometimes, you want to send extra event information or profile information to Converge. Suppose for example that you want to track a Subscribed To Newsletter event.

Not only would you like for Converge to track that event, but you would also want Converge to:

Send the email in the properties of the event (i.e. send email as an event property)
Identify the user in Converge with this email (i.e. send email as a profile property)
Use this email address to match the user across different sessions.(i.e. send email as a profile alias)

In the snippet below we give such a full example:

We find the selector to the submit-button of the newsletter form.
We add an EventListener that will trigger once someone clicks that button and do the following things: a. Retrieve the value of the inputfield in the form that holds the email b. If the email is a valid email, the Converge event gets sent c. Notice that the $email property gets set across the (event)properties, profileProperties and aliases.

Code Example

<script>
  // Helper function to test if an email is valid
  function isValidEmail(email) {
    const pattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return pattern.test(email);
  }

  jQuery(document).ready(function ($) {
      var submitButton = document.querySelector('#create_customer > div.extras > input');
      submitButton.addEventListener( 'click', function() {

         // Get Email from input field
         var email = document.querySelector('#Email').value;

         // Send Converge Event if valid email
         if (email && isValidEmail(email)){
              cvg({
                  method: "event",
                  event: "Subscribed To Newsletter",
                  properties: {"$email": `${email}`},
                  aliases: [`urn:email:${email}`],
                  profileProperties: {"$email": `${email}`}
                });
         }
      };, false);
  });
</script>

5. Tracking Landing Page Builders

Many Ecommerce stores use custom landing page builders such as Unbounce. Converge can track $page_load-events on these landing pages and stitch their sessions with Purchases on the actual store.

Log in to the Converge webapp on app.runconverge.com and click on the Sources tab in the left side-bar.
Click on Create a new source and pick Client-side from the modal
Name your pixel: e.g. {Storename} Landing Pages

After creating the pixel, click on your pixel and from the modal pick HTML, it should look something like this.

<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,argum
  ents):c.queue.push(arguments)},c.queue=[]);
  cvg({method:"track",eventName:"$page_load"});
</script>

Copy the HTML snippet and include it in the Scripts section of your landing page builder.

Converge Pixel

Table of contents

1. Quickstart

📌 Note for single-page applications

2. Implementing Basic Ecommerce Events

a) Viewed Product

b) Description

Code example:

b) Viewed Collection

Description

Code example:

c) Added To Cart

Description

Code example:

d) Started Checkout

Description

Code example:

e) Added Payment Info

Description

Code example:

f) Placed Order

Description

Code example:

g) Subscribed To Newsletter

Description

Code example:

h) Logged In

Description

Code example:

3. Cross-domain tracking

4. Tracking Custom Events

a) Tracking a Custom PageView

b) Tracking a Custom Button Click

Step-by-step

d) Tracking an Email Form Submission

Code Example

5. Tracking Landing Page Builders