Javascript Tracking

Updated 29 October 2021 12:18

Each Distil Account has its own unique organisational identifier that will be included in their tracking script. This information is included on the Tracking page within the Distil Settings screen, like so:

Placement of JS Code

The JavaScript snippet will load the Distil Tracking script onto the page and initialise it. It should be placed in the Head section of the page (recommended) or within the Body for every page on your site.

Using the JS Code

The JS code will automatically create a unique identifier (AnonymousID) for each user visiting the site, and store this information in local storage for re-use over time (i.e. so that the same ID is used for the same user across multiple visits). The code will also automatically capture the page the user is on, their IP address, the referring URL and the time of the event - nothing has to be done by the developer to enable this, it is automatically included on every call to the tracking functions.

These pieces of information are called the ‘Context’ Object - as they provide automatic contextual information about each tracking call made.

Example of the context object information:

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

Therefore to use the Distil tracking code, once it has been included on the page, it is a matter of calling the correct tracking event functions at the correct time.

Tracking Events

The following events / functions are available in the Distil tracking code to track the following types of interaction that may occur on the website:

Identify Customer
Track Product
Track Content
Track Order
Track Page View

Data Types

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

Type	Description	Example
String	Any combination of characters surrounded by double quotes (double quotes are always recommended rather than a single quote). There should not be any line return characters contained within the string.	“Title” : “This is a string”
Boolean	A true or false value - without quotes	“Available” : true
Decimal	A numerical value with a decimal point.	“Amount” : 12.34
Integer	A numerical value representing a whole number	“Age” : 23
Date (String)	A DateTime represented as a string in the following format : yyyy-MM-dd HH:mm:ss	“expirydate” : “2021-09-17 10:00:00”

Identify Customer

When a user is browsing the site - their browsing history is tied to their AnonymousID.

When someone identifies themselves explicitly, by either logging in, or filling in a form with personal details, we can then capture this information and tie it to the browsing history. The identifyCustomer event needs to be added to all pages where this type of activity occurs.

In order to do that, we require that the identifyCustomer event is called:

distil.identifyCustomer(customerProperties);

with the following argument passed to the function:

Argument

Data Type

Description

customerProperties

JSON Object

A JSON Object containing all of the other user properties to record.

Any customer property the Distil Account would like to record can be passed in this JSON object. Distil will automatically try to recognise the properties sent based on the name of the property, and so naming is key.

There are some mandatory properties for the identifyCustomer function - which are referenced below.

Property	Type	Description	Mandatory
CustomerId	String	ID of the Customer	Yes
EmailAddress	String	Email Address for the Customer	Yes
GDPRStatus	JSON	GDPRStatus Object – see definition below for object properties below	Yes
FirstName	String	The Customer’s First Name	No
LastName	String	The Customer's Last Name	No
FacebookSlug	String	The URI to the customer facebook profile	No
TwitterHandle	String	The URI to the customer twitter profile	No
InstagramHandle	String	The URI to the customer instagram profile	No
PostalAddress	JSON	PostalAddress Object – see definition below for object properties below	No

Customer GDPRStatus Object properties

Property	Type	Description	Mandatory
MarketingSubscribed	Boolean	Whether the user has opted in	Yes
RightOfAccessRequested	Boolean	Whether the user has been asked to opt in	No
DataAnonymization	Boolean	Whether the user has asked for their data to be anonymised	No

Customer PostalAddress Object properties

Property	Type	Description	Mandatory
Line1	String	Customer’s Address Line 1	No
Line 2	String	Customer’s Address Line 2	No
Line 3	String	Customer’s Address Line 3	No
Town	String	Customer’s Address Town	No
Region	String	Customer’s Address Region	No
Country	String	Customer’s Address Country	No
Postcode	String	Customer’s Address Postcode	No

Examples of call with only mandatory fields:

1. With Customer ID

<script>

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

   distil.identifyCustomer(customerProperties);

</script>

2. With Email Address

<script>

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

   distil.identifyCustomer(customerProperties);

</script>

3. Or With Both CustomerID and Email Address

<script>

  let customerProperties = {

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

   distil.identifyCustomer(customerProperties);

</script>

Other Custom properties

All other fields included in the customerProperties JSON object will be saved against the Customer and will be available within Distil.

Track Product

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

In order to do that, we require that the trackProduct event is called:

distil.trackProduct(productProperties, customerProperties);

with the following 2 arguments passed to the function:

Argument

Data Type

Description

productProperties

JSON Object

A JSON Object containing all of the other product properties to record.

Any product property the Organisation would like to record can be passed in this JSON object. Distil will automatically try to recognise the properties sent based on the name of the property, and so naming is key.

There are some mandatory properties for the trackProduct function - which are referenced below.

customerProperties

JSON Object

A JSON Object containing all of the other Customer properties to record for this event.

The customerProperties are not mandatory and can be omitted - but if the object is supplied, then at least one of the identifying properties for the customer must be included (i.e. CustomerId or EmailAddress)

Product Properties

The properties which are automatically recognised by Distil are:

Property	Type	Description	Mandatory
ProductId	String	The Product ID	Yes
Name	String	The name of the Product	Yes
Precis	String	The description of the product	No
ThumbnailUrl	String	The URI to a thumbnail image for the product	No
FullImageUrl	String	The URI to a full size image for the product	No
ProductShopUrl	String	The URI to the product in the shop / store	No
Categories	String	A comma delimited list of the categories the product belongs to	No
Available	Boolean	A boolean indicating whether the product is currently available	No
ListPriceExTax	Decimal	The price of the product with no tax	No
ListPriceIncTax	Decimal	The price of the product including tax	No
Currency	String	The 3 letter currency code	No
PriceBreaksDesc	String	This is only used in the case of building campaigns directly from this data so can be formatted as you wish	No

All other properties not listed above in the productProperties JSON object will be saved as Custom Properties in Distil.

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 call with Customer Properties included:

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

let customerProperties = {
  EmailAddress: "joe.bloggs@acme.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, which needs to be added to all pages where this type of activity occurs.

In order to do that, we require that the trackContent event is called:

distil.trackContent(contentProperties, customerProperties);

with the following 2 arguments passed to the function:

Argument

Data Type

Description

contentProperties

JSON Object

A JSON Object containing all of the other content properties to record.

Any content property the Organisation would like to record can be passed in this JSON object. Distil will automatically try to recognise the properties sent based on the name of the property, and so naming is key.

There are some mandatory properties for the trackContent function - which are referenced below.

customerProperties

JSON Object

A JSON Object containing all of the other Customer properties to record for this event.

Content Properties

Additional content properties which are automatically recognised by Distil are:

Property	Type	Description	Mandatory
ContentId	String	The ID of the Content	Yes
Title	String	The title of the Content	Yes
ContentType	String	The Type of Content	No
ThumbnailUrl	String	The URI to a thumbnail image for the content	No
FullImageUrl	String	The URI to the full image for the content	No
PublicUrl	String	The URI to the content	No
Precis	String	Description for the content	No
PublishedOnUTC	Date (String)	Date of Publishing Need to be in the format : 'yyyy-MM-dd HH:mm:ss' i.e. '2021-05-25 11:34:01'	No
ExpiresOnUTC	Date (String)	Date the content expires Need to be in the format : 'yyyy-MM-dd HH:mm:ss' i.e. '2021-05-25 11:34:01'	No
KeyWords	String	List of comma separated keywords for the content	No
Available	Boolean	A boolean indicating whether the content is currently available	No

All other properties not listed above in the contentProperties JSON object will be saved as Custom Properties in Distil.

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 call with Customer Properties included:

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

let customerProperties = {
  EmailAddress: "joe.bloggs@acme.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.

In order to do that, we require that the trackOrder event is called:

distil.trackOrder(orderProperties, customerProperties);

with the following 2 arguments passed to the function:

Argument

Data Type

Description

orderProperties

JSON Object

A JSON Object containing all of the order properties to record.

Any order property the Organisation would like to record can be passed in this JSON object. Distil will automatically try to recognise the properties sent based on the name of the property, and so naming is key.

There are some mandatory properties for the trackOrder function - which are referenced below.

customerProperties

JSON Object

A JSON Object containing all of the other Customer properties to record for this event.

The Customer details are not mandatory and can be omitted - but if the object is supplied, then at least one of the identifying properties for the customer must be included (i.e. CustomerId or EmailAddress)

OrderProperties Object

Additional order properties which are automatically recognised by Distil are:

Property	Type	Description	Mandatory
OrderId	String	The Order ID	Yes
OrderLineItems	JSON	See OrderLineItems object definition below for the object properties.	Yes
TotalOrderValueExTax	Decimal	This is the Total Order Value excluding any Tax. The value should be in the same Currency as specified in the Currency Attribute.	No
TotalOrderValueIncTax	Decimal	This is the Total order Value including Tax.	No
PaymentMethod	String	Free text string for you to specify the Payment method.	No
Currency	String	ISO Currency Code.	No
BillingAddress	JSON	Address Object – see definition below for object properties	No
DeliveryAddress	JSON	Address Object – see definition below for object properties	No

OrderLineItems Object Properties

Property	Type	Mandatory	Mandatory
OrderExternalId	String	The Order Id (same as the OrderId property in the OrderProperties object)	Yes
ProductId	String	This should match a Product Id from the Product Data	Yes
OrderLineItemId	String	The unique line item ID (can be a concatenation of the OrderExternalId and ProductId if the system does not have such a concept)	No
Name	String	The Name of the product	No
Url	String	URL to the Product page	No
Qty	Integer	This is the Qty of the Product in this Line Item	No
PriceExTax	Decimal	The price of the item excluding tax	No
PriceInTax	Decimal	The price of the item including tax	No
ThumbnailUrl	String	URL to the Product Thumbnail	No
FullImageUrl	String	URL to the Product image in full	No
Categories	Array (String)	An array of Categories for the product	No

Address object properties

Property	Type	Description	Mandatory
Title	String	Title of the Customer	No
FirstName	String	First Name of the Customer	No
LastName	String	Last Name of the Customer	No
Line1	String	Line 1 of the Address	No
Line2	String	Line 1 of the Address	No
Line3	String	Line 1 of the Address	No
Town	String	Town/City for the address	No
Region	String	Region of the address	No
Country	String	Country for the Address	No
Postcode	String	Postcode of the Address	No
Phone	String	The Customer’s phone number	No
Company	String	The name of the Company	No

All other properties not listed above in the orderProperties JSON object will be saved as Custom Properties in Distil.

CustomerProperties object properties

Property	Type	Description	Mandatory
CustomerId	String	ID of the Customer	Yes
EmailAddress	String	Email Address for the Customer	Yes
GDPRStatus	JSON	GDPRStatus Object – see definition below for object properties below	No
FacebookSlug	String	The URI to the customer facebook profile	No
TwitterHandle	String	The URI to the customer twitter profile	No
InstagramHandle	String	The URI to the customer instagram profile	No
PostalAddress	JSON	PostalAddress Object – see definition below for object properties below	No

GDPRStatus Object properties

Property	Type	Description	Mandatory
MarketingSubscribed	Boolean	Whether the user has opted in	No
RightOfAccessRequested	Boolean	Whether the user has been asked to opt in	No
DataAnonymization	Boolean	Whether the user has asked for their data to be anonymised	No

PostalAddress Object properties

Property	Type	Description	Mandatory
Line1	String	Customer’s Address Line 1	No
Line 2	String	Customer’s Address Line 2	No
Line 3	String	Customer’s Address Line 3	No
Town	String	Customer’s Address Town	No
Region	String	Customer’s Address Region	No
Country	String	Customer’s Address Country	No
Postcode	String	Customer’s Address Postcode	No

Example of call with only mandatory fields

 let orderProperties = {
    OrderId: "Ord1234",
    OrderLineItems: [{
     OrderExternalId: "Ord1234",
     ProductId: "ABC-1234"
    }]
 };

 let customerProperties = {
   EmailAddress: 'user@yourcompany.com'
 };
 
 distil.trackOrder(orderProperties, customerProperties);

Javascript Tracking

Placement of JS Code

Using the JS Code

Tracking Events

Data Types

Identify Customer

Customer GDPRStatus Object properties

Customer PostalAddress Object properties

Other Custom properties

Track Product

Product Properties

Track Content

Content Properties

Track Order

OrderProperties Object

OrderLineItems Object Properties

Address object properties

CustomerProperties object properties

GDPRStatus Object properties

PostalAddress Object properties

Comments

Still have questions?