Tâches

Ce guide décrit les tâches, une fonctionnalité avancée permettant de personnaliser la manière dont analytics.js valide, construit et envoie les requêtes de protocole de mesure.

Présentation

Chaque fois que la commande send est appelée, analytics.js exécute une séquence de tâches pour valider, construire et envoyer une demande de protocole de mesure à Google Analytics depuis le navigateur de l'utilisateur. Le tableau suivant décrit chacune de ces tâches, dans l'ordre dans lequel elles sont exécutées:

Nom de la tâche Description
customTask Par défaut, cette tâche n'a aucun effet. Remplacez-le pour fournir un comportement personnalisé.
previewTask Annule la requête si la page n'est affichée que pour générer une vignette "Top des sites" dans Safari.
checkProtocolTask Annule la requête si la valeur du protocole de la page n'est pas http ou https.
validationTask Annule la requête si des champs obligatoires sont manquants ou incorrects.
checkStorageTask Annule la requête si l'outil de suivi est configuré pour utiliser des cookies, mais que les cookies sont désactivés dans le navigateur de l'utilisateur.
historyImportTask Importe les informations de cookies ga.js et ear.js afin de préserver l'historique des visiteurs lorsqu'un site migre vers Universal Analytics.
samplerTask Échantillonne les visiteurs en fonction du paramètre sampleRate pour cet outil de suivi.
buildHitTask Crée une chaîne de requête de protocole de mesure et la stocke dans le champ hitPayload.
sendHitTask Il transmet la requête de protocole de mesure stockée dans le champ hitPayload aux serveurs Google Analytics.
timingTask Génère automatiquement un hit de vitesse de chargement du site en fonction du paramètre siteSpeedSampleRate pour cet outil de suivi.
displayFeaturesTask Envoie un appel supplémentaire si les fonctionnalités d'affichage sont activées et qu'aucun appel précédent n'a été envoyé dans le délai imparti par le cookie des fonctionnalités de publicité (_gat).

Chacune de ces tâches est implémentée en tant que fonction JavaScript qui accepte un seul paramètre de modèle en entrée. Le modèle est un objet simple qui donne accès à l'un des champs définis dans le document de référence sur les champs Analytics.js.

Vous pouvez accéder aux tâches ou les remplacer à l'aide des outils de suivi standards get et set. Ces méthodes vous permettent de remplacer des tâches par vos propres fonctions personnalisées ou d'améliorer les fonctionnalités existantes en enchaînant vos fonctions personnalisées pour qu'elles s'exécutent avant ou après une tâche existante.

Implémentation

Cette section explique comment ajouter de nouvelles fonctionnalités à des tâches existantes, remplacer les fonctions de tâches intégrées par votre propre code personnalisé ou désactiver complètement une fonction de tâche.

Remplacer une tâche

Pour remplacer une tâche, vous pouvez set affecter sa valeur à une fonction qui effectue une autre action. L'une des raisons les plus courantes est d'ignorer les tâches si vous souhaitez utiliser la fonctionnalité stub lorsque vous testez vos intégrations analytics.js.

Le code suivant remplace sendHitTask par une fonction qui consigne la charge utile de l'appel dans la console:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'sendHitTask', function(model) {
  console.log(model.get('hitPayload'));
});

Ajouter à une tâche

Pour insérer une nouvelle fonctionnalité, vous pouvez enchaîner votre fonction de tâche personnalisée à exécuter avant ou après une tâche existante. Dans l'exemple ci-dessous, sendHitTask est remplacé par une fonction de tâche personnalisée qui appelle d'abord la fonction sendHitTask d'origine pour envoyer la balise de requête normale à google-analytics.com/collection, puis exécute un code personnalisé pour envoyer une copie de la requête de protocole de mesure à un serveur local.

ga('create', 'UA-XXXXX-Y', 'auto');

ga(function(tracker) {

  // Grab a reference to the default sendHitTask function.
  var originalSendHitTask = tracker.get('sendHitTask');

  // Modifies sendHitTask to send a copy of the request to a local server after
  // sending the normal request to www.google-analytics.com/collect.
  tracker.set('sendHitTask', function(model) {
    originalSendHitTask(model);
    var xhr = new XMLHttpRequest();
    xhr.open('POST', '/localhits', true);
    xhr.send(model.get('hitPayload'));
  });
});

ga('send', 'pageview');

Annulation du traitement d'une tâche

Une tâche peut annuler le traitement des tâches suivantes en générant une exception. Si la tâche qui génère l'exception s'exécute avant sendHitTask, cela empêche l'envoi de la demande de protocole de mesure aux serveurs Google Analytics. Dans l'exemple ci-dessous, nous annulons la requête chaque fois que le navigateur de l'utilisateur contient un cookie nommé "&&39;testing' ayant la valeur 'true'.

ga('create', 'UA-XXXXX-Y', 'auto');

ga(function(tracker) {
  var originalBuildHitTask = tracker.get('buildHitTask');
  tracker.set('buildHitTask', function(model) {
    if (document.cookie.match(/testing=true/)) {
      throw 'Aborted tracking for test user.';
    }
    originalBuildHitTask(model);
  });
});

ga('send', 'pageview');

Désactiver une tâche

Pour désactiver l'une des fonctions de tâche intégrées, remplacez-la par "null".

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'checkProtocolTask', null); // Disables file protocol checking.
ga('send', 'pageview');