Referencia de los métodos: seguimiento web (analytics.js)

La biblioteca analytics.js proporciona dos objetos principales para interactuar con Google Analytics. Cada objeto contiene varios métodos:

Métodos del objeto ga

Al incluir el fragmento JavaScript analytics.js predeterminado en la página, se crea un objeto global llamado ga. Los programadores usan el objeto ga para crear objetos de seguimiento que, a su vez, envían datos a una propiedad web de Google Analytics.

create

Crea un nuevo objeto de seguimiento predeterminado.

ga('create', trackingId, opt_configObject);

Parámetros

  • String trackingId: ID de propiedad web del sitio web del que se realizará el seguimiento.
  • Object opt_configObject: objeto opcional que contiene los pares campo-valor de configuración.

Ejemplos

Crear un objeto de seguimiento predeterminado:

ga('create', 'UA-XXXX-Y', 'auto');

Crear un objeto de seguimiento con un nombre de cookie personalizado:

ga('create', 'UA-XXXX-Y', 'auto', {'cookieName': '_ga2'});

Crear un objeto de seguimiento con la sintaxis síncrona:

var tracker = ga.create('UA-XXXX-Y', 'auto');

ga('create', ...) puede aceptar argumentos de posición y de objeto para los campos trackingId, cookieDomain y name. El orden es importante. Por ejemplo, los dos fragmentos siguientes son idénticos:

ga('create', 'UA-XXXX-Y', 'auto', 'T1000');
ga('create', {trackingId: 'UA-XXXX-Y', cookieDomain: 'auto', name: 'T1000'});

getByName

Devuelve el objeto de seguimiento con el nombre indicado, o "null" si no existe ningún objeto de seguimiento con ese nombre.

ga.getByName(name);

Parámetros

  • String name: nombre del objeto de seguimiento que se debe recuperar.

Devuelve

  • Tracker: un objeto de seguimiento.

Ejemplo

Devuelve el objeto de seguimiento denominado shoehorn:

ga(function() {
  var tracker = ga.getByName('shoehorn');
});

getAll

Devuelve una matriz que contiene todos los objetos de seguimiento que existen actualmente, en el orden en que se crearon.

ga.getAll();

Devuelve

  • Array<Tracker>: una matriz de todos los objetos de seguimiento.

Ejemplo

Devuelve todos los objetos de seguimiento y muestra sus nombres en una alerta:

ga(function() {
  var trackers = ga.getAll();

  for (var i=0; i < trackers.length; ++i) {
    var tracker = trackers[i];
    alert(tracker.get('name'));
  }
});

Métodos del objeto de seguimiento

Después de que el objeto de seguimiento se haya creado con el método create, se pueden usar los métodos siguientes para interactuar con Google Analytics.

send

Envía un beacon de seguimiento a los servidores de recopilación de Google. Con el objeto de campo opcional, los usuarios pueden anular uno o varios valores de campo solo para este hit.

ga('send', hitType, opt_fieldObject);

Parámetros

  • String hitType: tipo de hit que se enviará. Los valores admitidos son:
  • Object opt_fieldObject: objeto que contiene uno o varios pares campo-valor que se usan para anular un valor de campo solo para este hit. Los campos volverán a sus valores originales una vez que se complete el hit.

Ejemplo

Enviar una visita de tipo visita de página vista y anular el título de la página:

ga('send', 'pageview', {'title': 'my new title'});

set

Actualiza el valor asociado actualmente al campo indicado. Se puede llamar al método set con un campo y un valor individuales:

ga('set', fieldName, value);

Parámetros

  • String fieldName: nombre del campo que se debe configurar.
  • String|Number|Object|Boolean value: nuevo valor que se asociará al campo indicado.

También se puede llamar a set con un objeto que contenga varios pares campo-valor para realizar una actualización masiva.

ga('set', fieldObject);

Los valores que se configuran persistirán con todas las llamadas posteriores a send mientras dure el objeto de seguimiento.

Parámetros

  • Object fieldObject: objeto que contiene uno o varios pares campo-valor para configurar.

Ejemplos

Configurar el campo page para todos los hits posteriores:

ga('set', 'page', '/my-new-page');

Configurar page y title para todos los hits posteriores:

ga('set', {
  'page': '/my-new-page',
  'title': 'my new title'
});

get

Devuelve el valor asociado actualmente al campo indicado. Se debe llamar con un objeto de seguimiento del que se ha creado una instancia.

var fieldValue = tracker.get(fieldName);

Parámetros

  • String fieldName: nombre del campo que se debe recuperar.

Devuelve

  • String|Number|Object: valor del campo.

Ejemplo

Obtener la página actual de un objeto de seguimiento:

ga(function(tracker) {
  var page = tracker.get('page');
});

Esta función se ejecuta una vez que se ha cargado la biblioteca analytics.js. Cuando se ejecuta la función, el parámetro tracker tiene una referencia al objeto de seguimiento predeterminado (suponiendo que se haya creado antes que la función de llamada). Después, la referencia de objeto de seguimiento se usa para obtener el valor page.

Sintaxis de llamada

Existen varias formas de llamar a cada uno de los métodos de ga.

Asíncrona (objeto de seguimiento predeterminado)

El fragmento JavaScript anaytics.js se ha diseñado para cargarse de forma asíncrona a fin de evitar que los navegadores detengan la carga de la biblioteca. Por lo tanto, no tienes que sincronizar el código referente a la carga de la biblioteca y puedes usar el objeto ga como una función enviándole el nombre de método como primer parámetro:

ga('create', 'UA-XXXX-Y', 'auto');
ga('send', 'pageview');

Se ejecutará tan pronto como la biblioteca termine de cargarse. El método create creará un objeto de seguimiento predeterminado llamado t0. Después, el método send, o cualquier método que se llame con esta sintaxis, se ejecutará en el objeto de seguimiento predeterminado.

En este caso, la creación de un objeto de seguimiento predeterminado se lleva a cabo por motivos de simplificación en la mayoría de las implementaciones.

Asíncrona (objeto de seguimiento con nombre)

En algunos casos, puedes crear varios objetos de seguimiento en la misma página. Para diferenciar unos de otros, se debe asignar un nombre a cada uno.

El objeto de seguimiento con nombre se crea estableciendo el campo de configuración name mediante el parámetro de objeto de configuración opcional del método create.

ga('create', 'UA-XXXX-Y', 'auto', {'name': 'tracker2'});

Después, se llaman los métodos de los objetos de seguimiento con nombre anteponiendo a dichos métodos el nombre del objeto de seguimiento y un punto (.):

ga('tracker2.send', 'pageview');

Síncrona

La biblioteca anaytics.js también admite una forma síncrona de llamar los métodos. En este caso, los métodos se llaman directamente en los objetos ga o tracker, respectivamente:

var tracker = ga.create('UA-XXXX-Y', 'auto');
tracker.send('pageview');

Sincronización asíncrona

En ocasiones, determinados métodos deben llamarse solo una vez que se haya cargado la biblioteca. Por ejemplo, el método get solo funcionará cuando se haya cargado la biblioteca, el objeto de seguimiento se haya creado y los campos estén configurados. Para solucionar este problema, puedes enviar al objeto ga una función que solo se ejecutará cuando se haya cargado la biblioteca:

ga(function(tracker) {
  var page = tracker.get('name');
});

La función que le pases al objeto ga acepta un parámetro que, una vez ejecutado, tendrá el valor del objeto de seguimiento predeterminado. Este objeto se puede usar con la sintaxis síncrona. Por ejemplo, el siguiente código también funciona:

ga('create', 'UA-XXXX-Y', 'auto');
ga(function(tracker) {
  tracker.send('pageview');
});

Del mismo modo, para realizar el seguimiento de una página vista en todos los objetos de seguimiento que se han creado, puedes usar:

ga(function() {
  var trackers = ga.getAll();
  for (var i=0; i<trackers.length; ++i) {
    var tracker = trackers[i];
    tracker.send('pageview');
  }
});

Este código puede resultar muy útil si quieres programar extensiones en las que no sepas la cantidad de objetos de seguimiento que se han creado en un sitio. Con esta sintaxis, la función puede ejecutar mucha lógica adicional, por cada objeto de seguimiento de la página, una vez que se ha cargado el código de seguimiento.