Tracking Setup: Distil Tracking Code

The Code

We've already written the code snippet for you, so you can just copy and paste it. The code is in Settings > Tracking > JS Bespoke tab. The script includes a unique 32-character identifier for your Distil Account, so take care not to modify this value.

Where To Put the Code

We recommend that the JavaScript code is inserted into the Head section of the HTML within each page on your website. This means that Distil Tracking will be initialised as soon as the page is loaded.

Alternatively, the JavaScript code can be included in the Body section. However, if users click away from the page before the JavaScript code initialises Distil Tracking, then this may result in some Tracking data being lost.

Adding the JavaScript Tracking code is straightforward if you're using a Content Management System (CMS) such as Wordpress, Squarespace, Magnolia or Weebly. Search online for instructions for your specific CMS.

Using the Code

Once the Tracking code is on a web page as described above, capturing Tracking data is a matter of calling the correct tracking event function at the correct time. The section below explains how to use the various functions, including the properties that they return.

Context Object

In addition to returning the properties of the called function, the JavaScript Tracking code will also automatically capture additional contextual information. This information includes the page that the user is on, their IP address, the referring URL and the time of the event. These pieces of information are stored in the Context object.

Here's an example of the Context object:

"Context”: {
    "DistilAccountId": "f1a2df172a8045489d95cf4658bd60ba",
    "AnonymousUserID": "598b0746-a073-4ac6-aa68-808ec3f6df68",
    "Device Information": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.114 Safari/537.36",
    "EventTimestampUTC": "2021-04-13 16:26:12",
    "EventTimestampLocal": "2021-04-13 17:26:12",
    "PageTitle": "Product 2",
    "PageUrl": "http://www.fakesite.com/product-2",
    "ReferrerUrl": "http://www.fakesite.com/product-1",
    "IpAddress": "86.161.138.123"
}

The JavaScript Tracking code will automatically create a unique identifier called AnonymousUserID for each user visiting the site, and store this information in the browser's local storage (Distil does not use cookies). You can see this ID in the example object above. The same ID will be used to identify the user each time they visit, ensuring that the entirety of their behaviour is tracked and tied to a single Customer: from a first anonymous visit through to multiple purchases. For more information, read our article on how Distil identifies Customers.

Data Types

The following are the data types that are accepted by the Distil JavaScript Tracking code, in the JSON object property blocks.

Add Distil Event Tracking Calls

The following event functions are available in the Distil Tracking code:

• Track Page
• Identify Customer
• Track Product
• Track Content
• Track Order
• Track Event

Track Page

By default - each time a new page is loaded and the Distil tracking code is embedded in the page, then the trackPage function will be invoked automatically. This function will only pass the Context information for the current page. 

Call the trackPage function:

distil.trackPage();

Single Page Applications

For single page applications where the URL does not change, then by default the page does not reload, and therefore trackPage is not being called on each refresh. Therefore, it is up to the owner of the site to implement the call to this function each time the page changes.

Also - as the page URL does not change, then in order to track the virtual path, it is possible to pass in the path of the current page manually in the tracking like so:

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

There are some caveats around how this works and what is allowed to be entered into this property, as described in the section: Overriding Current Page Path

Identify Customer

When a user is browsing the site, their browsing history is tied to their AnonymousUserID. When this user identifies themselves explicitly by logging in or filling in a form with personal details, Distil captures this identifying information via the identifyCustomer event function and ties it to that person's browsing history via their AnonymousUserID (for more information, read our article on how Distil identifies Customers).

The identifyCustomer event function needs to be added to all pages where visitors identify themselves by logging in or filling in a form with personal details.

When this event function is called, the Distil Tracking code will also automatically pass a Context object as explained in the section above.

Call the event function:

distil.identifyCustomer(customerProperties, [additionalOptions]);

Pass the following argument to the function:

CustomerProperties Object properties

Note that customerProperties is required when using the identifyCustomer event function - and specific fields are required to be sent with each identifyCustomer request. A minimum of either the CustomerId OR the EmailAddress are required in order to identify the Customer to Distil (passing both is perfectly valid and encouraged if the CustomerId is unique) plus the current Marketing Subscribed status for the user.

GDPRStatus Object properties

Note that some of the properties of GDPRStatus are mandatory.

PostalAddress Object properties

Examples

Examples of a call with only mandatory fields:

1. With Customer ID

  let customerProperties = {
    CustomerId: '1234',
    GDPRStatus: {
      MarketingSubscribed: true / false
    }
  }

  distil.identifyCustomer(customerProperties);

2. With Email Address

  let customerProperties = {
    EmailAddress: 'user@yourcompany.com',
    GDPRStatus: {
      MarketingSubscribed: true / false
    }
  }

  distil.identifyCustomer(customerProperties);

3. Or With Both CustomerID and Email Address

  let customerProperties = {
    CustomerId: '1234,
    EmailAddress: 'user@yourcompany.com',
    GDPRStatus: {
      MarketingSubscribed: true / false
    }
  }

  distil.identifyCustomer(customerProperties);

Track Product

When a user views a single product page on the website, this information can be captured using the trackProduct event function, which needs to be added to all pages where this type of activity occurs.

When this event function is called, the Distil Tracking code will also automatically pass a Context object as explained in the section above.

Call the event function:

distil.trackProduct(productProperties, customerProperties, [additionalOptions]);

Pass the following arguments to the function:

ProductProperties Object properties

Note that some of the properties of ProductProperties are mandatory.

Examples

Example of call with only mandatory fields:

let productProperties = {
  ProductId : 'Prod1234',
  Name: 'Product Name goes here'
}

distil.trackProduct(productProperties);

The customer property is not passed in the above as it is not mandatory.

Example of a call with Customer Properties included:

let productProperties = {
  ProductId : 'Prod1234',
  Name: 'Product Name goes here'
}

let customerProperties = {
  EmailAddress: 'joe@bloggs.com'
}

distil.trackProduct(productProperties, customerProperties);

Track Content

When a user views a Content page on the website, this information can be captured using the trackContent event function, which needs to be added to all pages where this type of activity occurs.

When this event function is called, the Distil Tracking code will also automatically pass a Context object as explained in the section above.

Call the event function:

distil.trackContent(contentProperties, customerProperties, [additionalOptions]);

Pass the following arguments to the function:

ContentProperties Object properties

Note that some of the properties of contentProperties are mandatory.

Examples

Example of call with only mandatory fields:

let contentProperties = {
  ContentId: 'Cont1234',
    Title: 'Content Title goes here'
  }

  distil.trackContent(contentProperties);

The customer property is not passed in the above as it is not mandatory.

Example of a call with Customer Properties included:

let contentProperties = {
ContentId: 'Cont123',
  Title: 'Content Title goes here'
};

let customerProperties = {
  EmailAddress: 'joe@bloggs.com'
};

distil.trackContent(contentProperties, customerProperties);

Track Order

When a user places an order on the website, this information is captured using the trackOrder event, which needs to be added to all pages where this type of activity occurs.

When this event function is called, the Distil Tracking code will also automatically pass a Context object as explained in the section above.

Call the event function:

distil.trackOrder(orderProperties, customerProperties, [additionalOptions]);