Utiliser des plug-ins

Les plug-ins sont des scripts qui améliorent les fonctionnalités d'analytics.js afin de faciliter la mesure des interactions des utilisateurs. Les plug-ins sont généralement spécifiques à un ensemble de fonctionnalités qui peuvent ne pas être requises par tous les utilisateurs de Google Analytics (comme l'e-commerce ou les mesures multidomaines). Ils ne sont donc pas inclus par défaut dans analytics.js.

Ce guide explique comment exiger et utiliser les plug-ins analytics.js.

Exiger des plug-ins

La commande require prend le nom d'un plug-in et l'enregistre afin de l'utiliser avec la file d'attente de commandes ga(). Si le plug-in accepte les options de configuration, elles peuvent être transmises en tant qu'argument final à la commande require.

Voici la signature complète de la commande require:

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

Par exemple, voici comment vous pourriez avoir besoin du plug-in de commerce électronique amélioré pour l'utiliser avec l'outil de suivi par défaut:

ga('require', 'ec');

Voici comment vous devez utiliser le plug-in Fonctionnalités de publicité pour un outil de suivi nommé "myTracker" et transmettre une option de configuration qui remplace la valeur par défaut du nom du cookie:

ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

Charger le code du plug-in

La commande require initialise les méthodes du plug-in à utiliser avec la file d'attente de commandes ga(), mais elle ne charge pas le script du plug-in. Si vous utilisez un plug-in tiers ou si vous écrivez un plug-in vous-même, vous devez ajouter manuellement le code du plug-in à la page.

La méthode recommandée pour ajouter le code du plug-in à la page consiste à utiliser une balise <script> avec l'attribut async défini pour éviter que le chargement d'autres fonctionnalités sur votre site ne soit bloqué.

Le code suivant nécessite et charge un plug-in de suivi des liens fictif.

<script>
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'linkTracker');
ga('send', 'pageview');
</script>

<!--Note: plugin scripts must be included after the tracking snippet. -->
<script async src="/path/to/link-tracker-plugin.js"></script>

En attente du chargement des plug-ins

Étant donné que la bibliothèque analytics.js et les plug-ins analytics.js sont chargés de manière asynchrone, il peut être difficile de savoir quand les plug-ins sont entièrement chargés et prêts à être utilisés.

La bibliothèque analytics.js résout ce problème en arrêtant l'exécution de la file d'attente de commandes lorsqu'elle rencontre une commande require pour un plug-in qui n'est pas encore chargé. Une fois le plug-in chargé, l'exécution de la file d'attente se poursuit normalement.

Il est donc extrêmement important de tester les plug-ins que vous utilisez pour vous assurer qu'ils se chargent et s'exécutent correctement. Si un plug-in ne se charge pas ou qu'il génère une erreur, toutes les commandes analytics.js suivantes seront exécutées.

Appeler des méthodes de plug-in

Après avoir demandé un plug-in, vous pouvez utiliser ses méthodes avec la file d'attente de commandes ga(). Voici la signature de commande pour appeler les méthodes du plug-in:

ga('[trackerName.][pluginName:]methodName', ...args);

Par exemple, la méthode addProduct du plug-in de commerce électronique amélioré peut être appelée comme suit:

ga('ec:addProduct', {
  'id': 'P12345',
  'quantity': 1
});

Ou sur un outil de suivi nommé en ajoutant le nom de l'outil de suivi à la chaîne de commande:

ga('myTracker.ec:addProduct', {
  'id': 'P12345',
  'quantity': 1
});

Étapes suivantes

Si vous avez lu tous les guides de cette section, vous devez vous familiariser avec la plupart des fonctionnalités d'analytics.js. Le guide suivant vous explique comment déboguer vos intégrations analytics.js afin de détecter plus facilement les erreurs et de voir exactement ce que fait votre code.