Écrire des plug-ins

Les plug-ins sont des scripts qui améliorent le fonctionnement d'analytics.js afin de faciliter la résolution des problèmes et de mesurer les interactions des utilisateurs. Ce guide décrit le processus de création de vos propres plug-ins analytics.js. Pour en savoir plus sur l'utilisation des plug-ins analytics.js dans vos propres implémentations, consultez Utiliser des plug-ins.

Définir un plug-in

Les plug-ins sont définis via la commande provide, qui doit être appelée en utilisant le nom du plug-in en premier, suivi de la fonction constructeur du plug-in. Lorsque la commande provide est exécutée, elle enregistre le plug-in à utiliser avec la file d'attente de commandes ga().

Constructeur de plug-in

Voici l'exemple le plus basique de plug-in analytics.js:

// Defines the plugin constructor.
function MyPlugin() {
  console.log('myplugin has been required...');
}

// Registers the plugin for use.
ga('provide', 'myplugin', MyPlugin);

Les plug-ins doivent fonctionner correctement, même si l'objet ga global a été renommé. Par conséquent, si vous écrivez un plug-in pour une utilisation tierce, vous devez inclure une vérification pour voir si la variable GoogleAnalyticsObject a été définie sur une chaîne autre que 'ga'. La fonction providePlugin suivante effectue cette opération:

// Provides a plugin name and constructor function to analytics.js. This
// function works even if the site has customized the ga global identifier.
function providePlugin(pluginName, pluginConstructor) {
  var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
  if (typeof ga == 'function') {
    ga('provide', pluginName, pluginConstructor);
  }
}

Configuration des instances de plug-ins

Lorsque la file d'attente de commandes ga() exécute une commande require, elle instancie un nouvel objet à l'aide de l'opérateur new sur la fonction constructeur du plug-in provide. Le constructeur reçoit l'objet Tracker en tant que premier argument, et toutes les options de configuration sont transmises à la commande require en tant que deuxième argument.

Prenons l'exemple de la commande require suivante, qui a été ajoutée à la balise Google Analytics:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'localHitSender', {path: '/log', debug: true});
ga('send', 'pageview');

Et le code localHitSender:

function LocalHitSender(tracker, config) {
  this.path = config.path;
  this.debug = config.debug;
  if (this.debug) {
    console.log('localHitSender enabled for path: ' + this.path);
    console.log('on tracker: ' + tracker.get('name'));
  }
}

providePlugin('localHitSender', LocalHitSender);

Lorsque la commande require est exécutée, les éléments suivants sont consignés dans la console (notez que le nom de l'outil de suivi par défaut est "t0"):

// localHitSender enabled for path: /log
// on tracker: t0

Définition des méthodes de plug-in

Les plug-ins peuvent exposer leurs propres méthodes, qui peuvent être appelées à l'aide de la syntaxe de file d'attente de commandes ga:

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

où trackerName est facultatif et methodName correspond au nom d'une fonction sur le prototype des constructeurs de plug-in. Si methodName n'existe pas dans le plug-in ou si le plug-in n'existe pas, une erreur s'affiche.

Exemples d'appels de méthode par plug-in:

// Execute the 'doStuff' method using the 'myplugin' plugin.
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'myplugin');
ga('myplugin:doStuff');

// Execute the 'setEnabled' method of the 'hitCopy' plugin on tracker 't3'.
ga('create', 'UA-XXXXX-Y', 'auto', {name: 't3'});
ga('t3.require', 'hitcopy');
ga('t3.hitcopy:setEnabled', false);

Exemples de définitions de méthodes de plug-in:

// myplugin constructor.
var MyPlugin = function(tracker) {
};

// myplugin:doStuff method definition.
MyPlugin.prototype.doStuff = function() {
  alert('doStuff method called!');
};

// hitcopy plugin.
var HitCopy = function(tracker) {
};

// hitcopy:setEnabled method definition.
HitCopy.prototype.setEnabled = function(isEnabled) {
  this.isEnabled = isEnabled;
}:

Chargement des plug-ins...

Les plug-ins sont généralement chargés à partir d'un fichier JavaScript distinct ou regroupés avec le code de votre application principal.

<script async src="myplugin.js"></script>

Les plug-ins n'ont pas nécessairement besoin d'être définis avant d'être requis. Étant donné que analytics.js est chargé de manière asynchrone et que les plug-ins le sont souvent aussi de manière asynchrone, la file d'attente de commande ga() est conçue pour gérer cela.

Si la file d'attente de commandes reçoit une commande require pour un plug-in qui n'a pas encore été fourni, elle interrompt l'exécution des autres éléments de la file d'attente jusqu'à ce que le plug-in soit disponible.

Le code suivant montre que la commande ga('require', 'myplugin') n'est réellement exécutée que lorsque la commande ga('provide', 'myplugin', ...) s'affiche, trois secondes plus tard.

ga('require', 'myplugin');

function MyPlugin() {
  console.log('myplugin has been required...');
}

// Waits 3 second after running the `require`
// command before running the `provide` command.
setTimeout(function() {
  ga('provide', 'myplugin', MyPlugin);
}, 3000);

Important : Bien que l'ordre des commandes require et provide ne soit pas important, elles ne peuvent pas être appelées avant l'exécution de l'extrait de code de suivi JavaScript, car ils font tous deux référence à la fonction de file d'attente de commande ga globale.

Exemples

L'exemple de plug-in suivant est conçu pour capturer des valeurs de campagne personnalisées à partir de l'URL d'une page et les transmettre à l'outil de suivi. Ce plug-in montre comment définir et enregistrer un script de plug-in, transmettre des paramètres de configuration de plug-in, et définir et appeler des méthodes de plug-in.

// campaign-loader.js

function providePlugin(pluginName, pluginConstructor) {
  var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
  if (typeof ga == 'function') {
    ga('provide', pluginName, pluginConstructor);
  }
}

/**
 * Constructor for the campaignLoader plugin.
 */
var CampaignLoader = function(tracker, config) {
  this.tracker = tracker;
  this.nameParam = config.nameParam || 'name';
  this.sourceParam = config.sourceParam || 'source';
  this.mediumParam = config.mediumParam || 'medium';
  this.isDebug = config.debug;
};

/**
 * Loads campaign fields from the URL and updates the tracker.
 */
CampaignLoader.prototype.loadCampaignFields = function() {
  this.debugMessage('Loading custom campaign parameters');

  var nameValue = getUrlParam(this.nameParam);
  if (nameValue) {
    this.tracker.set('campaignName', nameValue);
    this.debugMessage('Loaded campaign name: ' + nameValue);
  }

  var sourceValue = getUrlParam(this.sourceParam);
  if (sourceValue) {
    this.tracker.set('campaignSource', sourceValue);
    this.debugMessage('Loaded campaign source: ' + sourceValue);
  }

  var mediumValue = getUrlParam(this.mediumParam);
  if (mediumValue) {
    this.tracker.set('campaignMedium', mediumValue);
    this.debugMessage('Loaded campaign medium: ' + mediumValue);
  }
};

/**
 * Enables / disables debug output.
 */
CampaignLoader.prototype.setDebug = function(enabled) {
  this.isDebug = enabled;
};

/**
 * Displays a debug message in the console, if debugging is enabled.
 */
CampaignLoader.prototype.debugMessage = function(message) {
  if (!this.isDebug) return;
  if (console) console.debug(message);
};

/**
 * Utility function to extract a URL parameter value.
 */
function getUrlParam(param) {
  var match = document.location.search.match('(?:\\?|&)' + param + '=([^&#]*)');
  return (match && match.length == 2) ? decodeURIComponent(match[1]) : '';
}

// Register the plugin.
providePlugin('campaignLoader', CampaignLoader);

Le code ci-dessus peut être inclus dans une page HTML comme suit:

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');

ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'campaignLoader', {
  debug: true,
  nameParam: 'cname',
  sourceParam: 'csrc',
  mediumParam: 'cmed'
});
ga('campaignLoader:loadCampaignFields');

ga('send', 'pageview');
</script>

<!--Note: plugin scripts must be included after the tracking snippet. -->
<script async src="campaign-loader.js"></script>

Plug-ins de suivi automatique

La bibliothèque autotrack est disponible en Open Source sur GitHub. Elle inclut plusieurs plug-ins analytics.js qui facilitent le suivi des interactions courantes des utilisateurs. Reportez-vous au code source de suivi automatique pour mieux comprendre le fonctionnement des plug-ins.