matomo_widgets
brotkrueml/typo3-matomo-widgets
main
en
Chris Müller
This document is published under the Creative Commons BY 4.0 license.
Wed, 26 Nov 2025 17:58:37 +0000
Dashboard widgets showing Matomo reports
Table of Contents:
Table of Contents
The extension provides charts for various Matomo reports via the Reporting API.
The default parameters of the widgets can be adjusted to your needs, for example, in the Visits per month widget display 24 month instead of 12 months.
Tip
The Matomo Integration extension provides an easy way to integrate Matomo into TYPO3.
Example for a Matomo Dashboard
You can use the Matomo demo installation for evaluation. Just enter the following settings into the site configuration:
This extension uses semantic versioning which basically means for you, that
The changes between the different versions can be found in the changelog.
You can add the widgets to every TYPO dashboard. For your convenience, there is also a preset available with the most common widgets. You can select it when creating a new dashboard:
Select the Matomo dashboard preset
If you have a multi-site TYPO3 installation which connects to different Matomo instances there are presets for each configured Matomo instance available:
Select one of the Matomo dashboard preset
Note
The widget titles in the widget selection modal are always English if more than one Matomo instance is configured.
You can add the Matomo widgets like any other widget to a dashboard. Please note, that the widgets have to be enabled in the site configuration and the permissions for editors have to be granted to be able to use these widgets.
Hint
Most widgets need an activated module in Matomo to work. If a module is not available, an error is displayed in the widget. The parameters of the underlying data providers can be adjusted. Have a look into the Widget configuration section.
The following widgets are available. A link to the corresponding page in Matomo is displayed via in icon in the header bar of the widget if the report is available.
Tip
Do you miss a widget? Open a feature request and with a little luck the widget is available in the next release.
This widget displays the number of actions per day for the last 28 days (including the current day). Actions are:
Widget Actions per day
config.yaml Configuration/Services.yaml fileThis widget displays the number of actions per month for the last 12 months (including the current month). Actions are:
Widget Actions per month
config.yaml Configuration/Services.yaml fileNote
Please ensure that you use at least Matomo in version 5.5.
The AI assistants for the last 28 days shows this widget:
Widget AI Assistants
config.yaml Configuration/Services.yaml fileDisplay a list of the recent annotations in the last 365 days:
Widget Annotations
config.yaml Configuration/Services.yaml fileThis widget displays the number of conversions per month for the last 12 months (including the current month). For this, you have to define at least one goal.
Widget Conversions per month
config.yaml Configuration/Services.yaml fileThis widget provides a form to create an annotation conveniently from the TYPO3 backend:
Widget Create annotation
After submitting the form, a notification is displayed in the upper right corner of the browser window. If the creation of the annotation was successful, the Note field will be cleared.
config.yaml Note
The annotation is stored in Matomo under the user configured in the site configuration. A log entry has been created that can be viewed in the System > Log module. In addition to the user, the date, the note and the note ID received are saved:
Entry in the administration log
Note
For the creation of an annotation the according Matomo user needs only the
view permission.
The bounce rate for the last 28 days shows this widget:
Widget Bounce rate
config.yaml Configuration/Services.yaml fileThis report shows which browser plugins your visitors had enabled in the last 28 days:
Widget Browser Plugins
config.yaml Configuration/Services.yaml fileThe browser share for the last 28 days shows this widget:
Widget Browsers
config.yaml Configuration/Services.yaml fileDisplays a report of the campaigns for the last 28 days:
Widget Campaigns
config.yaml Configuration/Services.yaml fileThe content name report is part of content tracking. The widget displays the names, impressions and interaction rate of the content the visitors viewed and interacted with.
Widget Content Names
config.yaml Configuration/Services.yaml fileThe content piece report is part of content tracking. The widget displays the pieces, impressions and interaction rate of the content the visitors viewed and interacted with.
Widget Content Pieces
config.yaml Configuration/Services.yaml fileShows a list of countries from which the website was visited in the last 28 days:
Widget Countries
config.yaml Configuration/Services.yaml fileWith custom dimensions any custom data can be assigned to visitors or actions. Before a custom dimension can be used as a dashboard widget it has to be configured for a site.
The columns for a custom dimension widget depend on the scope of the custom dimension.
Configuration/Services.yaml fileThe <idDimension> is the ID of the custom dimension as available in the
Matomo configuration.
Example widget for a custom dimension with scope "action"
Example widget for a custom dimension with scope "visit"
Displays a list of JavaScript errors that occurred in the last 14 days:
Widget JavaScript errors
Clicking on the message opens a modal with details to this message:
Modal with details for a specific error
config.yaml Configuration/Services.yaml fileNote
To use this widget, JavaScript error tracking must be activated. This can be done either by adding the enableJSErrorTracking code or by enabling the corresponding option in the installed Matomo Integration extension.
A call-to-action widget is used to show a link to the configured Matomo installation:
Widget Link to Matomo
config.yaml Show the most viewed pages of a site for the last 28 days:
Widget Most viewed pages
config.yaml Configuration/Services.yaml fileTip
When you see URLs with the addition "- Others" then Matomo groups pages automatically after a given limit: You can increase the limit. Maybe you want then invalidate the historical reports to adopt the change.
The operating system families used by the visitors for the last 28 days:
Widget Operating system families
config.yaml Configuration/Services.yaml fileList of pages in the last 28 days which returned a status code 404 (not found):
Widget Pages not found
config.yaml Configuration/Services.yaml fileOverview of the search keywords that visitors searched for on the internal search engine:
Widget Site search keywords
config.yaml Configuration/Services.yaml fileList of the site search keywords that did not return any search result:
Widget Site search keywords with no result
config.yaml Configuration/Services.yaml fileThis widget displays the number of visits per day for the last 28 days:
Widget Visits per day
config.yaml Configuration/Services.yaml fileThis widget displays the number of visits per month for the last 12 months:
Widget Visits per month
config.yaml Configuration/Services.yaml fileTarget group: Administrators
Note
The extension in version main supports TYPO3 v13 LTS and TYPO3 v14, and requires at least Matomo in version 5.4.
The recommended way to install this extension is by using Composer. In your Composer-based TYPO3 project root, just type:
composer req brotkrueml/typo3-matomo-widgetsand the recent version will be installed.
In a legacy installation you can also install the extension from the TYPO3 Extension Repository (TER).
The extension offers some configuration which is explained in the Configuration chapter.
Target group: Developers, Integrators
Table of Contents
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
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..
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/.
Note
A Matomo instance is only connected to a site if a base URL and a site ID are defined.
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!
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.
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}
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:
_paq.push([
'setDocumentTitle',
'404/URL = ' + encodeURIComponent(document.location.pathname+document.location.search) + ' /From = ' + encodeURIComponent(document.referrer)
]);Pay attention to whitespaces!
The values from the Sites module are stored in the according YAML file. Following is a list of the possible keys and values.
string
''
Comma-delimited list of the widget names. You can find the according widget value in the widget overview as "Active widgets value".
bool
false
With installed Matomo Integration extension the URL and the site ID are taken from the configuration of that extension.
array
[]
Configuration for custom dimensions, see Custom dimensions.
int
''
The site ID to track into.
string
'404/URL = {path}/From = {referrer}'
The template for a 404 page, see How to track error pages in Matomo for more information.
string
''
The widgets are prefixed with this title.
string
''
The authorisation token pro retrieving the data via the API.
string
''
The URL of the Matomo installation.
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/ 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
matomo as shown in line 2 of the example. It is
followed by an array which describes the custom dimensions:
action or
visit.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.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.
It is possible to add widgets for one or more Matomo site IDs independently of
a site configuration. YAML files in the config/ folder
are included at build time in addition to the sites. Add a YAML file for each
Matomo site, for instance demo.. The configuration keys can be used, such as:
matomoWidgetsActiveWidgets: 'actionsPerDay,bounceRate,visitsPerDays'
matomoWidgetsIdSite: 1
matomoWidgetsTitle: 'Demo'
matomoWidgetsUrl: 'https://demo.matomo.cloud/'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.
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_ of this extension for the current 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.
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.
Target group: Developers
Have a look into the event dispatcher documentation if you are not familiar with PSR-14 events.
This event provides a possibility to adjust the site ID and the authentication token just before making the request to the Matomo API. This may be helpful in a big multi-site installation where you added a configuration independent from a site.
The event
\Brotkrueml\
provides the following methods:
->getIdSite()
->setIdSite()
->getTokenAuth()
->setTokenAuth() Dependent on the host name the current backend user is using we change the site ID:
<?php
declare(strict_types=1);
namespace YourVendor\YourExtension\EventListener;
use Brotkrueml\MatomoWidgets\Event\BeforeMatomoApiRequestEvent;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\Attribute\AsEventListener;
use YourVendor\YourExtension\Mapping\MatomoSiteMapper;
#[AsEventListener(
identifier: 'your-extension/before-matomo-api-request',
)]
final readonly class BeforeMatomoApiRequestEventListener
{
public function __construct(
private MatomoSiteMapper $matomoSiteMapper,
) {}
public function __invoke(BeforeMatomoApiRequestEvent $event): void
{
$hostName = $this->getRequest()->getServerParams()['REMOTE_HOST'];
if ($idSiteFromHostName = $this->matomoSiteMapper->getIdSiteFromHostName($hostName)) {
$event->setIdSite($idSiteFromHostName);
}
}
private function getRequest(): ServerRequestInterface
{
return $GLOBALS['TYPO3_REQUEST'];
}
}
Target group: Developers, Integrators
All strings are translatable. Translations are managed on Crowdin. Click the button below to help translating!
You can override translations in the usual way. Have a look into the according TYPO3 documentation: Custom translations.
However, if you feel that a translation provided by the translation server could be improved, please suggest an alternative on Crowdin.
Important
Before updating from a version before 0.3 to 1.x, 2.x or 3.x you should update to version 0.3.2 first and execute the upgrade wizards. Then update to the newest 1.x version and run the next upgrade wizards. Then you can upgrade to version 2.x, 3.x or 4.x.
No migration necessary.
No migration necessary.
The date ranges for the following widgets have been changed:
You can define your custom date ranges as described in the widget configuration.
No migration necessary.
In version 1.0 the format changed how the active widgets for a site are stored in the site configuration. For the migration of this configuration an upgrade wizard is available.
Attention
As with all upgrades: Please backup your data before executing the upgrade wizard!
The migration can be started in the TYPO3 backend via Admin Tools > Upgrade > Upgrade Wizard.
Migrate configuration in backend
Alternatively, you can also execute the migration wizard on a TYPO3 console:
Migrate configuration on console
Note
After executing the upgrade wizard you have to flush the cache via the module Admin Tools > Maintenance.
The migration wizard updates:
config/<site_identifier>/config.yaml To allow the configuration of more than one Matomo instance the configuration moved from the extension configuration to the site management.
Attention
As with all upgrades: Please backup your data before executing the upgrade wizard!
Note
If only one site is available the migration of the configuration can be done with a upgrade wizard. If there is more than one site configured you have to migrate the configuration by yourself. For this purpose the extension configuration is still available but has no effect at all.
The migration can be started in the TYPO3 backend via Admin Tools > Upgrade > Upgrade Wizard.
Migrate configuration in backend
Alternatively, you can also execute the migration wizard on a TYPO3 console:
Migrate configuration on console
Note
After executing the upgrade wizard you have to flush the cache via the module Admin Tools > Maintenance.
The migration wizard updates:
typo3conf/LocalConfiguration.php config/<site_identifier>/config.yaml Hint
If you use Git for versioning your site configuration you should consider to store the authentication token in an environment variable for better security.
As the identifiers of the dashboard widgets have changed they can also be migrated to the new identifiers. If multiple site configuration exist the widgets have to be assigned manually to the dashboards again.
The migration can be started in the TYPO3 backend via Admin Tools > Upgrade > Upgrade Wizard.
Migrate dashboard widgets in backend
Alternatively, you can also execute the migration wizard on a TYPO3 console:
Migrate dashboard widgets on console
Note
After executing the upgrade wizard you have to flush the cache via the module Admin Tools > Maintenance.
The migration wizard updates:
Use this upgrade wizard to migrate the widget identifiers to the new format. If multiple site configuration exist the widgets have to be assigned manually to the backend user groups again.
Migrate widgets identifiers of backend user groups in backend
Alternatively, you can also execute the migration wizard on a TYPO3 console:
Migrate widgets identifiers of backend user groups on console
The migration wizard updates:
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
WidgetConfiguration::getAdditionalCssClasses() in TYPO3 v13.4.14 (#56)Initial release