Documentation de référence sur la file d'attente de commandes GA

La file d'attente de commandes ga() fournit une interface permettant d'effectuer presque tout ce que vous devez faire avec la bibliothèque analytics.js.

L'extrait de code de suivi JavaScript définit la fonction initiale de la file d'attente de commandes ga(). Vous pouvez donc l'utiliser avant même que la bibliothèque analytics.js soit complètement chargée. Une fois la bibliothèque analytics.js chargée, les éléments de la file d'attente de commandes sont exécutés dans l'ordre dans lequel ils ont été reçus. Une fois cette opération effectuée, les nouvelles commandes placées dans la file d'attente sont exécutées immédiatement.

Afin de réduire au maximum l'extrait de code de suivi, la file d'attente de commandes ga() est surchargée afin d'accepter les arguments dans de nombreux formats différents. Ce document détaille toutes les différentes manières d'appeler la fonction de file d'attente de commandes ga().

Signature de la fonction
ga(command, [...fields], [fieldsObject])

Lorsque vous appelez la fonction de file d'attente de commandes ga() avec la signature de fonction suivante, des commandes sont ajoutées à la file d'attente et leur exécution est planifiée une fois la bibliothèque chargée.

ga(readyCallback)

Lorsque vous appelez la fonction de file d'attente de commandes ga() en lui transmettant une fonction, celle-ci est exécutée au point suivant de la file d'attente.

Les commandes ne s'exécutant qu'une fois la bibliothèque analytics.js entièrement chargée. Par conséquent, la fonction la plus courante pour transmettre la file d'attente de commandes est un rappel lorsque la bibliothèque analytics.js est chargée et prête.

Ajouter des commandes à la file d'attente

Lorsque vous appelez la fonction de file d'attente de commandes ga() avec la signature de fonction suivante, des commandes sont ajoutées à la file d'attente et leur exécution est planifiée une fois la bibliothèque chargée.

Utilisation

ga(command, [...fields], [fieldsObject])

Paramètres

Nom Type Obligatoire Description
command string oui

Identifiant représentant la commande à ajouter à la file d'attente. Cet identifiant est constitué de trois parties (les deux premières étant facultatives):

[trackerName.][pluginName:]methodName
trackerName Nom du coach électronique sur lequel appeler la commande programmée. Si aucun nom de suivi n'est spécifié, la commande est appelée sur l'outil de suivi par défaut.
pluginName Nom d'un plug-in analytics.js requis. Si pluginName est spécifié, methodName doit être une méthode fournie par le plug-in.
methodName Nom de la méthode dont l'exécution est planifiée. Si vous ne spécifiez pas de nom de plug-in, cette méthode doit correspondre à l'une des méthodes de commande indiquées ci-dessous.
...fields * non Un ou plusieurs paramètres facultatifs permettant de spécifier rapidement des champs courants. Le nombre de champs autorisés et spécifiques varie en fonction de la méthode de commande appelée.
fieldsObject Object non

Objet permettant de spécifier les valeurs restantes non spécifiées dans les paramètres fields.

Si un champ est défini à la fois dans un paramètre fields et dans fieldsObject, la valeur de fieldsObject est utilisée.

Pour en savoir plus sur chaque champ, reportez-vous à la documentation de référence sur les champs.

Exemples

Consultez la section Méthodes de commande ci-dessous pour obtenir des exemples individuels de commandes.

Rappel prêt

Lorsque vous appelez la fonction de file d'attente de commandes ga() en lui transmettant une fonction, celle-ci est exécutée au point suivant de la file d'attente.

Les commandes ne s'exécutant qu'une fois la bibliothèque analytics.js entièrement chargée. Par conséquent, la fonction la plus courante pour transmettre la file d'attente de commandes est un rappel lorsque la bibliothèque analytics.js est chargée et prête.

Utilisation

ga(readyCallback)

Paramètres

Nom Type Obligatoire Description
readyCallback Function oui

Fonction de rappel à invoquer lorsque la bibliothèque est entièrement chargée et prête à interagir La fonction est appelée avec l'objet de suivi par défaut comme premier argument. Si aucun outil de suivi par défaut n'a été créé, le premier argument est undefined.

Remarque: Lorsque la fonction de rappel est appelée, toutes les méthodes d'objet ga sont disponibles.

Exemples

// Queues a tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto');

// Once the tracker has been created, log the
// client ID to the console.
ga(function(tracker) {
  console.log(tracker.get('clientId'));
});
// Queues a named tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto', 'myTracker');

// When there is no default tracker, the first
// argument of the ready callback is `undefined`.
ga(function(tracker) {
  console.log(tracker); // Logs `undefined`.
});

Détails de la méthode de commande

Vous trouverez ci-dessous la liste de toutes les méthodes pouvant être transmises à la file d'attente de commandes ga() (à l'exception des méthodes de plug-in).

create

Crée une instance de suivi avec les champs spécifiés.

Utilisation

ga('create', [trackingId], [cookieDomain], [name], [fieldsObject]);

Paramètres

Pour en savoir plus sur chaque champ, reportez-vous à la documentation de référence sur les champs.

Renvoie

undefined

Exemples

// Creates a default tracker for the Property UA-XXXXX-Y
// and uses automatic cookie domain configuration.
ga('create', 'UA-XXXXX-Y', 'auto');
// Creates a tracker with the name "myTracker" for the Property
// UA-XXXXX-Y, sets the cookieDomain to "example.com", and specifies
// a transport mechanism of "beacon".
ga('create', 'UA-XXXXX-Y', 'example.com', 'myTracker', {
  transport: 'beacon'
});

send

Envoie un appel à Google Analytics.

Utilisation

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

Les champs envoyés sont les valeurs spécifiées dans les paramètres ...fields et fieldsObject, fusionnés avec les champs actuellement stockés dans l'outil de suivi.

Paramètres

Les champs pouvant être spécifiés par les paramètres ...fields varient en fonction du type d'appel. Le tableau suivant répertorie les champs correspondant à chaque type d'appel. Les types d'appels non répertoriés n'acceptent que les paramètres ...fields, mais uniquement les fieldsObject.

Type d'appel ...fields
pageview page
event eventCategory, eventAction, eventLabel et eventValue
social socialNetwork, socialAction et socialTarget
timing timingCategory, timingVar, timingValue et timingLabel

Pour en savoir plus sur chaque champ, reportez-vous à la documentation de référence sur les champs.

Renvoie

undefined

Exemples

// Sends a pageview hit.
ga('send', 'pageview');
// Sends an event hit for the tracker named "myTracker" with the
// following category, action, and label, and sets the nonInteraction
// field value to true.
ga('send', 'event', 'link', 'click', 'http://example.com', {
  nonInteraction: true
});

set

Définit une seule paire champ/valeur ou un groupe de paires champ/valeur sur un objet de suivi.

Utilisation

// Sets a single field and value.
ga('[trackerName.]set', fieldName, fieldValue);
// Sets a group of field/value pairs.
ga('[trackerName.]set', fieldsObject);

Paramètres

Pour en savoir plus sur chaque champ, reportez-vous à la documentation de référence sur les champs.

Renvoie

undefined

Exemples

// Sets the page field to "/about.html".
ga('set', 'page', '/about.html');
// Sets the page field to "/about.html" and the title to "About".
ga('set', {
  page: '/about.html',
  title: 'About'
});

require

Nécessite un plug-in analytics.js.

Utilisation

ga('[trackerName.]require', pluginName, [pluginOptions]);

Paramètres

Nom Type Obligatoire Description
pluginName string oui Nom du plug-in requis. Remarque : Si le plug-in n'est pas un plug-in analytics.js officiel, il doit être fourni ailleurs sur la page.
pluginOptions Object non Objet d'initialisation qui sera transmis au constructeur du plug-in lors de l'instanciation.

Renvoie

undefined

Exemple

// Requires the Enhanced Ecommerce plugin.
ga('require', 'ec');
// Requires the Advertising Features plugin
// named "myTracker" and override its default cookie name.
ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

provide

Fournit un plug-in analytics.js et ses méthodes à utiliser avec la file d'attente de commandes ga().

ga('provide', pluginName, pluginConstuctor);

Paramètres

Nom Type Obligatoire Description
pluginName string oui Nom du plug-in fourni. Le nom utilisé doit être identique à celui utilisé pour les appels require.
pluginConstuctor Function oui Une fonction constructeur fournit toute la logique et les méthodes du plug-in. Ce constructeur sera appelé avec l'objet pluginsOptions spécifié dans la méthode require.

Exemple

// Defines a plugin constructor
function MyPlugin(tracker, options) {
  // ...
}

// Provides the plugin for use with the ga() command queue.
ga('provide', 'myplugin', MyPlugin);

remove

Supprime un objet de suivi.

Utilisation

ga('[trackerName.]remove');

Exemples

// Remove the default tracker.
ga('remove');
// Remove the  tracker named "myTracker".
ga('myTracker.remove');