Configuration

Site configuration

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

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.

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:

matomoWidgetsActiveWidgets: 'actionsPerDay,actionsPerMonth'
matomoWidgetsCustomDimensions:
  -
    scope: 'visit'
    idDimension: 1
    title: 'User Type'
    description: 'Displays the custom dimension for the user type'
  -
    scope: 'action'
    idDimension: 4
    title: 'Page Location'
    description: 'Display the custom dimension for the page location'
matomoWidgetsIdSite: 1
matomoWidgetsTitle: ''
matomoWidgetsTokenAuth: ''
matomoWidgetsUrl: '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:.

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:

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.

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:

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.

You can find all configuration parameters in the chapter Widgets.