Cardinal Path’s response to COVID-19 Cardinal Path is sharing all we know to help marketers during COVID-19.  Learn more.

Whether you’re a marketer or an analyst, you probably want to get more out of your analytics data. Custom Dimensions allow you to record data about your pages, screens, users, and user experience that Google Analytics would not capture by default.

In this post, you’ll learn what Custom Dimensions are and how to set them up in Google Analytics and Google Tag Manager.

You’ve Already Done the Hard Part (i.e., Taxonomy)

The procedures for pulling Custom Dimension data into GA are fairly straightforward, as outlined below. The hard work that you have probably already completed is your taxonomy: classifications about your pages, your products, and your customers. Make sure to take those few extra steps to incorporate your taxonomies into GA. Your reporting will provide better insights and actionability and keep more people in your organization engaged overall.

Custom Dimension Examples

Extra Information About Your Pages: Author

Author is an example of one custom dimension we use on When a visitor views a page on our blog, the name of the author that is on the page is sent to Google Analytics and stored in the custom dimension called Author. This value would not be tracked by default. We configured this custom dimension and now we can send the name of each author to GA and use this dimension in a custom report to analyze certain metrics by author like Pageviews, Unique Pageviews and Average Time on Page as shown in Figure 1. Custom dimensions are just like the predefined dimensions in GA, except you get to define what they are and choose the values yourself.

Figure 1. If we capture Author as a Custom Dimension, we can create a custom report with Author as the primary dimension.

Insight and action: Asmaa’s posts are generating the highest Average Time on Page. Ask Asmaa to write more!

Extra Information About Your Users: Loyalty Level

If your organization has taken the initiative to create a user classification, such as loyalty level, it is incumbent upon us – as Google Analytics implementers and analysts respectively – to capture this data as a Custom Dimension and to use it in our reporting, as illustrated in Figure 2.

Figure 2. A Customer Loyalty dimension used in a custom report.

Insight and action: User’s with the gold customer level, not platinum, are demonstrating the highest Ecommerce Conversion Rate. Perhaps put more effort in moving your customer from silver to gold than from gold to platinum.


When capturing custom dimensions, make sure to avoid any personally identifiable information. It’s acceptable to merge Google Analytics data with PII data (such as CRM) outside in another platform (such as BigQuery), but the Google Analytics terms of service still clearly prohibit any PII within Google Analytics itself.

Extra Information About Your Users and Sessions: Loyalty Level

As one example of a Custom Dimension about your user sessions, let’s say that you’re a publisher who monetizes pageviews or screen views through CPC or CPM advertising and you have integrated your DoubleClick for Publisher (DFP) data into Google Analytics 360.

The Publisher Pages report will very helpfully indicate advertising performance for each page, but why limit yourself to just predefined dimensions? If you capturing a Login Status dimension for each session in which a login occurs, you’ll also be able to view advertising performance based on the login state of your users as in Figure 3.

Figure 3: DoubleClick for Publisher metric by logged-in and logged-out users.

Insight and action: Logged-in users are generating greater revenue per session for you as a publisher. Encourage signups and logins.

Extra Information About Your Products: Color

When you’re sending Basic or Enhanced Ecommerce data to Google Analytics, you can take advantage of product-scoped custom dimensions to provide descriptors – such as color, size, brand, manufacturer, or any other product variation – that go beyond the predefined Google Analytics ecommerce dimensions.

Figure 4 below displays a custom report defined with a Color Custom Dimension as the primary dimension. By taking advantage of the Plot Rows feature in the Google Analytics UI, we note a spike in Product Revenue for blue clothing in May.

Figure 4: With Color recorded as a product-scoped custom dimension, we’re able to create a custom report that shows an unexpected spike for sales of navy blue clothing in May.

Insight and action: Align marketing and merchandising for next May to take advantage of this unexpected trend of increased sales of blue clothing in May, especially if you can demonstrate the same trend in previous years..

Where Can I See Custom Dimensions in Google Analytics?

The examples above demonstrate Custom Dimensions that we have used as the primary dimension in a custom report; there are several additional Google Analytics functionalities that allow us to use Custom Dimensions, as listed below:

  • Secondary Dimensions
  • Custom Segments
  • Custom Reports
  • Audiences for AdWords Remarketing, Optimize*, and DoubleClick for Publishers*
  • Core Reporting API

*Integration available for Google Analytics 360.

Sending the Custom Dimension Value to GA

The diagram in Figure 5 shows how the default dimensions are sent to Google Analytics. The blue box represents a packet of data – otherwise known as a hit – that is sent every time a user views a page.

Figure 5: You can send one or more Custom Dimension values along with the predefined dimensions included in a pageview, event, or Ecommerce hit.

When the GA tracking code (analytics.js) executes on the page, it sends a pageview hit to GA with all of the predefined, built-in dimensions like source, medium, page, browser, country, etc. These pre-defined dimensions are helpful but they’re general.

Going back to our example, the small, red, extra box in the image represents the Author custom dimension we added at E-Nor. Each time you add a custom dimension to your implementation, you’re populating a new field in the packet that gets sent to GA with the Pageview hit. You can also add Custom Dimension values to Event and Ecommerce hits.

To set up a Custom Dimension in GA, go to Admin, select the property where you want the dimension applied, click ‘Custom Definitions’ and ‘Custom Dimension’, then click ‘New Custom Dimension’. For our example in Figure 6, the name would be Author and the scope would be hit to make sure the value is sent with each hit (we discuss Custom Dimension scopes below). To complete the setup, check ‘Active’ and click ‘Create’.

Creating a Custom Dimension “Slot” in GA

Figure 6. Creating a Custom Dimension in Google Analytics Admin

Once the custom dimension is created, you will be given an example code. Check the dimension number and make a note of it because you will use it in your Custom Dimension settings in Google Tag Manager for the “Index” input later. This tells Google where to store the information you will send.

Setting up a custom dimension in GA is almost like creating the new column for it in a Google Analytics report. Next, you need to determine how to extract the actual values for the new custom dimension (the name of each author) from the page and send it to GA.

Where Custom Dimension Values Can Come From

You can send data to Google Analytics from back end sources such as a Customer Relationship Management tool like Salesforce or a Content Management System like WordPress.

As we’ll see in Figure 7 and the sections below, in order to get the data to GA, we’ll need to use different variables in GTM – and potentially involve our developers – depending on the availability of the Custom Dimension value within the text or markup of the page.

Figure 7: Many of our Custom Dimension values originate from CMS or CRM data.

Extracting Values for the Custom Dimension with Google Tag Manager

Google Tag Manager (GTM) is Google’s tag management system that makes it easy to add and update website tags, the snippets of JavaScript on your site that send information to third parties. GTM is based on code injection but you can also use it to access DOM elements on your site and send different pieces of data to Google Analytics from a webpage. We’ll can use GTM to populate a Custom Dimension that we have already set up in the Google Analytics admin.

Is the Value You Need Already on the Page?

This is probably the most important question to ask when first determining how you’re going to populate the Custom Dimension: is the Custom Dimension value that you need already present somewhere on the page?

In the case of our Author custom dimension example, the name of the author is on the blog page. We can extract the name and send it to GA with the pageview hit each time a visitor views a blog page.

Since the name is on the page, we should have one of three options below for extracting it with GTM and this is an important point. In order to send the value for one of your custom dimensions to Google Analytics, the value has to be available somewhere on the page or in the page source.

Identify Custom Dimension Value on Page by HTML Element or CSS Class/ID

If the author’s name appears on the page in any of the following formats, we can use a GTM DOM Element variable to extract it, and send it to GA as illustrated in Figures 8 and 9.

Allaedin Ezzedin

Allaedin Ezzedin

Allaedin Ezzedin

Allaedin Ezzedin

Allaedin Ezzedin


Figure 8: Google Analytics pageview tag in GTM, with Custom Dimension index 1 populated with a DOM Element Variable.
Figure 9: DOM Element variable in GTM that uses a CSS selector to read in the author value.

Reading the Custom Dimension Value from the Data Layer

There are two main scenarios for reading your Custom Dimension values from the GTM data, layer instead of from the page:

  • the Custom Dimension value doesn’t appear on the page: if the value doesn’t appear anywhere on the page or in the page source, you need to work with your developers to write the value to the data layer, from which you can then read it in as a GTM data layer variable, as illustrated below. This scenario may be more likely for back-end data (such as Customer Level) than page-level information such as Author.
  • you want to avoid any dependency on page markup: in the previous section, we saw how straightforward it is to read in Custom Dimension values from a page with a DOM Element variable, but this convenience comes with some vulnerability. See Data Layer Is Safer than DOM Element below.

Working with Your Developers to Populate the Data Layer

The GTM data layer isn’t magical, and it’s empty by default. We have to work with our developers to write the necessary page-level code to populate the data layer, as illustrated below for a Customer Loyalty that we’re reading from the back end:

Listing: Writing a Value to the Data Layer

Where on the Page Should I Place the Data Layer Code?

When placing the data layer code on the page, we should remember that our tags in the GTM container can’t read in any data layer variables if they haven’t already been written to the data layer. With this in mind, we have two feasible approaches:

  • place the data layer code before the GTM container code: if the data layer code appears ahead of the GTM container code on the page, any data layer variable that you have written to the data layer will be ready when any of the GTM tags start firing.
  • use a DOM Ready trigger instead of a Page trigger: if, for any reason, it’s not feasible to place the data layer code before the GTM container code, you can apply a DOM Ready trigger, as shown in Figure 10, (instead of a Page View trigger) to any tags that use data layer variables. The DOM Ready trigger will force your tags to wait till the page source – including any data layer script – has been fully parsed before the tags execute.
Figure 10: If you can’t place your data layer script before the GTM container code, a DOM ready trigger applied to you tags

Once we have completed the more difficult step of writing to the data layer at page level, we can now follow the same steps in GTM as above for populating the custom dimension, but instead of using a DOM Element variable in GTM to read the Custom Dimension value from the page, we’ll use a Data Layer variable in GTM to read the Custom Dimension value from the Data Layer, as shown in Figure 11:

Figure 11: Data Layer variable in GTM to read in the customer loyalty value that we have written to the data layer.

Data Layer is Safer than DOM Element

Even when a value that we need to populate Custom Dimensions is present on the page, as with Author above, E-Nor’s engineering team recommends writing it to the data layer and using a GTM Data Layer variable instead of reading it directly from the page with a GTM DOM Element variable.

Particularly in the case of CSS class names that denote style instead of function (which go against CSS best practices but are still used quite routinely), any change to the class will break the DOM Element variable. For instance, if your front-end developer changed blueHeading to blackHeading in the example below, our GA tags would no longer be able to read the Custom Dimension value.

Allaedin Ezzedin


On the other hand, an HTML data attribute as in the example below might be less likely to change, and a DOM Element variable would therefore be less likely to break, so it would not be as important to take the data layer approach instead.

Allaedin Ezzedin


Setting the Custom Dimension Scope

When you set up a new custom dimension you have to select a scope, as referenced in our examples above. The scope determines which hits the Custom Dimension value will be applied to. Each Custom Dimension can have one of four scopes.:

Figure 12. Custom Dimensions with their Scopes and Example Values

Hit: A hit is a visitor’s interaction with your website or app. It results in a hit being sent to Google Analytics. The most common hits are pageviews, screenviews, events and transactions. The value of the Custom Dimension is sent with each hit as with the Author example.

Session: A session is a group of recorded hits for one visitor in a given time period. A session expires after 30 minutes of visitor inactivity or after midnight, or if the visitor comes back to the site from a different campaign. One visitor can have many sessions. Let’s say you wanted to see the content categories associated with sessions in the channels report. You would be able to do this using a session-scoped Custom Dimension for category.

User: A user in Google Analytics is a random assigned Client ID set by the GA cookie when a browser loads your site content. When a Custom Dimension is user-scoped, the value is applied to all the hits in the current session as well as future sessions for that user, until there is a change in the value of the Custom Dimension. If you wanted to capture the logged in status of your visitors, the value ‘yes’ would be applied to the user. The value would remain the same until the user logged out and the status changed.

Product: When a Custom Dimension is product-scoped, the value is calculated and sent once per product. Product scope can only be set for Custom Dimensions when you have Enhanced Ecommerce tracking set up on your site. If you wanted to capture the availability of a product each time the product was viewed, you could create a Custom Dimension called product availability and send the values ‘in stock’ or ‘out of stock’ to GA depending on availability.

One way to determine scope is to consider which reports you would like to use the Custom Dimension in. Which metrics would you like to see? It only makes sense to combine dimensions and metrics that share the same scope. In the case of our example, it makes sense to see the name of the Author with the number of Pageviews for a blog page. Pageviews are hits so the Custom Dimension is hit-scoped.

The Google Guide for Custom Dimensions & Metrics covers other important things to consider when setting the scope.

Custom Dimension Limits

You can set up 20 custom dimensions in Google Analytics Standard and 200 in Google Analytics 360. It’s important to plan ahead when creating custom dimensions and think about the business questions you want to analyze.

Setting up custom dimensions takes planning and work, but the rich, business-specific data you get in return is well worth the effort. All of our implementations at E-Nor involve Custom Dimensions because they’re so important for detailed analysis and segmentation.

To learn more about Custom Dimensions and other customizations that can enhance your Google Analytics implementation, check out our Google Analytics Breakthrough: Supplemental Notes and Resources.