THRON Tracking Library

THRON 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 Content Analytics , you will be able to understand the interests of your users and to adapt your communication in order to increase your conversion rates.


THRON Tracking Library can be integrated with external projects exploiting THRON content when THRON Player is not involved. To do so, follow these steps:


First of all, make sure to include the folowing script into the <head> section of your website:

<script id="ta_bootstrapper" src="//<clientId>-cdn.thron.com/shared/plugins/tracking/current/bootstrapper-min.js"></script>

 

Automatic tracking of content related events.

After including this script, you will just have to decide which events must be tracked on any content in the page. Please note that automatic content tracking is only available for images, videos and audios, since documents, pages and playlists  can only be delivered via THRON Player. Available events that will be tracked automatically are:

  • impression: this event is launched when at least 1/3 of the html element including the content is visible in the viewport.
  • load: this event registers the content visualization. In case of video and audio, it is launched then the user presses the "play" button. In case of images this occurs when the html element including the content has been visible in the viewport for at least three seconds.
  • progress: this event is launched as long as content playback progresses. More specifically, a progress event will be launched each time a decile is reached. Only available for video and audio.
  • seek: this event is launched as soon as the user skips on a specific time frame of the content (backward or forward). Only available for video and audio.
  • click: this event is launched each time a user clicks on the html element including the content.

In order to enable the tracking of such events you will have to add a specific class to the html tag including the src of the content. The class is made of two elements: prefix and event, in the form:

"tci_impression_load_progress_seek_click"

 

If you wish to avoid a specific event's tracking you will just have to omit it form the class. Including the class "tci" (with no events), will track the following events: load, progress, seek.

Some examples:

<video controls style="width:1024px; height:576px;" class="tci_load_progress_seek" src="//<clientId>-cdn.thron.com/delivery/public/video/<clientId>/<contentId>/<pkey>/<channel>/<prettyId>" />

 

<img class="tci_impression_load" src="//<clientId>-cdn.thron.com/delivery/public/image/<clientId>/<contentId>/<pkey>/std/<divArea>/<prettyName>?<rtieParameters>" />

IMPORTANT: Please note that the automatic content tracking will not be performed if you are including a content thumbnail (hence you are using the /public/thumbnail webservice); if you wish to include an image and have automatic tracking you must use the public/image web service.

 

Manual tracking of download event (and other events)

Since the download of a THRON content in the absence of THRON Player requires some integration, the tracking of this event can not be handled automatically and has to be launched manually. In order to do so, the standard version of the tracking library must be included in the <head> section of the page, using the form:

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

Then, a specific content tracker has to be initialized, using the form:

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.
     

If you do not want to use a sessId you will have to provide contentType and contentLength using the form:

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

where:

  • 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. 

Now that ContentTracker has been initialized, you can track download event by using the method:

tracker.downloadEvent();

Other events that can be managed manually when needed are:

  • 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

 

Contact profiling

Tracking Library can be useful even when you want to enrich the set of information about a specific contact, for example in presence of a form or a call to action where the user is asked to provide some identities (email address, phone number, address, etc.). 

If this is your case, the first thing to do (after including the library) is to initialize a specific tracker using 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.

Then, available profiling methods are:

 

1) Login

 

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. 

The loginAs method has a dual function:

  • That of associating a device to a profiled contact;
  • That of recognizing already profiled contacts and, if the identities provided coincide with those already collected, associating them to the device in use. If the identities provided are different from those already collected, they will be added to the contact currently associated with the device. For this reason, if you want to make sure that an identity with a specific key (e. g. email) is not associated with different values to the same contact, you will need to use the logout method.

Be careful, in all those contexts where contact profiling happens "out" from THRON (e.g. via an email campaign), you will need to proactively update THRON to keep your identities aligned.

 

2) Logout 

 

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).

 

Best practice

When an explicit logout is made at the end of a session, always invoke the corresponding library method to make sure you disconnect the device from the contact.
If the session ends without an explicit logout, you have two options:

  1. force the logout in any case,
  2. when opening the new session, proactively present the previous identity using the getContactInformation method.
Was this article helpful?
0 out of 0 found this helpful

Have any question?

Open a ticket
Comments