How To Set Custom Dimensions and Metrics in Google Analytics 4

Custom definitions (also known as custom dimensions and metrics) are critical to any business that relies on Google Analytics, and they have been completely overhauled in Google Analytics 4 (GA4). In this post, we will discuss how custom definitions have changed, explain what you need to know before migrating them from Universal Analytics, and review the steps to set them up correctly.

What Are Custom Dimensions and Metrics?

If you are familiar with custom definitions in Universal Analytics then feel free to skip this section. Otherwise, here is a quick definition:

Any time you fire a hit to Google Analytics, a variety of data points are collected automatically so that they can be used for analysis later. A few examples include:

  • A description of the content that is currently being viewed (such as the URL or app activity)
  • A unique identifier for the user (such as the client ID or device ID)
  • Information about the device being used (browser, screen resolution, etc)

Custom definitions were introduced with Universal Analytics in 2013, and they allow you to add other data points to the hit that are custom to your website or application. These data points are called custom dimensions and custom metrics (they are equivalent to eVars and success events in Adobe Analytics).  

When creating custom dimensions in Universal Analytics, you also determine if the scope should be set to “hit,” “session,” “user,” or “product.” This is important because your selection here determines the types of reports you can build (more on that here).


Describe the current hit

Ex. Page title


Describe the entire session
If more than one value is set during the session, the later values will overwrite the previously set values.

Ex. Login status


Describe the user
If more than one value is set, the later values will overwrite the previously set values.

Ex. Account status


Describe the product
If more than one value is set, the later values will overwrite the previously set values.

Ex. Color

How Custom Dimensions have Changed in Google Analytics 4 (GA4)

The new version of Google Analytics still allows you to create custom definitions (and custom metrics remain relatively unchanged), but the scope of your custom dimensions will now always be set to the hit level. This means that a custom dimension should always describe the event that is sending it. To illustrate, here are some examples of good and bad custom dimensions that you might send with a “search” event:
search_filter = “price < $100”
search_results_returned = 400
account_type = “paying customer”
user_company = “microsoft”

If you currently set custom dimensions that describe your users, sessions, and products, you will need to be a bit strategic about how to pass those attributes into Google Analytics 4.

This brings us to our next topic…

How to Migrate Custom Dimensions to Google Analytics 4 from Universal Analytics

To reiterate the section above, it is no longer possible to set the scope of a custom dimension. Instead, the term “Custom Dimension” implies hit scope in Google Analytics 4.  Here are a few tips to migrate your custom dimensions that currently use “user,” “session,” or “product” scope:

    User Properties have replaced user-scoped custom dimensionsDon’t let the name confuse you—they work exactly the same. 
    There are no session-scoped custom dimensions in GA4.  Although the concept of a session still exists in GA4, it is far less important than it was in Universal Analytics (more about that here). In many cases, you can set what was previously a session-scoped dimension as a hit-scoped dimension. If this will not work for you, BigQuery receives a random number that is used to identify each session called “ga_session_id”, and you can use this to aggregate a dimension by session if you have enabled the BigQuery integration.
    Item parameters have replaced product-scoped custom dimensions. If you take a look at the developer guide, you’ll notice five optional properties in the “items” node of the eCommerce schema: “item_category,” “item_category2,” …”item_category5.”  These are optional and can be used exactly the same way as product-scoped custom dimensions were used in Universal Analytics.

How to Properly Configure Custom Dimensions in Google Analytics 4

In GA4, custom dimensions and metrics are automatically created for you from your event parameters, so to set a custom dimension or metric, you simply create a custom event parameter. When two events are setting the same parameter, you can merge them into a single dimension.

The example below will generate a new custom dimension called “foo” using the “App + Web Event” tag in Google Tag Manager:

How to set a custom dimension and metric in google analytics 4 using the "app+web" event

About 24 hours after data has started collecting to this parameter, you will see two changes in the user interface:

  1. A new data card will be added to the report for this eventimage1 2
  2. And when you open up your “All events” report and click the “Manage Custom Definitions” button, you will see that a new custom dimension has been created for this parameter. example of custom dimension and metric (custom definitions) in google analytics 4 (GA4) If you have two events that both set the same parameter, GA4 will attempt to create two separate custom dimensions. You can merge these into a single custom dimension by editing the custom dimension name.


In Universal Analytics, properties running the free version were limited to 20 custom dimensions and 20 custom metrics. When you upgraded to GA360, your quota was extended to 200 custom dimensions and 200 custom metrics.

With Google Analytics 4, you can create 100 custom dimensions or metrics (source), and 25 user properties (source). These will be increased if you choose to upgrade your property to 360 when it is released in 2021.

How to Remove Unused Custom Definitions

If you no longer need a custom dimension or metric, you should remove it so that it does not count towards your limit. To do this, you can go to your “Manage Custom Definitions” screen, and “Archive” the dimension or metric that you would like to remove.

image2 1

WARNING: Once a custom dimension or metric has been archived, it cannot be recovered. Any audiences or reports that rely on this variable will not work.

Share Feedback

I will expand this article over time to share more best practices as I come across them.

If you have issues, comments, or additional questions related to custom definitions in GA4, please fill out this form and we’ll chat.

Leave a Comment

Your email address will not be published.

Contact Us

Related Posts

Join the Conversation

Check out Kelly Wortham’s Optimization based YouTube channel: Test & Learn Community.

Search Discovery
Education Community

Join Search Discovery’s new education community and keep up with the latest tools, technologies, and trends in analytics.




Scroll to Top


Catch the latest industry trends we’re watching and get new insights from our thought leaders delivered directly to your inbox each month.