Triggers

Foreword

This tagging guide is designed for advanced users.

Principle

Our library works with triggers that generate specific types of processing, according to predefined events. The library gives default access to a set of contextual data sent when specific events are triggered, and provides advanced users with a customised event management system. The advanced user can also link a callback function to a trigger executed when an associated event occurs.

Trigger format

A trigger is a name/label made up of a group of fields (levels or categories), separated by a colon (” : “).

Example

'Tracker:Hit:Sent:Ok'

In this example, the trigger is defined at the Tracker level and is executed after a hit is successfully sent.

It is technically possible to connect to this event to potentially trigger actions. Detailed information, such as the value of the hit at the time of sending, is automatically added when the trigger is executed.

Listening to a trigger

The Tracker has an “onTrigger()” method allowing you to listen to a trigger. This method takes three parameters:

• trigger : Name of the trigger to which you want to listen; mandatory.
• callback : Method you wish to execute.
• singleUse : If you want to call the callback method just once, or at each event trigger (“true” or “false”; “false” by default).

To listen to a specific trigger, you must know its exact value.

Example with a page tag:

var tag = new ATInternet.Tracker.Tag();
tag.page.set({
    name: 'pageName',
    level2: '123'
});
function callback(trigger, data) {
    console.log('Trigger = ' + trigger);
    console.log('Data = ' + JSON.stringify(data));
}
tag.onTrigger('Tracker:Hit:Sent:Ok', callback);
tag.dispatch();

Example of data added in the console by the custom “callback()” method:

Trigger = Tracker:Hit:Sent:Ok
Data = {"details":{"hit":"//logdev.xiti.com/hit.xiti?s=410501&ts=1452501322251&p=pageName&s2=123&vrn=1"}}

You may listen to a list of triggers belonging to the same category.

Example of triggers that belong to the same category:

'Tracker:Hit:Sent:Ok'
'Tracker:Hit:Sent:Error'

Here, we have two triggers, fired respectively, when the hit was successfully sent, or when the hit failed (network error, etc.).
The trigger management system enables you to listen to a list of triggers belonging to the same category, by using the special character ” * “.

var tag = new ATInternet.Tracker.Tag();
tag.page.set({
    name: 'pageName',
    level2: '123'
});
function callback(trigger, data) {
    console.log('Trigger = ' + trigger);
    console.log('Data = ' + JSON.stringify(data));
}
tag.onTrigger('Tracker:Hit:Sent:*', callback);
tag.dispatch();

In this example, listening to the trigger ‘Tracker:Hit:Sent:*’ lets you add information in the console in order to know if the hit has been correctly sent, or if there was an error.

By extension, you can listen to all triggers by directly using ” * ” as a name/label.

Creating a trigger

The Tracker has an “emit()” method allowing a trigger to be generated. This method takes two parameters:

• trigger: Name of the trigger to emit; mandatory.
• data: Data you wish to transmit.

Full example with a page tag (using the “emit()” and “onTrigger()” functions):

var tag = new ATInternet.Tracker.Tag();
var trigger = 'Trigger:Custom:Page';
var pageData = {
    name: 'pageName',
    level2: '123'
};
var data = {
    lvl: 'DEBUG',
    msg: 'Page data',
    details: pageData
};
function callback(trigger, data) {
    console.log('Trigger = ' + trigger);
    console.log('Data = ' + JSON.stringify(data));
}
tag.onTrigger(trigger, callback);
tag.emit(trigger, data);
tag.page.set(pageData);
tag.dispatch();

Example of data added to the console by the custom “callback()” method:

Trigger = Trigger:Custom:Page
Data = {"lvl":"DEBUG","msg":"Page data","details":{"name":"pageName","level2":"123"}}

Existing triggers

Description

By default, our library generates a series of triggers that provide a set of data related to the specific context of execution, and to which you can listen.

Certain triggers are only accessible in the debug version of SmartTag.

Triggers can have a technical origin, meaning they can be directly related to the Tracker‘s functioning.

• Each helper (plugin tagging method) creates a trigger according to the format ‘[PluginName]:[Object]:[Helper]‘.
• Certain tagging values are verified, and errors can be flagged in cases where they don’t match the expected format. A trigger in the format ‘[PluginName]:[Object]:[Helper]:[Property]:Error‘ will be detected.
• Certain plugins proceed with tagging verification when the hit is sent by the “dispatch()” method. They generate triggers in the format ‘[PluginName]:onDispatch:Error‘ in cases where an error or a warning is detected. The plugins in question are NuggAd, SalesTracker and TvTracking.
• Certain plugins send detailed information when they are initialised, via a trigger in the format ‘[PluginName]:Ready‘. This is notably the case with the plugins ClientSideUserId, ContextVariables, IdentifiedVisitor, InternalSearch, Offline and OnSiteAds.

List of triggers by feature

TRACKER
'Tracker:Config:Set:' + key
'Tracker:Hit:Sent:Ok'
'Tracker:Hit:Sent:Error'
'Tracker:Hit:Build:Error'
'Tracker:Plugin:Load:' + name + ':Ok'
'Tracker:Plugin:Load:' + name + ':Error'
'Tracker:Plugin:Unload:' + name + ':Ok'
'Tracker:Plugin:Unload:' + name + ':Error'
'Tracker:Plugin:Lazyload:File:Complete'
'Tracker:Plugin:Lazyload:Exec:Complete'
'Tracker:Plugin:Dependencies:Loaded'
'Tracker:Plugin:Dependencies:Error'
'Tracker:Ready'

CLICKS
'Clicks:click:send' (version debug)
'Clicks:click:set' (version debug)
'Clicks:clickListener:send' (version debug)

CONTEXTVARIABLES
'ContextVariables:Ready'

IDENTIFIEDVISITOR
'IdentifiedVisitor:identifiedVisitor:set' (version debug)
'IdentifiedVisitor:identifiedVisitor:unset' (version debug)
'IdentifiedVisitor:Ready'

ONSITEADS
'OnSiteAds:publisher:set' (version debug)
'OnSiteAds:publisher:add' (version debug)
'OnSiteAds:publisher:send' (version debug)
'OnSiteAds:selfPromotion:set' (version debug)
'OnSiteAds:selfPromotion:add' (version debug)
'OnSiteAds:selfPromotion:send' (version debug)
'OnSiteAds:Ready'

CLIENTSIDEUSERID
'ClientSideUserId:clientSideUserId:set' (version debug)
'ClientSideUserId:Ready'

PAGE
'Page:customVars:set' (version debug)
'Page:dynamicLabel:set' (version debug)
'Page:tags:set' (version debug)
'Page:customTreeStructure:set' (version debug)
'Page:page:set' (version debug)
'Page:page:send' (version debug)
'Page:page:reset' (version debug)

SALESTRACKER
'SalesTracker:order:set:newCustomer:Error' (version debug)
'SalesTracker:order:set:amount:Error' (version debug)
'SalesTracker:order:set:delivery:Error' (version debug)
'SalesTracker:order:set:discount:Error' (version debug)
'SalesTracker:order:set:confirmationRequired:Error' (version debug)
'SalesTracker:order:set:orderCustomVariables:Error' (version debug)
'SalesTracker:cart:set:isBasketPage:Error' (version debug)
'SalesTracker:cart:add:product:Error' (version debug)
'SalesTracker:order:set' (version debug)
'SalesTracker:cart:set' (version debug)
'SalesTracker:cart:add' (version debug)
'SalesTracker:aisle:set' (version debug)
'SalesTracker:product:add' (version debug)
'SalesTracker:product:add:Error' (version debug)
'SalesTracker:order:onDispatch:Error' (version debug)

TVTRACKING
'TvTracking:tvTracking:onDispatch:Error' (version debug)
'TvTracking:tvTracking:set' (version debug)

RICHMEDIA
'RichMedia:richmedia:isBuffering:Error' (version debug)
'RichMedia:richmedia:isEmbedded:Error' (version debug)
'RichMedia:richMedia:playerId:Error' (version debug)
'RichMedia:richMedia:add' (version debug)
'RichMedia:richMedia:remove' (version debug)
'RichMedia:richMedia:removeAll' (version debug)
'RichMedia:richMedia:send:Error' (version debug)
'RichMedia:richMedia:send' (version debug)

NUGGAD
'NuggAd:nuggAd:set' (version debug)
'NuggAd:nuggAd:onDispatch:Error' (version debug)

INTERNALSEARCH
'InternalSearch:internalSearch:set' (version debug)
'InternalSearch:internalSearch:send' (version debug)
'InternalSearch:Ready'

MVTESTING
'MvTesting:mvTesting:set' (version debug)
'MvTesting:mvTesting:add' (version debug)

OFFLINE
'Offline:offline:getLength' (version debug)
'Offline:offline:remove' (version debug)
'Offline:offline:get' (version debug)
'Offline:offline:send' (version debug)
'Offline:Ready'