Custom Events Tracking

Use the Intelligems Javascript API to track any visitor behavior in your store in order to better analyze test results, track custom goals, and more.

What are Custom Events and How Do They Help?

Intelligems allows you to track the behavior of visitors as they browse your site - for example which visitors viewed a certain page, clicked a newsletter signup button, lingered on a page, or scrolled down far enough to see some explanatory text. You do this in javascript code by

1. Defining any number of these actions as a "Custom Event" and

2. Letting Intelligems know every time a visitor has triggered one of them

Two reasons you may wish to collect this kind of information:

• To better analyze results: When viewing the results of a test in the Intelligems Analytics page, you can filter the data to only include visitors that triggered one or more of your Custom Events. This helps you determine whether your test results were somehow influenced or correlated to these behaviors. For example, let's say you run a test that alters the site nav and your Variant delivers more conversions than your Control Group. You may suspect this is because the Variant navigation made the "Product Benefits" page more discoverable. By creating a Custom Event "Viewed Benefits Page" triggered every time a visitor views that page, you can filter your test results to see whether the conversion rate was indeed higher for people who saw the benefits page.

• To track custom goals: There may be times when your main goal is to maximize a specialized metric rather than orders, revenue, or profit. For example, if you want to maximize subscriptions to your newsletter you may run a test to see which homepage layout achieves this. If you define a Custom Event "Signed up for Newsletter" that's triggered every time someone presses the signup button, you will be able to see in Intelligems Analytics a chart that shows what percent of visitors in each test group pressed the signup button, allowing you to determine which website layout is the winner.

Setup & Prerequisites

Make sure Intelligems is installed on your site. Verify this by running window.igData in your browser's developer console.

The code in a nutshell

To record a Custom Event, write a javascript event handler function that captures a visitor action on the site (for example clicking a certain button) and, in that handler, push an object to the igEvents array in the following format:

window.igEvents.push({"event": "myCustomEventName"});

Where to place the code

Your Custom Event javascript can be added in one of two places:

• Theme.liquid (recommended): Placing Custom Event code in the header of your Shopify theme's theme.liquid fie ensures that it's loaded quickly and that your events are triggered and sent to Intelligems at all times, allowing you to make use of the data across tests. When you no longer need a certain Custom Event, you should remove it from your Shopify theme code.

  

  Placing code into your Shopify theme
• Javascript Injection on individual tests: Many types of tests allow you to specify custom Javascript code to run on the site for each test group. You can place your Custom Event code directly into this UI widget when you are setting up the test - making sure that you duplicate the code for every test group. Intelligems will stop tracking your Custom Events once the test has ended, so this approach makes sense if your Custom Event(s) are only useful for one test.

Placing code into a test's JS Injection widget

API

igEvents should be initialized as an empty array if the Intelligems script hasn't yet loaded. This ensures that timing won't affect the integrity of your tracking. Once Intelligems has loaded, all events in this array will be retroactively tracked, and all consequent events will be tracked immediately.

<script>
    window.igEvents = window.igEvents || [];
    window.igEvents.push({"event": "myCustomEvent"});
</script>

Track an event by calling igEvents.push() . The object passed into push can have two keys:

event (required): the name of your event, meant to uniquely identify the action you're tracking. This will be used to categorize events when viewing analytics in our dashboard.

Commas, single quotes, and trailing spaces will be stripped from event names

properties (optional): arbitrary key value pairs, anything goes as long as it's valid JSON. Use this to add context relevant to the event . It'll help you create more fine grained queries among a single event when digging into your analytics.

Properties will be saved for future use, but are not currently available for analysis in Intelligems analytics.

Intelligems Context

Intelligems appends other meaningful metadata to your events. This lets you associate custom event flows with actionable outcomes that Intelligems tracks by default. Includes but not limited to:

• Intelligems assigned unique user identifier, set in local storage so it persists across sessions

• Test groups the user is assigned to for any active experiment

• Campaigns the user is included in

Example Usage

Track a button click by pushing to igEvents in the onclick handler.

<script>
function trackIntelligemsEvent(event) {
  window.igEvents = window.igEvents || [];
  window.igEvents.push({
    "event": event
  })
}

// wait for my button to exist in the DOM, then add an event listener
window.igEvents = window.igEvents || [];
function waitForElements(selector) {
  return new Promise(resolve => {
    if (document.querySelectorAll(selector)) {
      return resolve(document.querySelectorAll(selector));
    }

    const observer = new MutationObserver(mutations => {
      if (document.querySelectorAll(selector)) {
        observer.disconnect();
        resolve(document.querySelectorAll(selector));
      }
    });

    observer.observe(document.body, {
      childList: true,
      subtree: true
    });
  });
}

waitForElements('#my-button').then((elements) => {
  for (const el of elements) {
    el.addEventListener("click", () => {
      window.igEvents.push({
        "event": "My Button Clicked"
      })
    });
  }
});
</script>

Track a page view in a window event listener.

window.addEventListener("load", (event) => {
  window.igEvents = window.igEvents || [];
  window.igEvents.push({
    "event": "Product Page Viewed"
  })
});

Track a mouseover event on an element to see if users hovered over it.

myElement.addEventListener("mouseover", (event) => {
  window.igEvents = window.igEvents || [];
  window.igEvents.push({
    "event": "ATC Hovered"
  })
});

Testing Your Custom Events

Before deploying a Custom Event you may want to make sure that the visitor behavior is 1. correctly triggering your javascript code and 2. the event is sent to the Intelligems backend successfully. To do this:

• Open your site in the browser with Dev Tools (or other debugger) set to view Network Traffic

• Perform the event (clicking a button, hovering over an element, visiting a page)

• In the Network Traffic view, look for network calls to intelligems.io/v3/track that contain the event type "custom_event". If these appear, it means that your code is correctly triggering the event and that it's being sent to Intelligems.

Viewing Custom Events in Intelligems

Once you have set up Custom Event(s), you can view them in two locations in the Intelligems Analytics Dashboard:

• You can view how many visitors have completed your custom event(s) in the charts at the bottom of the Visitors tab.

Analytics for Custom Event "Mobile Menu Opened"

• You can filter your results to visitors that have triggered each of your custom event(s) at least once under the filters option in the top right corner of the analytics dashboard.

Filtering Analytics by Custom Event "Mobile Menu Opened"

Custom Events & Page Targeting: If your test uses Page Targeting, its analytics will only show custom events that fire from one of the pages you are targeting. For example if your test only targets the Home Page, but you record two click events on a PDP, those click events will not be visible in the test's analytics unless you also include the PDP in your test's page targeting. The same applies for Personalizations.

Note that a Custom Event may be triggered (and recorded by Intelligems) over the course of many experiments, especially if you placed your Custom Event code directly into the Shopify theme. When viewing and filtering Analytics for a given experiment, Intelligems will only count occurrences of that event while that particular experiment was live. For example, a visitor will not be counted as having triggered Custom Event "Viewed Benefits" during a February experiment if they viewed the Benefits page only in January.

Note that