La dernière ligne de l'extrait de mesure JavaScript ajoute une commande send à la file d'attente de commandes ga() pour envoyer une page vue à Google Analytics:
ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');
L'objet qui effectue l'envoi est l'outil de suivi dont la création a été planifiée pour la ligne de code précédente. Les données envoyées sont celles qui y sont stockées.
Ce guide décrit les différentes manières d'envoyer des données à Google Analytics et explique comment contrôler les données envoyées.
Appels, types d'appel et protocole de mesure
Lorsqu'un outil de suivi envoie des données à Google Analytics, il s'agit d'un appel qui doit être associé à un type d'appel. La balise Google Analytics envoie un appel de type pageview. Les autres types d'appel sont screenview, event, transaction, item, social, exception et timing. Ce guide décrit les concepts et les méthodes courants pour tous les types d'appels. Des guides individuels pour chaque type d'appel sont disponibles dans la section Mesure des interactions courantes des utilisateurs dans le panneau de navigation de gauche.
L'appel est une requête HTTP composée de paires champ/valeur encodées sous forme de chaîne de requête et envoyées au protocole de mesure.
Si vous avez ouvert les outils pour les développeurs de votre navigateur lorsque vous chargez une page qui utilise analytics.js, vous pouvez voir les appels envoyés dans l'onglet "Réseau". Recherchez les requêtes envoyées à google-analytics.com/collect.
Quelles sont les données envoyées ?
Lorsqu'ils envoient un appel au protocole de mesure, les outils de suivi envoient tous les champs actuellement stockés et qui sont des paramètres du protocole de mesure valides. Par exemple, des champs tels que title et location sont envoyés, mais pas cookieDomain ni hitCallback.
Dans certains cas, il se peut que vous souhaitiez envoyer des champs à l'appel Google Analytics pour l'appel en cours, mais pas pour les appels suivants. C'est le cas, par exemple, d'un appel avec événement dont les champs eventAction et eventLabel ne concernent que l'appel en cours.
Pour envoyer uniquement des champs avec l'appel en cours, vous pouvez les transmettre en tant qu'arguments à la méthode send. Pour que les données de champ soient envoyées avec tous les appels suivants, vous devez mettre à jour l'outil de suivi à l'aide de la méthode set.
Méthode d'envoi
Une méthode send de suivi peut être appelée directement sur l'objet de suivi lui-même ou en ajoutant une commande send à la file d'attente de commandes ga(). Comme la plupart du temps, vous n'avez pas de référence à l'objet de suivi, nous vous recommandons d'utiliser la file d'attente de commandes ga() pour envoyer des données de suivi à Google Analytics.
Utiliser la file d'attente de commandes ga()
Pour ajouter une commande send à la file d'attente de commandes ga(), procédez comme suit:
ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);
Comme indiqué ci-dessus, les valeurs spécifiées dans les paramètres hitType, ...fields et fieldsObject ne sont envoyées que pour l'appel en cours. Ils ne sont pas stockés sur l'objet de suivi et ne sont pas envoyés avec les appels suivants.
Si l'un des champs transmis avec la commande send est déjà défini sur l'objet de suivi, les valeurs transmises dans la commande seront utilisées à la place des valeurs stockées dans l'outil de suivi.
Les appels de la commande send doivent spécifier un hitType. Selon le type spécifié, d'autres paramètres peuvent également être requis. Pour en savoir plus, consultez les guides dédiés à la mesure des interactions courantes des utilisateurs dans le panneau de navigation de gauche.
La méthode la plus simple pour utiliser la commande send, qui fonctionne pour tous les types d'appels, consiste à transmettre tous les champs à l'aide du paramètre fieldsObject. Exemple :
ga('send', {
hitType: 'event',
eventCategory: 'Video',
eventAction: 'play',
eventLabel: 'cats.mp4'
});
Pour plus de commodité, certains types d'appels permettent de transmettre directement des champs couramment utilisés en tant qu'arguments à la commande send. Par exemple, la commande send ci-dessus pour le type d'appel d'événement peut être réécrite ainsi:
ga('send', 'event', 'Video', 'play', 'cats.mp4');
Pour obtenir la liste complète des champs pouvant être transmis en tant qu'arguments pour les différents types d'appels, consultez la section "Paramètres" de la documentation de référence sur la méthode d'envoi.
Utiliser un coach électronique nommé
Si vous utilisez un outil de suivi nommé au lieu de l'outil de suivi par défaut, vous pouvez transmettre son nom dans la chaîne de commande.
La commande send suivante sera appelée sur l'outil de suivi nommé"myTracker" :
ga('myTracker.send', 'event', 'Video', 'play', 'cats.mp4');
Sur l'objet de suivi lui-même
Si vous avez une référence à l'objet de suivi, vous pouvez appeler directement la méthode send de cet outil de suivi:
ga(function(tracker) {
tracker.send('event', 'Video', 'play', 'cats.mp4');
});
Savoir quand l'appel a été envoyé
Dans certains cas, vous avez besoin de savoir quand un appel est envoyé à Google Analytics afin de pouvoir prendre des mesures immédiatement après. Cette situation est fréquente lorsque vous devez enregistrer une interaction particulière qui conduit l'internaute à quitter la page active. De nombreux navigateurs cessent d'exécuter JavaScript dès le début du déchargement de la page. Par conséquent, les commandes analytics.js permettant d'envoyer des appels peuvent ne jamais s'exécuter.
C'est par exemple le cas lorsque vous souhaitez envoyer un événement à Google Analytics pour enregistrer qu'un utilisateur a cliqué sur un bouton d'envoi de formulaire. Dans la plupart des cas, le fait de cliquer sur le bouton d'envoi lance immédiatement le chargement de la page suivante et les commandes ga('send', ...) ne s'exécutent pas.
La solution consiste à intercepter l'événement pour arrêter le déchargement de la page. Vous pouvez ensuite envoyer votre appel à Google Analytics comme d'habitude. Une fois l'appel envoyé, vous pouvez renvoyer le formulaire par programmation.
hitCallback
Pour recevoir une notification lorsqu'un appel est terminé, définissez le champ hitCallback. hitCallback est une fonction qui est appelée dès que l'appel a été envoyé.
L'exemple suivant montre comment annuler l'action d'envoi par défaut d'un formulaire, envoyer un appel à Google Analytics, puis renvoyer le formulaire à l'aide de la fonction hitCallback:
// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');
// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {
// Prevents the browser from submitting the form
// and thus unloading the current page.
event.preventDefault();
// Sends the event to Google Analytics and
// resubmits the form once the hit is done.
ga('send', 'event', 'Signup Form', 'submit', {
hitCallback: function() {
form.submit();
}
});
});
Gérer les délais avant expiration
L'exemple ci-dessus fonctionne bien, mais présente un problème sérieux. Si (pour une raison quelconque) la bibliothèque analytics.js ne se charge pas, la fonction hitCallback ne s'exécute jamais. Si la fonction hitCallback ne s'exécute jamais, les utilisateurs ne pourront jamais envoyer le formulaire.
Chaque fois que vous ajoutez des fonctionnalités de site critiques à la fonction hitCallback, vous devez toujours utiliser une fonction de délai avant expiration pour gérer les cas où la bibliothèque analytics.js ne se charge pas.
L'exemple suivant met à jour le code ci-dessus pour utiliser un délai avant expiration. Si une seconde s'est écoulée après que l'utilisateur a cliqué sur le bouton d'envoi, et que hitCallback n'a pas été exécuté, le formulaire est quand même renvoyé pour examen.
// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');
// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {
// Prevents the browser from submitting the form
// and thus unloading the current page.
event.preventDefault();
// Creates a timeout to call `submitForm` after one second.
setTimeout(submitForm, 1000);
// Keeps track of whether or not the form has been submitted.
// This prevents the form from being submitted twice in cases
// where `hitCallback` fires normally.
var formSubmitted = false;
function submitForm() {
if (!formSubmitted) {
formSubmitted = true;
form.submit();
}
}
// Sends the event to Google Analytics and
// resubmits the form once the hit is done.
ga('send', 'event', 'Signup Form', 'submit', {
hitCallback: submitForm
});
});
Si vous utilisez le modèle ci-dessus à de nombreux endroits de votre site, il est probablement plus simple de créer une fonction utilitaire pour gérer les délais d'inactivité.
La fonction utilitaire suivante accepte une fonction en entrée et renvoie une nouvelle fonction. Si la fonction renvoyée est appelée avant le délai avant expiration (le délai par défaut est d'une seconde), elle efface le délai avant expiration et appelle la fonction d'entrée. Si la fonction renvoyée n'est pas appelée avant le délai d'expiration, la fonction d'entrée est appelée malgré tout.
function createFunctionWithTimeout(callback, opt_timeout) {
var called = false;
function fn() {
if (!called) {
called = true;
callback();
}
}
setTimeout(fn, opt_timeout || 1000);
return fn;
}
Vous pouvez désormais encapsuler facilement toutes les fonctions hitCallback avec un délai d'inactivité pour vous assurer que votre site fonctionne comme prévu, même dans les cas où les appels ne sont pas envoyés ou lorsque la bibliothèque analytics.js ne se charge jamais.
// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');
// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {
// Prevents the browser from submitting the form
// and thus unloading the current page.
event.preventDefault();
// Sends the event to Google Analytics and
// resubmits the form once the hit is done.
ga('send', 'event', 'Signup Form', 'submit', {
hitCallback: createFunctionWithTimeout(function() {
form.submit();
})
});
});
Spécifier différents mécanismes de transport
Par défaut, analytics.js sélectionne la méthode HTTP et le mécanisme de transport avec lesquels envoyer les appels de manière optimale. Les trois options sont 'image' (avec un objet Image), 'xhr' (avec un objet XMLHttpRequest) ou 'beacon' avec la nouvelle méthode navigator.sendBeacon.
Les deux anciennes méthodes partagent le problème décrit dans la section précédente (où les appels ne sont souvent pas envoyés si la page est déchargée). La méthode navigator.sendBeacon, en revanche, est une nouvelle fonctionnalité HTML créée pour résoudre ce problème.
Si le navigateur de votre utilisateur est compatible avec navigator.sendBeacon, vous pouvez spécifier 'beacon' comme mécanisme transport et ne pas avoir à définir un rappel d'appel.
Le code suivant définit le mécanisme de transport sur 'beacon' dans les navigateurs compatibles.
ga('create', 'UA-XXXXX-Y', 'auto');
// Updates the tracker to use `navigator.sendBeacon` if available.
ga('set', 'transport', 'beacon');
Étapes suivantes
Mesurer certains types d'interactions des utilisateurs peut parfois nécessiter des implémentations complexes. Cependant, dans de nombreux cas, ces implémentations ont déjà été développées et mises à disposition en tant que plug-ins analytics.js. Le guide suivant explique comment utiliser les plug-ins analytics.js avec la file d'attente de commandes ga().