This article is about Google Analytics 4 properties. Refer to the Universal Analytics section if you're still using a Universal Analytics property, which will stop processing data on July 1, 2023 (July 1, 2024 for Analytics 360 properties).

[GA4] Custom dimensions and metrics

Create dimensions and metrics from event parameters and user properties so you can easily access data in reports and explorations

Custom dimensions and metrics are dimensions and metrics that you create. They allow you to analyze data that is specific to your business needs. They're useful when you create custom event parameters or custom user properties.

Custom Dimensions and Metrics in Google Analytics

How it works

When you create a custom dimension or metric, you provide the name of the custom event parameter or custom user property that Analytics should associate with the new dimension or metric. Analytics then populates the new dimension or metric with whatever value it collects from the corresponding event parameter or user property.

Benefits

Creating custom dimensions and metrics allows you to easily access and use your event properties and user properties. For example, without creating a custom dimension for your custom color event parameter, you won't be able to see the parameter values in reports or use them in audiences.

Best practices

Before you create custom dimensions and metrics, use the default dimensions and metrics.

If you have a standard property, do not create unnecessary high-cardinality custom dimensions. High-cardinality dimensions may negatively impact your reports and cause data to aggregate 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.

Limits & caveats

If you reach any of the following limits, archive the custom dimensions or metrics you don't use to create new ones:

Item Standard property limits Analytics 360 property limits
Event-scoped custom dimensions 50 125
User-scoped custom dimensions 25 100
Item-scoped custom dimensions 10 25
All custom metrics 50 125

 

Note: You can send up to 27 item-scoped custom parameters from your website or app, of which you can configure 10 item-scoped custom parameters for standard properties and 25 for Analytics 360 properties. This gives you the flexibility to choose from a larger pool of parameters without having to retag.

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

  1. In the Property column, click Custom definitions.
  2. On the top right, click Quota information.

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.

Before you begin

You must have the Editor or Administrator role to create custom dimensions and metrics.

Create a custom dimension

  1. In the Properties column, click Custom definitions.
  2. In the Custom dimensions tab, click Create custom dimensions.
  3. Complete the following information:
    • Dimension name: Enter a unique name for the dimension.
      You can't use hyphens in the name, but you can use underscores and spaces instead.
    • Scope: Choose a scope for the custom dimension. Learn more
    • Description: Enter a memorable description for the custom dimension.
    • Event parameter/User property: Choose the source of data. Learn more
  4. Click Save.

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

Create a custom metric

  1. In the Properties column, click Custom definitions.
  2. In the Custom metrics tab, click Create custom metrics.
  3. Complete the following information:
    • Metric name: Enter a unique name for the metric.
      You can't use hyphens in the name, but you can use underscores and spaces instead.
    • Scope: You must create an event-scoped metric. Learn more
    • Description: Enter a memorable description for the custom metric.
    • Event parameter: Choose the source of data. Learn more
    • Unit of measurement: Choose the unit of measurement. Learn more
  4. Click Save.

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

Scopes

A custom dimension can have one of the following scopes:

Scope Description
Event An event-scoped dimension provides information about an action that a user performs. For example, the title of the article someone viewed or the name of an event someone triggered would be an event-scoped dimension.
User A user-scoped dimension provides information about the user who performed the action. For example, the profession of the person who viewed an article would be a user-scoped dimension.
Item

An item-scoped dimension provides information about the products or services that users interact with in an event. For example, when someone makes a purchase, you might want to know the color of the item sold.

Note: Item-scoped custom dimensions may not be used in standard reports.


A custom metric always has an event scope.

Units of measurement

When you create a custom metric, you can choose from the following units 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.

Source of data

As you create a custom dimension or metric, you will be asked to choose the event parameter or user property from which you want to derive data. The source of data for a custom dimension differs from the source of data for a custom metric.

Item Data can come from...
Custom dimension
  • an item parameter when you choose the Item scope
  • an event parameter when you choose the Event scope
  • a user property when you choose the User scope
Custom metric an event parameter


You can enter the name of the event parameter or user property, or you can use the drop-down menu. You must wait up to 48 hours to see a new event parameter or user property in the drop-down menu.

Edit a custom dimension or metric

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

  1. On the left, click Admin > Custom definitions.
  2. In the row for the dimension or metric, click More > Edit.
  3. Make the changes you want, then click Save.

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.

Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue

Search
Clear search
Close search
Google apps
Main menu
Search Help Center
true
true
true
true
true
69256