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 le traceur dont la création programmée a été programmée dans la ligne de code précédente. Les données envoyées sont celles stockées dans cet outil.
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'appels et protocole de mesure
Lorsqu'un outil de suivi envoie des données à Google Analytics, on parle d'envoi d'un appel. Chaque appel 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 communs à tous les types d'appels. Des guides individuels pour chaque type d'appel sont disponibles dans la section Mesurer les interactions courantes des utilisateurs dans le panneau de navigation de gauche.
Un appel est une requête HTTP, composée de paires de champs et de valeurs encodées sous la forme d'une chaîne de requête, et envoyées au protocole de mesure.
Si les outils pour les développeurs de votre navigateur sont ouverts lorsque vous chargez une page qui utilise analytics.js, vous pouvez voir les appels envoyés dans l'onglet "Réseau". Recherchez les demandes envoyées à google-analytics.com/collect.
Quelles données sont envoyées ?
Lorsqu'ils envoient un appel au protocole de mesure, les outils de suivi envoient tous les champs actuellement stockés et correspondant à des paramètres du protocole de mesure valides. Par exemple, des champs tels que title et location sont envoyés, mais pas cookieDomain et hitCallback.
Dans certains cas, vous souhaitez envoyer des champs à Google Analytics pour l'appel actuel, mais pas pour les appels suivants. Par exemple, dans le cas d'un appel avec événement, les champs eventAction et eventLabel ne concernent que l'appel actuel.
Pour envoyer des champs avec l'appel actuel uniquement, 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.
La méthode d'envoi
La méthode send d'un outil 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(). Étant donné que 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 les données de suivi à Google Analytics.
Utiliser la file d'attente de commandes ga()
La signature permettant d'ajouter une commande send à la file d'attente de commandes ga() est la suivante:
ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);
Comme indiqué ci-dessus, les valeurs spécifiées via les paramètres hitType, ...fields et fieldsObject ne sont envoyées que pour l'appel actuel. Ils ne sont pas stockés dans 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 sont utilisées à la place de celles stockées dans l'outil de suivi.
Les appels de la commande send doivent spécifier un hitType et, selon le type spécifié, d'autres paramètres peuvent également être requis. Pour en savoir plus, consultez les guides individuels pour mesurer les interactions utilisateur courantes dans le panneau de navigation de gauche.
Le moyen le plus simple d'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 "événement" pourrait être réécrite comme suit:
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 traceur 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 ce traceur:
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 agir immédiatement après. Cette situation est courante lorsque vous devez enregistrer une interaction particulière qui redirige l'utilisateur vers une autre page. De nombreux navigateurs cessent d'exécuter JavaScript dès que la page commence à se décharger. Par conséquent, les commandes analytics.js permettant d'envoyer des appels risquent de 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 le bouton d'envoi d'un formulaire. Dans la plupart des cas, le fait de cliquer sur le bouton "Envoyer" lance immédiatement le chargement de la page suivante, et aucune commande ga('send', ...) n'est exécutée.
La solution consiste à intercepter l'événement pour empêcher la page de se décharger. Comme d'habitude, vous pouvez ensuite envoyer votre appel à Google Analytics. Une fois l'appel terminé, vous pouvez renvoyer le formulaire par programmation.
hitCallback
Pour être averti lorsqu'un appel est envoyé, définissez le champ hitCallback. hitCallback est une fonction qui est appelée dès que l'appel a bien é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écutera jamais. Si la fonction hitCallback ne s'exécute jamais, les utilisateurs ne pourront jamais envoyer le formulaire.
Chaque fois que vous placez une fonctionnalité critique du site dans la fonction hitCallback, vous devez toujours utiliser une fonction de délai avant expiration pour gérer les cas d'échec du chargement de la bibliothèque analytics.js.
L'exemple suivant met à jour le code ci-dessus pour utiliser un délai avant expiration. Si une seconde s'écoule 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é.
// 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 sur votre site, il est sans doute plus facile de créer une fonction utilitaire pour gérer les délais avant expiration.
La fonction utilitaire suivante accepte une fonction en entrée et en renvoie une nouvelle. Si la fonction renvoyée est appelée avant le délai d'expiration (le délai d'inactivité par défaut est d'une seconde), le délai est effacé et la fonction d'entrée est appelé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 indépendamment.
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 avant expiration pour garantir le bon fonctionnement de votre site, même si l'envoi de vos appels échoue ou si 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 choisit la méthode HTTP et le mécanisme de transport avec lesquels envoyer des 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 premières méthodes présentent le même problème que celui décrit dans la section précédente (dans ce cas, les appels ne sont généralement pas envoyés lorsque 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 l'utilisateur est compatible avec navigator.sendBeacon, vous pouvez spécifier 'beacon' comme mécanisme transport, sans 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
La mesure de certains types d'interactions des utilisateurs peut parfois nécessiter des implémentations complexes. Toutefois, dans de nombreux cas, ces intégrations ont déjà été développées et mises à disposition sous forme de plug-ins analytics.js. Le guide suivant explique comment utiliser les plug-ins analytics.js avec la file d'attente de commandes ga().