Crear plugins

Los plugins son secuencias de comandos que mejoran la funcionalidad de analytics.js para solucionar problemas y para medir la interacción del usuario. 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 plugin 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 plugins deben funcionar correctamente, incluso en las situaciones en las que se haya cambiado el nombre del objeto global ga, por lo que, si vas a crear un plugin para que lo utilicen otras personas, debes verificar si la variable GoogleAnalyticsObject se ha configurado como 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 de ga() ejecuta un comando require, crea una instancia de un nuevo objeto con el operador new en la función provide del constructor del complemento. El primer argumento que se pase al constructor debe ser el objeto de seguimiento y el segundo argumento debe ser las opciones de configuración que se pasan al comando require.

Por ejemplo, el siguiente comando require se agrega al fragmento de seguimiento JavaScript:

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

El código de localHitSender es el siguiente:

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 ejecuta el comando require, se registrará lo siguiente en la consola (el nombre del objeto de seguimiento predeterminado es "t0"):

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

Definir métodos de plugin

Los complementos pueden presentar sus propios métodos, los cuales pueden invocarse mediante la siguiente sintaxis de cola de comandos de ga:

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

donde trackerName es opcional y methodName corresponde al nombre de una función en el prototipo constructores del plugin. Si no existe methodName en el complemento o si el complemento no existe, se producirá un error.

Ejemplos de llamadas a métodos 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);

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 plugins

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 plugins antes de que se necesiten. Debido a que analytics.js se carga asíncronamente y los plugins también se suelen cargar de forma asíncrona, la cola de comandos de ga() se ha diseñado para afrontar esta situación.

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 componente esté disponible.

En el siguiente código se muestra que 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 plugin demuestra cómo definir y registrar una secuencia de comandos de plugin, cómo enviar los parámetros de configuración de plugin y cómo definir y llamar a métodos de plugin.

// 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 seguimiento automático

La biblioteca autotrack es un software libre, disponible en Github, e incluye varios complementos analytics.js que permiten realizar el seguimiento de interacciones de usuario habituales. Consulta el código fuente de seguimiento automático para hacerte una idea más clara de cómo funcionan los complementos.