Create a custom dimension

Analytics

Needed permissions: owner or manage

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

Create a session custom dimension

To create a session 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 a session dimension.
    Add a session custom dimension in Piwik PRO
  5. Name the dimension.
  6. Click Save.
  7. 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.
    Set values for a session custom dimension

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

  8. Note Dimension ID. You’ll need it in the next steps.
    Session custom dimension (ID)
  9. Go to Menu > Tag Manager.
  10. Navigate to Variables.
  11. On the left, click Create new variable.

    Note: Each site or app has a different construction, so each variable setup will be unique.

  12. Name the variable and click Save.
  13. Choose the variable type.
    Variable in Piwik PRO
  14. Set up the variable.
  15. When you’re done, click Save.
  16. Navigate to Tags.
  17. Click Add new tag.
  18. Name the tag and choose the following type: Custom dimension.
  19. In Dimension ID, type the ID. You created in step 8.
    Custom dimension (ID)
  20. In Dimension value, type the value. This is the variable you created in steps 9 –– 15.
    Custom dimension (value)
  21. In Advanced tag settings, choose Consent type. Set it up if you use Consent Manager. The tag will fire only when the selected consent is given by a visitor.
  22. Respect visitor privacy is turned on by default. Leave it as is, if you want to respect visitors who set a Do-Not-Track option in their browser or opted out from tracking.
  23. Adjust trigger conditions.
  24. When you’re done, click OK for the trigger.
  25. Click Save for the tag.
  26. Test your tag in debug mode.
  27. When you’re happy how the tag works, click Publish.
  28. After some time, data will be collected and you’ll it under Menu > Analytics > Reports > Custom dimensions.

Create an event custom dimension

To create a session custom dimension, follow these steps:

  1. Go to Menu > Analytics.
  2. Navigate to Settings.
  3. On the left, click Custom dimensions.
  4. Click Add an event dimension.
    Add an event custom dimension in Piwik PRO
  5. Name the dimension.
  6. Click Save.
  7. 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.

  8. Note Dimension ID. You’ll need it in the next steps.
    Event custom dimension (ID)
  9. Go to Menu > Tag Manager.
  10. Navigate to Variables.
  11. On the left, click Create new variable.

    Note: Each site or app has a different construction, so each variable setup will be unique.

  12. Name the variable and click Save.
  13. Choose the variable type. We’ll choose DOM element for our example.
    Variable (DOM element)
  14. 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.
    Variable settings
  15. When you’re done, click Save.
  16. 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 new tag > Virtual page view).
    • For events: the custom event tag (Menu > Tag Manager > Tags > Add new 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.

  17. When you’re done, test your tag in debug mode.
  18. When you’re happy how the tag works, click Publish.
  19. After some time, data will be collected and you’ll see it under Menu > Analytics > Reports > Custom dimensions.
    Custom dimension report in Piwik PRO

Debug mode: how to check your custom dimension

To check if values for your custom dimension are collected, 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.
    Debug mode in Piwik PRO
  8. Navigate to Variables.
    Debug mode in Piwik PRO
  9. Scroll down until you see the name and value of your custom dimension.
    Debug mode in Piwik PRO

Inspector tool: how to check your custom dimension

To check if values for your custom dimension are collected, 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.
    Inspect your website
  5. On the list with query string parameters, look for the custom dimension. In our case it is the dimension2: John Doe.
    Inspect your website
  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.

Custom reports: how to use custom dimensions

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.
    Custom reports in Piwik PRO
  7. Scroll down until you see Custom dimensions.
  8. Pick the custom dimension you want to use in the custom report.
    Custom reports in Piwik PRO
  9. Set up all conditions and click Create report.

Make a custom dimension inactive

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 the three-dot icon.
  5. Click Deactivate.
    Custom dimensions in Piwik PRO

Was this article helpful?

Technical support

If you still have some questions, visit our community.
There’s always someone ready to help!

Back to help center