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');