Matomo Analytics Integration Plugin

Matomo Analytics is a web analytics platform available as a hosted Cloud service or a self-hosted On-Premise installation. It provides traffic and engagement reports together with controls for data collection, retention, privacy, and consent.

The Matomo Analytics Integration plugin connects a Publii site to the Matomo JavaScript tracker or Matomo Tag Manager. It supports standard and cookieless tracking, optional tracking features, and Publii's built-in Cookie Banner. You do not need to edit your theme or paste the complete Matomo installation snippet into every page.

Requirements

Publii 0.45 or newer.
A Matomo Cloud account or a working Matomo On-Premise installation.
A Matomo URL and numeric Website ID for the direct tracker, or a complete Matomo Tag Manager container script URL.
An existing Publii Cookie Group if you enable Cookie Banner integration.

Matomo Cloud and Matomo On-Premise are separate from the Publii plugin. Check the current Matomo plans and hosting requirements before choosing an installation type.

Installing the Plugin

Open Publii's App Menu using the three-dot icon in the top-right corner.
Select Plugins.
Click Get More Plugins to open the Publii Plugin Marketplace.
Open the Matomo Analytics plugin page and download the installation package.
Return to the Plugins screen in Publii and click Install Plugin.
Select the downloaded ZIP file. Do not extract it before installation.

Choosing an Integration Method

The plugin provides two integration methods. Select one before entering the connection details.

Matomo Analytics tracker – Publii creates the standard Matomo page-view tracker. Use this method when you want to configure link tracking, 404 reporting, the Heartbeat Timer, Do Not Track support, cookieless tracking, and consent behavior directly in the plugin.
Matomo Tag Manager – Publii loads a published Matomo Tag Manager container. The tags, triggers, variables, and their consent requirements are configured in Matomo Tag Manager.

Do not use both methods for the same Matomo page-view tag unless you have designed the setup to prevent duplicate tracking.

Finding the Matomo URL and Website ID

Use these values when Matomo Analytics tracker is selected:

Sign in to Matomo.
Open Administration using the settings icon.
Go to Websites → Tracking Code.
Select the website you want to track.
Locate the base Matomo address and the value used by setSiteId in the JavaScript tracking code.
Enter the base address in Matomo URL and the numeric identifier in Website ID.

A Matomo Cloud address usually looks like https://example.matomo.cloud/. A self-hosted installation may use a subdomain or directory, such as https://analytics.example.com/ or https://example.com/matomo/.

Enter the base URL only. Do not add matomo.js, matomo.php, a query string, or a page fragment. The plugin normalizes the trailing slash and uses the address to build the tracking endpoint.

Finding the Matomo Tag Manager Container URL

Use these steps when Matomo Tag Manager is selected:

Sign in to Matomo and open Tag Manager.
Select the website and container.
Publish the container to the environment you want to use.
Open Install Code.
Find the complete JavaScript address assigned to g.src. It will resemble https://analytics.example.com/js/container_AbC12345.js.
Copy only that complete address and paste it into Container script URL in Publii.

The complete URL is required because development and staging containers can include an environment name and access token in the filename. See the Matomo Tag Manager embedding guide for current instructions.

Activating the Plugin

Open Tools & Plugins in Publii.
Find Matomo Analytics Integration and enable its switch.
Click the plugin card to open its options.
Select the integration method and enter the required connection details.
Review the tracking and privacy settings, then save the changes.
Regenerate and publish the website.

The plugin does not generate integration code when a required URL, Website ID, or consent setting is missing or invalid.

Matomo Analytics Plugin Options

Configuration

Integration method – Selects the direct Matomo Analytics tracker or Matomo Tag Manager.
Matomo URL – The base URL of a Matomo Cloud or self-hosted installation. This field appears for the direct tracker and is required.
Website ID – The positive numeric website identifier from the Matomo tracking code. This field appears for the direct tracker and is required.
Custom matomo.js URL – An optional complete URL for the Matomo JavaScript file. Leave it empty for a standard installation. Use it only when the tracking code supplied by Matomo points to a separate CDN, reverse proxy, or customized script location.
Container script URL – The complete JavaScript URL copied from the Matomo Tag Manager installation code. It is required when Tag Manager is selected.
Output code in Preview Mode – Includes the integration code in pages opened through Publii Preview. The option is disabled by default because preview visits can affect analytics reports. Enable it temporarily when inspecting the generated code or network requests.

Tracking Options

These settings apply to the direct Matomo Analytics tracker. Configure equivalent behavior inside Matomo Tag Manager when you use a container.

Track downloads and outbound links – Calls Matomo's automatic link tracking after the page view. It is enabled by default.
Track 404 error pages – Changes the Matomo page title on Publii's 404 page to include the missing path, query string, and referrer. This makes broken URLs easier to identify in Matomo reports.
Improve visit duration with Heartbeat Timer – Sends a heartbeat when an active visitor leaves or hides a page. Matomo can use this signal to improve visit-duration reporting for single-page visits and the final page of a visit.
Minimum heartbeat interval – Sets the minimum active time before a heartbeat can be sent. Enter a value of at least 5 seconds. The plugin uses 15 seconds when the value is missing or invalid and limits values above 3600 seconds.
Respect the browser's Do Not Track setting – Tells Matomo not to track a visitor when the browser sends a Do Not Track preference. Matomo notes that browser support for this header is limited and the feature is deprecated, so do not use it as a replacement for consent controls that apply to your site.

Privacy and Consent

Disable Matomo tracking cookies – Runs the direct tracker without Matomo analytics cookies. This option is available when Publii Cookie Banner integration is disabled.
Use Publii's Cookie Banner – Connects the integration to an existing Cookie Group in Publii's advanced Cookie Banner configuration.
Consent behavior – Chooses whether Publii blocks tracking until consent or Matomo tracks without cookies until cookie consent is granted. This option appears for the direct tracker when Cookie Banner integration is enabled.
Cookie Group ID – The internal ID of an existing group under Site Settings → Privacy Settings → Cookie Groups. An Analytics group with the ID analytics is suitable for many sites.

Using Matomo Cloud

Matomo Cloud uses separate addresses for the JavaScript file and the tracking endpoint. Enter your Cloud base URL in Matomo URL, for example https://example.matomo.cloud/. Leave Custom matomo.js URL empty.

The plugin sends tracking requests to the configured Cloud instance and detects the corresponding cdn.matomo.cloud address for matomo.js automatically. Add a custom script URL only when the tracking code supplied for your account explicitly uses another location.

Using a Self-Hosted Matomo Installation

Enter the public base URL of the Matomo installation and its numeric Website ID. The plugin normally loads matomo.js and sends requests to matomo.php at that base address.

If a proxy, CDN, or security configuration serves the JavaScript file elsewhere, enter its complete URL in Custom matomo.js URL. The tracking endpoint remains connected to the base Matomo URL.

Disabling Matomo Tracking Cookies

Enable Disable Matomo tracking cookies when you want the direct tracker to run without Matomo analytics cookies and you are not using Publii's Cookie Banner integration. The plugin calls Matomo's disableCookies method before recording the page view.

Disabling cookies does not stop JavaScript tracking requests. It can also reduce the accuracy of returning-visitor and related reports. Cookieless tracking does not automatically remove consent or disclosure requirements. Your complete Matomo configuration, the information you collect, your visitors, and applicable law determine whether prior consent is required. Read Matomo's cookieless tracking guide before publishing.

Configuring the Publii Cookie Banner

Open Site Settings → Privacy Settings.
Enable the Cookie Banner and its advanced cookie configuration.
Create or review the group used for analytics consent.
Set a Group ID, such as analytics. Use letters, numbers, hyphens, or underscores without spaces. The first character must be a letter or number.
Open the Matomo plugin and enable Use Publii's Cookie Banner.
Enter the exact same value in Cookie Group ID.
Select the consent behavior, save the settings, and regenerate the website.

If the Cookie Banner, advanced configuration, selected group, or Group ID is missing, the plugin does not output the Matomo integration. This prevents an incomplete consent configuration from loading tracking code.

Read the Publii Cookie Banner documentation for details about Cookie Groups. Publii's privacy tools do not replace a review of the tracking technologies and legal requirements that apply to your website.

Choosing the Consent Behavior

Wait for Consent Before Tracking

Publii blocks the direct tracker and all requests to Matomo until the visitor accepts the selected Cookie Group. No Matomo page view is sent before that consent.

If the visitor later withdraws consent, the tracker remains blocked after the page reloads. The plugin also removes standard Matomo cookies whose names begin with _pk_ and match the configured Website ID. It cannot remove renamed cookies, cookies created by custom scripts, or cookies outside the current website's accessible domain and path.

Track Without Cookies Until Consent

The plugin loads the direct tracker immediately and uses Matomo's cookie-consent API. Before consent, tracking requests continue without Matomo analytics cookies. When the visitor accepts the selected group, the plugin allows Matomo to create its tracking cookies.

If consent is not present on a later page load, the plugin tells Matomo to delete its tracking cookies and continues in cookieless mode. Choose this behavior only after confirming that cookieless tracking without prior consent is appropriate for the website. Matomo explains the distinction between tracking consent and cookie consent in its tracking consent guide.

Using Consent with Matomo Tag Manager

When Cookie Banner integration is enabled for Matomo Tag Manager, Publii blocks the entire container until the visitor accepts the selected Cookie Group. The plugin does not provide the adaptive cookieless mode for Tag Manager.

Use container-level blocking only when every tag inside the container can share the same consent category. If the container includes analytics, marketing, functionality, or other tags with different requirements, configure consent for each tag inside Matomo Tag Manager. Publii cannot inspect those tags or delete cookies created by arbitrary scripts loaded through the container.

Updating from Version 1.x

Version 2.0.0 requires Publii 0.45 or newer. Update Publii before installing the new plugin version if the site uses an older release.

The plugin retains the existing Matomo URL, Website ID, preview, Cookie Banner integration, and Cookie Group settings. A valid version 1.x configuration continues to use the direct Matomo Analytics tracker after the update. No manual migration is required.

After updating, open the plugin options and review the new tracking and consent settings. Regenerate the website and test the published output before deploying it to production.

Testing the Integration

Regenerate and publish the site to a staging or public URL.
Open the browser's developer tools and select the Network panel.
For the direct tracker, filter requests for matomo.js and matomo.php. For Tag Manager, filter for container_.
Open Matomo's real-time visits or visits log and confirm that the test page view appears.
If Cookie Banner integration is enabled, test the site in a new browser profile. Check the page before consent, after accepting the selected group, and after withdrawing consent and reloading.

Ad blockers, browser privacy features, Content Security Policy rules, and consent settings can prevent Matomo requests. Test with those factors in mind before changing the plugin configuration.

Preview Mode

The plugin does not output Matomo code in Publii Preview unless Output code in Preview Mode is enabled. This default prevents local preview activity from entering analytics reports.

Enable the option temporarily when you need to inspect the generated source or requests. Disable it again after testing and use a staging or public URL for the final check.

Troubleshooting

No Matomo code appears in the generated page – Confirm that the plugin is enabled and that the required values for the selected integration method are valid. If Cookie Banner integration is enabled, verify that the banner, advanced configuration, and selected Cookie Group all exist.
The direct tracker does not load – Enter a complete HTTP or HTTPS base address without matomo.js, matomo.php, credentials, a query string, or a fragment. Confirm that the Website ID is a positive whole number.
Matomo Cloud returns a script error – Enter the Cloud base URL and leave Custom matomo.js URL empty unless Matomo supplied a different script address.
A custom tracker script is rejected – Enter a complete HTTP or HTTPS URL whose path ends in .js. Do not include a page fragment.
The Tag Manager container does not load – Copy the complete JavaScript URL from Install Code. Confirm that the selected environment has a published container version.
Tracking remains blocked after consent – Check that the Cookie Group ID in the plugin exactly matches the Group ID in Privacy Settings, including capitalization.
Cookies remain after consent is withdrawn – Reload the page. Automatic cleanup applies to standard _pk_ cookies for the configured Website ID in the blocking tracker mode. Custom cookie names and cookies created by Tag Manager tags must be handled separately.
Reports contain duplicate page views – Check the theme, Custom HTML, Tag Manager, and other plugins for another Matomo installation. Keep one page-view implementation unless the duplication is intentional.
404 pages are not labeled separately – Enable Track 404 error pages, regenerate the site, and test Publii's generated 404 page.
Preview visits appear in Matomo – Disable Output code in Preview Mode and regenerate the preview.
No requests appear although the configuration is correct – Test without an ad blocker and review the browser console, Content Security Policy, network errors, and Matomo's real-time reports.

For tracker behavior and advanced configuration, see the official Matomo guides for JavaScript tracking, tracking and cookie consent, and Matomo Tag Manager embedding.