[GA4] Custom dimensions and metrics

This article is for advanced Analytics customers that want to create custom dimensions and metrics.

Custom dimensions and custom metrics are like default dimensions and metrics in your Analytics account, except you create them yourself. You can use them to collect and analyze data that Analytics doesn't by default. Custom dimension and metric values are supplied by logged event parameters and user properties.

In this article

Note

Event scope was previously referred to as hit scope in Universal Analytics.

Create a new custom dimension

To create a new custom dimension you need edit permission to the property:

  1. Navigate to Configure [Config] > Custom definitions > Custom dimensions.
  2. Click Create custom dimension.
  3. Enter a descriptive Dimension name that will be displayed in your reports.
  4. Choose a Scope from the drop-down menu, e.g. "Event" or "User."
  5. Enter a Description for your custom dimension.
  6. Select an Event parameter (or user property) that will supply the value to your custom dimension or enter the name of a parameter or property you'll collect in the future.
  7. Click Save.

New custom dimension

Create a new custom metric

To create a custom metric you need edit permission to the property:

  1.  Navigate to Configure [Config] > Custom definitions > Custom metrics.
  2. Click Create custom metric.
  3. Enter a descriptive Metric name. This will be displayed in your reports.
  4. Choose a Scope from the drop-down menu, e.g. "Event" or "User."
  5. Enter a Description for your custom metric.
  6. Select an Event parameter (or user property) that will supply the value to your custom metric or enter the name of a parameter or property you'll collect in the future.
  7. Choose a Unit of measurement from the drop-down menu.
  8. Click Save.

New custom metric

Edit a custom dimension or metric

  1. Navigate to Configure > Custom definitions.
  2. In the row for the dimension or metric, click More [], then click Edit.
  3. Make the changes you want, then click Save.

Archive a custom dimension or metric

If you need to create new custom dimensions and/or metrics but you have reached your limit, you can archive ones you are no longer using in order to free up quota.

  1. Navigate to Configure > Custom definitions.
  2. In the row for the dimension or metric, click More  [], then Archive.
Note
 
Archiving a custom dimension or metric is permanent. It can't be undone and the corresponding data can't be restored. Any segment or funnel using this custom dimension in Analysis won't work.

About scope

Scope specifies to which data the custom dimension or metric will be applied. Dimensions and metrics can only have one scope and it cannot be changed after it has been saved. Currently event-scoped custom dimensions and metrics and user-scoped custom dimensions are supported. Session and item-scoped custom dimensions and metrics are on the product roadmap.

Event-scoped custom dimensions

Event-scoped custom dimensions and metrics take their values from the event parameters you collect via the Analytics measurement code. During the creation process, you identify the event parameter that will supply the value for the custom dimension or metric.

With event-scoped custom dimensions and metrics, parameters are identified for property-wide dimensions and metrics, allowing you to create a single dimension or metric based on a parameter and report on it for as many events as you wish. Previously with custom-parameter reporting, parameters were identified for individual events. Consequently, if you wanted to report on the same parameter for five different events, you had to use five of your 100 limit.

With the deprecation of custom-parameter reporting, Analytics has preserved historical event-scoped aggregates, and new aggregates seamlessly extend that historical data. In cases where a parameter was registered for multiple events, Analytics disambiguates between them by assigning a dimension/metric name that includes the currently assigned event name (e.g., “custom_dimension_name [event_name]”).

As a best practice, you should remove duplicate custom dimensions and metrics that were registered across multiple events to help preserve quota.

User-scoped custom dimensions

User-scoped custom dimensions are available in Google Analytics 4 properties and are populated from collected user properties. This eliminates the need for marketers and developers to think about "slots." User properties become aliases for user-scoped custom dimension slots, allowing developers to focus on tracking meaningfully named data points without having to associate each data point with an arbitrary slot number.

Set user-scoped custom dimensions to identify static or slowly changing attributes of your users, such as "spender=true", "profession=engineer", or "favorite_team=Real Madrid". User-scoped custom dimensions are effectively sticky event-scoped custom dimensions.

You can see user-scoped custom dimensions in the Realtime overview and other reports. For example, you can create comparisons with user-scoped custom dimensions, e.g. see how the game-play habits of spenders differ from non-spenders.

NOTE:
When you set user-scoped custom dimensions, never include personally identifiable information such as names, social security numbers, or email addresses, even in hashed form.

Limits

Event-scoped custom dimensions and metrics: GA4 property users can create up to 50 custom dimensions and 50 custom metrics per property.

User-scoped custom dimensions: GA4 property users create up to 25 uniquely named user-scoped custom dimensions.

You can review the total number of custom dimensions and metrics you've created by clicking the Quota information button.

Quota information

This will display your quota information, including how many custom dimensions and metrics you've created and your total capacity of each.

Quota information 2

If you have reached your quota but need to create new custom dimensions and/or metrics, you can archive the ones you are no longer using.

NOTE: You may see a value of "not set" for a custom dimension during the first 24 hours.
Was this helpful?
How can we improve it?