{"id":109975,"date":"2025-02-25T22:37:34","date_gmt":"2025-02-25T22:37:34","guid":{"rendered":"https:\/\/peraltafinancing.com\/analytics\/customtask-the-guide-simo-ahavas-blog\/"},"modified":"2025-02-25T22:37:34","modified_gmt":"2025-02-25T22:37:34","slug":"customtask-the-guide-simo-ahavas-blog","status":"publish","type":"post","link":"https:\/\/fivemor.com\/?p=109975","title":{"rendered":"customTask – The Guide | Simo Ahava’s blog"},"content":{"rendered":"


\n<\/p>\n

\n

Last updated 4 September 2018<\/em><\/p>\n

If you have been reading my blog articles over the past year, you might have noticed a disturbing trend. I\u2019ve published 9 articles on customTask<\/code><\/a> since the API was released. It might not sound like much, but I can\u2019t think of a single feature in Google Analytics<\/a> or Google Tag Manager<\/a> that has so completely convinced me of its usefulness in such a short time.<\/p>\n

The customTask<\/code> API is a feature of the Universal Analytics library<\/a> (used by Google Tag Manager\u2019s tags, too). It lets you get<\/code> and set<\/code> values from and to the (Measurement Protocol) hit as it\u2019s being generated. This is really useful for a couple of reasons, which I\u2019ve covered in the previous articles, but I\u2019ll go over them briefly in the beginning of this guide, too.<\/p>\n

\n

<\/p>\n

\"customTask<\/p>\n

<\/a><\/p>\n<\/div>\n

Suffice to say that especially for Google Tag Manager, customTask<\/code> adds a lot of value. With GTM, it\u2019s always been quite difficult to access the hit-building process when using tag templates. Luckily, customTask<\/code> offers a solution to this problem, and at least for this particular developer it\u2019s opened a whole new world of Google Analytics customization.<\/p>\n

However, in spite of writing all those articles on customTask<\/code>, I recently realized that I never actually took the time to explain more thoroughly how it works. Also, I haven\u2019t yet shared solutions for combining multiple customTask<\/code> tricks in a single tag. This guide seeks to address these points.<\/p>\n

\n

Be sure to check out my customTask Builder<\/a> tool as well – it will help you compile the necessary JavaScript for customTask<\/code> to run in your setup without conflicts!<\/p>\n<\/blockquote>\n


\n X<\/span><\/p>\n

\n
\n The Simmer Newsletter<\/strong>\n <\/p>\n

\n Subscribe to the Simmer newsletter<\/a> to get the latest news and content from Simo Ahava into your email inbox!\n <\/p>\n

<\/span><\/p>\n

How Tasks work<\/h2>\n

When you run the ga('send', 'pageview')<\/code> command either directly in your site JavaScript or indirectly via Google Tag Manager\u2019s Google Analytics tags, you actually request that the Universal Analytics JavaScript library (analytics.js) compile an HTTP request to the Google Analytics servers.<\/p>\n

The endpoint to which the hits are sent is typically \/collect<\/code> on the Google Analytics collector domain. The process of building and sending hits to the GA servers is also known as Measurement Protocol<\/strong> (MP). In fact, MP is the underlying process used by all<\/strong> GA tracking mechanisms, be they the ga('send'...)<\/code> JavaScript SDK, Google Tag Manager\u2019s GA tags, native SDKs for Android and iOS, and custom-built HTTP requests from point-of-sales systems, for example.<\/p>\n

\n

<\/p>\n

\"Tracker<\/p>\n

<\/a><\/p>\n<\/div>\n

When you use the JavaScript SDK, either via ga('send', 'pageview')<\/code> or the Google Analytics tags in GTM, you are thus initiating a sequence of processes, where the final product is the actual MP request to Google Analytics. This sequence comprises a number of tasks<\/strong><\/a>, of which customTask<\/code> is the first one that is executed.<\/p>\n

Here\u2019s a quick recap of what each task does, listed in the order they are applied to the hit.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Task<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
customTask<\/strong><\/td>\nNo functionality of its own, but can be used to manipulate the model<\/code> object before it is processed by the other tasks.<\/td>\n<\/tr>\n
previewTask<\/strong><\/td>\nIf the request is generated from the pageview of a \u201cTop Sites\u201d thumbnail in Safari, abort the hit.<\/td>\n<\/tr>\n
checkProtocolTask<\/strong><\/td>\nAborts the request if the page protocol is not valid (http<\/strong> or https<\/strong>).<\/td>\n<\/tr>\n
validationTask<\/strong><\/td>\nChecks if the fields in the request have valid and expected values. Aborts the request if this is not the case (e.g. trying to send a string as the Event Value).<\/td>\n<\/tr>\n
historyImportTask<\/strong><\/td>\nIf there is still legacy tracking running on the site, this task imports information from the old GA library cookies into Universal Analytics. Very useful if the site is migrating to Universal Analytics.<\/td>\n<\/tr>\n
samplerTask<\/strong><\/td>\nIf you\u2019ve decided to manually sample<\/a> the users to stay within Google Analytics\u2019 processing limits, this task aborts the request if the user is sampled out of data collection.<\/td>\n<\/tr>\n
buildHitTask<\/strong><\/td>\nGenerates the hitPayload<\/code> string, which is essentially the list of query parameters and their values passed to the Measurement Protocol request.<\/td>\n<\/tr>\n
sendHitTask<\/strong><\/td>\nSends the hitPayload<\/code> in a Measurement Protocol request to the GA servers.<\/td>\n<\/tr>\n
timingTask<\/strong><\/td>\nIf you are automatically sampling pages for page speed measurements, this task sends the timing hit to Google Analytics.<\/td>\n<\/tr>\n
displayFeaturesTask<\/strong><\/td>\nIf you have enabled display features in GA settings, this task compiles the request to the DoubleClick servers.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Each tasks receives the model<\/code> object as a parameter. The model<\/code> object contains all the fields that have been set in the tracker, as well as any enhancements applied in the tasks themselves.<\/p>\n

The beauty of customTask<\/code> is that because it runs before any of the other tasks, you can use it to overwrite behavior of these other tasks. For example, if you want to run Google Analytics locally or in a Chrome Extension<\/a>, you\u2019ll need to make sure checkProtocolTask<\/code> is never run, because it aborts the hit builder if the page protocol is not http<\/strong> or https<\/strong>. The customTask<\/code> would look like this:<\/p>\n

\n
var<\/span> customTask = function<\/span>(model) {\n  \/\/ Prevent checkProtocolTask from running\n<\/span>  model.set('checkProtocolTask'<\/span>, null<\/span>);\n};\n<\/code><\/pre>\n<\/div>\n
As you can see, the task is actually a field in the model<\/code> object that you can manipulate just as you can manipulate any other field in the model<\/code>. For example, if you want to grab the tracking ID (UA-XXXXXX-Y) and send it in the Custom Dimension with index 15, you can use the following customTask<\/code>:<\/p>\n
\n
var<\/span> customTask = function<\/span>(model) {\n  \/\/ Get the tracking ID from the model object\n<\/span>  var<\/span> trackingId = model.get('trackingId'<\/span>);\n  \n  \/\/ Set the tracking ID to Custom Dimension 15\n<\/span>  model.set('dimension15'<\/span>, trackingId);\n};\n<\/code><\/pre>\n<\/div>\n
By running these model<\/code> interactions with customTask<\/code>, you have a lot of control over how the task sequence is run. Especially with Google Tag Manager, it would be difficult to run any complicated logic for when and how to manipulate sendHitTask<\/code>, if you applied it directly to the tag as a field.<\/p>\n
How to add customTask<\/code> to your hits<\/h2>\n
To add customTask<\/code> to your Google Tag Manager<\/strong> tags, you need to create a Custom JavaScript variable which returns the customTask<\/code> method in the variable body. Practically all my customTask<\/code> articles show examples of what this Custom JavaScript variable looks like.<\/p>\n
When you are ready to add the variable to your tags, you can do it either via a Google Analytics Settings variable (recommended)<\/a>, or by overriding the tag settings<\/a> directly.<\/p>\n
You need to scroll down to Fields to set<\/strong>, and add a new field which looks like this:<\/p>\n
\n
    <\/p>\n
    \"Set<\/p>\n
    <\/a><\/p>\n<\/div>\n
If using the on-page Universal Analytics (analytics.js) snippet, you add the customTask<\/code> like this, for example:<\/p>\n
\n
var<\/span> _customTask = function<\/span>() {\n  \/\/ Set Client ID to Custom Dimension 199\n<\/span>  return<\/span> function<\/span>(customTaskModel) {\n    customTaskModel.set('dimension199'<\/span>, customTaskModel.get('clientId'<\/span>));\n  };\n};\n\nga('create'<\/span>, 'UA-12345-1'<\/span>);\nga('set'<\/span>, 'customTask'<\/span>, _customTask());\nga('send'<\/span>, 'pageview'<\/span>);\n<\/code><\/pre>\n<\/div>\n
Do note that you can only set one customTask<\/code> per tracker \/ hit \/ tag<\/strong>. If you want to add more than one \u201ctrick\u201d to the customTask<\/code> function, you need to write the JavaScript that combines all the different solutions into one coherent whole.<\/p>\n
Things you can do with customTask<\/code><\/h2>\n
As written above, customTask<\/code> is special for two reasons.<\/p>\n
    \n
  1. \n
    It has no special functionality of its own. A task queue can and will run perfectly without customTask<\/code> defined.<\/p>\n<\/li>\n
  2. \n
    It runs before any other task, meaning you have full control over how the queue is processed.<\/p>\n<\/li>\n<\/ol>\n
    With these two things in mind, here\u2019s the list of all the customTask<\/code> tricks I\u2019ve written about, with a description of what makes them special.<\/p>\n
    1. Set Client ID as a Custom Dimension<\/h3>\n
    Link to article: #GTMTips: Use customTask To Access Tracker Values In Google Tag Manager<\/a>.<\/p>\n
    This is one of the simpler tricks. It doesn\u2019t manipulate the task queue itself at all, it simply gets<\/em> the Client ID from the model object, and then sets<\/em> it as the value of the specified Custom Dimension.<\/p>\n
    It\u2019s an elegant solution to a difficult problem. Without customTask<\/code>, getting and setting the Client ID in a Google Analytics tag was difficult. If the tag is run for a first-time visitor who hasn\u2019t received a Client ID yet, the actual clientId<\/code> field is not available when the regular tag fields are resolved. A typical hack for this solution was to fetch the Client ID by creating a dummy tracker<\/a> or by sending the Client ID with an Event tag that fired after the Pageview.<\/p>\n
    But with customTask<\/code>, there\u2019s no need for such unorthodox methods.<\/p>\n
    2. Duplicate Google Analytics tags to more than one property<\/h3>\n
    Link to article: #GTMTips: Send Google Analytics Tag To Multiple Properties<\/a>.<\/p>\n
    This is customTask<\/code> at its purest. The customTask<\/code> function first stores a reference to sendHitTask<\/code> in a global variable, after which it overwrites sendHitTask<\/code> in the current model object with the duplicator code.<\/p>\n
    The duplicator first lets the original hit fire to GA, after which it replaces the Tracking ID in the hitPayload<\/code> with the Tracking ID of the second property. Then, the global sendHitTask<\/code> is invoked again, and the hit is sent to the second property with an identical payload.<\/p>\n
    Note!<\/strong> The reason the reference to sendHitTask<\/code> is stored in a global variable is to avoid issues with field multiplication. Let\u2019s say you always use this to get the original sendHitTask<\/code> reference:<\/p>\n
    var originalSendTask = model.get('sendHitTask');<\/code><\/p>\n
    Each time this customTask<\/code> code is run, it will get a reference to what is stored in the model object\u2019s sendHitTask<\/code>. Unfortunately, when building standard Ecommerce hits, or when automatically sampling timing hits, the tag is automatically sent more than once. Thus the reference to the original sendHitTask<\/code> is recursively augmented with each iteration of model.set('sendHitTask');<\/code>, resulting in code being executed erratically.<\/p>\n
    By having a global variable store the reference to the original sendHitTask<\/code>, this recursive problem is avoided.<\/p>\n
    3. Track offline users in Google Analytics<\/h3>\n
    Link to article: Track Users Who Are Offline In Google Analytics<\/a>.<\/p>\n
    This is all David Vallejo<\/a>. His solution tackles the problem of lost internet connectivity and hits that are aborted because of this. It uses customTask<\/code> to check if the user is offline, and if they are, the hits are stored in a batch queue. Once connectivity is restored, the queue is processed, and the hits are finally sent to GA.<\/p>\n
    4. Remove PII from GA payloads<\/h3>\n
    Link to article: #GTMTips: Remove PII From Google Analytics Hits<\/a>.<\/p>\n
    With GDPR coming soon, covering all your bases with regard to private data is a good idea. Fixing potential PII leaks before they hit Google Analytics servers is a good method as any to make sure you\u2019re complying with Google Analytics\u2019 Terms of Service as well as the increasingly stricter regulations for sending and collecting personal data.<\/p>\n
    \n
        <\/p>\n
        \"Redacted<\/p>\n
        <\/a><\/p>\n<\/div>\n
    Here, customTask<\/code> takes the hit payload before it is sent to GA, and purges it of all matches against any given regular expressions. These regular expressions can be built to match things like email addresses and social security numbers.<\/p>\n
    5. Fix site speed sampling messing with your Custom Metrics<\/h3>\n
    Link to article: Prevent Site Speed Sampling Rate From Skewing Custom Dimensions And Custom Metrics<\/a>.<\/p>\n
    This is a fairly simple trick, but it fixes a potential issue with Custom Metric data being skewed by the automatically collected page timing hits. The issue is that the timing hit copies all parameters from the Page View tag that is being sampled, and thus any Custom Dimensions and Custom Metrics are sent more than once, too.<\/p>\n
    Here, customTask<\/code> is attached to the Page View tag, where it checks if the hit type is timing<\/code> (due to the automatically generated timing hit), and if it is, it removes all references to Custom Dimensions and Metrics from the request.<\/p>\n
    6. Respect opt-out<\/h3>\n
    Link to article: #GTMTips: Respect Opt-Out From Advertising And Analytics<\/a>.<\/p>\n
    A simple trick, again. This time customTask<\/code> checks if the user has specific opt-out settings in the browser, and if they do, it aborts the requests to Google Analytics and DoubleClick. You\u2019ll need to manually create the setting itself, be it a pop-up that stores the opt-out in a browser cookie or something, but once you\u2019ve done it, this solution makes it easy to enact the opt-out programmatically.<\/p>\n
    7. Send details about Optimize experiments to Google Analytics<\/h3>\n
    Link to article: Send Event And Custom Dimension If Google Optimize Experiment Is Running<\/a>.<\/p>\n
    This trick tackles an issue with how Google Optimize data is being reported in Google Analytics. Basically, the Experiment Name and Experiment ID dimensions are scoped to the user for the duration of the experiment. Thus it\u2019s not possible to get a segment of the actual sessions when the user was actively participating in an experiment page.<\/p>\n
    The customTask<\/code> checks for certain features of the Page View tag it is attached to, and if these features are found, it updates a Custom Dimension in the hit payload with details about the experiment. You can then segment your GA data with these Custom Dimensions to see sessions where the user was actually active on an experiment page.<\/p>\n
Or, you can use my customTask Builder tool<\/strong><\/a>, which does the dirty work for you.<\/p>\n
To see what fields are available in the model object, check this developer documentation<\/a>. Note that it\u2019s not complete, since it\u2019s missing all the tasks.<\/p>\n