Adding a custom dimension to Google Analytics involves several interconnected parts: the data layer, tag manager setup, and admin settings in GA. This post walks through each step of the process to show how they fit together.
Step 1: Push Values into the Data Layer
Step 2: Set up Custom Dimensions in Google Analytics Admin
Step 3: Set up Google Tag Manager Variables
Step 4: Add Dimensions to the GA Tags in GTM
Step 5: Add a Trigger to your Tag
STEP 1: PUSH VALUES INTO THE DATA LAYER
The first step is to set up the data layer. The data layer is a key part of working with Google Tag Manager. It holds information you want to process in an object that can be read by Google Tag Manager, where it then gets pushed to Google Analytics.
The data layer needs to be configured by someone with access to your site code, typically a web developer. They should add the data layer to your site's code before the GTM script, using the following syntax:
window.dataLayer = window.dataLayer || ;
'event' : 'eventName',
'dim1' : 'value1',
'dim2' : 'value2'
Simo Ahava's always-helpful blog discusses the specifics of this syntax: https://www.simoahava.com/gtm-tips/datalayer-declaration-vs-push/. Also, this post provides some examples of different data layer pushes: GTM dataLayer.push Examples (Standard, Ecommerce, Advanced)
So, if you were interested in tracking page types and login status, it would look something like this:
window.dataLayer = window.dataLayer || ;
'event' : 'pageview',
'loginStatus' : 'logged in',
'pageType' : 'product details page'
STEP 2: SET UP CUSTOM DIMENSIONS IN GOOGLE ANALYTICS ADMIN
For the next step, enter GA and go to Admin > Property > Custom Definitions > Custom Dimensions > +New Custom Dimension and fill out the name and scope for your variable. Click Create.
On the following screen, click Done and note the Index number on the summary screen. This index number is assigned automatically and we'll need it later.
STEP 3: SET UP GOOGLE TAG MANAGER VARIABLES
Next, set up Data Layer Variables in Google Tag Manager (GTM). These Variables will collect the values pushed into the data layer in step 1.
To set up these Variables, navigate in GTM to Variables > User-Defined Variables > New > Variable Configuration > Choose variable type = Data Layer Variable. Enter in the name of the data layer variable to read from, making sure the name you use here exactly matches the name used in the data layer.
STEP 4: ADD DIMENSIONS TO THE GA TAGS IN GTM
The fourth step is sending the dimension value to GA. To send these values, dimensions need to be attached to other hits like pageviews, events, or ecommerce.
In GTM, find the tag you want to attach the dimensions to. Usually this will be the GA page view tag, but other hit types will work exactly the same way. Click the "Enable overriding settings in this tag " checkbox > More Settings > Custom Dimensions. (Or, alternately, you can set up these custom dimensions in the Google Analytics Settings Variable).
In the Index slot, use the same index number as assigned in GA Admin in step 2. Under Dimension Value, add add the new Variable you created in step 3.
STEP 5: ADD A TRIGGER TO YOUR TAG
As described above, all custom dimensions need to be attached to a tag.
Every tag needs a trigger to fire, so in this step make sure you've chosen the right trigger. Specifically, you need to choose one that doesn't fire too soon. For example, if you're tracking page-related dimensions like page categories, those values need to be ready and available when the page view tag fires. The data layer push often occurs after the initial page load, so if you choose All Pages as your trigger, the values would still be null at the time the tag fired, resulting in page category values of "(not set)" in Google Analytics.
The best way to avoid this problem is to create a Custom Event Trigger for your data layer event key (in the example in step 1, it would be 'pageview'), like this:
Then, use that trigger to fire your Pageview tag, like this:
This way will ensure that the Pageview tag fires only after your dimensions are pushed into data layer.
(If you don't have an event key in your data layer push, you can alternately choose a delayed page view trigger like DOM Ready. However it's better to use a Custom Event Trigger since it fires your tag more quickly).
Following these 5 steps will enable you to populate custom dimensions in Google Analytics via the data layer and Google Tag Manager. Once these dimensions are collecting data, you can view these dimensions as a Secondary Dimension in any regular report, or create a custom report using your new dimension as a primary dimension.