What is a Custom Dimension?

With Custom Dimensions you can assign any custom data to your visitors or actions (like pages, events, site search, …) and then visualize the reports of how many visits, conversions, pageviews, etc. there were for each Custom Dimension. They are similar to Custom Variables see the comparison of Custom Dimensions and Custom Variables.

Custom Dimension Reporting

Depending on the scope of a Custom Dimension you can access a report either via the “Visitors” or “Behaviour” menu in the Dashboard section. The name of the menu item will be the name of your Custom Dimension. Matomo (Piwik) reports all the standard metrics: unique visitors, visits, actions, time on site, bounce rate, exit rate, etc. The available metrics may be different depending on the scope.

custom dimension reporting

The custom dimension values are also displayed in the Visits Log:

  • In the left of each visit in the Visits Log, the Custom Dimensions of scope “Visit” are displayed.
  • On hover on each Pageview or Action, the values of your “Page” scope dimensions will be displayed in the tooltip.

The custom dimension values are also displayed in the Visitor Profile. On the left, you will find the list of all custom dimensions values that were tracked for this visitor (for all “Visit” scope dimensions).

Installing Custom Dimensions

If you are using Matomo 4, then Custom Dimensions is already a part of the Matomo setup.

Creating Custom Dimensions

To get to the “Manage Custom Dimensions” screen, go to “Administration” by clicking the cogwheel icon in the top right. There will be a new menu item “Custom Dimensions” in the left menu. They can be edited by anyone having at least ‘Write’ or ‘Admin’ access for a specific website. For each website or app different Custom Dimensions can be created.

Managing Custom Dimensions

Before creating a new Custom Dimension you have to choose whether you need a new dimension in scope “Visit” or “Action”.

Custom Dimensions in scope “Visit” can be sent along any tracking request and are stored in the visit of a specific visitor. If you set different values for a given “Visit” scope dimension during the lifetime of a visit, the last value set (in this visit) will be used. A typical example could be any device information or the version of the app the visitor is using.

Custom Dimensions in scope ‘Action’ can be sent along any action (page view, download, event, etc.). A typical example would be for example to track a language along any page view, download or event.

Tracking a Custom Dimension

In general you can track any Custom Dimension via the JavaScript Tracker, the PHP Tracker or via the HTTP Tracker API. Some more trackers might support the tracking of Custom Dimensions as well. To find out how to track a specific Custom Dimension the easiest way is to go to the “Manage Custom Dimensions” screen. By clicking on the edit button you will find the tracking instructions:

tracking custom dimensions via javascript or SDK

Alternatively you can find tracking instructions in the Plugin FAQ.

Managing Custom Dimensions

We have seen how to create new custom dimensions, how to track their values, and how to view reports. Now let’s learn about other other capabilities.

Using extractions to set a custom dimension value

Extractions may be defined for Custom Dimensions in scope “Action” so that the value is extracted from the Page URL, Page Title or a Page URL query parameter automatically instead of having to set it manually in your website or app.

An example use case could be a Custom Dimension named “Language”. Matomo can automatically extract the language code from the URL during any tracking request (no tracking code is needed in the website or app).

To extract the value from a Page URL or Page Title you need to define a Regular expression with exactly one sub-expression (one ( followed by a )). For example if you want to extract the language en from page_en.html you could define the pattern page_(.{2}).html. Note that the pattern matches the whole page URL or page title.

Multiple extraction rules can be defined for one Dimension so if the first rule doesn’t match it will check the following rules and try to extract the correct value.

custom dimensions extraction rules - content groups

Check out our FAQ section for more details on how to use URL extractions with Custom Dimensions.

Deactivating a Dimension

It is not possible to delete a Dimension, instead they can be deactivated. Once you deactivate a Dimension the links in the menu will disappear, no value will be tracked for this Dimension and no report will be generated for it anymore. Once the Dimension is activated again everything will work as before and previously generated reports as well as raw log data will be still available.

Segmenting a Custom Dimension by Action type

By default a report for a Custom Dimension in scope “Action” will show values across all kinds of actions (page views, events, content tracking, downloads, etc.). If you want the Custom Dimensions report to show values only for a specific type of actions, say “Page views” or “Downloads”, you can create a new segment using “Action Type”:

segmenting action type custom dimensions

Data Limits for Custom Dimensions

Custom Dimensions are useful to track any information related to any action or visitors. Here are some more information about the data limits in use:

  • Up to 5 Custom Dimensions in scope “Action” and 5 Custom Dimensions in scope “Visit” can be used by default for each website. A higher number of custom dimensions can be made available by changing the schema of the database (schema changes can be slow depending on the size of the database). Learn more. You can typically increase the limit and track up to 50 dimensions in each website.
  • Each value is limited to a length of 255 characters in length
  • Learn more about the Data Limits in Matomo

Learn more