Plugins: seguimiento web (analytics.js)

En esta guía se describen los plugins, una función avanzada que permite a los programadores reunir sus bibliotecas de seguimiento personalizadas en secuencias de comandos cargadas de forma asíncrona que pueden interactuar directamente con la cola de comandos de analytics.js.

Descripción general

A menudo, los usuarios avanzados pueden crear cientos de líneas de código personalizado para administrar el seguimiento de un sitio complejo o para ofrecer funciones avanzadas que no estén disponibles en analytics.js. Estas bibliotecas personalizadas suelen cargarse en un sitio a partir de un archivo JavaScript independiente. Para cargar estas secuencias de comandos rápidamente, sin interrumpir la carga y la visualización del sitio web, te recomendamos que cargues siempre estas secuencias de comandos de forma asíncrona.

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

Dado que analytics.js también se carga de forma asíncrona, puede ser difícil coordinar la ejecución de la secuencia de comandos de seguimiento personalizada con la cola de comandos de analytics.js. El sistema de plugins de analytics.js resuelve este problema mediante dos comandos simples: require y provide.

Require

El comando require se usa con el nombre de un plugin y evita la ejecución de cualquier comando posterior hasta que el plugin objetivo se haya cargado y ejecutado.

ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'myplugin');
ga('send', 'pageview');

En el ejemplo anterior, si aún no se ha cargado 'myplugin', la cola de comandos de analytics.js se detiene hasta que esté disponible. El comando 'send' y cualquier comando posterior en la página quedarán bloqueados hasta ese momento.

Provide

Para registrar tu plugin personalizado en analytics.js, usa el comando provide. El comando provide usa dos argumentos: el nombre de tu plugin y una función de constructor que crea instancias del plugin.

function MyPlugin(tracker) {
  alert('Loaded plugin on tracker ' + tracker.get('name'));
}
ga('provide', 'myplugin', MyPlugin);

En este ejemplo, myplugin.js contiene una función de plugin simple que muestra un cuadro de alerta cuando se carga. Esta función se invocará cada vez que se llame a ga('require', 'myplugin');.

Implementación

Una vez descritos los conceptos básicos del sistema de plugins de analytics.js, podemos ver cómo crear una secuencia de comandos de plugin, cómo configurar instancias de plugin y cómo definir métodos de plugin.

Crear una secuencia de comandos de plugin

Además de cualquier otra lógica personalizada, cada secuencia de comandos de plugin debe incluir al menos una función de constructor de plugin y una llamada al comando provide para registrar el plugin. Dado que la secuencia de comandos del plugin debe funcionar correctamente aunque el fragmento de analytics.js se haya configurado para usar un identificador personalizado para el objeto global ga, no basta con llamar al comando ga('provide', ..). En su lugar, incluimos la copia de la función providePlugin que se muestra a continuación en cada secuencia de comandos del plugin y la usamos para registrarlo.

myplugin.js

// 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 (ga) ga('provide', pluginName, pluginConstructor);
}

// Plugin constructor.
function MyPlugin(tracker) {
  alert('Loaded myplugin on tracker ' + tracker.get('name'));
}

// Register the plugin.
providePlugin('myplugin', MyPlugin);

Configurar instancias de plugin

Además de especificar el nombre del plugin que se debe cargar, el comando require permite enviar un objeto de configuración usado para iniciar una instancia del plugin.

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

El objeto de configuración se envía al constructor del plugin como segundo parámetro.

function LocalHitSender(tracker, config) {
  this.url = config.url;
  this.debug = config.debug;
  if (this.debug) {
    alert('Enabled local hit sender for: ' + this.url);
  }
}
providePlugin('localHitSender', LocalHitSender);

Definir métodos de plugin

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

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

targetName es el nombre del objeto de seguimiento. Si targetName no se especifica, se usa el nombre predeterminado "t0". pluginName es el nombre del plugin. methodName es el nombre de un método de la instancia del plugin. Si no existe methodName en el plugin o si el plugin no existe, se producirá un error.

Ejemplos de llamadas a métodos de plugin:

// 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;
}:

Ejemplo

El siguiente plugin de ejemplo está pensado para recopilar los valores de campaña personalizados de la URL de una página y enviarlos al objeto de seguimiento. 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 (ga) 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);

index.html


<!DOCTYPE html>
<html>
  <head>

    <!-- Google Analytics Snippet-->
    <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>

    <!-- Plugin Script (must be sourced after the analytics.js snippet) -->
    <script async src="campaign-loader.js"></script>

  </head>

    ...