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 have two scopes: session and event.
• You can create up to 25 custom dimensions for each scope. If you need more space, contact us.
• You can make custom dimensions active or inactive. But you can’t delete it.
• After creating a custom dimension you need to set its values. You can use Tag Manager or manual setup for that. The value can be up to 255 characters long.

About the scope for a custom dimension

The scope may be a bit confusing so we’ll explain it before you start. We’ve got two types of scopes: session and event.

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 you’d be left with the last value only at the end of the visit.

Now let’s move on to creating the custom dimension.

Create a custom dimension

Once you know what information you want to capture from which scope, you can create a custom dimension and set up the tracking. The setup is a few step process, so follow the instructions in this article to stay on the right track.

To create a custom dimension, follow these steps:

1. Go to Menu > Analytics.
2. Navigate to Settings.
3. On the left, click Custom dimensions.
4. Here you can choose the scope for the custom dimension: session or event. Click Add session dimension or Add event dimension.
   

   

5. Name the dimension.
6.  Click Save.
7. Set values for created custom dimension.
   • For a session custom dimension: use Tag Manager or manual setup.
   • For an event custom dimension: use extractions, Tag Manager or manual setup.

   Note: The value can be up to 255 characters long.

   Note: When you collect values for an event dimension with a custom dimension tag, you need to run the tag before the tracking code. This is because a custom dimension tag needs to send data before a page view is tracked. Read more about setting tag priority.

8. Note Dimension ID. You’ll need it to set up tracking in Tag Manager.
   

   

Make a custom dimension inactive

By default, each new custom dimension is set to be active. However, you can make it inactive at any time.

To make the custom dimension inactive, follow these steps:

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

   

Set up a variable for a custom dimension

In most cases, before modifying the tracking code, you will need to create the variable that will hold and pass information with the value of a custom dimension. For example, we’ve set up a custom dimension for a blog author and we need to pull out information on the author’s name from the blog post.

Using a variable for tracking custom dimension is a solution that works in some cases and  setting a variable differs depending on the website construction. If you need help in finding the best approach for your site, contact us and we’ll help you out. In case you feel confident with setting up a variable, read on.

To set the variable, follow these steps:

1. Go to Menu > Tag Manager.
2. Navigate to Variables.
3. On the left, click Create new variable.
4. Name the variable and click Save.
5. Choose the variable type. In our case, we’ll use the DOM element.
   

   

6. Set up the variable. In our case, 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.
   

   

7. When you’re done, click Save.

Modify the tracking code

When you have the custom dimension and variable ready, you can modify the tracking code. But no worries, you don’t need to engage the technical person for that, you can simply use our ready-made option available in the Piwik PRO tag in Tag Manager.

To modify the tracking code, follow these steps:

1. Go to Menu > Tag Manager.
2. Navigate to Tags.
3. On the left, click Piwik PRO. This is the tag with the tracking code.
4. In Collect data for custom dimensions, click + Add a dimension.
   

   

5. Enter Dimension ID. You created it under Analytics > Settings > Custom dimensions.
   

   

6. Enter Dimension value. For example, {{ Blog author }}.
   

   

7. When you’re done, click Save.
8. Click Publish.

Check the tracking code and publish

At this point, the best practice is to check if the tracking code catches the new custom dimension. To do that, you can use the debug mode and inspector tool in your browser.

To check the tracking code in debug mode, follow these steps:

1. Go to Menu > Tag Manager.
2. Navigate to Tags.
3. In the top-right corner, click Debug.
4. Your website will open in a new tab with debug mode running.
5. Make an action that triggers capturing the custom dimension. In our example, that will be visiting a blog post.
6. On the right, navigate to Events log.
7. Click the element on the top of the list, for example, stg.timer.
   

   

8. Navigate to Variables.
   

   

9. Scroll down until you see the name and value of your custom dimension.
   

   

By checking the variable in debug mode, we learn if the variable set in Tag Manager is working correctly. Now we need to use the inspector tool in our browser to check if the tracking code sends the dimension with the variable to Piwik PRO.

To check the tracking code with the inspector tool in your browser, follow these steps:

1. Open your website.
2. Open the inspector tool in your browser and navigate to network requests.
3. Make an action that triggers capturing the custom dimension. In our example, that will be visiting a blog post.
4. On the list with network requests, click ppms.php.
   

   

5. On the list with query string parameters, look for the custom dimension. In our case it is the dimension2: John Doe.
   

   

6. When you’re happy with how the tracking code works, go back to Tag Manager and click Publish to make the changes go live.

View the custom dimension report and use custom reports

Once the custom dimension is all set, Piwik PRO will start collecting data about it and present it in the custom dimension report. Additionally, the new dimension will be available in custom reports.

To view the custom dimension report, follow these steps:

1. Go to Menu > Analytics.
2. Navigate to Reports.
3. On the left, click Custom dimensions.
4. Pick the report you want to see.
   

   

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

1. Go to Menu > Analytics.
2. Navigate to Custom reports.
3. Click Add new report.
4. Pick the report type.
5. Name the report.
6. On the right, click Dimensions.
   

   

7. Scroll down until you see Custom dimensions.
8. Pick the custom dimension you want to use in the custom report.
   

   

9. Set up all conditions and click Create report.