Los complementos son secuencias de comandos que mejoran la funcionalidad de analytics.js para solucionar problemas y para medir la interacción de los usuarios. En esta guía se describe el proceso de crear complementos de analytics.js propios. Si quieres obtener información sobre cómo usar los complementos de analytics.js en tus implementaciones, consulta Usar complementos.
Definir un complemento
Los complementos se definen con 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, registra el complemento que se va a usar con la cola de comandos de ga().
Constructor del complemento
A continuación se muestra el ejemplo más básico de un complemento de 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 aunque se haya cambiado el nombre del objeto global ga. Por lo tanto, si creas un complemento para uso externo, debes asegurarte de que la variable GoogleAnalyticsObject se haya asignado a una cadena distinta de 'ga'. La función providePlugin hace lo siguiente:
// 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);
}
}
Configurar instancias de complemento
Cuando la cola de comandos ga() ejecuta un comando require, se crea una instancia de un nuevo objeto con el operador new en la función del constructor del complemento provide. El primer argumento que se transmite al constructor debe ser el objeto de seguimiento y el segundo argumento debe ser las opciones de configuración que se transmiten al comando require.
De este modo, se añade el comando require a la etiqueta de Google Analytics.
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'localHitSender', {path: '/log', debug: true});
ga('send', 'pageview');
También se añade 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 objeto de seguimiento predeterminado es "t0"):
// localHitSender enabled for path: /log
// on tracker: t0
Definir métodos de complementos
Los complementos pueden presentar sus propios métodos, que pueden invocarse usando la siguiente sintaxis de la cola de comandos de ga:
ga('[trackerName.]pluginName:methodName', ...args);
trackerName es opcional y methodName corresponde al nombre de una función en el prototipo del constructor del complemento. Si no existe methodNameen el complemento o si el complemento no existe, se producirá un error.
Ejemplos de llamadas a métodos de complementos:
// 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);
Ejemplo 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;
}:
Cargar complementos
Los plugins normalmente se cargan desde un archivo JavaScript independiente o se incluyen con el código de la aplicación principal.
<script async src="myplugin.js"></script>
No es necesario que se definan los complementos antes de que se necesiten. Debido a que analytics.js se carga asíncronamente y los complementos también se suelen cargar de forma asíncrona, la cola de comandos de ga() se ha diseñado en consecuencia.
Si la cola recibe un comando require para un complemento que todavía no se ha proporcionado, detendrá la ejecución de los elementos restantes hasta que el complemento esté disponible.
El siguiente código muestra cómo el comando ga('require', 'myplugin') no se ejecuta realmente hasta que se encuentra el comando ga('provide', 'myplugin', ...), tres segundos más tarde.
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á pensado para recopilar los valores de campaña personalizados de la URL de una página y enviarlos al rastreador. Este complemento demuestra cómo definir y registrar una secuencia de comandos de complemento, cómo enviar los parámetros de configuración de complemento y cómo definir y llamar a métodos de 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 del siguiente modo:
<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>
Complementos de autotrack
La biblioteca autotrack es un software libre, disponible en GitHub. Incluye varios complementos analytics.js que permiten hacer el seguimiento de interacciones de usuario habituales. Consulta el código fuente de los complementos de autotrack para tener una idea más clara de cómo funcionan.