Google Analytics Custom Definitions – The Right Way

Google Analytics Custom Definitions

Google Analytics Custom Definitions are essential additions to every Analytics setup that has been tailored to a specific business. And they all should be.

The basic setup provides you with plenty of dimensions and metrics but there are things that are specific to your business and need some manual configuration in order to be tracked properly.

This is exactly what Google Analytics Custom Definitions are good for – including non-standard data in your reports.

Topics covered in this article

  • When do we need Custom Definitions
  • Custom Dimensions vs Custom Metrics
  • Custom Definition Scopes
  • How to set up Custom Definitions
  • How to include Custom Definitions in your reports

Use Custom Definitions only when the built-in one is not available

Custom definitions will make your Google Analytics setup more complicated and somewhat difficult to use for everyone not entirely familiar with your configuration. Built-in reports are basically the same for every website, and even if there are some best practices, every custom setup is still a bit different.

That being said, there are cases when you need to use Dimensions or Metrics that are not built in. This is where Google Analytics Custom Definitions come into play.

When to use Custom Dimensions

Custom dimensions are good for collecting many types of information. And they can be used pretty much the same way as the built-in dimensions like City, Browser, Device etc.

One of the most popular ways of using custom dimensions is for associating Google Analytics reports with your user database or CRM. For example, you could use custom dimensions to collect data about visitor gender, age or interests – whatever is available in your database. And create reports based on this data later on.

If your website has a free and paid version, you can use a custom dimension to collect data about the version a specific visitor is using.

For those using Enhanced Ecommerce, you can use custom dimensions to send custom attributes about the product purchased. Take a look at product level scope of custom dimensions.

Just think about your business and your visitors, if there’s is anything qualitative about your visitors or their behavior that matters, you should collect it as a custom dimension. If it’s not already done by default dimensions, of course.

When to use Custom Metrics

Much like built-in metrics, Custom Metrics also let you collect all sorts of quantitative data about your visitors and their behavior. You can use them in your custom reports just like you would use the built-in metrics. And you can combine custom metrics with custom dimensions.

Use custom metrics for counting things. Count how many elements a user scrolled past in your feed, how many bonus points did they use when buying a specific product or the number of times a user changed the value for a filter on your category page.

If you are using Enhanced Ecommerce, you can use custom metrics to track any numeric values related to that product, for example, the number of reward points a visitor earned by buying it.

Again, your imagination is the limit. Just make sure it is countable, it really matters and it is not counted yet.

Custom Definitions and Scopes

When setting up a new custom definition, you will be asked to choose the scope. You have to choose from Hit, Session, User and Product (enhanced ecommerce only).

Even if the names are quite straightforward and you might think you get the concept, too it is still very important that you think it through before setting anything up. Changing the scope after some data has been collected can skew your results!


Use Hit level scope for dimensions and metrics that can change between hits in a single session.

For example chosen filter, that can change more than once even in the same page view.


Session scope is for data that will not change in a single session but could change in the long run.

If you want to count the days from when the visitor started their free trial, you should use Session scope in your custom dimension.


Choose User level for values that rarely change.Or the ones that never do.

Information about your visitors, like their user ID or gender should be tracked with a custom dimension of User scope.


This feature is available for those using Google Analytics Enhanced Ecommerce.

Use Product scope to send collect data with a specific product. Different products can have different values for the same dimension.

How to configure Google Analytics Custom Definitions

While everything is made quite easy and straightforward in the Google Analytics Admin Panel, you should definitely use a developers help when configuring the actual Javascript that is going to send the data to Google Analytics.

Custom Dimension

Start by thinking through what kind of reports you wish to see once the data has been collected. Then figure out the scope that is going to match your goal the best.

After your plan is ready, go to Admin Panel in Google Analytics and choose Custom Definitions and then Custom Dimensions.

Click on New Custom Dimension and give your new dimension a nice descriptive name. Then choose the Scope and check the “Active” checkbox.

You will see something like this:

Filled Google Analytics Custom Dimension
Filled Google Analytics Custom Dimension

When everything is done in the admin panel, ask your developer to figure out the way how to pass the desired value into a Javascript variable. Then let Google Analytics know about it with a function similar to this:

var value = getTheValue();
ga('set', 'dimension1', value );

Keep in mind that setting the value alone doesn’t send it to Google Analytics. It needs to be followed by a hit, such as a pageview or an event.

So your final setup would look something like this:

ga('create', 'UA-XXXX-Y', 'auto');

var value = getTheValue();
ga('set', 'dimension1', value );

// Send the custom dimension value with a pageview hit.
ga('send', 'pageview');

Custom Metric

Just like when custom dimensions, start by thinking everything through. What exactly is that you are going to achieve here and which values and scopes would represent it the best.

Done planning, go to Admin Panel in Google Analytics and choose Custom Definitions and then Custom Metrics.

Click on New Custom Metric and give your new metric a nice descriptive and name. Then choose the Scope, Formatting Type and check the “Active” checkbox. Sometimes you would also want to define a min and max values but going with default empty is just fine in most cases.

You should see a screen like this:

Filled Google Analytics Custom Metric
Filled Google Analytics Custom Metric

Technical setup is very similar to the custom dimension. In the end you would want to see something like this:

ga('create', 'UA-XXXX-Y', 'auto');

ga('set', 'metric1', 1 );

// Send the custom dimension value with an event hit.
ga('send', 'event', 'Category', 'Action');

How to use Custom Definitions in your reports

The whole idea for every metric or dimension is to use it in your reports. And same goes for Google Analytics Custom Definitions.

You can use custom dimensions in all of your custom reports and as a secondary dimension for your regular reports. You can use custom dimensions and metrics also when creating custom segments.

Custom Segments

There are a few ways that you can use Google Analytics Custom Definitions to create custom segments.

Most common one is to choose Conditions in the Advanced sections and then find the Custom Dimension or Custom Metric that you would like to use as a filter for the segment you are creating. You can also create a condition that checks whether the dimension has a value or not. For example, if a visitor doesn’t have a unique ID then they haven’t logged in yet.

Here’s an example of Custom Segment which contains only users that have chosen credit card as their payment method:

Google Analyitcs Custom Definitions Credit Card
Custom Dimension Credit Card

Custom Reports

Creating custom reports with your new Dimensions and Metrics will definitely provide you some good insights that will improve your business.

Here’s an example of using custom dimension as a secondary dimension in a built-in report:

Google Analytics Custom Definitions
Custom Definitions with built-in reports

One more example, number of sessions by a weekday (a custom dimension)

Custom Dimension Weekday
Custom Dimension Weekday

There are many more, very powerful reports that you can create using Google Analytics Custom Definitions and we recommend you play around and explore them yourself.


Using custom dimensions and custom metrics, you can give your Google Analytics setup some real super powers. We hope that after reading this article you will think about your website and its visitors, figure out what kind of actions they take or what characteristics they have, and essentially how to use custom definitions to track them.

After going through this article you will have a good overview of

  • what Google Analytics Custom Definitions are
  • when you should use them
  • difference between dimensions and metrics
  • the meaning of Custom Definition Scope
  • how to set up Custom Definitions
  • how to use them in your reports

This article is a part of our popular series called Most common Google Analytics issues (in-depth overview)

If you find something missing or misleading, please let us know in the comments.

Feel free to share this valuable information with your friends and colleagues.

4 thoughts on “Google Analytics Custom Definitions – The Right Way

  1. Great as always. Thank you guys. Can’t wait the next one in the series. Are you going to send an email update for subscribers, cause I have a feeling I didn’t receive anything for this one…

    1. Hey Talia,

      We are posting about once a week. There should be an email update at same pace. Will look into it, thanks for letting us know!


  2. Thank you so much, Silver. We are currently in the process of creating a custom integration with our CRM tool. Will share this article with our developers. Looking forward to a next atricle in this series.

Leave a Reply

Your email address will not be published. Required fields are marked *

Sign up for Reflective Data

5,000 sessions / month ×

Please enter your email


After submitting your email, we will send you the registration form.