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)
            identifiers: {},                // clés/valeurs permettant d'identifier l'utilisateur actuel de façon unique
            ndrstndDomain: `ndrstnd.io`,    // domaine de tracking
        },
    );
    // ...
});

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.

identifiers​

L'API utilise les cookies pour identifier l'utilisateur en train de naviguer. Il est possible d'envoyer à l'API des informations supplémentaires qui permettent d'identifier un utilisateur dans l'objet identifiers.

Données à caractère personnel

Vous ne devez pas envoyer de données à caractère personnel dans l'objet identifiers.

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.

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
Type de message

Actuellement Webmarketer utilise uniquement le type de message pageview afin construire les sessions de navigation des utilisateurs. Les données supplémentaires ajoutées sur les messages ne sont pas encore utilisées par l'outil.

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>