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
- Create a new custom dimension
- Create a new custom metric
- Edit a custom dimension or metric
- Archive a custom dimension or metric
- About scope
- Event-scoped custom dimensions and metrics
- User-scoped custom dimensions and metrics
- Limits
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:
- Navigate to Configure [
] > Custom definitions > Custom dimensions.
- Click Create custom dimension.
- Enter a descriptive Dimension name that will be displayed in your reports.
- Choose a Scope from the drop-down menu, e.g. "Event" or "User."
- Enter a Description for your custom dimension.
- 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.
- Click Save.
Create a new custom metric
To create a custom metric you need edit permission to the property:
- Navigate to Configure [
- Click Create custom metric.
- Enter a descriptive Metric name. This will be displayed in your reports.
- Choose a Scope from the drop-down menu, e.g. "Event" or "User."
- Enter a Description for your custom metric.
- 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.
- Choose a Unit of measurement from the drop-down menu.
- Click Save.
Edit a custom dimension or metric
- Navigate to Configure > Custom definitions.
- In the row for the dimension or metric, click More [
], then click Edit.
- Make the changes you want, then click Save.
], then click Edit.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.
- Navigate to Configure > Custom definitions.
- In the row for the dimension or metric, click More [
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.
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.
This will display your quota information, including how many custom dimensions and metrics you've created and your total capacity of each.
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.