Les triggers

 

Avant-propos

Ce guide de marquage est destiné aux utilisateurs avancés.

 

Principe

Notre bibliothèque fonctionne avec des déclencheurs (triggers en anglais) qui provoquent des traitements particuliers en fonction d’événements prédéfinis. Elle permet par défaut l’accès à un ensemble de données contextuelles transmises lors du déclenchement d’événements spécifiques et fournit à l’utilisateur avancé un système de gestion d’événements personnalisés. Ce dernier peut de plus associer une fonction de rappel (callback en anglais) à un trigger qui sera exécutée lors de la « levée » de l’événement associé.

 

Format d’un trigger

Un trigger est un libellé constitué d’un ensemble de champs (niveaux ou catégories) séparés par le caractère « : »

 

Exemple

'Tracker:Hit:Sent:Ok'

Dans cet exemple, le trigger est défini au niveau du Tracker et se déclenche après l’envoi d’un hit réussi.

Il est possible techniquement de se brancher sur cet événement pour éventuellement déclencher des actions. Des informations détaillées telles que la valeur du hit au moment de l’envoi sont automatiquement ajoutées lors de l’exécution du trigger.

 

Inscription sur un trigger

Le Tracker dispose d’une méthode « onTrigger() » permettant de s’inscrire sur un trigger. Elle prend trois paramètres en entrée :

  • trigger : Libellé du trigger sur lequel vous souhaitez vous inscrire ; obligatoire.
  • callback : Méthode que vous souhaitez exécuter.
  • singleUse : Si vous souhaitez appeler une seule fois la méthode callback où à chaque déclenchement de l’événement (« true » ou « false » ; « false » par défaut).

Pour s’inscrire sur un trigger spécifique, il est nécessaire de connaître sa valeur exacte.

Exemple avec un marqueur de page :

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();

Exemple de données ajoutées dans la console par la méthode personnalisée « callback() » :

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

Vous avez la possibilité de vous inscrire sur une liste de triggers appartenant à une même catégorie.

Exemple de triggers appartenant à une même catégorie :

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

Nous avons ici deux triggers déclenchés respectivement lorsque le hit a été correctement envoyé ou lorsque ce dernier est en échec (erreur réseau, etc.).

Le système de gestion des triggers permet de s’inscrire sur une liste de triggers appartenant à une même catégorie grâce à l’utilisation du caractère spécial « * ».

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();

Dans cet exemple, l’inscription sur le trigger ‘Tracker:Hit:Sent:*’ permettra d’ajouter des informations dans la console pour savoir si le hit est correctement envoyé ou si il est en erreur.

Par extension vous pouvez vous inscrire sur l’ensemble des triggers en utilisant directement « * » en tant que libellé.

 

Création d’un trigger

Le Tracker dispose d’une méthode « emit() » permettant de générer un trigger. Elle prend deux paramètres en entrée :

  • trigger : Libellé du trigger à émettre ; obligatoire.
  • data : Données que vous souhaitez transmettre.

Exemple complet avec un marqueur de page (utilisation des fonctions « emit() » et « onTrigger() ») :

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();

Exemple de données ajoutées dans la console par la méthode personnalisée « callback() » :

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

Les triggers existants

 

Description

Notre bibliothèque génère par défaut une série de triggers fournissant un ensemble de données liées à leur contexte spécifique d’exécution et sur lesquels il est possible de s’inscrire.

Certains triggers ne sont accessibles que dans la version debug du smartTag.

Les triggers peuvent être d’origine technique c’est-à-dire en relation directe avec le fonctionnement du Tracker.

  • Chaque helper (méthode de marquage d’un plugin) crée un trigger selon le format ‘[PluginName]:[Object]:[Helper]‘.
  • Certaines valeurs de marquage sont vérifiées et des erreurs peuvent être levées dans le cas où elles ne correspondent pas au format attendu. Un trigger au format ‘[PluginName]:[Object]:[Helper]:[Property]:Error‘ sera levé.
  • Certains plugins procèdent à une vérification de marquage au moment de l’envoi de hit par la méthode « dispatch() ». Ils génèrent des triggers de la forme ‘[PluginName]:onDispatch:Error‘ dans le cas où une erreur ou un avertissement est levé. Il s’agit des plugins NuggAd, SalesTracker et TvTracking.
  • Certains plugins envoient des informations détaillées au moment de leur initialisation, via un trigger au format ‘[PluginName]:Ready‘. C’est le cas notamment des plugins ClientSideUserId, ContextVariables, IdentifiedVisitor, InternalSearch, Offline et OnSiteAds.
 

Liste des triggers par fonctionnalités

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'

 

Dernière mise à jour : 08/12/2017