Target group: Developers, Integrators

Site configuration

To configure the extension, go to Site Management > Sites and select the appropriate site configuration. Click on the Matomo Widgets tab:

Options in the site management

Options in the site management


Due to technical restrictions it is not possible to import the Matomo Widgets configuration from another file. It has to be stored in the site configuration's config.yaml.


If you adjust settings for the Matomo widgets in the site configuration you have to flush the cache via Admin Tools > Maintenance or in TYPO3 v11+ on console with vendor/bin/typo3 cache:flush.


A Matomo instance is only connected to a site if a base URL and a site ID are defined.


The title will prefix the widget title. You can leave it empty if you only have one site. But you should define a title when connecting multiple Matomo instances with your TYPO3 installation to differentiate them in the dashboard.

Consider configuration from Matomo Integration extension

This field is only displayed with installed and activated Matomo Integration extension. Enable this option to use common configuration (like base URL and site ID) from the "Matomo Integration" extension. In this case the common configuration is hidden from this tab.

Base URL

Enter the URL of your Matomo instance. This field is only available when Consider configuration from Matomo Integration extension is deactivated.


Please ensure TLS (https) is used for connecting to the Matomo installation as the authentication token is transferred in plain text!

Site ID

Enter the site id for the website. This field is only available when Consider configuration from Matomo Integration extension is deactivated.

Authentication token

Enter the authentication token (token_auth).

See the Matomo documentation for how to generate a token_auth.


It is recommended to create an own user in Matomo which has only read access to the given site. If you use Git for versioning your site configuration you should consider to store the authentication token in an environment variable for better security.

Active Widgets

You can activate or deactivate each available widget for a site. Deactivated widgets cannot be selected in the dashboard.

Pages Not Found Template

New in version 1.3.0.

Enter the template to specify the page title for pages which are not found. See How to track error pages in Matomo for more information. Please use the placeholders {path} for the path/URL and {referrer} for the referrer. This field is only available when Consider configuration from Matomo Integration extension is deactivated.

Default: 404/URL = {path}/From = {referrer}

Custom dimensions

Custom dimensions cannot be configured via the Site Management module as there is currently no possibility to add IRRE elements to a site configuration by an extension. So, custom dimensions have to be configured manually in the config/sites/*/config.yml file:

 1matomoWidgetsActiveWidgets: 'actionsPerDay,actionsPerMonth'
 3  -
 4    scope: 'visit'
 5    idDimension: 1
 6    title: 'User Type'
 7    description: 'Displays the custom dimension for the user type'
 8  -
 9    scope: 'action'
10    idDimension: 4
11    title: 'Page Location'
12    description: 'Display the custom dimension for the page location'
13matomoWidgetsIdSite: 1
14matomoWidgetsTitle: ''
15matomoWidgetsTokenAuth: ''
16matomoWidgetsUrl: ''

You begin the configuration for a custom dimension with the key matomoWidgetsCustomDimensions as shown in line 2 of the example. It is followed by an array which describes the custom dimensions:

scope (required)

The scope can be action or visit.

idDimension (required)

The id of the custom dimension as given in the Matomo configuration.

title (optional)

Give a meaningful title for the custom dimension. If it is left out or empty, the title will be Custom Dimension <idDimension>. You can also use a localisation string starting with LLL:. The title is shown as the widget title and in the Add widget modal.

description (optional)

The description is used in the Add widget modal. If it is left out or empty, it is not used. You can also use a localisation string starting with LLL:.


You can add as many custom dimensions as you want. Configured custom dimensions are always active and cannot be deactivated unless they are removed from the configuration.

Permission of widgets

You have to grant access for editors to use some or all of the Matomo widgets. You can find more information in the Dashboard manual.


Only activated widgets for a site are available. The widget titles are always English if more than one Matomo instance is configured.

Cache configuration

The extension stores the data retrieved from the Matomo instance in a cache for better performance. You can adjust the cache configuration, have a look into ext_localconf.php of this extension for the current configuration.

Widget configuration

The widgets provided by this extension are a starting point. You can adjust some parameters sent to the Matomo instance for each widget. An example would be to raise the displayed number of days for the Visits per month widget from 12 months to 24 months.


      period: 'month'
      date: 'last24'  # default value: 'last12'

period and date are parameters from the Matomo Reporting API. There are some more that might be interesting for you.


Have a look into the Matomo Reporting API for a reference of the available Matomo parameters and values.

You can find all configuration parameters in the chapter Widgets.


Please provide all necessary parameters for the Matomo API, otherwise you will get an error. This means that even if you only overwrite the date parameter, you must specify the period parameter even though it has not changed.