Aller au contenu principal

Mise en place du tracking

Cette page décrit la mise en place du tracking sur votre site. Elle couvre les deux canaux par lesquels vos données arrivent dans Webmarketer, à ne pas confondre :

  • L'envoi des pages vues se fait par le script de tracking. Celui-ci dépose le cookie d'identification de l'internaute et envoie une page vue à chaque navigation. C'est de là que Webmarketer reconstruit les sessions, les interactions et l'origine du trafic.
  • L'envoi des événements se fait par l'API Webmarketer, jamais par le script. Ce sont vos conversions (achat, formulaire, inscription, etc.), celles qui deviennent des événements dans vos rapports.

Les deux canaux se rejoignent par l'identifiant déposé par le script : transmis avec l'événement, il permet de le rattacher à la navigation de l'internaute, et donc de l'attribuer aux sources de trafic qui l'ont permis.

Chargement du script​

Par défaut le script peut être récupéré depuis l'url https://cdn.ndrstnd.io/ndrstnd-v1.js ou si vous avez configuré un sous domaine de tracking depuis l'url https://{votre sous domaine}/scripts/ndrstnd-v1.js, par exemple https://ndrstnd.acme.com/scripts/ndrstnd-v1.js.

Il est possible d'ajouter le script directement sur un site, cependant il est conseillé d'utiliser le code suivant afin de sauvegarder dans une file d'attente les commandes exécutées via la fonction globale ndrstnd avant la fin du chargement du script sur le site :

<script>
    (function (w, d, s, u, n, e, a) {
        w["NDRSTND_ALIAS"] = n; w[n] = w[n] || function (cb) { (w[n].q = w[n].q || []).push(cb); };
        e = d.createElement(s); e.src = u; e.async = 1;
        a = d.getElementsByTagName(s)[0]; a.parentNode.insertBefore(e, a);
    })(window, document, "script", "https://cdn.ndrstnd.io/ndrstnd-v1.js", "ndrstnd");

    // avec un sous-domaine de tracking, par exemple ndrstnd.acme.com :
    // })(window, document, "script", "https://ndrstnd.acme.com/scripts/ndrstnd-v1.js", "ndrstnd");
</script>

Dans cet exemple, les deux derniers paramètres passés à la fonction permettent de configurer respectivement :

  • l'url depuis laquelle le script est récupéré
  • le nom de la fonction globale définie sur l'objet window permettant de communiquer avec l'API (ndrstnd dans la suite)

Envoi des pages vues​

Les pages vues alimentent la reconstruction des sessions et des interactions. Elles sont envoyées par le script, à l'infrastructure de collecte.

La fonction ndrstnd exécute des commandes sous la forme de callbacks dont le premier paramètre est le client permettant de communiquer avec l'API (ce pattern permet de délayer l'exécution des commandes jusqu'à ce que le script soit chargé).

ndrstnd(function(client) {
    // code à exécuter
});

Créer un tracker​

Un tracker est un objet créé par le client qui permet d'envoyer des données à l'API pour un projet spécifique. Pour créer un tracker il faut appeler la méthode createTracker du client.

ndrstnd(function(client) {
    const tracker = client.createTracker("projectId");
    // avec un sous-domaine de tracking, par exemple ndrstnd.acme.com :
    // const tracker = client.createTracker("projectId", { ndrstndDomain: "ndrstnd.acme.com" });
    // ...
});

La méthode createTracker prend en premier paramètre l'identifiant du projet Webmarketer. La méthode accepte également en deuxième paramètre un objet qui permet de configurer le tracker.

ndrstnd(function(client) {
    const tracker = client.createTracker(
        "projectId",
        // valeurs par défaut des options :
        {
            cookieName: "ndrstnd",          // nom du cookie javascript défini par le script
            cookieDomain: "auto",           // domaine sur lequel le cookie javascript doit être défini
            name: "default",                // nom du tracker (utile quand plusieurs trackers sont créés avec le même client)
            ndrstndDomain: `ndrstnd.io`,    // domaine de tracking (ex: `ndrstnd.acme.com` avec un sous-domaine)
            spaCompatibilityEnabled: true,  // active la compatibilité avec les applications SPA
        },
    );
    // ...
});

Il n'est généralement pas utile de déclarer plusieurs tracker, mais lorsque plusieurs projets Webmarketer doivent recevoir la donnée il convient d'en créer plusieurs avec un cookieName différent.

Lors du chargement du script, un cookie javascript est défini sur le site, par défaut le nom du cookie défini est ndrstnd. Afin d'éviter un possible conflit, il est possible de modifier le nom du cookie en définissant la valeur cookieName.

Par défaut le script défini le cookie javascript sur le domaine de plus haut niveau possible, cela permet de partager le même cookie sur un ensemble de sous domaines de votre site. Il est possible de modifier ce comportement en définissant la valeur cookieDomain.

Domaine invalide

Si le domaine configuré n'est pas le même domaine ou un domaine parent du domaine actuel un warning apparaîtra dans la console et le cookie sera défini sur le domaine de plus haut niveau possible (comportement par défaut).

name​

Nom du tracker, utile pour différencier les trackers créés par le client quand il y en a plusieurs.

ndrstndDomain​

Par défaut le script communique avec l'API sur le domaine ndrstnd.io. Lorsqu'un projet est configuré pour utiliser un sous domaine de tracking, il faut renseigner le sous domaine configuré dans l'option ndrstndDomain (par exemple ndrstnd.acme.com).

spaCompatibilityEnabled​

Cette option permet d'activer la compatibilité automatique avec les applications SPA (Single Page Application).

Fonctionnement

voir plus

Le referrer de la page est l'URL du site par lequel est arrivé l'internaute. Cette information est utilisée par Webmarketer pour analyser quel moteur de recherche, réseau social ou tout autre site vous a apporté du trafic.

Pour comptabiliser correctement le nombre de sessions, Webmarketer a besoin que le referrer soit correctement renseigné, sans quoi les sessions de navigation des utilisateurs pourraient pas être correctement construites.

Dans les application SPA, le referrer de la page n'est pas mis à jour lors de la navigation, faussant alors la construction des sessions.
Pour palier à ce problème, le script de tracking utilise le pageview précédent comme referrer pour chaque pageview envoyé (pour le premier pageview, le referrer est défini à document.referrer).

Je souhaite implémenter un comportement différent

voir plus

Si vous souhaitez implémenter un comportement différent, veuillez désactiver cette option et implémenter votre propre logique pour renseigner le referrer dans le tracker.

Voici un exemple de code pour renseigner le referrer manuellement :

ndrstnd(function(client) {
    const tracker = client.createTracker("projectId", { ndrstndDomain: "ndrstnd.acme.com" });
    tracker.send("pageview", {r: "https://acme.com/page-1"});
});

Récupérer un tracker​

Il est possible de récupérer un tracker déjà créé à l'aide de la méthode getTracker du client. Sans argument, elle retourne le tracker nommé default, celui que crée createTracker lorsque l'option name n'est pas précisée :

ndrstnd(function(client) {
    const tracker = client.getTracker();
    // ...
});

Si plusieurs trackers ont été créés, passez le nom de celui que vous voulez récupérer :

ndrstnd(function(client) {
    const tracker = client.getTracker("trackerName");
    // ...
});

C'est par cette méthode que l'on récupère le tracker d'une page déjà chargée, par exemple pour lire l'identifiant de l'internaute au moment d'un envoi d'événement.

Lister les trackers​

Il est possible de lister les noms des trackers créés avec le client grâce à la méthode getTrackers.

ndrstnd(function(client) {
    const trackers = client.getTrackers();
    console.log(trackers);
    // ["tracker1", "tracker2", ...]
});

Envoyer une page vue​

La méthode send d'un tracker permet d'envoyer un hit de navigation à l'infrastructure de collecte.

tracker.send("pageview");

La méthode send prend en paramètre :

  • le type de message à envoyer (ici pageview) en premier paramètre
  • un objet optionnel en deuxième paramètre qui permet d'ajouter de l'information au message sous forme de clés/valeurs
Page vues

Afin d'avoir des sessions utilisateurs cohérentes dans Webmarketer, il est important d'envoyer un message de type pageview à chaque fois que l'utilisateur navigue sur une nouvelle page du site.

Exemples d'intégration​

<script>
    (function (w, d, s, u, n, e, a) {
        w["NDRSTND_ALIAS"] = n; w[n] = w[n] || function (cb) { (w[n].q = w[n].q || []).push(cb); };
        e = d.createElement(s); e.src = u; e.async = 1;
        a = d.getElementsByTagName(s)[0]; a.parentNode.insertBefore(e, a);
    })(window, document, "script", "https://cdn.ndrstnd.io/ndrstnd-v1.js", "ndrstnd");

    // create a tracker for project "projectId" and send a pageview
    ndrstnd(function(client) {
        const tracker = client.createTracker("projectId");
        tracker.send("pageview");
    });
</script>

Envoi des événements​

Les événements (achat, formulaire, inscription, etc.) ne passent pas par le script : ils s'envoient à l'API Webmarketer. Les deux canaux sont distincts et complémentaires :

Script de trackingAPI Événements
Ce qui est envoyéles pages vues (hits)les événements (achat, formulaire, inscription, etc.)
Destinationle domaine de collecte (ndrstnd.io ou votre sous-domaine)https://api.webmarketer.io
Ce que Webmarketer en faitdes interactionsdes événements attribués

Un événement s'envoie donc via l'API Webmarketer, sur l'une des deux routes suivantes :

  • POST /events : ingestion asynchrone. La réponse 200 confirme la prise en compte de l'appel, pas la validité de l'événement ; un événement invalide se retrouve dans la corbeille de l'interface.
  • POST /events/sync : ingestion synchrone. La réponse 200 n'est renvoyée qu'une fois l'événement entièrement traité.

Contrairement au reste de l'API, ces deux routes ne nécessitent pas de compte de service : elles peuvent être appelées directement depuis le navigateur.

Le champ eventType doit référencer un type d'événement déclaré dans votre projet, et l'objet data doit respecter son schéma.

C'est le champ trackerId qui fait le lien entre les deux canaux : il contient la valeur du cookie déposé par le script de tracking. Webmarketer s'en sert pour retrouver l'internaute et ses interactions, et donc pour attribuer l'événement aux sources de trafic à l'origine de la visite.

Sans trackerId, l'événement est bien ingéré, mais il ne peut être rattaché à un utilisateur que par la réconciliation sur ses données personnelles (email, téléphone, etc.).

Cette valeur se lit sur le tracker, avec la méthode get et la clé fc (pour first party cookie). Au chargement de la page, là où le tracker est créé :

ndrstnd(function (client) {
    // avec un sous-domaine de tracking : { ndrstndDomain: "ndrstnd.acme.com" }
    var tracker = client.createTracker(projectId, { ndrstndDomain: domain });
    tracker.send("pageview");
    var trackerId = tracker.get("fc");
});

get("fc") doit être appelé après createTracker : c'est cette méthode qui lit ou dépose le cookie, donc qui rend la valeur disponible dans le navigateur. Qu'elle soit exploitable par Webmarketer est une autre condition, décrite plus bas.

Le client étant partagé par tous les appels à ndrstnd, un tracker déjà créé se relit plus tard avec getTracker :

ndrstnd(function (client) {
    var trackerId = client.getTracker().get("fc");
});
Envoi depuis votre serveur

Si l'événement est envoyé depuis votre backend (par exemple à la validation d'une commande), c'est à vous de transmettre cette valeur du navigateur vers votre serveur, puis de la passer dans trackerId. Côté serveur, la donnée peut être récupérée dans le cookie dont le nom a été choisi lors de la création d'un tracker.

La page vue doit aussi avoir été envoyée

Disposer de la valeur ne suffit pas. Webmarketer résout le trackerId auprès de l'infrastructure de collecte, qui ne connaît un identifiant qu'à partir du moment où une page vue l'a transporté. Tant que ce cookie n'a été vu dans aucun hit, l'événement est mis en attente, puis ingéré sans rattachement.

Envoyez donc vos événements depuis des pages où le script est installé et a déjà envoyé son pageview, et non depuis une page qui se contenterait de créer le tracker.

Exemple​

La page vue est envoyée une seule fois, au chargement de la page. L'envoi de l'événement est isolé dans sa propre fonction, appelée au moment de la conversion, et réutilise le tracker déjà créé :

var PROJECT_ID = "projectId";

// au chargement de chaque page du site
ndrstnd(function (client) {
    var tracker = client.createTracker(PROJECT_ID);
    // avec un sous-domaine de tracking, par exemple ndrstnd.acme.com :
    // var tracker = client.createTracker(PROJECT_ID, { ndrstndDomain: "ndrstnd.acme.com" });
    tracker.send("pageview");
});

// à appeler au moment de la conversion, par exemple à la validation d'une commande
function sendPurchase(order) {
    ndrstnd(function (client) {
        // Le tracker a été créé au chargement de la page, la valeur du trackerId est récupérable.
        var trackerId = client.getTracker().get("fc");

        fetch("https://api.webmarketer.io/api/v1/events", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
                projectId: PROJECT_ID,
                eventType: "purchase",
                nonce: order.id,
                trackerId: trackerId,
                data: {
                    email: order.customerEmail,
                    turnover: { amount: order.total, currency: "EUR" },
                },
            }),
        });
    });
}

getTracker() renvoie le tracker nommé default. Si votre site en crée plusieurs, passez le nom voulu (voir name).

Le champ nonce sert à dédupliquer l'événement : deux envois portant les mêmes projectId, eventType et nonce à moins de 24 heures d'intervalle ne créent qu'un seul événement. Réutilisez donc un identifiant stable de votre côté (ici le numéro de commande) plutôt qu'une valeur aléatoire.