Los complementos son secuencias de comandos que mejoran la funcionalidad de analytics.js para resolver problemas y ayudar a medir la interacción del usuario. En esta guía, se describe el proceso para escribir tus propios complementos de analytics.js. Si deseas obtener información para usar los complementos de analytics.js en tus propias implementaciones, consulta Cómo usar complementos.
Cómo definir un complemento
Los complementos se definen mediante el comando provide, que se debe invocar con el nombre del complemento como primer argumento seguido de la función del constructor del complemento. Cuando se ejecuta el comando provide, se registra el complemento para usar con la cola de comandos de ga().
El constructor del complemento
El siguiente es el ejemplo más básico de un complemento analytics.js:
// Defines the plugin constructor.
function MyPlugin() {
console.log('myplugin has been required...');
}
// Registers the plugin for use.
ga('provide', 'myplugin', MyPlugin);
Los complementos deben funcionar correctamente incluso en los casos en los que se cambió el nombre del objeto ga global. Por lo tanto, si escribes un complemento para uso de terceros, debes incluir una verificación para ver si la variable GoogleAnalyticsObject se estableció en una cadena distinta de 'ga'. La siguiente función providePlugin hace esto:
// 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);
}
}
Cómo configurar instancias de complementos
Cuando la cola de comandos ga() ejecuta un comando require, crea una instancia de un objeto nuevo con el operador new en la función del constructor del complemento provide. El constructor recibe el objeto de seguimiento como su primer argumento, y cualquier opción de configuración pasa al comando require como su segundo argumento.
Considera agregar el siguiente comando require a la etiqueta de Google Analytics:
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'localHitSender', {path: '/log', debug: true});
ga('send', 'pageview');
Y el código 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);
Cuando se ejecute el comando require, se registrará lo siguiente en la consola (ten en cuenta que el nombre del rastreador predeterminado es "t0"):
// localHitSender enabled for path: /log
// on tracker: t0
Cómo definir métodos de complementos
Los complementos pueden exponer sus propios métodos, que se pueden invocar con la sintaxis de la cola de comandos ga:
ga('[trackerName.]pluginName:methodName', ...args);
donde trackerName es opcional y methodName corresponde al nombre de una función en el prototipo de los constructores del complemento. Si methodName no existe en el complemento o el complemento no existe, se producirá un error.
Ejemplos de llamadas de método de complemento:
// 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);
Ejemplos de definiciones de métodos de complemento:
// 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;
}:
Cargando complementos
Por lo general, los complementos se cargan desde un archivo JavaScript independiente o se agrupan con el código de tu aplicación principal.
<script async src="myplugin.js"></script>
No es necesario definir los complementos antes de ser requeridos. Dado que analytics.js se carga de forma asíncrona y los complementos a menudo también se cargan de forma asíncrona, la cola de comandos de ga() está creada para controlar esto.
Si la cola de comandos recibe un comando require para un complemento que aún no se proporcionó, se detendrá la ejecución de los elementos restantes de la cola hasta que el complemento esté disponible.
En el siguiente código, se muestra que el comando ga('require', 'myplugin') no se ejecuta hasta que se encuentra el comando ga('provide', 'myplugin', ...), tres segundos después.
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);
Ejemplos
El siguiente complemento de ejemplo está diseñado para capturar valores de campaña personalizados de la URL de una página y pasarlos a la herramienta de seguimiento. Este complemento muestra cómo definir y registrar una secuencia de comandos del complemento, pasar parámetros de configuración del complemento y definir y llamar a métodos del complemento.
// 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);
El código anterior se puede incluir en una página HTML de la siguiente manera:
<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>
Seguimiento automático de complementos
La biblioteca autotrack es de código abierto y está disponible en GitHub e incluye varios complementos de analytics.js que ayudan a realizar un seguimiento de las interacciones comunes de los usuarios. Consulta el código fuente del seguimiento automático para comprender mejor el funcionamiento de los complementos.