Create a custom dimension

A custom dimension is an additional dimension that you can create to collect and analyze data. A custom dimension can be a user’s email, visitor’s age, blog category, blog author and the like.

In this article, we’ll show you how to create a custom dimension.

Before you start

Here are some things to know before you create your first custom dimension:

Custom dimensions can belong to a session scope or an event scope.
The session scope relates to the whole visit and holds captured custom dimension for the whole session. If during a session the value of a custom dimension will change, Piwik PRO will record the last value. For example, let’s say you’ve created a custom dimension of visitor’s age in the session scope. That’s a good way to do that since the age is not changing during the session. But, let’s say that the visitor first by mistake input the 23 as an age and during the session changed it to 32. In this case, Piwik PRO will capture the last value, which in this case is the number 32.

The event scope relates to events like a page view or downloading a file and holds captured dimension for each event. For example, if you want to record each page view for the author of the blog, you will use the event scope. If you used a session scope, Piwik PRO would overwrite the previous value with each next page view, so you’d be left with the last value only at the end of the visit.
Custom dimensions can’t be removed. You can make them inactive though.
Custom dimension value can be up to 255 characters long.
Avalialiable number of slots in each scope:
- For versions below 16.0.0: 25 slots for each scope.
- For versions 16.25.0 and higher: 200 slots for each scope.
In meta sites/apps, you can map custom dimensions and see combined data in Analytics > Reports > Custom dimensions.

Create a session custom dimension

To create a session custom dimension, follow these steps:

Go to Menu > Analytics.
Navigate to Settings.
On the left, click Custom dimensions.
Here you can choose the scope for the custom dimension: session or event. Click Add a session dimension.
Name the dimension.
Click Save.
Now it’s time to set up dimension values and data collection:
- Tag Manager: Set up a variable and a custom dimension tag. Read the next steps.
- For developers: You can set values and data collection manually using the JavaScript tracker API or the HTTP tracker API.
Note: The value can be up to 255 characters long.
Note Dimension name or ID. You’ll need it in the next steps.
Go to Menu > Tag Manager.
Navigate to Variables.
On the left, click Create a variable.

Note: Each site or app has a different construction, so each variable setup will be unique.
Name the variable and click Save.
Choose the variable type.
Set up the variable.
When you’re done, click Save.
Navigate to Tags.
Click Add a tag.
Name the tag and choose the following type: Custom dimension.
In Dimension, choose your dimension. You created it in step 8.
In Dimension value, type the value. This is the variable you created in steps 9 –– 15.
In Advanced tag settings, choose Consent type. Set it up if you use a consent form on your site. This tag will fire only for visitors who accept the selected consent type.
Respect opt-out and DNT is turned on by default. Leave it as is, if you want to respect visitors who set Do-Not-Track in their browsers, or visitors who opt out of tracking using our opt-out form.
Adjust trigger conditions.
When you’re done, click OK for the trigger.
Click Save for the tag.
Test your tag in debug mode.
When you’re happy how the tag works, click Publish.
After some time, data will be collected and you’ll it under Menu > Analytics > Reports > Custom dimensions.

Create an event custom dimension

To create an event custom dimension, follow these steps:

Go to Menu > Analytics.
Navigate to Settings.
On the left, click Custom dimensions.
Click Add an event dimension.
Name the dimension.
Click Save.
Now it’s time to set up dimension values and data collection:
- Extractions: Use a regex (regular expression) to extract values from the page URL or title. Or use a parameter to extract values from the page URL.
- Tag Manager: Set up a variable and a custom dimension tag. Read the next steps if you use this method.
- For developers: You can set values and data collection manually using the JavaScript tracker API or the HTTP tracker API.
Note: The value can be up to 255 characters long.
Note Dimension name or ID. You’ll need it in the next steps.
Go to Menu > Tag Manager.
Navigate to Variables.
On the left, click Create a variable.

Note: Each site or app has a different construction, so each variable setup will be unique.
Name the variable and click Save.
Choose the variable type. We’ll choose DOM element for our example.
Set up the variable. For our example, we’ll use the CSS selector and add .author. The .author element relates to the HTML element with the .author class used for the blog author on our website.
When you’re done, click Save.
Now we need to match the dimension with its value. You can use the following methods:
- For page views: a tracking code tag (Menu > Tag Manager > Tags > Piwik PRO > Collect data for custom dimensions) or a virtual page view tag (Menu > Tag Manager > Tags > Add a tag > Virtual page view).
- For events: the custom event tag (Menu > Tag Manager > Tags > Add a tag > Custom event).
Note: When you use an event dimension and track it with a custom dimension tag, you need to run this tag before the tracking code (Piwik PRO tag). This is because a custom tag needs to send data before a page view is tracked. Read more about setting tag priority.
When you’re done, test your tag in debug mode.
When you’re happy how the tag works, click Publish.
After some time, data will be collected and you’ll see it under Menu > Analytics > Reports > Custom dimensions.

Debug mode: how to check your custom dimension

To check if values for your custom dimension are collected, follow these steps:

Go to Menu > Tag Manager.
Navigate to Tags.
In the top-right corner, click Debug.
Your website will open in a new tab with debug mode running.
Make an action that triggers capturing the custom dimension. In our example, that will be visiting a blog post.
On the right, navigate to Events log.
Click the element on the top of the list, for example, stg.timer.
Navigate to Variables.
Scroll down until you see the name and value of your custom dimension.

Inspector tool: how to check your custom dimension

To check if values for your custom dimension are collected, follow these steps:

Open your website.
Open the inspector tool in your browser and navigate to network requests.
Make an action that triggers capturing the custom dimension. In our example, that will be visiting a blog post.
On the list with network requests, click ppms.php.
On the list with query string parameters, look for the custom dimension. In our case it is the dimension2: John Doe.
When you’re happy with how the tracking code works, go back to Tag Manager and click Publish to make the changes go live.

Custom reports: how to use custom dimensions

To use custom dimensions in custom reports, follow these steps:

Go to Menu > Analytics.
Navigate to Custom reports.
Click Add a report.
Pick the report type.
Name the report.
On the right, click Dimensions.
Scroll down until you see Custom dimensions.
Pick the custom dimension you want to use in the custom report.
Set up all conditions and click Create report.

Make a custom dimension inactive

To make the custom dimension inactive, follow these steps:

Go to Menu > Analytics.
Navigate to Settings.
On the left, click Custom dimensions.
Find the custom dimension that you want to work with and on the right, click the three-dot icon.
Click Deactivate.