MainWP Matomo Extension
See Matomo Cloud or On-Premise visitor data for every child site in your MainWP Dashboard.
Put Matomo traffic numbers on your Overview pages and client reports
The MainWP Matomo Extension is a Pro MainWP add-on that brings each child site’s Matomo (formerly Piwik) visitor data into your MainWP Dashboard and your client reports. You connect a Matomo Cloud or Matomo On-Premise instance, assign a Matomo property to each site, and read the numbers in the Matomo Analytics widget and in Pro Reports.
Traffic checks and report numbers in one place
Checking client traffic by hand means switching between Matomo and MainWP for each site, then copying the numbers into client reports yourself. The MainWP Matomo Extension shows Matomo data on the Overview pages of your MainWP Dashboard, and Pro Reports tokens fill in visits, bounce rate and other summary values for each site.
Features
The MainWP Matomo Extension covers the Matomo connection, the property each site reports to, and the numbers your reports pull in.
| Feature | What it means for you |
|---|---|
| Matomo Analytics widget | See Matomo data on your MainWP Dashboard Overview page and on each site’s Overview page. |
| Matomo Cloud or On-Premise | Connect with your Matomo URL and an API token. As of version 5.2.1, Matomo installed in a subfolder, such as https://example.com/matomo/, connects too. |
| Property assignment per site | Pick the Matomo property for each site when you edit it in MainWP, or turn on Automatically assign properties to sites to let MainWP match them. Each property belongs to one MainWP site. |
| Reporting period and sync frequency | Choose the reporting period, how often MainWP fetches data from Matomo, and a connection timeout from 1 to 30 seconds. |
| Pro Reports tokens | Add [piwik.visits], [piwik.pageviews], [piwik.pages.visit], [piwik.bounce.rate], [piwik.new.visits] and [piwik.avg.time] to client reports. |
| MainWP Abilities | Twelve abilities read the connection status, list cached properties, preview and update site assignments, read analytics snapshots and trends, and request, check or cancel background refreshes. |
| Team Control permissions | In the MainWP Team Control Extension, the Matomo extension permission decides which roles can view or change a site’s Matomo property. |
| Protected API token | The saved token is stored apart from the general settings row, stays hidden in the form, and goes to the Matomo address it was saved for. |
Requirements
The MainWP Matomo Extension reads from your own Matomo instance, so you need Matomo access and an API token alongside the add-on.
| Item | Requirement |
|---|---|
| License | MainWP Pro |
| Matomo | A Matomo Cloud or Matomo On-Premise instance available over HTTPS. Subfolder installations need version 5.2.1 or later of the extension. |
| Matomo API token | A token with access to the properties you want to use |
| PHP | 8.1 or later on your MainWP Dashboard site for version 5.2.1 or later |
| WordPress | 6.2 or later on your Dashboard site for version 5.2.1 |
| Child sites | Set up for tracking in Matomo, with the Matomo tracking code added manually or through a separate plugin, and added to your MainWP Dashboard |
| MainWP Abilities (optional) | WordPress 6.9 or later and a MainWP Dashboard with Abilities API support |
Setup: connect Matomo and assign properties
Setting up the MainWP Matomo Extension has two parts: connect your Matomo instance once, then pick a property for each site.
Connect Matomo
- Go to MainWP > Add-ons > Matomo > Settings and find Matomo Connection.
- Enter the address you use to open Matomo in Matomo URL, including any subfolder, and paste your token into API token. The address must use HTTPS.
- Select the Reporting period and Sync frequency, and set Connection timeout to a value from 1 to 30 seconds. Turn on Automatically assign properties to sites if you want MainWP to match properties for you.
- Click Save Settings. MainWP checks the connection and loads the properties your token can see.
Assign a Matomo property to each site
- Go to MainWP > Sites > Manage Sites, find the site, and click Edit.
- In General Options, under Matomo (formerly Piwik), select the site’s property in Matomo account property.
- Click Update Site, then repeat for your other sites.
Full instructions, URL rules and the 5.2 update steps: MainWP Matomo Extension documentation.
How the analytics reach your Dashboard
The MainWP Matomo Extension reads analytics from your separate Matomo instance through the Matomo API, using the token you saved. It keeps cached analytics for each assigned site and refreshes them on the sync frequency you choose. After an update to version 5.2, an administrator opens a wp-admin page on your MainWP Dashboard once, and the connection settings and site data move to the new storage.
Matomo Extension FAQ
How often does the MainWP Matomo Extension update its data?
The MainWP Matomo Extension fetches data from Matomo on the Sync frequency you choose under MainWP > Add-ons > Matomo > Settings. It also fetches data right after you save the settings, and the Fetch Latest Data button on the Data tab pulls new numbers on demand.
Which Matomo numbers can I add to Pro Reports?
Pro Reports can show six Matomo summary values for the report’s date range: visits [piwik.visits], actions [piwik.pageviews], actions per visit [piwik.pages.visit], bounce rate [piwik.bounce.rate], unique visitors [piwik.new.visits] and average time on site [piwik.avg.time]. Despite its name, [piwik.new.visits] shows unique visitors.
What happens to Matomo data when I delete a site or the add-on?
Your Matomo property and tracking data stay on your Matomo server in both cases. Removing a site from MainWP removes its local Matomo mapping and cached analytics. Deleting the MainWP Matomo Extension removes its saved connection and token, its database tables and options, and its scheduled tasks. Deactivating it keeps the saved connection and local data and clears its scheduled tasks.
What do I need to pay for?
The MainWP Matomo Extension is part of MainWP Pro. You also need access to Matomo, either a Matomo Cloud account or your own self-hosted Matomo On-Premise instance.
Where do I get support?
The Matomo team handles issues with Matomo itself; see matomo.org. MainWP support handles issues with the MainWP Matomo Extension.