Tasks

This guide describes tasks, an advanced feature used to customize how analytics.js validates, constructs, and sends measurement protocol requests.

Overview

Each time the send command is called, analytics.js executes a sequence of tasks to validate, construct, and send a measurement protocol request from the user's browser to Google Analytics. The following table describes each of these tasks, in the order they are executed:

Task Name Description
customTask By default this task does nothing. Override it to provide custom behavior.
previewTask Aborts the request if the page is only being rendered to generate a 'Top Sites' thumbnail for Safari.
checkProtocolTask Aborts the request if the page protocol is not http or https.
validationTask Aborts the request if required fields are missing or invalid.
checkStorageTask Aborts the request if the tracker is configured to use cookies but the user's browser has cookies disabled.
historyImportTask Imports information from ga.js and urchin.js cookies to preserve visitor history when a site migrates to Universal Analytics.
samplerTask Samples out visitors based on the sampleRate setting for this tracker.
buildHitTask Builds a measurement protocol request string and stores it in the hitPayload field.
sendHitTask Transmits the measurement protocol request stored in the hitPayload field to Google Analytics servers.
timingTask Automatically generates a site speed timing hit based on the siteSpeedSampleRate setting for this tracker.
displayFeaturesTask Sends an additional hit if display features is enabled and a previous hit has not been sent within the timeout period set by the advertising features cookie (_gat).

Each of these tasks is implemented as a JavaScript function which takes a single model parameter as input. The model is a simple object that provides access to any of the fields defined in the Analytics.js Field Reference.

Tasks can be accessed or replaced using the standard tracker get and set methods. Using these methods, you may replace tasks with your own custom functions, or augment the existing functionality by chaining your custom functions to execute before or after an existing task.

Implementation

This section describes how to add new functionality to existing tasks, replace the built-in task functions with your own custom code, or disable a task function entirely.

Overriding a task

To override a task, you can set its value to a function that does something different. A common reason to override tasks is to stub functionality when testing your analytics.js implementations.

The following code replaces the sendHitTask with a function that logs the hit payload to the console:

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

Adding to a task

To insert new functionality you can chain your custom task function to execute before or after an existing task. In the example below, the sendHitTask is replaced with a custom task function that first calls the original sendHitTask function to send the normal request beacon to google-analytics.com/collection, then executes custom code to send a copy of the measurement protocol request to a local server.

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');

Aborting Task Processing

A task can abort the processing of subsequent tasks by throwing an exception. If the task throwing the exception executes before the sendHitTask, this has the effect of preventing the measurement protocol request from being sent to Google Analytics servers. In the example below, we abort the request whenever the user's browser contains a cookie named 'testing' with the value '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');

Disabling a Task

To disable any of the built-in task functions, replace it with null.

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