Utility Custom Dimensions in GTM

Subscribe to our monthly newsletter to get the latest updates in your inbox

Custom dimensions are one of the most useful and powerful features of Google Analytics (GA) because they allow you to pass custom data directly into the platform for use in day-to-day analysis. And the type of data you can send to GA via custom dimensions is virtually limitless. From page-level data to information about users and their journeys, if you have access to something, it can almost always be passed as a custom dimension. But there's another side to custom dimensions that's frequently overlooked. GA users often think of them as fields only used for data about site user behavior or experience; and while that’s true, they can also be used for more detailed information for in-depth troubleshooting and analysis, particularly if you're using Google Tag Manager (GTM). We like to call these, “utility custom dimensions,” and they're one of the ways we can fully leverage the capabilities of GTM. There are two main categories of utility custom dimensions that we’ll discuss here: those related to the function of GTM itself and those related to more detailed review of users and their time on your site. You might not use all of these dimensions every day, but when you need them they can be extremely useful, and as a result we recommend configuring all of those listed here if your data model and GA dimension limits will accommodate them. Below is a summary of each of the core utility custom dimensions, including a description of what they capture and some information about situations in which that data can be useful. The included images provide examples of how the base variables can be configured, and from there they can be set or referenced in tag custom dimension fields per your preferred conventions. For the purposes of this post, we're also going to assume that you have some familiarity with GTM, and at least have a cursory understanding of different variable types and the concept/process of setting custom dimension indexes and values on tags. If not, we have some other great resources to check out for a quick refresher.

GTM System Dimensions

The dimensions in this section deal specifically with GTM itself. They can help you understand what containers/versions hits are coming to GA from, as well as understanding what portions of your container may be inactive or broken. This handful of custom dimensions helps serve as the missing link while you perform tracking investigations in GA.  

Container ID - (hit-scoped)

Container ID is a wonderfully simple dimension that can remove a great deal of headache while troubleshooting in GA. It allows you to check which GTM container is sending hits to your GA property and determine if there are any extraneous containers piping traffic into analytics.

Configuration for this a breeze. Container ID is a built-in GTM variable that, once enabled, can be used or referenced for the custom dimension value in GTM.


Container Version - (hit-scoped)

Along with Container ID, Container Version as a dimension will let you see all of the versions sending data into GA. Sometimes you might get hits you don't expect or thought you removed in a recent publish, and Container Version lets you see not only which container they're originating from but also which version of the container sent the hit.

As with Container ID, Container Version is a built-in GTM variable that can be used as your custom dimension value.


Tag Name - (hit-scoped)

The Tag Name custom dimension is probably the best way to not only understand where which GA tags the hits you see in GA are coming from but also learn which tags may be broken or legacy. From investigation to container cleanup, Tag Name is a dimension we always recommend as it can help keep close track of the intermediate data collection step that GTM manages. The dimension is hit-scoped and specific to your GA tags (events and pageviews), and should be sent with each of them. The result will be that when any hit gets sent to GA, it will include information about which GTM tag sent that hit.

When it comes to configuration, this one might require just a bit of leg work. Since you generate your tag names, and GTM can't self-reference those via its own logic, you'll need to manually add the name dimension to each tag by typing it in the custom dimension value field. You'll want to make sure this matches exactly and that any updates to tag naming are followed by an update to the dimension value. But in our experience, this little bit of extra work is absolutely worth it.


User Tracking Dimensions

This set of dimensions we're about to cover deals more with detailed aspects of a user's journey on your site. Whereas the GTM dimensions give you information about the container and its tags, these help provide some more detailed information to stitch together users and their sessions for the purpose of deep analysis, reporting flexibility, and investigation of tracking issues.  

User Agent (session-scoped)

The user agent is a global variable in the browser containing a single string that holds information about the browser and operating system. While it's not always the most reliable field, it contains a great deal of information that you can use that you wouldn't have the same access to via the built-in GA dimensions. And if you're feeling ambitious, you can even work to parse out specific elements of the user agent to be able to pass to other places and parties via GTM.

One thing you might be wondering is why this dimension is recommended to be set as session-scoped.

Since this is a global variable in the browser, GTM configuration is fairly straightforward. You'll use a "JavaScript Variable" variable type, the name for which will be "navigator.userAgent".


User Timezone Timestamp (session-scoped)

Timezone Timestamp is one of two dimensions that can be very helpful for enhancing your ability to understand user behavior trends. Built-in, geo-specific dimensions in GA are excellent, but in many cases you might care about really understanding time of day that users are visiting the site in addition to the location. Since each GA view has a set timezone that it applies, knowing the true timezones of your traffic can be very helpful.

Much like User Agent, this dimension should be session-scoped. Even though it is unlikely that the majority of users will change timezones across their sessions, there are certainly some people who will visit your site from multiple places around the country or world, and you want to allow for that.

To configure in GTM, add a "Custom JavaScript" variable per the example below. The value returned by this variable will consist of a full timestamp including date, time, and timezone for the session.

  function() {
    var now = new Date();
    return now;

User Timezone Offset (session-scoped)

Along with the timezone timestamp, timezone offset is a way to break down where sessions are originating from, represented as the difference between UTC and local time. Once again, configuration is a Custom JavaScript GTM variable that pulls timezone offset from the browser and returns it.

function() {
    var d = new Date();
    var offSet = d.getTimezoneOffset()/60;
    return offSet;

Client ID (user-scoped)

The Client ID is the value of a cookie set by GA that allows it to track users. Even though GA’s user metric and tracking are based entirely around the Client ID, aside from the User Explorer report, there’s no built-in way to pull in that value as a dimension in reporting. With this information available to you separately, you can look at actions of specific users via segments, etc. or pass it elsewhere if necessary.

This is set up by creating a "Custom JavaScript" GTM variable and populating it with the script below. Even though this variable looks like one of the more complex of those we're discussing here, the script itself is still very straightforward and is reading and returning the value of the GA cookie that contains the Client ID.

function() {

       var _gaCookie = 0;

    if (_gaCookie && /GA[0-9]\.[0-9]\.[0-9]+\.[0-9]+$/.test(_gaCookie)) {

       return _gaCookie.match(/GA[0-9]\.[0-9]\.(.*)$/)[1];

    } else {
       ga(function() {
            var trackers = ga.getAll();
            if (trackers && trackers[0]) {
                return trackers[0].get('clientId');

            return undefined;


Client ID (hit-scoped)

Yes, you read that correctly; there are two Client ID dimensions we generally recommend. The first reason this Client ID dimension can be valuable is for the same reason as the user-scoped version: it gives you access to pull in the Client ID as a dimension where you otherwise wouldn't be able to. The second (and main) reason is that it allows you to avoid the issues of dimension scope when doing detailed troubleshooting. Having the Client ID as a value on every hit allows you to see it in rows with other hit-scoped dimensions and understand if it were ever to change for a user.

The hit-scoped version and the user-scoped versions should use or reference the exact same variable in GTM, the only difference is on the GA processing side.


Responsive Breakpoint (hit-scoped)

Responsive breakpoints are essentially thresholds for changing the layout of a site when the browser window has certain dimensions. This is another piece of custom data that can be used as an enhancement to built-in GA information related to mobile vs. desktop traffic.

This is set up by creating a "Custom JavaScript" GTM variable and populating it with the script below. Once the variables in the script are updated to match your site's specific breakpoints, the script will test against them and return a device category based on the browser's dimensions.

function() {

  var desktopBreakpoint = 1004; //update with site specific breakpoint
  var tabletBreakpoint = 756; //update with site specific breakpoint

  function getResolution(desktopWidth, tabletWidth) {
      //breakpoints are based upon experimenting with the site
      if (window.innerWidth > desktopWidth) {
        return 'desktop';
      else if (window.innerWidth > tabletWidth) {
          return 'tablet';
      else {
          return 'mobile';

      return undefined;

  return getResolution(desktopBreakpoint, tabletBreakpoint);

Session ID (session-scoped)

In many ways, Session ID is the last gap to fill when it comes to proper scoping for thorough investigation in GA. The user-scoped version of Client ID serves as a way that we can identify lifespans of specific users for testing and troubleshooting. Hits themselves don't contain anything else from a scoping standpoint, so we can identify them from their own contents. But sessions are the missing piece. The Session ID dimension allows for grouping hits together that occurred within a session, or to investigate a suspected issue with certain sessions as a whole. For example, when you publish GTM, you might suspect that certain sessions are coming in via cached versions of GTM. Well, you can use the Container ID/Version we covered before in conjunction with this Session ID dimension in GA to be able to isolate that issue.

The configuration for this one is deceptively simple. It can be set up by creating a "Custom JavaScript" GTM variable and populating it with the script below. We're simply creating a semi-random string to assign as the Session ID. Much like the Client ID, this doesn't have to be particularly meaningful or human-readable, it just needs to be unique for each session and serve as a key that we can use to follow any particular session in GA.

function() {
  return new Date().getTime() + '.' + Math.random().toString(36).substring(5);

Hit Referrer

And last but not least, we've already written a post dedicated to the Hit Referrer dimension a while back, but we'd be remiss if we didn't include it in this list. Right now you might be thinking, "But there's already a Full Referrer dimension in GA," and you'd be correct. But that dimension is scoped to the session, so you'll mostly see entries that are reminiscent of the Source dimension in GA. Hit Referrer allows you to understand navigation and user pathing in ways that the built-in dimensions can't, and it also helps identify any pages that might not have tracking code in place.

Configuration for this is a breeze. Referrer is another built-in variable in GTM that you can directly reference or use in the custom dimension value field on your tags (or GA settings variable).

    We hope you've enjoyed this overview of our favorite utility custom dimensions in GTM. We see these come in handy for analysis and deep GA investigation on a regular basis, and we encourage you to try out as many as you can and see what you think. Even if they're not used for your everyday reports, many of them are extremely helpful when you think something might be amiss and want to uncover why. And, of course, we'd always love to hear about other utility custom dimensions you use and find helpful!