Enviar datos a Google Analytics

La última línea del fragmento de seguimiento JavaScript agrega el comando send a la cola de comandos de 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 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, se denomina enviar un hit, y cada hit debe tener un tipo. El fragmento de seguimiento JavaScript 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 Seguimiento de 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 actualmente y que son parámetros de Protocolo de medición válidos. Por ejemplo, se envían campos como title y location, pero no se envían cookieDomain ni hitCallback.

En algunos casos, es recomendable enviar a Google Analytics campos correspondientes al hit actual, pero no a los hits posteriores (por ejemplo, un evento donde los campos eventAction eventLabel solo son relevantes para el hit actual).

Para enviar campos solo con el hit actual, puedes pasarlos 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

El método send de un objeto de seguimiento se puede llamar directamente en dicho objeto, o agregando un comando send a la cola de comandos de ga(). Como la mayor parte del tiempo no tienes una referencia al objeto de seguimiento, usar la cola de comandos de ga() es la forma recomendada de enviar datos del objeto a Google Analytics.

Usar la cola de comandos de ga()

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

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

Tal como se ha mencionado anteriormente, los valores especificados mediante los parámetros hitType, ...fields y fieldsObject solo se envían 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 pasados con el comando send ya está configurado en el objeto de seguimiento, se utilizarán los valores pasados en el comando en vez de los guardados 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 del seguimiento de las interacciones habituales del usuario en el panel de navegación izquierdo.

La forma más sencilla de usar el comando send, que funciona para 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 cómodo, algunos tipos de hits permiten que los campos utilizados habitualmente se pasen directamente como argumentos al comando send. Por ejemplo, el comando send anterior para 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 una lista completa de los campos que se pueden pasar como argumentos para 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 pasar su nombre en la cadena del comando.

El siguiente comando send se llamada 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 directamente a su método send:

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. En la mayoría de casos, hacer clic en el botón Enviar iniciará inmediatamente la carga de la página siguiente y no se ejecutarán 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 un hit haya terminado de enviarse, debes configurar el campo hitCallback. La función hitCallback se llama tan pronto como el hit se haya 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 hitCallback nunca se ejecutará. Y si la función hitCallback nunca 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 haya 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 periodo de espera, la función de entrada se llama 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 hitCallback con un tiempo de espera para garantizar que tu sitio web funciona del modo previsto, incluso en los casos en los que no se envíen los hits o 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 transporte

De forma predeterminada, analytics.js elige el método HTTP y el mecanismo de transporte 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 compartes 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 para solucionar este problema.

Si el navegador del usuario admite navigator.sendBeacon, puedes especificar 'beacon' como el mecanismo de transporte (transport) para no tener que preocuparte de configurar una devolución de llamada de hit.

En el código siguiente se establece el mecanismo de transporte en '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().