Configuration

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

Attention

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.

Important

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.

Note

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

Title

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.

Important

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.

Important

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

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}

Configuration keys

The values from the Sites module are stored in the according YAML file. Following is a list of the possible keys and values.

matomoWidgetsActiveWidgets
Type

string

Default

''

Comma-delimited list of the widget names. You can find the according widget value in the widget overview as "Active widgets value".

matomoWidgetsConsiderMatomoIntegration
Type

bool

Default

false

With installed Matomo Integration extension the URL and the site ID are taken from the configuration of that extension.

matomoWidgetsCustomDimensions
Type

array

Default

[]

Configuration for custom dimensions, see Custom dimensions.

matomoWidgetsIdSite
Type

int

Default

''

The site ID to track into.

matomoWidgetsPagesNotFoundTemplate
Type

string

Default

'404/URL = {path}/From = {referrer}'

The template for a 404 page, see How to track error pages in Matomo for more information.

matomoWidgetsTitle
Type

string

Default

''

The widgets are prefixed with this title.

matomoWidgetsTokenAuth
Type

string

Default

''

The authorisation token pro retrieving the data via the API.

matomoWidgetsUrl
Type

string

Default

''

The URL of the Matomo installation.

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:

config/sites/your_site/config.yml
 1matomoWidgetsActiveWidgets: 'actionsPerDay,actionsPerMonth'
 2matomoWidgetsCustomDimensions:
 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: 'https://demo.matomo.cloud/'

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

Note

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.

Configuration independent from a site

It is possible to add widgets for one or more Matomo site IDs independently of a site configuration. YAML files in the config/matomo_widgets/ folder are included at build time in addition to the sites. Add a YAML file for each Matomo site, for instance demo.yaml. The configuration keys can be used, such as:

config/matomo_widgets/demo.yaml
matomoWidgetsActiveWidgets: 'actionsPerDay,bounceRate,visitsPerDays'
matomoWidgetsIdSite: 1
matomoWidgetsTitle: 'Demo'
matomoWidgetsUrl: 'https://demo.matomo.cloud/'

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.

Note

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.

Example:

EXT:your_site_package/Configuration/Services.yaml
parameters:
   matomo_widgets.visitsPerMonth.parameters:
      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.

Tip

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.

Hint

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.