--- title: "Configuration" manual: "Matomo Widgets" version: "main" permalink: "https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:configuration@main" source: "Configuration/Index.rst" rendered: "2026-09-21T17:59:19+00:00" --- # Configuration {#configuration} Target group: **Developers, Integrators** **Table of Contents** - [Site configuration](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:site-configuration-1@main) - [Configuration keys](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:configuration-keys-1@main) - [Custom dimensions](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:custom-dimensions@main) - [Configuration independent from a site](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:configuration-independent-from-a-site@main) - [Permission of widgets](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:permission-of-widgets@main) - [Cache configuration](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:cache-configuration@main) - [Widget configuration](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widget-configuration-1@main) ## Site configuration {#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](../Images/SiteManagement.png) > [!WARNING] > **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 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](https://docs.typo3.org/p/brotkrueml/typo3-matomo-integration/main/en-us/Introduction/Index.html#introduction) 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](https://matomo.org/faq/general/faq_114/). > [!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](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ApiOverview/SiteHandling/UsingEnvVars.html#sitehandling-using-env-vars) for > better security. - **Active Widgets** You can activate or deactivate each available [widget](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets@main) 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](https://matomo.org/faq/how-to/faq_60/) 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}* > [!NOTE] > Please ensure that the template has the same structure as the > configuration of the 404 page title. For example, for the default template > specified above: > > ```javascript > _paq.push([ > 'setDocumentTitle', > '404/URL = ' + encodeURIComponent(document.location.pathname+document.location.search) + ' /From = ' + encodeURIComponent(document.referrer) > ]); > ``` > > Pay attention to whitespaces! ## Configuration keys {#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](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets@main) as "Active widgets value". - **matomoWidgetsConsiderMatomoIntegration** - *type:* bool - *Default:* false With installed [Matomo Integration](https://docs.typo3.org/p/brotkrueml/typo3-matomo-integration/main/en-us/Index.html) 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](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:configuring-custom-dimensions@main). - **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](https://matomo.org/faq/how-to/faq_60/) 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 {#configuring-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** ```yaml 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 `. 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 {#configuration-independent-from-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](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:configuration-keys@main) can be used, such as: **config/matomo_widgets/demo.yaml** ```yaml matomoWidgetsActiveWidgets: 'actionsPerDay,bounceRate,visitsPerDays' matomoWidgetsIdSite: 1 matomoWidgetsTitle: 'Demo' matomoWidgetsUrl: 'https://demo.matomo.cloud/' ``` ## Permission of widgets {#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](https://docs.typo3.org/c/typo3/cms-dashboard/14.3/en-us/Configuration/PermissionHandlingOfWidgets.html#permission-handling-of-widgets). > [!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 {#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 {#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** ```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](https://developer.matomo.org/api-reference/reporting-api) for a reference of the available > Matomo parameters and values. You can find all configuration parameters in the chapter [Widgets](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets@main). > [!TIP] > **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.