Add Client ID to Custom Dimension With Gtag.js

When Google released gtag.js, the new, global tracking library designed to (eventually) replace analytics.js, many Universal Analytics practitioners and users were confused (see e.g. Jeff’s great overview here). It seemed like gtag.js wasn’t really solving any immediate problem, since analytics.js had done a bang-up job with Universal Analytics tracking for all these years. However, gtag’s modus operandi is the ability to leverage the same semantic information (distributed across dataLayer!) across a number of Google products, starting with GA and AdWords.

But migrating to gtag.js isn’t just a find-and-replace operation - there are many things to consider due to the fact that they are completely different tracking libraries, and feature parity is yet to be reached.

One of the things I was really concerned about was how to add my favorite custom dimension to the hits: the Client ID stored in the _ga cookie. With gtag.js, this is actually ridiculously easy, and you don’t need to leverage customTask or the ga.getAll() tracker method (which still does exist when using gtag.js!).

Huge thanks to Yamata Ryoda for pointing this method out. You can read the original tip (in Japanese) here.

How to add Client ID to a custom dimension with gtag.js

So after the long preamble here’s the tip in all its glory:

gtag('config', 'UA-12345-1', {
  'custom_map': {
    'dimensionX': 'clientId'
  }
});

Just replace UA-12345-1 with your Universal Analytics tracking ID, and the X in dimensionX with the custom dimension index, and gtag.js takes care of the rest.

Such a simple way to do it. My main gripe right now is that this isn’t officially documented, and we don’t know what other “special” values gtag.js hides under its hood. And what if I wanted to send the string “clientId” to GA as the value of that custom dimension? Hmm. Might not be that common.

Summary

So there is a really easy way to add the Client ID to a custom dimension when using gtag.js. It’s so easy, in fact, that you should do it right now. Sending the Client ID to Google Analytics is almost necessary in order to see reports distributed row-by-row, where each row is a distinct Google Analytics user. You only get this otherwise in the User Explorer reports.