Les tâches

Ce guide décrit les tâches, une fonctionnalité avancée permettant de personnaliser la façon dont analytics.js valide, construit et envoie les requêtes du 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 requête de protocole de mesure depuis le navigateur de l'utilisateur vers Google Analytics. 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-la pour fournir un comportement personnalisé.
previewTask Annule la requête si la page n'est en cours d'affichage que pour générer une vignette "Principaux sites" pour Safari.
checkProtocolTask Annule la requête si le protocole de la page n'est pas http ou https.
validationTask Annule la requête si des champs obligatoires sont manquants ou non valides.
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 des informations à partir des cookies ga.js et urchin.js pour préserver l'historique des visiteurs lorsqu'un site migre vers Universal Analytics.
samplerTask Échantillonne les visiteurs en fonction du paramètre sampleRate de cet outil de suivi.
buildHitTask Crée une chaîne de requête du protocole de mesure et la stocke dans le champ hitPayload.
sendHitTask Transmet la requête du protocole de mesure stockée dans le champ hitPayload aux serveurs Google Analytics.
timingTask Génère automatiquement un appel de temps 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é avant le délai défini par le cookie des fonctionnalités publicitaires (_gat).

Chacune de ces tâches est implémentée sous la forme d'une fonction JavaScript utilisant un seul paramètre de modèle en entrée. Le modèle est un objet simple qui donne accès à n'importe quel champ défini dans la documentation de référence sur les champs Analytics.js.

Il est possible d'accéder aux tâches ou de les remplacer à l'aide des méthodes de suivi standards get et set. À l'aide de ces méthodes, vous pouvez remplacer des tâches par vos propres fonctions personnalisées, ou 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 sa valeur vers une fonction qui effectue autre chose. Le remplacement des tâches est souvent dû à la fonctionnalité bouchon lorsque vous testez vos implémentations d'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'));
});

Ajout à une tâche...

Pour insérer une nouvelle fonctionnalité, vous pouvez enchaîner votre fonction de tâche personnalisée afin qu'elle s'exécute 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 du code personnalisé pour envoyer une copie de la requête du 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');

Abandon du traitement de la 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, la demande du protocole de mesure ne peut pas être envoyée 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é "testing" avec 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âches intégrées, remplacez-la par la valeur "null".

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