Tracking: Sending your own events

Optional: identifying customers and recording other actions.

Beyond page views and bookings, your site can send Distil other information. These calls can be made from your site's code, or from a GTM Custom HTML tag.

Identifying a customer

When a visitor signs in or gives their details (for example on a newsletter form), link the visit to them:

distil.identifyCustomer({
  CustomerId: '12345',                     /* string or number; one of CustomerId/EmailAddress required */
  EmailAddress: 'customer@example.com',    /* string */
  GDPRStatus: {                            /* required */
    MarketingSubscribed: MARKETING_CONSENT /* required: replace with true or false, the customer's real choice */
  }
});

It needs:

• a CustomerId or an EmailAddress (or both), and
• GDPRStatus with MarketingSubscribed: true if the customer has agreed to marketing, false if not.

Single-page sites

On most sites, every page is a fresh page load, and the tracking script records each page view automatically. On a single-page site (built with React, Vue, Angular and similar), the page doesn't reload when the visitor moves around, so only the first page view is recorded automatically.

With Distil's ready-made Google Tag Manager setup, set the variable Distil - Single Page Site to yes. It records a page view on every page change, so you don't need the code below.

Installed directly on your website? Add this script straight after the tracking script, on every page. It records a page view each time the page changes:

<script>
(function(){if(window.__distilPageChanges)return;window.__distilPageChanges=true;
var last=location.pathname+location.search;
function changed(){setTimeout(function(){
var now=location.pathname+location.search;if(now===last)return;last=now;
if(window.distil&&window.distil.trackPage)window.distil.trackPage()},500)}
function wrap(name){var orig=history[name];if(typeof orig!=="function")return;
history[name]=function(){var r=orig.apply(this,arguments);changed();return r}}
wrap("pushState");wrap("replaceState");
window.addEventListener("popstate",changed);
})();
</script>

• What counts as a page change: a new path or query string in the browser's address, including the visitor using Back and Forward. A change to the # part only, or to the same address, isn't recorded.
• It waits half a second before recording, so your site has time to update the page title.
• If your site has a cookie banner, load this script the same way as the tracking script: only after the visitor accepts analytics cookies.

If you'd rather record page changes from your site's own code, for example in your router's page-change handler, call trackPage instead of adding the script. Don't do both, or each page change is recorded twice.

Call trackPage each time the page changes:

distil.trackPage();

If the browser's address doesn't change when the page does, tell Distil which page the visitor is on:

distil.trackPage({ pageUrl: '/menus/dinner' });

• A path is enough: '/menus/dinner' and 'menus/dinner' both record that page on the site the visitor is on. A full address is only used if it matches the visitor's current site exactly (www. included).
• The current query string is kept, so UTM tags in the browser's address are still recorded. Any query string you add in pageUrl is added to it, and replaces a parameter with the same name.
• It must be your own domain. A pageUrl on a different domain is ignored, and the browser's real address is recorded instead.

The other calls in this section accept the same option as their last argument, for example distil.trackEvent('click', 'newsletter-signup', {}, null, { pageUrl: '/newsletter' }).

Recording another action

distil.trackEvent('click', 'newsletter-signup', {
  campaign: 'summer-promo'
});

The first two values name the event. The object holds any details you want to attach.