How to Set Custom Dimensions and Metrics in Google Analytics 4

Dimensions can be confusing.

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. 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.

LAST UPDATE (Dec 31, 2021)

This post has been updated to show the benefits of upgrading to New GA 360.


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).

Hit Describe the current hit Ex. Page title
Session 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
User Describe the user
If more than one value is set, the later values will overwrite the previously set values.
Ex. Account status
Product 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

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 be set to either the user level or the hit level.

This means that a custom dimension should always describe the user who triggered the event, or the event itself. To illustrate, here are some examples of good and bad custom dimensions that you might send with a "search" event:

Event Scope: search_filter = "price < $100" Session Scope: traffic source = "google"
User Scope: pdf_downloaded = true Product Scope: product_color = "red"

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.

Which 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 to the session or the product. Here are a few tips to migrate your custom dimensions that currently use "session", or "product" scope:

    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 5 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 created from your event parameters, so to set a custom dimension or metric, you simply provide it with a name, and identify the parameter that should populate it. It is okay if the parameter is being set by more than one event, because all events with the identified parameter will feed the new dimension/metric.

New custom definition

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

Event parameter in GTM

About 24 hours after data has started collecting to this parameter, you can navigate to the "Custom definitions" report in Google Analytics, and create a new custom dimension or metric. The new parameter ("foo") will show up in the "Event parameter" drop down similar to the "file_extension" parameter that is shown in the screenshot above.

Once you've set the parameter as a custom metric or dimension, two things will happen:

  1. A new data card will be added to the report for this event.
    Data card
  2. The new dimension/metric will be available for use in your Analysis Hub reports.
    New dimension


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 hit-scoped custom dimensions or metrics (source), and 25 user-scoped (source). If you upgrade to the enterprise version (called "New GA 360") then you will be able to create 250 custom dimensions or metrics, and 100 user-scoped.

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 "Custom Definitions" screen, and "Archive" the dimension or metric that you would like to remove.

Archive a custom definition

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

Add a comment if you have issues or additional questions related to custom definitions. I will expand this article over time to share more best practices as I come across them.