Tareas

En esta guía se describe la función avanzada de tareas, que permite personalizar cómo analytics.js valida, crea y envía solicitudes de Measurement Protocol.

Descripción general

Cada vez que se hace una llamada al comando send, analytics.js ejecuta una secuencia de tareas para validar, crear y enviar una solicitud de Measurement Protocol desde el navegador del usuario a Google Analytics. En esta tabla se describen las tareas por orden de ejecución:

Nombre de la tarea	Descripción
customTask	De forma predeterminada, esta tarea no realiza ninguna acción. Anúlala para enviar el comportamiento del cliente.
previewTask	Anula la solicitud si la página solo se muestra para generar una miniatura de los mejores sitios web en Safari.
checkProtocolTask	Anula la solicitud si el protocolo de la página no es ni http ni https.
validationTask	Anula la solicitud si faltan campos obligatorios o no son válidos.
checkStorageTask	Anula la solicitud si el objeto de seguimiento se configura para usar cookies, pero el navegador del usuario tiene las cookies inhabilitadas.
historyImportTask	Importa información de las cookies de ga.js y urchin.js para conservar el historial del visitante cuando un sitio migra a Universal Analytics.
samplerTask	Muestrea las visitas según el valor que se haya asignado a sampleRate en este objeto de seguimiento.
buildHitTask	Crea una cadena de solicitud de Protocolo de medición y la almacena en el campo hitPayload.
sendHitTask	Envía la solicitud de Protocolo de medición almacenada en el campo hitPayload a los servidores de Google Analytics.
timingTask	Genera automáticamente un hit de tiempos de velocidad de sitio basado en el valor que se haya asignado a siteSpeedSampleRate en este objeto de seguimiento.
displayFeaturesTask	Envía un hit adicional si las funciones de display están habilitadas y no se ha enviado un hit anterior dentro del tiempo de espera que define la cookie de Funciones publicitarias (_gat).

Cada una de estas tareas se implementa como una función de JavaScript que usa un parámetro de modelo único como dato de entrada. El modelo es un objeto simple que ofrece acceso a cualquiera de los campos definidos en la referencia de campos de Analytics.js.

Se puede acceder a las tareas o sustituirlas mediante los métodos de objeto de seguimiento estándar get y set. Con estos métodos, puedes sustituir tareas con tus propias funciones personalizadas o ampliar la funcionalidad actual encadenando funciones personalizadas para que se ejecuten antes o después de una tarea que ya tienes.

Implementación

En esta sección se describe cómo añadir nuevas funciones a tareas, cómo sustituir las funciones integradas en las tareas con código personalizado y cómo inhabilitar una función de tarea completamente.

Anular una tarea

Para anular una tarea, puedes asignarle un valor correspondiente a una función distinta mediante set. Esto se suele hacer para sustituir una función por otra al probar implementaciones de analytics.js.

En el código siguiente, sendHitTask se sustituye por una función que registra la carga útil del hit en la consola:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'sendHitTask', function(model) {
  console.log(model.get('hitPayload'));
});

Nota: La biblioteca autotrack usa esta técnica para probar sus complementos. Por ejemplo, la prueba eventTracker anula la tarea sendHitTask y la sustituye por código que comprueba si se han definido los campos de evento pertinentes.

Añadir funciones a una tarea

Si quieres insertar nuevas funciones, puedes encadenar la función de tarea personalizada para que se ejecute antes o después de una tarea. En el ejemplo que se muestra a continuación, sendHitTask se reemplaza por una función de tarea personalizada que primero hace una llamada a la función sendHitTask original para enviar el beacon de solicitud normal a google-analytics.com/collection. A continuación, se ejecuta el código personalizado para enviar una copia de la solicitud de Measurement Protocol a un servidor local.

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

ga(function(tracker) {

  // Grab a reference to the default sendHitTask function.
  var originalSendHitTask = tracker.get('sendHitTask');

  // Modifies sendHitTask to send a copy of the request to a local server after
  // sending the normal request to www.google-analytics.com/collect.
  tracker.set('sendHitTask', function(model) {
    originalSendHitTask(model);
    var xhr = new XMLHttpRequest();
    xhr.open('POST', '/localhits', true);
    xhr.send(model.get('hitPayload'));
  });
});

ga('send', 'pageview');

Anular el procesamiento de una tarea

Una tarea puede anular el procesamiento de las tareas posteriores arrojando una excepción. Cuando la tarea que genera una excepción se ejecuta antes de sendHitTask, se hace para evitar que la solicitud de Measurement Protocol se envíe a los servidores de Google Analytics. En el siguiente ejemplo, se anulará la solicitud cada vez que el navegador del usuario contenga una cookie llamada "testing" con el valor "true".

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

ga(function(tracker) {
  var originalBuildHitTask = tracker.get('buildHitTask');
  tracker.set('buildHitTask', function(model) {
    if (document.cookie.match(/testing=true/)) {
      throw 'Aborted tracking for test user.';
    }
    originalBuildHitTask(model);
  });
});

ga('send', 'pageview');

Inhabilitar una tarea

Para inhabilitar las funciones integradas en las tareas, solo tienes que reemplazarlas por "null".

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'checkProtocolTask', null); // Disables file protocol checking.
ga('send', 'pageview');