(Deprecated) How to integrate Tracking Library

(Deprecated) How to integrate Tracking Library

 The following article contains obsolete information. If you are starting a new implementation we recommend you to use the latest version of THRON Tracking Library. Further information can be found  here.

 

Tracking library, natively integrated with THRON player, allows you not only to record user interactions with your content, but also to identify users accessing them. Thanks to this feature, combined with the Content Marketing module, you will be able to understand the interests of your users and to adapt your communication in order to capture their attention.


Tracking library can be integrated with external projects exploiting THRON content without using directly THRON Player (which would automatically handle content tracking). To do so, follow these steps:


First of all, make sure to include it in the page where your content are distributed. To do that, paste this string in the <head> of your HTML:

<script src="//[clientId]-cdn.thron.com/shared/plugins/tracking/current/tracking-library-min.js"></script>

If you want to include the library into an AMD project instead, use the form:

define([//[clientId]-cdn.thron.com/shared/plugins/tracking/current/tracking-library-min.js], function(trackLib){YourCodeHere})

 

 

Track contacts when a content is embedded

After including the library, the first thing to do is to create a new ContentTracker. This can be done either using a list of parameters:

var tracker = _ta.initContentTracker("clientId", "xcontentId", "sessId", "contextId", disableUserProfiling);

or an object:

var tracker = _ta.initContentTracker({clientId: "clientIdHere", xcontentId: "xcontentIdHere", sessId: "sessIdHere", contextId:"contextIdHere", disableUserProfiling: statushere});

 

where the parameters are:

  • clientId: (mandatory) string, it's the domain name used to access THRON, usually company name.
  • xcontentId: (mandatory) string, content's unique identifier.
  • sessId: (optional) string, it can be either a pkey or a valid xtokenId.
  • contextId: (optional) string, the ID of the context used to identify all visualizations coming from a specific context (e.g. a web page). Further information on how to extract contextId can be found in this article. If you don't need a specific context, simply put empty string ("").
  • disableUserProfiling: (optional) boolean, if true, anonymous analytics will be collected and it will not be possible to add tags or identities to the contact. Default false.
     

Please note that if you don’t provide a pkey or a valid token in the sessId parameter, you must pass the following information on the content (object form illustrated below must be used in this case):

  • contentType:  string, the type of your content. Can be "IMAGE", "VIDEO", "AUDIO" or "OTHER".
  • contentLength: number of seconds for “AUDIO” and “VIDEO”; number of pages for “OTHER”. If content is an "IMAGE", this parameter can be omitted.

 

Hence, assuming you want to pass an object, you will have to provide this:

 

var tracker = _ta.initContentTracker({clientId: "clientIdHere", xcontentId: "xcontentIdHere", contentType: "contentTypeHere", contentLength: "contentLengthHere", contextId:"contextIdHere", disableUserProfiling: statushere});

 

Now that ContentTracker has been initiated, available methods are:

  • tracker.loginAs(“loginType”, “loginValue”,“contactName”) : This method is used to link an identity to an anonymous contact through a connect request. You only need to call this method once (if you have more than one content embedded on your page).You must link this to an identification form and pass the information by filling required parameters:
    • loginType: (mandatory) String; it is the type of identity provided, you can use a free text here (e.g.: "email") but remember to keep coherence in the name (please note that "thronuser" is a reserved key used to identify THRON usernames)
    • loginValue: (mandatory) String; it is the value of the identity provided (e.g. the email address)
    • contactName: (optional) String, it is the full name of the new contact.

Such method will return a promise which includes a "then" method whose parameter is the result of the request. 

IMPORTANT: This method will profile contacts only if the module "THRON SALES INSIGHTS" is active on the specific domain. Otherwise it will always return anonymous contacts.

  • tracker.loadEvent() : This method is used to track user’s access to your content. It will perform a get request to "hook" the device used to access the content.

 

  • tracker.progressEvent(NumberOfSecondsHere): This method is used to track content playhead. It is available for audios, videos, and documents; required parameter is
    • number of seconds for audios and videos. A valid rule to determine the frequence of progress events to be sent is to divide the content length by 10. If the result is lower than 1 second you should launch a progress every second; if the result is higher than 1 minute you should send a progress every minute; otherwise, use the result as your frequence.
    • page number for documents. For a proper tracking you should consider launching a progress event on documents only when a page remains still for at least 2 seconds.

 

  • tracker.seekEvent(NumberOfSecondsHere): This method is used to track content seek. It is available for audios, videos, and documents; required parameter is
    • number of seconds for audios and videos
    • page number for documents

 

  • tracker.logout(): This method is used to unlink the contact from the device in use. It is performed through a disconnect request. Such method will return a promise which includes a "then" method whose parameter is the result of the request.

 

Track contacts when no content is embedded

If necessary , you can initialize a tracker in the absence of content. This approach is particularly useful when you want to enrich the set of information about a contact, without involving content but simply providing additional identities. In this case you have to use the form:

var tracker = _ta.initTracker("clientId", disableUserProfiling);

Parameters are:

  • clientId: (mandatory) string, it's the domain name used to access THRON, usually company name.
  • disableUserProfiling: (optional) boolean, if true, anonymous analytics will be collected and it will not be possible to add tags or identities to the contact. Default false.

 

Available methods are:

  • tracker.loginAs(“loginType”, “loginValue”,“contactName”); : This method is used to link an identity to an anonymous contact through a connect request. You only need to call this method once (if you have more than one content embedded on your page).You must link this to an identification form and pass the information by filling required parameters:
    •  loginType: (mandatory) String; it is the type of identity provided, you can use a free text here (e.g.: "email") but remember to keep coherence in the name (please note that "thronuser" is a reserved key used to identify THRON usernames)
    •  loginValue: (mandatory) String; it is the value of the identity provided (e.g. the email address)
    •  contactName: (optional) String, it is the full name of the new contact.

Such method will return a promise which includes a "then" method whose parameter is the result of the request.

 

  • tracker.logout(): This method is used to unlink the contact from the device in use. It is performed through a disconnect request. Such method will return a promise which includes a "then" method whose parameter is the result of the request.

 

In some cases, users might explicitly refuse to be profiled; such cases can be handled by using a specific library's method:

_ta.optout("clientId",status);

where:

  • clientId: (mandatory) string, it's the domain name used to access THRON, usually company name.
  • status: (optional) boolean, the current user's optout status; if true this method will inform THRON that the user is refusing to be tracked in order to receive customized communication. Anonymous analytics data will still be collected but it will not be possible to tag contact or provide identity to it. If omitted this method will return a promise which includes a "then" method whose parameter is the current otpout status.

 

If you wish to retrieve the contactId and deviceId of a contact, you can use the method:

_ta.getContactInformation("clientId");

where :

  • clientId: (mandatory) string, it's the domain name used to access THRON, usually company name.

 

This method will return a promise object, whose value (once resolved) contains both the contactId and deviceId of the contact.

To check the correct profiling of your contact you can invoke a detail web service using the contactId retrieved with the previous method, or you can search for the contact within the Single Customer View (please note that some processing time is required in order to find the new contact in the Single Customer View).

 

Smart tracking of images via css rule

 

THRON Tracking Library exposes a method which can be used to automatically track different users interactions with images included into a web page by simply using an inline css rule.

This means that on your webpage you will have to include a specific "class" to any <img> tag including the images you want to track. Images must be static assets delivered by THRON, instructions on how to obtain the proper image to be included into your web pages can be found in this article.


This class is made of two elements: prefix and event, in the form:

<img class="tci_impression_load_click">

Where tci is the default prefix used by the library (but it can be configured), while available events are:

  • impression: the event is registered when at least 1/3 of the image is visible on screen.
  • load: the event is registred when the user spent a certain amount of time (configurable at will) with at least 1/3 of the image visible on screen.
  • click: the event is registered when a user clicks on the image to trigger some action.

 

This is how to configure the parser which will handle the automatic tracking of the events:

  • First of all make sure that tracking library is included in the <head> of your page.
  • Then initialise a parser by using the form:
var parser = _ta.getPageParser( {clientId:<clientId>, prefix_class: <class of the images to be tracked>, filter_class: <class of the images to be ignored>, disableUserProfiling: <true or false> } 

Where:

  • clientId: (mandatory) is the domain name used to access THRON, usually your company name.
  • prefix_class: (optional) is the prefix to be used on the class applied to the images to be tracked, default is "tci".
  • filter_class: (optional) is the prefix to be used on the class applied to the images that must not be tracked, default is "tci-filter".
  • disableUserProfiling: (optional) boolean, if true, anonymous analytics will be collected and it will not be possible to add tags or identities to the contact. Default false.


Once the parser has been initialised you will be able to use the following methods:

parser.parseImages(timeForLoad);

Where:

  • timeForLoad: (optional) it is used to set the amount of time for the image to be visible on screen before a "load" event is tracked; value is expressed in ms, default is 2000.

 

Finally, the parser also exposes methods for contact profiling such as: 

parser.loginAs(key, value, contactName);

 and

parser.logout();

 

loginAs parameters are the same illustrated above for the tracker.

 

 

Was this article helpful?
3 out of 3 found this helpful

Have more questions?

SUBMIT A REQUEST

Hai altre domande?

INOLTRA UNA RICHIESTA

Comments