Enviar datos a Google Analytics

La última línea del fragmento de medición de JavaScript añade el comando send a la cola de comandos ga() para enviar una página vista a Google Analytics:

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

El objeto que realiza el envío es el objeto de seguimiento que se ha programado para crearse en la línea de código anterior y los datos que se envían son los que están almacenados en ese objeto de seguimiento.

En esta guía se describen distintas formas de enviar datos a Google Analytics y se explica cómo controlar qué datos se envían.

Hits, tipos de hits y el Protocolo de medición

Cuando un objeto de seguimiento envía datos a Google Analytics, esa operación se denomina enviar un hit, y cada hit debe tener un tipo. La etiqueta de Google Analytics envía un hit del tipo pageview; otros tipos de hits son screenview, event, transaction, item, social, exception y timing. En esta guía se explican los conceptos y los métodos comunes a todos los tipos de hits. En la sección Medir las interacciones habituales del usuario del panel de navegación izquierdo, se pueden encontrar las guías de cada tipo de hit.

El hit es una solicitud HTTP, que consta de pares de campo y valor codificados como una cadena de consulta, y se envía al Protocolo de medición.

Si tienes abiertas las herramientas para desarrolladores del navegador al cargar una página que use analytics.js, podrás ver los hits que se envían en la pestaña de red. Busca las solicitudes enviadas a google-analytics.com/collect.

Qué datos se envían

Al enviar un hit al Protocolo de medición, los objetos de seguimiento envían todos los campos que están almacenados y que son parámetros de Protocolo de medición válidos. Por ejemplo, se envían campos como title y location, pero no cookieDomain ni hitCallback.

En algunos casos, es recomendable enviar a Google Analytics los campos correspondientes a un hit concreto, pero no a todos. Un ejemplo de esto es un hit de evento en el que los campos eventAction y eventLabel son relevantes solo para ese hit.

Para enviar campos solo con el hit actual, puedes transmitirlos como argumentos del método send. Para que los datos de campo se envíen con los hits posteriores, debes actualizar el objeto de seguimiento con el método set.

Método send

Se puede llamar al método send de un objeto de seguimiento en el propio objeto o añadiendo un comando a la cola de comandos de ga(). Puesto que la mayoría de las veces no se tiene ninguna referencia al objeto de seguimiento, se recomienda enviar datos de seguimiento a Google Analytics a través de la cola de comandos de ga().

Utilizar la cola de comandos de ga()

La firma para añadir un comando send a la cola de comandos de ga() es la siguiente:

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

Como se ha mencionado anteriormente, los valores especificados mediante los parámetros hitType, ...fields y fieldsObject se envían solo para el hit actual. No se almacenan en el objeto de seguimiento ni se envían con los hits posteriores.

Si alguno de los campos transferidos con el comando send ya está definido en el objeto de seguimiento, se utilizarán los valores transferidos a través del comando en lugar de los almacenados en el objeto de seguimiento.

Las llamadas al comando send deben especificar un hitType y, según el tipo especificado, es posible que también se necesiten otros parámetros. Si quieres obtener más información, consulta las guías de medición de las interacciones habituales de los usuarios en el panel de navegación izquierdo.

La forma más sencilla de usar el comando send, que funciona con todos los tipos de hit, consiste en pasar todos los campos con el parámetro fieldsObject. Por ejemplo:

ga('send', {
  hitType: 'event',
  eventCategory: 'Video',
  eventAction: 'play',
  eventLabel: 'cats.mp4'
});

Para que resulte más sencillo, algunos tipos de hits permiten que los campos utilizados habitualmente se pasen directamente como argumentos al comando send. Por ejemplo, el comando sendanterior con el tipo de hit "event" se podría reescribir del siguiente modo:

ga('send', 'event', 'Video', 'play', 'cats.mp4');

En la sección "Parámetros" de la referencia del método send, puedes consultar la lista completa de los campos que se pueden pasar como argumentos con los diferentes tipos de hits.

Usar un objeto de seguimiento con nombre

Si usas un objeto de seguimiento con nombre en vez del predeterminado, puedes transmitir su nombre en la cadena del comando.

El siguiente comando send se llamará en el objeto de seguimiento denominado "myTracker":

ga('myTracker.send', 'event', 'Video', 'play', 'cats.mp4');

En el propio objeto de seguimiento

Si tienes una referencia al objeto de seguimiento, puedes llamar a su método send directamente:

ga(function(tracker) {
  tracker.send('event', 'Video', 'play', 'cats.mp4');
});

Determinar cuándo se ha enviado el hit

En algunos casos, necesitas saber cuándo se ha enviado un hit a Google Analytics para poder actuar inmediatamente. Esto es habitual cuando es necesario registrar una determinada interacción que haría que un usuario abandonara la página. Muchos navegadores dejan de ejecutar JavaScript tan pronto como la página empieza a descargar, lo que significa que nunca se ejecutarán los comandos de analytics.js que envían hits.

Un ejemplo de esta situación se produce cuando se quiere enviar un evento a Google Analytics para registrar que el usuario ha hecho clic en el botón Enviar de un formulario. La mayoría de las veces, al hacer clic en el botón de envío se inicia inmediatamente la carga de la siguiente página y no se ejecutan los comandos ga('send', ...).

La solución consiste en interceptar el evento para detener la descarga de la página. A continuación, puedes enviar el hit a Google Analytics de la forma habitual y, una vez que se ha terminado de enviar, puedes volver a enviar el formulario programáticamente.

hitCallback

Para recibir una notificación cuando se envía un hit, debes configurar el campo hitCallback. hitCallback es una función que se ejecuta en cuanto el hit se ha enviado.

En el ejemplo siguiente se muestra cómo cancelar la acción de envío predeterminada de un formulario, enviar un hit a Google Analytics y, a continuación, volver a enviar el formulario con la función hitCallback:

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: function() {
      form.submit();
    }
  });
});

Gestionar los tiempos de espera

El ejemplo anterior funciona correctamente, pero tiene un problema grave. Si, por cualquier motivo, no se carga la biblioteca analytics.js, la función hitCallbacknunca se ejecutará. Y si la función hitCallback no se ejecuta, los usuarios no podrán enviar el formulario.

Cuando incluyas funciones esenciales para el sitio web en una función hitCallback, siempre debes usar una función de tiempo de espera para gestionar los casos en los que no se cargue la biblioteca analytics.js.

En el siguiente ejemplo se ha actualizado el código anterior para usar un tiempo de espera. Si transcurre un segundo después de que el usuario haga clic en el botón Enviar y no se ha ejecutado hitCallback, el formulario se vuelve a enviar.

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Creates a timeout to call `submitForm` after one second.
  setTimeout(submitForm, 1000);

  // Keeps track of whether or not the form has been submitted.
  // This prevents the form from being submitted twice in cases
  // where `hitCallback` fires normally.
  var formSubmitted = false;

  function submitForm() {
    if (!formSubmitted) {
      formSubmitted = true;
      form.submit();
    }
  }

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: submitForm
  });
});

Si utilizas el patrón anterior en muchas partes del sitio web, probablemente será más fácil crear una función de utilidad para gestionar los tiempos de espera.

En la siguiente función de utilidad se acepta una función como entrada y devuelve una nueva función. Si se llama a la función devuelta antes del periodo de espera, que es de un segundo de forma predeterminada, se anula el tiempo de espera y se invoca la función de entrada. Si no se llama a la función devuelta antes de que acabe el tiempo de espera, la función de entrada se ejecuta de todos modos.

function createFunctionWithTimeout(callback, opt_timeout) {
  var called = false;
  function fn() {
    if (!called) {
      called = true;
      callback();
    }
  }
  setTimeout(fn, opt_timeout || 1000);
  return fn;
}

Ahora puedes incluir fácilmente todas las funciones hitCallbackcon un tiempo de espera para que tu sitio web funcione del modo previsto, incluso en los casos en los que no se envíen los hits o no se cargue la biblioteca analytics.js.

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: createFunctionWithTimeout(function() {
      form.submit();
    })
  });
});

Especificar diferentes mecanismos de transferencia

De forma predeterminada, analytics.js elige el método HTTP y el mecanismo de transferencia con los que se enviarán los hits de forma óptima. Las tres opciones son 'image' (con un objeto Image), 'xhr' (con un objeto XMLHttpRequest) o 'beacon' (con el nuevo método navigator.sendBeacon).

Los dos primeros métodos tienen el problema descrito en la sección anterior (en la que los hits no se suelen enviar si la página está descargada). Por el contrario, el método navigator.sendBeacon es una nueva función HTML que se ha creado como solución a este problema.

Si los navegadores de los usuarios admiten navigator.sendBeacon, puedes especificar 'beacon' como mecanismo de transport para no tener que preocuparte de configurar una retrollamada de hits.

En el código siguiente se establece el mecanismo de transferencia con un valor de 'beacon' en los navegadores que lo admiten:

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

// Updates the tracker to use `navigator.sendBeacon` if available.
ga('set', 'transport', 'beacon');

Pasos siguientes

En ocasiones, medir determinados tipos de interacciones de usuario puede necesitar implementaciones complejas. No obstante, en muchos casos, estas implementaciones ya se han desarrollado y están disponibles como complementos de analytics.js. En la siguiente guía, se explica cómo usar los complementos de analytics.js con la cola de comandos de ga().