[GA4] Custom dimensions and metrics

Custom dimensions and metrics enable you to report on information about your users and how they interact with your site or app. They're useful when the data you want to analyze isn't available through the predefined dimensions and metrics.

Custom dimensions and metrics are built using the custom event parameters and user properties on your website or app. Only the event parameters and user properties that have been sent from your site or app and collected by Google Analytics can be used to build custom dimensions and metrics.

Custom Dimensions and Metrics in Google Analytics

Types of custom dimensions and metrics

You can set up the following types of custom dimensions and metrics. The type you should choose depends on the type of data you want to analyze. Included in the table are limits on the number of custom dimensions and metrics you can create for standard and premium properties.

Type	Details	How it works	Standard property limits	Analytics 360 property limits
User-scoped custom dimensions	Analyze an attribute about users on your website or app.	Defined based on a custom user property.	25	100
Event-scoped custom dimensions	Analyze an attribute about an event, such as the value of the event or whether the intended action was completed successfully.	Defined based on a custom event parameter.	50	125
Item-scoped custom dimensions	Analyze an attribute about a product or service sold on your online store. For example, you can analyze the color, size, rating, or status of a product.	Defined based on a custom event parameter within an items array. Item-scoped custom dimensions currently do not appear in the Realtime report or DebugView.	10	25
Custom metrics	Analyze the data points from an event parameter. For example, you can analyze the value of a transaction from an event parameter.	Defined based on a custom event parameter.	50	125

See quota information

To see the number of custom dimensions and metrics you've created:

1. In Admin, under Data display, click Custom definitions.
2. On the top right, click Quota information.

Best practices

Before you create custom dimensions and metrics, use the predefined dimensions and metrics whenever possible.

If you have a standard property, do not create unnecessary high-cardinality custom dimensions. High-cardinality dimensions may negatively impact your reports and explorations, and cause data to be condensed under the (other) row.

Example

The following are examples of high-cardinality dimensions that aren't allowed or should be avoided:

• Using a custom dimension for a unique ID per user; instead, use the User-ID feature
  • Learn more about how to meet your use cases without creating a custom dimension for a user ID
• Using a custom dimension to send unique IDs per session, like a Session ID
• Sending a timestamp as a custom dimension

Lastly, registering a custom dimension for a parameter that is already a predefined dimension, such as the page and screen dimensions, or transaction ID, is not a best practice. It will not affect cardinality, but it will use one of your custom dimension quota.

Create a custom dimension or metric

You must be an Editor or Administrator to create and edit custom dimensions and metrics.

Create a user-scoped custom dimension

Create a user-scoped custom dimension

1. In Admin, under Data display, click Custom definitions.
2. In the Custom dimensions tab, click Create custom dimensions.
3. In Dimension name, enter a unique name for the new dimension. You can't use hyphens in the name, but you can use underscores and spaces instead.
4. In Scope, select User.
5. In User property, enter the name of the user property.
6. Click Save.

You will see a value of (not set) for a custom dimension in the first 48 hours.

Example

 

You configure a user property called profession, which details each user's profession. In order to analyze different professions, you might consider the following configuration:

 

• Dimension name: Profession
• Scope: User
• Description: The profession of a user
• Item parameter: profession

Edit a user-scoped custom dimension

1. In Admin, under Data display, click Custom definitions.
2. In the Custom dimensions tab, click > Edit next to the dimension.
3. Modify the dimension name or description.
4. Click Save.

Create an event-scoped custom dimension

Create an event-scoped custom dimension

1. In Admin, under Data display, click Custom definitions.
2. In the Custom dimensions tab, click Create custom dimensions.
3. In Dimension name, enter a unique name for the new dimension. You can't use hyphens in the name, but you can use underscores and spaces instead.
4. In Scope, select Event.
5. In Event parameter, enter the name of the event parameter.
6. Click Save.

You will see a value of (not set) for a custom dimension in the first 48 hours.

Example

 

You configure the recommended payment_type parameter for the add_payment_info event. In order to analyze different payment types, you might consider the following configuration:

 

• Dimension name: Payment type
• Scope: Event
• Description: The chosen method of payment
• Item parameter: payment_type

Edit an event-scoped custom dimension

1. In Admin, under Data display, click Custom definitions.
2. In the Custom dimensions tab, click > Edit next for the dimension.
3. Modify the dimension name or description.
4. Click Save.

Create an item-scoped custom dimension

To give you the flexibility to choose from a larger pool of parameters without having to retag your site or app, you can send up to 27 item-scoped custom parameters, of which you can configure:

• 10 item-scoped custom parameters for standard properties
• 25 item-scoped custom parameters for Analytics 360 properties

Create an item-scoped custom dimension

1. In Admin, under Data display, click Custom definitions.
2. In the Custom dimensions tab, click Create custom dimensions.
3. In Dimension name, enter a unique name for the new dimension. You can't use hyphens in the name, but you can use underscores and spaces instead.
4. In Scope, select Item.
5. In Item parameter, enter the name of the item-scoped event parameter.
6. Click Save.

You will see a value of (not set) for a custom dimension in the first 48 hours.

Example

 

In addition to the recommended event parameters for the add_to_cart event, you add a color event parameter to describe a shirt in the add_to_cart event. To analyze the color event parameter, you might consider the following configuration:

 

• Dimension name: Color
• Scope: Item
• Description: The color of an item
• Item parameter: color

Edit an item-scoped custom dimension

1. In Admin, under Data display, click Custom definitions.
2. In the Custom dimensions tab, click > Edit next for the dimension.
3. Modify the dimension name or description.
4. Click Save.

Create a custom metric

Create a custom metric

1. In Admin, under Data display, click Custom definitions.
2. In the Custom metrics tab, click Create custom metrics.
3. In Metric name, enter a unique name for the new metric. You can't use hyphens in the name, but you can use underscores and spaces instead.
4. In Event property, enter the name of the event parameter.
5. In Unit of measurement, select a unit of measurement.

   Unit of measurement	Details
   Currency	When you select Currency, you must also identify if the custom metric is a cost and/or revenue metric under Data type. When you identify the custom metric as a cost and/or revenue metric, you can restrict access to it when you configure user roles that restrict access to cost and/or revenue metrics.
   Distance (Feet, Miles, Meters, Kilometers)	These options allow you to compare distances with different units of measurement. For example, you can compare a metric in meters with one in kilometers.
   Time (Milliseconds, Seconds, Minutes, Hours)	These options allow you to compare times with different units of measurement. For example, you can compare a metric in seconds with one in minutes.

6. Click Save.

You will see a value of (not set) for a custom dimension in the first 48 hours.

Example

 

In addition to the recommended event parameters for the level_end event, you add a value event parameter that counts the number of points someone earned when they completed a level. To analyze the value event parameter, you might consider the following configuration:

 

• Dimension name: Points after level
• Description: The number of points at the end of a level
• Event parameter: value
• Unit of measurement: Standard

Edit a custom metric

1. In Admin, under Data display, click Custom definitions.
2. In the Custom metric tab, click > Edit next for the metric.
3. Modify the metric name or description.
4. Click Save.

Analyze custom dimensions and metrics

Certain custom dimensions aren't available in your reports when combined with demographic information. You may experience thresholding or incompatibility constraints when requesting custom dimensions with demographic data.

Analyze a user-scoped custom dimension

Analyze the dimension in a report

To add a user-scoped custom dimension to a report:

1. On the left, click Reports.
2. Open the report you want to add the dimension to.
3. Click Customize report [] in the top right. If you don't see , you don't have permission to customize the report.
4. In Report data, click Dimensions.
5. Open the Add dimension drop-down menu.
6. Type the name of the dimension, or scroll to the Custom section.
7. Drag the dimension [] to reorder it in the report.
8. Click Apply.
9. Click Save > Save changes to current report.

Analyze the dimension in an exploration

To add a user-scoped custom dimension to a free-form exploration:

1. On the left, click Explore.
2. Create or open a free-form exploration.
3. In the Variables column on the left, click + next to Dimensions.
4. Click the Custom tab at the top.
5. Select the user-scoped custom dimension.
6. Click Import.
7. Drag the dimension from the Variables column and drag it into Rows or Columns in the Settings column.

Analyze an event-scoped custom dimension

Analyze the dimension in a report

To add an event-scoped custom dimension to a report:

1. On the left, click Reports.
2. Open the report you want to add the dimension to.
3. Click Customize report [] in the top right. If you don't see , you don't have permission to customize the report.
4. In Report data, click Dimensions.
5. Open the Add dimension drop-down menu.
6. Type the name of the dimension, or scroll to the Custom section.
7. Drag the dimension [] to reorder it in the report.
8. Click Apply.
9. Click Save > Save changes to current report.

Analyze the dimension in an exploration

To add an event-scoped custom dimension to a free-form exploration:

1. On the left, click Explore.
2. Create or open a free-form exploration.
3. In the Variables column on the left, click + next to Dimensions.
4. Click the Custom tab at the top.
5. Select the event-scoped custom dimension.
6. Click Import.
7. Drag the dimension from the Variables column and drag it into Rows or Columns in the Settings column.

Analyze an item-scoped custom dimension

You can't add an item-scoped custom dimension to standard reports.

Analyze the dimension in an exploration

To add an item-scoped custom dimension to a free-form exploration:

1. On the left, click Explore.
2. Create or open a free-form exploration.
3. In the Variables column on the left, click + next to Dimensions.
4. Click the Custom tab at the top.
5. Select the item-scoped custom dimension.
6. Click Import.
7. Drag the dimension from the Variables column and drag it into Rows or Columns in the Settings column.

Analyze a custom metric

Analyze the metric in a report

To add a custom metric to a report:

1. On the left, click Reports.
2. Open the report you want to add the metric to.
3. Click Customize report [] in the top right. If you don't see , you don't have permission to customize the report.
4. In Report data, click Metrics.
5. Open the Add metric drop-down menu.
6. Type the name of the metric, or scroll to the Custom section.
7. Drag the metric [] to reorder it in the report.
8. Click Apply.
9. Click Save > Save changes to current report.

Analyze the metric in an exploration

To add an custom metric to a free-form exploration:

1. On the left, click Explore.
2. Create or open a free-form exploration.
3. In the Variables column on the left, click + next to Metrics.
4. Click the Custom tab at the top.
5. Select the custom metric.
6. Click Import.
7. Drag the metric from the Variables column and drag it into Values in the Settings column.

Deprecation of custom-parameter reporting

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 quota of 100 custom dimensions and metrics.

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

User-scoped custom dimensions eliminate the need for you 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.