Les plug-ins sont des scripts qui améliorent les fonctionnalités d'analytics.js pour aider à résoudre les problèmes et à mesurer les interactions des utilisateurs. Ce guide décrit le processus d'écriture de vos propres plug-ins analytics.js. Pour savoir comment utiliser les 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 avec le nom du plug-in en tant que premier argument suivi de la fonction du 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-ins
Voici l'exemple le plus basique d'un 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 lorsque l'objet global ga
a été renommé. Par conséquent, si vous écrivez un plug-in pour une utilisation tierce, vous devez vérifier que la variable GoogleAnalyticsObject
a été définie sur une chaîne autre que 'ga'
. La fonction providePlugin
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);
}
}
Configurer des instances de plug-in
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 du constructeur du plug-in provide
. Le constructeur transmet l'objet de suivi 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 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, la commande suivante est consignée dans la console (notez que le nom de l'outil de suivi par défaut est &ttt):
// localHitSender enabled for path: /log
// on tracker: t0
Définir 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-ins. Si methodName
n'existe pas ou si le plug-in n'existe pas, une erreur se produit.
Exemples d'appels de méthode de 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 principal de votre application.
<script async src="myplugin.js"></script>
Il n'est pas nécessaire de définir les plug-ins avant de les utiliser. Étant donné que analytics.js se charge de manière asynchrone et que les plug-ins le sont souvent également, la file d'attente de commandes ga()
est conçue pour gérer ce problème.
Si la file d'attente de commandes reçoit une commande require
pour un plug-in qui n'a pas encore été fourni, l'exécution des autres éléments de la file d'attente sera interrompue jusqu'à ce que le plug-in soit disponible.
Le code suivant montre comment exécuter la commande ga('require', 'myplugin')
jusqu'à ce que la commande ga('provide', 'myplugin', ...)
soit détectée, soit 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);
Exemples
L'exemple de plug-in suivant est conçu pour capturer les 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 Autotrack
La bibliothèque autotrack est Open Source, disponible sur GitHub et inclut plusieurs plug-ins analytics.js qui permettent de suivre les interactions courantes des utilisateurs. Reportez-vous au code source du suivi automatique pour mieux comprendre le fonctionnement des plug-ins.