Tutorial: Implementing Custom Dimensions in Matomo

Custom Dimensions add descriptive attributes to Matomo data: for example, a membership tier for a visit or an article category for a page view. A dimension is a label for grouping data, not a metric such as a count or duration. The setup requires a matching dimension ID, the right scope and a value available when the tracking request is sent.

1. Create and activate the dimension

In Administration, open Websites or Measurables and then Custom Dimensions. Select the correct website, create a named dimension and activate it. The generated numeric ID is the reference used in tracking; the same number on a different website need not describe the same attribute.

• Visit scope: One value describes the visit. If the value changes during the visit, the last recorded value wins. An upgrade from Standard to Premium therefore does not preserve both stages as separate visit values.
• Action scope: The value describes an individual page view, event, download or outlink. Different actions can carry different values.

2. Send a value with the relevant request

The following example assumes that ID 1 is an active visit dimension for membership tier. It belongs in an existing, configured Matomo tracker before the page view. The value premium is only an example and must come from the actual application state.

var _paq = window._paq = window._paq || [];
_paq.push(['setCustomDimension', 1, 'premium']);
_paq.push(['trackPageView']);

The example replaces the existing pageview call for this hit; adding a second call would count the page twice.

setCustomDimension does not send a request itself. The configured value accompanies subsequent tracking requests in the same page load until changed or removed with deleteCustomDimension. This also matters for Action dimensions: action scope does not automatically clear the JavaScript tracker value after one action. For a value intended for one action only, Matomo also supports request-specific dimension data. Removing a tracker value does not delete previously collected server data.

3. Configure Matomo Tag Manager

In Matomo Tag Manager, create a variable for the value, such as a data-layer field. In the Matomo Configuration Variable, add the dimension ID under Custom Dimensions and assign the variable as Value. The Matomo tracking tag must use that configuration. Preview should confirm that the value exists when the intended tag fires.

4. Validate before comparing reports

Check the site ID, active dimension ID and transmitted dimension1 parameter in a controlled test. Test at least two values and a missing value. For an Action dimension, follow with another action to detect accidental carry-over. For a Visit dimension, test a changed value within one visit and confirm the last-value behaviour.

Custom Dimensions have dedicated reports and can support segments and, where available, Custom Reports. Availability and metrics depend on scope and the installed product features. An arbitrary secondary dimension cannot be assumed in every standard report. Recent requests may appear in the visit log before aggregated reports finish processing.

Fictional example: membership tiers

The figures below illustrate a report layout only. They are not collected results or evidence that Premium membership causes longer visits. Page views and average visit duration measure different things; the definition of duration and the selected reporting period must be consistent.

Stable category labels keep reports comparable. Email addresses, names or uncontrolled free text should not be collected merely to distinguish categories. A useful tier value is premium, rather than a personal identifier.