more dimensions

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

UPDATE (June 19, 2021):
This post has been updated to reflect changes to the way you configure custom dimensions and metrics.

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

HitDescribe the current hitEx. Page title
SessionDescribe 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
UserDescribe the user
If more than one value is set, the later values will overwrite the previously set values.
Ex. Account status
ProductDescribe 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 = trueProduct 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.

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

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.
    custom dimension data card
  2. The new dimension/metric will be available for use in your Analysis Hub reports.


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). At the time that I am writing this, it is not documented if these limits will be increased for properties that have enabled GA360.

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.

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.

15 Replies to “How to Set Custom Dimensions and Metrics in Google Analytics 4”

  1. Thank you, this guide for GA4 is very useful. A question for this article: to show this information (custom dimensions and metrics) in data studio it’s necessary use BigQuery, right?

    1. That’s correct, custom dimensions are not currently available in the Data Studio connector to GA4. However it is very likely that these will be added in the near future.

      1. Thank you so much for publishing this article. You’ve provided so much more information than GA has itself!
        Question around parameters with the same name… You write, “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.”

        I have a lot of parameters for “source” and now they all come in as separate:

        source[event abc]
        source[event def]
        source[event ghi]
        source[event xyz]

        When I look at a specific event, I see source parameters for the specific event, and other events that also have “source[event xxx]”. So when you say to merge these, how should I do that to ensure that I see the proper source attributions on each event without losing any?

        And moving forward with GA4, if I have a source parameter for an event logged in the code, will it just appear when the event is fired, or do I have to turn it on (like in Web + App)?

        Thank you Ken!

        1. Jennifer,

          You can remove the bracketed event name so that the custom dimension is simply “source”. Then, if you want to create a report that only displays the “source” dimension from the event “abc” you would add an event_name filter. You could also create a report that displays total events by “source” and “event_name” to see all combinations.

          Moving forward, when you add a new parameter to an event you will need to go to the “All Events” report and add it as a custom dimension for it to appear in reports.

  2. Thanks for this guide. Am I right in saying that GA4 custom dimensions are not yet included in the schema for BigQuery export? I’ve set up a daily export but the custom dimensions I’ve set up do not appear

    1. Custom dimensions are really just event parameters, so technically they already exist in the BigQuery export. I don’t think it’s likely that Google will make any changes to the schema.

      1. Thanks for reply. Yeah I can see the event parameters in the BQ export but without having them as top-level fields (like we have in UA where event category, action and label are top-level dimensions), it becomes very difficult to create meaningful reports and visualisations in Datastudio.

        For now it seems that the only place to view GA4 custom dimensions is within GA4 itself – there’s no means of automated export of these values. I’m trying to see whether Datastudio itself offers the ability to convert event paramater names into dimensions but doesn’t look possible?

  3. I have added my dimension in the custom dimensions list but I still can’t breakdown my events based on the custom dimension. The custom dimension which I added is not shown in the exploration’s dimension list.

  4. Ken, I believe that the method for creating Custom Dimensions has changed since this article was published.

    I read above, “to set a custom dimension or metric, you simply create a custom event parameter…about 24 hours after data has started collecting to this parameter, you will see two changes in the user interface…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”.

    But, there are buttons in the UI for creating CDs and CMs. And, the quotas on CDs and CMs would make auto-creation of them from event parameters problematic. Let me know if I’m reading it wrong or misunderstanding something!

    1. Chris, thanks for the comment because this post was out of date! You’re exactly right about the auto-creation of custom definitions, and I’ve updated the post to reflect the new workflow.

Leave a Reply

Your email address will not be published.