Aller au contenu principal

Script de tracking

Le script de tracking permet de suivre les actions des utilisateurs sur votre site.

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.

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");
</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)

Utilisation​

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");
    // ...
});

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.createTacker(
        "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
            spaCompatibilityEnabled: true,  // active la compatibilité avec les applications SPA
        },
    );
    // ...
});

cookieName​

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.

cookieDomain​

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]/docs/guides/getting-started/tracking-configuration), il faut renseigner le sous domaine configuré dans l'option ndrstndDomain.

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: "sous-domaine.mon-site.fr" });
    tracker.send("pageview", {r: "https://mon-site.fr/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.

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

Si aucun nom n'est passé à la méthode, elle retourne le tracker avec le nom default.

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 des données à l'API​

La méthode send d'un tracker permet d'envoyer des données à l'API.

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​

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