Adding Custom Data to Matomo: Setting Up Custom Dimensions

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. Dimension creation and activation

In Administration, Custom Dimensions is available under Websites or Measurables. Setup requires the correct website, a named dimension and activation. 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. A value in 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. Matomo Tag Manager configuration

In Matomo Tag Manager, a variable reads the value, for example from a data-layer field. The data layer holds structured application information, such as the current membership tier. In the Matomo Configuration Variable, the dimension ID belongs under Custom Dimensions and the variable supplies the Value. The Matomo tracking tag must use that configuration. Preview should confirm that the value exists when the intended tag fires.

4. Validation before report comparisons

A controlled test checks the site ID, active dimension ID and transmitted dimension1 parameter. It covers at least two values and a missing value. For an Action dimension, a subsequent action reveals accidental carry-over. For a Visit dimension, a value change within one visit tests whether the last value is retained.

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.