## What You'll Learn * Connect Matomo to MainWP Dashboard * Assign Matomo properties to managed sites * Complete the Matomo 5.2 storage migration * Use analytics in reports and through MainWP Abilities * Understand site deletion and add-on removal ## Prerequisites * An active MainWP Matomo Integration * A Matomo Cloud or Matomo On-Premise instance available over HTTPS at the site root * A Matomo API token with access to the properties you want to use * Sites configured for tracking in Matomo and added to MainWP Dashboard This integration reads data from a separate Matomo instance. It does not insert tracking code into your Child sites. Add the tracking code manually or through a separate plugin. Matomo for WordPress and Piwik Pro are not supported. Matomo Extension dashboard showing analytics data

Matomo Extension dashboard showing analytics data

The Matomo Analytics widget displays data on the MainWP Dashboard Overview and individual site Overview pages. Connect your account, then map each managed site to its corresponding Matomo property. ## Connect Matomo In MainWP Dashboard, go to **MainWP > Add-ons > Matomo > Settings** and locate **Matomo Connection**. Enter the address you use to open Matomo in **Matomo URL**, and paste your token into **API token**. If Matomo is installed in a subfolder, include the subfolder, such as `https://example.com/matomo/`. Otherwise, use the root address, such as `https://analytics.example.com`. The address must use HTTPS and must not contain a query string, fragment, or embedded username and password. For example, `http://analytics.example.com` is not supported. Select the **Reporting period** and **Sync frequency**, and set **Connection timeout (in seconds)** to a value from 1 to 30. Enable **Automatically assign properties to sites** if you want MainWP to match Matomo properties to your managed sites automatically. Click **Save Settings**. MainWP validates the connection and loads the properties available to the token. Resolve any connection or token error shown before continuing. ### Matomo URL rules MainWP saves a normalized form of the Matomo URL. Matomo 5.2.1 and later accept addresses such as: ```text theme={null} https://analytics.example.com https://example.com/matomo/ https://example.com/matomo/index.php https://example.com:8443/stats/ ``` A trailing `index.php` is removed, so `https://example.com/matomo/index.php` is saved as `https://example.com/matomo/`. MainWP rejects the URL and keeps the existing settings when: * A folder name contains characters other than ASCII letters, digits, `.`, `_`, `~`, and `-`. * A folder name is empty (two slashes in a row), `.`, or `..`, or contains `%` codes. * `index.php` appears anywhere other than the end of the address. * The server name contains unsupported characters, such as an underscore or non-ASCII letters. Enter international domain names in their `xn--` form. * The port is outside 1 to 65535, or the address is longer than 2048 characters. ### Saved API Tokens The **API token** field stays blank after saving. The saved token is protected and kept outside the general settings row; it is not displayed in the form. Leave the field blank to retain the saved token when saving settings for the same Matomo installation. The host, port, and subfolder must stay the same. Changing only `http://` to `https://` keeps the saved token. Paste a new token to replace it. Changing the server, port, or subfolder requires a token for the new installation. MainWP does not send the old token to a different address. Two Matomo installations in different subfolders on one server, such as `/matomo/` and `/stats/`, are separate connections with their own token, site assignments, and cached analytics. If MainWP reports that the saved connection cannot be verified or needs credential recovery, check the Matomo URL, paste the current API token, and click **Save Settings**. ### HTTPS and Certificate Verification Matomo 5.2 always verifies TLS certificates. The old `mainwp_piwik_sslVerifyCertificate` option no longer disables verification. Use a valid certificate and resolve certificate or trust-chain errors on the Matomo server before retrying the connection. ## Assign Matomo Properties to Sites Go to **MainWP > Sites > Manage Sites**, locate the site, and click **Edit**. Edit action for a managed site in the Manage Sites table

Edit action for a managed site in the Manage Sites table

In **General Options**, locate **Matomo account property** under **Matomo (formerly Piwik)** and select the corresponding property. Click **Update Site**, then repeat for the other managed sites. A Matomo property can be assigned to only one MainWP site. Properties already assigned elsewhere are unavailable for selection. If a conflicting selection is rejected, the previous valid assignment is retained; choose a different available property. If you change the Matomo server or replace its token, review your site assignments. Connection changes can invalidate earlier mappings and cached analytics, requiring properties to be assigned again. ## After Updating to Matomo 5.2 After updating, an administrator must open a MainWP Dashboard `wp-admin` page at least once. The upgrade moves connection settings and existing site data into the storage used by the new management features. Requests outside `wp-admin`, including API and report requests, cannot use that storage until the upgrade runs. Open **MainWP > Add-ons > Matomo > Settings** and check any migration notices. Large installations may need additional admin page loads to finish processing existing site data. * If the saved address uses HTTP, configure the HTTPS address and click **Save Settings**. * Saved subfolder connections from version 5.1.2 migrate automatically. If version 5.2 paused a subfolder connection, update to 5.2.1 or later. The connection resumes on an admin page load within about 15 minutes, without saving the settings again. * If MainWP asks you to save the connection again, verify the URL and token and follow the notice. * If site assignments could not be imported, save the connection to reload its property list, then review and save the affected site assignments. * Resolve any database or migration error displayed before relying on analytics or abilities. ## Team Control Permissions If you use the [Team Control Add-on](/add-ons/agency/team-control-extension), users need access to the Matomo Add-on to view or change **Matomo account property** when editing a site. Users without that permission cannot manage the mapping. To grant access, enable the Matomo extension permission when editing the role in **MainWP > Add-ons > Agency > Team Control**. Matomo abilities also enforce the Add-on permission and the selected site's access and edit permissions. Client Reports and Pro Reports have a separate read path. Report requests can read the six summary values below without the Matomo extension capability. Site access, Team Control restrictions, edit rights, a connected MainWP site, and a current Matomo assignment still apply. This access does not grant permission to change the connection or site mappings. ## Matomo Data in Reports Matomo 5.2 limits Client Reports and Pro Reports requests to these six summary values for the selected date range: | Matomo value | Meaning | Pro Reports token | | - | - | - | | `nb_visits` | Visits | `[piwik.visits]` | | `nb_actions` | Actions | `[piwik.pageviews]` | | `nb_actions_per_visit` | Actions per visit | `[piwik.pages.visit]` | | `bounce_rate` | Bounce rate | `[piwik.bounce.rate]` | | `nb_uniq_visitors` | Unique visitors | `[piwik.new.visits]` | | `avg_time_on_site` | Average time on site | `[piwik.avg.time]` | The token names remain unchanged. Despite its name, `[piwik.new.visits]` uses unique visitors, not a separate count of new visits. Matomo 5.1.2 returned additional data; integrations using those extra fields need to use the supported summaries or a separate data source. The report response excludes the connection and token. See [Available Pro Reports Tokens](/add-ons/agency/available-pro-reports-tokens) for the report token reference. ## MainWP Abilities Matomo 5.2 registers twelve abilities for reading connection status, listing cached properties, previewing and updating site assignments, reading analytics snapshots and trends, and requesting, checking, or cancelling background refreshes. Refresh requests are processed through WordPress scheduled tasks. An accepted request means it was queued; check the operation status to confirm completion. These features require WordPress 6.9 or later and MainWP Dashboard with Abilities API support. Use the dedicated [Matomo Abilities reference](/api-reference/abilities-api/matomo) for permissions, inputs, request examples, and error handling. ## Site Deletion and Add-on Removal Removing a managed site from MainWP also removes its local Matomo mappings, cached analytics, and related management records. This does not delete the property or tracking data from the Matomo server. Deleting the Matomo Add-on removes its saved connection and protected token, its own database tables and options, and its scheduled tasks. Deactivating the Add-on does not perform that uninstall cleanup. Save any information you need before deleting it; reconnect and reassign properties if you install it again. ## Unique Visitors for Custom Date Ranges MainWP requests Matomo analytics for custom date ranges, such as the last 7 or 30 days. Unique visitors may be unavailable for those ranges depending on the Matomo service and configuration. For Matomo On-Premise, follow [Matomo's guide to enabling Unique Visitors for custom date ranges](https://matomo.org/faq/faq_113/). Matomo Cloud does not support enabling this metric for custom date ranges. Do not add daily unique visitor counts together to estimate the unique visitors for the whole period; repeat visitors would be counted more than once. ## Related Resources * [Matomo Abilities](/api-reference/abilities-api/matomo) - Manage connections, mappings, and refresh operations * [Analytics Add-ons](/add-ons/analytics) - Browse analytics integrations * [Pro Reports Add-on](/add-ons/agency/pro-reports-extension-overview) - Include analytics in reports * [Available Pro Reports Tokens](/add-ons/agency/available-pro-reports-tokens) - Matomo token mappings This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.