What Are customTasks and How Do You Use Them with Google Analytics?

google-analytics-tag-manager-custom-tasks.png

Using the advanced feature customTasks, you can access a model object mid-tag. This allows you to modify the payload that is dispatched to Google Analytics. In other words, you can customize how analytics.js validates, constructs, and sends measurement protocol requests. Each task is implemented as a JavaScript function with input of a single model parameter.

By using standard get and set methods, you can access tasks, replace them with custom functions, or chain custom functions to execute before or after an existing task.

Overriding Tasks

You may want to override a task to stub functionality when testing analytics.js implementation. To override a task, set the task’s value to a different function. This involves changing the sendHitTask to this code:

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

Adding to Tasks

Chaining a custom task function to execute before or after an existing task allows you to insert a new functionality. Replace the sendHitTask with a custom task function.
The following code calls the original sendHitTask function to send a normal request beacon, after which it executes the 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 Tasks

By executing an exception before the sendHitTask, you can abort the processing of subsequent tasks. This stops the sending of the measurement protocol request to Google Analytics servers. For this, you need code like the following:

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 Tasks

Finally, you can disable any built-in task functions just by replacing them with null. This requires the following code:

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

Using Google Tag Manager

In Google Tag Manager, you can access the model object mid-tag simply by adding a new “Field to Set” in the tag you want to use to send data to Google Analytics. Use the field name “customTask” and set the value to a custom JavaScript variable. Utilize the following:

function() {
 // Modify customDimensionIndex to match the index number you want to send the data to
 var customDimensionIndex = 5;
 return function(model) {
   model.set(‘dimension’ + customDimensionIndex,
model.get(‘clientId’));
 }
}

As Google Tag Manager starts executing the tag code, it will find the customTask field and resolve the variable to a closure — this is a function that receives a parameter as a model object automatically. Again, you can manipulate the model object with get and set methods.

You’ll need to set the Custom Dimension at index 5 (the value comes from the customDimensionIndex) to the ClientID. The get method of the model object is necessary to retrieve it.

This tactic is sufficient to tell the Google Analytics tag to fetch the Client ID from the tracker object. It will then send it in a Custom Dimension — there are no more setups required. Despite the fact that you are overwriting a task method with this tag, it will lead to no problems. This is because a customTask has no other function in Universal Analytics.

Try the above for any fields in the model/tracker object to access and manipulate a variety of tasks.

If you like my articles,