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