Drupal with Matomo for self-hosted analytics: what the integration does
A Drupal team can replace Google Analytics with a self-hosted Matomo instance by installing the contributed Matomo Analytics module, which adds Matomo tracking to the Drupal site. The module only places the tracking code and forwards page views and events to a Matomo server. Matomo itself is a separate service that your team installs, patches and operates in infrastructure it controls, so the analytics data is stored there rather than in a third party's platform. Drupal teams usually reach this decision when analytics data must stay in their own environment, when the Google Analytics setup has become hard to justify for compliance reasons, or when they want a single place to manage tags and consent logic.
The current Matomo Analytics release, 8.x-1.26, supports Drupal ^10.3 or ^11, so a site on Drupal 10.3 or later can use it without a custom bridge. Drupal and all contributed files hosted on Drupal.org that are derivative works of Drupal are licensed under GPL-2.0-or-later, and there is no paid edition of Drupal itself. The module is therefore free to install, and the costs that matter are the ones around it: hosting and operating the Matomo server, its database and backups, the time to configure goals and consent behavior, and the ongoing work of keeping both Drupal and Matomo current. Confirm the Matomo server version and its own requirements with the Matomo project before sizing hardware, because those requirements sit outside the Drupal module's scope.
Before you commit, confirm three things in your own environment: which Drupal version and PHP version the site runs, where the Matomo server will be hosted, and which teams will own its upgrades. Matomo's tracking behavior, consent options and data retention settings are configured on the Matomo side and then reflected in the Drupal module, so the implementation plan should name an owner for each. A short test on a staging site will show whether the existing reports, goals and campaign tracking can be reproduced before you switch off the old tag.
What a Matomo connection needs before configuration
Before the Matomo Analytics module can send tracking data, the Drupal site, the Matomo instance and the network path between visitors' browsers and Matomo each need to be ready. Confirm these items in order, because a gap in any one of them shows up as missing or broken tracking that is hard to diagnose later.
Drupal version and PHP runtime
The Matomo Analytics 8.x-1.26 release supports Drupal ^10.3 or ^11. Drupal 10 requires PHP 8.1 or later and Drupal 11 requires PHP 8.3 or later, so a site on an older PHP runtime needs a runtime upgrade before the module can be installed. Check the PHP version on the same servers that serve the site, including any separate worker or cron hosts. Confirm the supported branch on the module page before you plan the target version.
Web server and database platform
Drupal runs on Apache, Nginx and other web servers, with MariaDB, MySQL, PostgreSQL or SQLite as the database. Confirm that your chosen combination is one the Drupal system requirements list for your target core version, and that the same platform is used in every environment that will test tracking. Record the versions in your build documentation so that the Matomo configuration is reproduced consistently across staging and production.
Reachable self-hosted Matomo over HTTPS
The module needs the address of a Matomo instance that you run in infrastructure you control. Use an HTTPS address with a valid certificate, because browsers block mixed content and a plain HTTP tracker will fail on secure pages. Confirm that the Matomo server is reachable from the public internet or from the visitor networks that will load the tracker, and that its own version is compatible with the module release you plan to install. Matomo version compatibility must be confirmed in the Matomo documentation and on the module page before go-live.
Site ID and API token
Each Drupal site or environment should map to a Matomo site ID, so that staging traffic does not pollute production reports. The module also needs an authentication token for Matomo's API, which should belong to a dedicated user with the narrowest permissions the module requires. Confirm the exact token scope with the Matomo documentation and the module page, and store the token in your secrets manager rather than in exported configuration.
Network rules from browsers to Matomo
Tracking requests travel directly from visitors' browsers to Matomo, so firewalls, web application firewalls, content security policies and ad-blocking rules all affect whether events arrive. Allow the tracker script and tracking endpoint on the Matomo host, and confirm that your Content Security Policy permits the Matomo origin. Test from a clean browser profile and from a network outside your office, because internal tests often pass when public visitors are blocked.
How to configure the Matomo Analytics module step by step
This sequence takes a Drupal site from a bare module install to verified, consent-aware Matomo tracking that reports only the pages and visitors you intend to measure.
Install the module with Composer
A developer adds the Matomo Analytics module to the site's Composer project so it is versioned with the rest of the codebase and deployed through the same release pipeline. Use the 8.x-1.26 release, which the Drupal.org project page lists as supporting Drupal ^10.3 or ^11, and confirm the constraint against your core version before running the update. Check that the module appears in the composer.lock file and that the site's status report shows no missing dependencies after the install.
Enable the module and its dependencies
Enable the module from the Extend page or with Drush, which runs in the same environment as the site. Enabling it should not expose any tracking output yet, so confirm that the public pages do not yet include a Matomo script in the page source. This keeps the rest of the configuration reversible until the base URL and site ID are verified in the next step.
Enter the Matomo base URL and site ID
Open the module settings and enter the base URL of your self-hosted Matomo instance, along with the numeric site ID created for this Drupal site in Matomo. Keep the base URL on infrastructure your organization controls, and confirm with your Matomo administrator that the site ID belongs to the production website, not a test property. Save the form and check that the rendered page source references your own Matomo host, not a third-party domain.
Choose the tracking code and page scope
Select the tracking mode the module offers and decide which pages receive the tracking snippet, typically all public pages with administrative and back-end routes excluded. Record the decision in the project's configuration notes so that later changes are reviewed. Verify the result by loading a public page and a node edit form in a private browser window and confirming that the snippet appears only on the public page.
Exclude administrative and role-based paths
Add path exclusions for admin routes, user account pages and any other pages that should not be tracked, and configure role-based exclusions for internal editors or staff if your policy requires it. Test these rules by signing in as a user in an excluded role and visiting an excluded path, then confirm in the page source that no tracking snippet is present. Document the excluded paths so they can be reviewed during updates.
Gate tracking behind cookie consent
If your site requires consent before analytics cookies are set, connect the tracking snippet to your consent manager so Matomo loads only after the visitor opts in, and confirm the exact integration with your legal or compliance team. Test in a clean browser session that no Matomo request fires before consent is given, and that the request fires after acceptance. The check is a network log that shows no calls to your Matomo host before the consent action.
Verify hits in Matomo's real-time view
Open the Real-time visitors view in Matomo, then load a public page on the Drupal site in a fresh browser session that has consented. Confirm that the visit appears within the view and that the page title and URL match the page you loaded. If nothing appears, check the site ID, the base URL, and whether the browser's privacy settings or ad blocking are interfering, then repeat the test with a page that was excluded to confirm that exclusions behave as configured.
Which Drupal events and identifiers map to Matomo fields
This table compares each Drupal data point with the Matomo field it can populate and whether that mapping comes from module settings or needs custom code or Matomo-side setup. Use it to scope configuration work before the build starts. The main takeaway is that anything identifying a person stays out of tracking until the consent basis and legal reasoning are written down.
| Drupal data point | Matomo field or mapping | Where it is set |
|---|---|---|
| Page views and URL paths | Page URL and page title per visit | Matomo Analytics module tracking settings |
| Content type | Custom dimension or page title pattern | Module setting or custom dimension in Matomo, confirm with your module version |
| Anonymous or authenticated role | Custom dimension set per visit | Custom module or tracking script change; the module alone does not map roles by default |
| Interface language | Custom dimension or site-level language segment | Custom code; confirm the exact hook with your Matomo and module versions |
| Form submissions and downloads | Event or goal | Custom event code or Matomo goal configuration in the Matomo interface |
| User ID or email address | User ID field | Do not send by default; send only where consent and legal basis are documented and reviewed |
| Visitor IP address | Anonymization setting | Matomo server configuration; confirm anonymization options with your privacy team |
| Cookie consent state | Tracking enabled or disabled | Consent manager integration; confirm how your consent tool gates the tracking script |
How cookie consent changes the analytics design
Self-hosting Matomo changes where analytics data is stored, but it does not remove the obligations that apply when a visitor's browser sends that data. Matomo still processes personal data at the point of collection, so the consent and privacy notice questions stay on the table. The benefit is narrower and more concrete: the data lands on infrastructure your organization controls rather than with a third-party analytics provider, which reduces the transfer exposure that the EDPB guidelines on Article 3 and Chapter V treat as the central question. Read the EDPB Guidelines 05/2021 with your privacy counsel before you describe the setup to anyone as compliant. A self-hosted instance is an input to that assessment, not the assessment itself.
In the Matomo Analytics module, the practical control is when the tracking script is added to the page. Decide which consent categories gate it, then load the tracking code only after an affirmative choice, instead of loading it on every page and relying on a later opt-out. Confirm how your consent manager signals the decision to Drupal, because the module's tracking output has to respect that state on every request, including cached pages. Test this in a private browser session: decline, navigate several pages, and confirm that no Matomo requests leave the browser. Also confirm whether your cookie settings and the Matomo site configuration both honor opt-out, since each layer can override the other.
When visitors decline, measurement drops to the traffic that does not depend on consent, and your reports will show a visitor count that is lower than server logs. Plan for that gap in advance. Agree with stakeholders that consent-based reports describe consenting visitors only, and avoid presenting them as total site traffic. The consent banner itself, including its wording, default state, button design and record keeping, is a separate piece of work with its own review by your legal and privacy owners, and it should not be left to the analytics build. Ask your implementation partner to scope that work explicitly, so the consent decision is documented once and consumed by both the banner and the Matomo module.
Hosting Matomo in the EEA, the US or on-premises
Hosting Matomo in an EU data center that the client operates keeps stored analytics data inside the EEA. Storage alone is not a transfer, but the analysis turns on who can reach the system from outside the EEA. The EDPB Guidelines 05/2021 treat remote access from a third country as a transfer.
- Storage location: Keep the Matomo database, logs, backups and archives in facilities the client controls within the EEA, and document each location.
- Remote access: A support engineer in a third country who views a dashboard or log on screen counts as a transfer under the guidelines, even if no copy is made.
- Backups and replicas: Off-site copies, disaster recovery sites and log shipping services must also sit inside the EEA or rest on a valid transfer basis.
- Vendor and contractor reach: Managed service staff, remote hands and monitoring tools based abroad belong in the transfer map.
- Third-country law: An EU-established provider owned by a non-EU parent may still receive foreign demands, which the guidelines' Example 12 says controllers should assess before engaging that provider.
Before go-live, ask counsel to confirm where every administrator sits and which tools send data out of the environment.
A Matomo instance in a US cloud account stores EU visitor data outside the EEA, which is a transfer that needs a Chapter V basis under Article 44 of the GDPR. Choosing a US region does not remove the transfer. An EU region operated by a US-headquartered provider still raises the question of the provider's home jurisdiction.
- Transfer basis: The EU-US Data Privacy Framework covers only US organizations on the Data Privacy Framework List under Commission Implementing Decision (EU) 2023/1795. Confirm the provider's listing and track the pending appeal, Case C-703/25 P.
- Standard contractual clauses: The CJEU's Schrems II judgment held that standard contractual clauses remained valid, but using them still requires a documented transfer assessment.
- Government access: The CLOUD Act provision at 18 U.S.C. 2713 applies to data in a provider's possession, custody or control, whether that data sits inside or outside the United States.
- Supplementary measures: EDPB Recommendations 01/2020 state that where a provider needs data in the clear and public authority powers go beyond what is necessary and proportionate, no effective technical supplementary measure can be envisioned. Analytics reporting usually needs clear data, so encryption at rest alone may not close the gap.
- Exposure: Infringements of Articles 44 to 49 can draw fines of up to EUR 20 million or 4% of worldwide annual turnover under Article 83(5)(c).
Ask counsel to document the transfer basis, the transfer assessment and the provider's answer on government access requests before the account goes live.
Matomo on premises, including on an air-gapped network, gives the most direct control over where personal data sits. Transfers still need checking, because the analysis follows people and connections as well as storage. Air-gapping limits network paths, but it does not limit who can work on the system in person or remotely.
- Storage control: Data stays in client-owned facilities, so the transfer question centers on access and exports.
- Vendor sessions: Remote support sessions, screen sharing and vendor-hosted ticket attachments can expose data to people abroad, which the EDPB guidelines treat as a transfer.
- Media and updates: Software packages, container images and module updates brought across an air gap usually carry no visitor data, but confirm that imports and exports do not carry visitor data out.
- Outbound connections: Confirm which outbound connections the deployment makes, such as update checks, email relays and error reporting, then block or document each one.
- Controller duties: Owning the hardware does not remove obligations for lawful basis, consent, retention and handling access requests from visitors.
Ask counsel to confirm the decision in writing, including where each support engineer works and how privileged sessions are logged.
Securing the Matomo tracking path
Matomo receives visitor data from every page of the Drupal site, so the tracking path, the Matomo admin console and the Drupal code that emits tracking calls all need to be treated as production security surface. The cards below cover the controls that connect them and the patching routine that keeps the module supported.
HTTPS for Matomo and the tracker
Serve both the Matomo web interface and the tracking endpoint over HTTPS, and make sure the tracker URL configured in the Drupal module uses the same secure scheme as the site. A mixed-content setup lets browsers block tracking calls or exposes requests to network observers, and it can silently drop visits without any visible error. Check the tracker URL on a logged-out page in each browser you support, and confirm the certificate chain is valid on the host that receives requests.
Least-privilege Matomo tokens
The Matomo Analytics module needs a token to call the Matomo API for certain features, so create a dedicated Matomo user with only the view or write access that the integration requires, rather than reusing a super user account. Store the token in environment configuration or a secrets manager, never in exported Drupal configuration committed to version control. Rotate it when team members leave and after any suspected exposure.
Restricting Matomo admin access
Limit who can sign in to the Matomo interface, enforce strong authentication for administrators, and review site and user permissions on a fixed schedule. Matomo holds visitor behavior, IP handling settings and API access, so an administrator account is a more valuable target than most Drupal editor accounts. Ask the Matomo host to restrict the admin path by network or SSO where your identity model allows it.
Reviewing what user data is sent
Audit every value the Drupal integration pushes to Matomo, including page titles, URLs with query strings, user IDs, roles and any custom dimensions. Pages whose URLs contain tokens, email addresses or form data should be excluded or sanitized before tracking. Document the final list of fields so the consent records and privacy notice describe what is actually sent, and re-check the list after each new content type or module is added.
Keeping Drupal and the module supported
Drupal core and the Matomo Analytics module both receive security fixes, and the Drupal Security Team publishes advisories with CVE identifiers and risk scores. Security releases ship on the third Wednesday of the month, so schedule a patch window that follows that cadence and test the Matomo integration on staging after each update. Confirm that your current Drupal version is still supported and that the module release matches it, since the module's 8.x-1.26 release targets Drupal ^10.3 or ^11.
How to verify tracking before the switch-off
Run Matomo and Google Analytics side by side before removing the Google tag. The aim is to show that Matomo records the same pages, in roughly the same proportions, as the current setup, so that reports built on Matomo can be trusted from the switch-off date. Pick a set of representative URLs (the homepage, a high-traffic article, a form landing page and a checkout or application step if the site has one) and compare page view counts for each over the same date range. Expect differences. Google Analytics applies its own processing, and Matomo may exclude traffic that Google counts, including requests blocked by visitors' browsers. Record the gap for each page and agree in advance what size of difference is acceptable. The length of the parallel run depends on traffic volume and on the reporting cycles your teams depend on, such as month-end or campaign reviews, so confirm those requirements with the business owners before setting an end date.
Test each consent outcome separately. In the Matomo Analytics module settings, confirm that tracking loads only when your consent banner records acceptance, and that declining consent produces no Matomo requests in the browser's network panel. Repeat the test for anonymous visitors and for logged-in editors, because Drupal sessions and cached pages can change what the tracking code receives. Then check the exclusion rules: administration paths such as /admin and /user should not send page views, and any roles you excluded in the module configuration should be tested with a real account from each role. Keep a dated test log that lists the browser, the consent choice, the account type, the URL tested and the observed result. This log, together with the parallel-run comparison and the configuration export, becomes the evidence for your records of processing activities and any data protection impact assessment. Ask your privacy lead which format they need, and note that the evidence should describe the Matomo instance and its hosting location, since that location is part of the data residency argument in the rest of this page.
Common Matomo tracking failures and their fixes
This table lists the failures teams most often see after pointing a Drupal site at a self-hosted Matomo instance, with the likely cause and the fix for each. Read it as a checklist: match the symptom you see in Matomo against the first column, then verify the fix in the Matomo real-time visitor log before changing anything else.
| Symptom | Likely cause | Fix |
|---|---|---|
| No hits appear in Matomo | Base URL or site ID in the Matomo Analytics module points to the wrong instance, or the URL has a trailing path error | Confirm the Matomo base URL and site ID in the module settings, then check the real-time visitor log in Matomo while loading a public page |
| No hits, and the tracking script returns errors in the browser console | Script or tracking request is blocked by an ad blocker, a content security policy, or a firewall rule on the Matomo host | Review the Content-Security-Policy header and allow the Matomo host for scripts and requests, then test with a clean browser profile |
| Hits arrive from some pages but not secure ones | Mixed content: the Drupal site is served over HTTPS but the Matomo base URL is http:// | Change the Matomo base URL to https:// and confirm the Matomo instance has a valid certificate |
| Duplicate page views in Matomo | A second tag manager, a hard-coded Matomo snippet in the theme, and the module all load tracking at once | Keep one tracking path. Remove hard-coded snippets from templates and disable any other Matomo or Google Tag Manager container that fires the same tag |
| Hits missing for visitors who accepted cookies | The consent banner accepts consent, but the event that enables Matomo tracking is not wired to the module or the consent tool | Connect the consent tool's accept event to the tracking gate, then test accept and reject paths separately in a private window |
| Hits recorded for visitors who rejected consent | Tracking loads before the consent decision, or a cached page serves a tracking state from an earlier visitor | Gate the tracking script on consent in the page, confirm the consent state is not cached in shared page caches, and re-test with consent rejected |
| Inflated counts from editors and administrators | Logged-in users with editing or admin roles generate page views while building and reviewing content | Use the module's role exclusions for administrative and editorial roles, and exclude admin paths such as node editing and configuration pages |
| Counts drop or tracking stops after a Drupal upgrade | The module version is not compatible with the new Drupal core, or a theme change removed the tracking attachment | Check the module release notes against your Drupal version before upgrading, run the upgrade in a staging copy, and re-verify tracking on key templates |
| Tracking errors after a Matomo upgrade | Matomo server version and the tracking endpoint or API expectations have changed | Upgrade Matomo in a test environment first, then confirm tracking and any scheduled archiving or reports before the production change |
Questions teams ask before running Matomo on Drupal
What does a Matomo migration on Drupal cost, and what drives the price?
Cost is driven by the scope of the work, not by the module itself. The Matomo Analytics module is free to download from Drupal.org, so the spend goes to people: planning the tracking design, configuring the module, building or reviewing consent handling, testing across environments, and documenting the result. The biggest drivers are the number of Drupal sites and subdomains, how many goals, events and custom dimensions you want, whether Matomo is already running and how it is hosted, and how many reports your stakeholders need rebuilt. Ask any provider for a fixed-scope quote that lists these items separately, and ask which items recur, such as Matomo server upkeep and module updates after launch.
How long does the work take before the first tracked page view?
Duration depends on decisions and checks more than on configuration. The module setup itself is short, but you need agreed answers on which pages and roles are tracked, which events matter, how the tag interacts with cookie consent, and where the Matomo instance lives. Verification takes time too: you should confirm tracking on each Drupal environment, check that excluded roles and paths are not reported, and compare traffic with the previous tool for a period before retiring it. Ask a provider to show the decision checkpoints and the acceptance tests in its written plan, then match the schedule to your review cycles.
What must our team provide before the work starts?
Three things block progress if they are missing. First, administrator access to the Matomo instance, including the site IDs, the tracking URL and the ability to create or review sites and users. Second, a named owner for consent wording and the decision on whether analytics requires consent in each market you serve. Third, access to the Drupal environments (development, staging and production), with a way to deploy code through your normal release process. Also provide your current analytics inventory, the list of reports and goals stakeholders use, and the people who will approve the final configuration.
Can an internal Drupal team implement Matomo alone?
Yes, a team with Drupal experience can install the Matomo Analytics module, enter the site ID and tracking URL, and configure the basic tracking options. The harder parts are the ones that carry risk: designing consent behavior so that tags do not fire before a valid choice, deciding what personal data is collected, scripting event and dimension tracking, and testing across multiple sites. Internal teams often underestimate the review and documentation work. A useful test is whether someone outside the build team can explain, from your documentation alone, what is tracked, when, and under which consent state.
Does Matomo remove the need for a cookie banner?
No. Moving from Google Analytics to Matomo does not by itself remove the need for consent. Whether an analytics cookie or tag needs consent depends on your legal basis, the cookies set, the data collected and the rules in each jurisdiction where your users are located. Self-hosting changes where data is stored and who processes it, which matters for transfers, but it does not turn a non-essential tracker into an essential one. Ask your legal or privacy team to confirm the position, then design the Matomo tag, cookie settings and any opt-out behavior to match that decision.
Why does hosting location matter for Matomo on Drupal?
Hosting location determines whether analytics data leaves the jurisdictions you have committed to. GDPR Article 44 requires that every transfer of personal data to a third country meets Chapter V conditions, and EDPB Guidelines 05/2021 state that storage in a cloud outside the EEA and remote access from a third country are transfers. Running Matomo on infrastructure you control in your chosen region lets you define that boundary, but you must still confirm that backups, support access and any managed services follow the same rules. Check each provider's data location and access model with your privacy team before choosing a host.
What does the module support, and what should we confirm?
The Matomo Analytics module 8.x-1.26 release supports Drupal ^10.3 or ^11, and Drupal 11 requires PHP 8.3 or later, so check those versions against your current site before planning. Confirm which Matomo server version your instance runs and whether your tracking requirements, such as custom dimensions or specific tracking options, need settings the module exposes. Drupal 7 sites cannot be updated in place to Drupal 10 or later, so any legacy analytics setup on those sites is a migration task, not a configuration change.
How DeployOpen scopes and delivers a Matomo integration
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, so the Matomo server and the Drupal site can both run where your data policy requires. Engagements start with a written scope that sets out what the Matomo Analytics module will track, where the data is stored and how consent is handled.
How we scope
- Inventory the current Google Analytics tags, custom dimensions, goals and the reports your teams rely on today.
- Confirm the Drupal version, PHP version and hosting location so the module version and Matomo server are compatible.
- Record the consent approach, data residency requirements and retention periods in the written scope before build starts.
How we build
- Install and configure the Matomo Analytics module, setting the site ID, tracking URL and which roles, paths and pages are excluded.
- Deploy the Matomo server in your infrastructure with a database, backups and HTTPS configured to your standards.
- Test tracking on staging, including consent-gated loading, form submissions and cross-domain behavior where your site needs it.
How we hand over
- Provide a written configuration record listing module settings, tracking code placement and Matomo site definitions.
- Document the data flows, storage locations and access roles so your privacy and security teams can review them.
- Walk your administrators through reporting, user access and the upgrade steps for both Drupal and the module.
How we support
- Offer ongoing support and upgrades as a retainer, covering Drupal core releases and module updates.
- Monitor tracking after releases and after changes to consent tooling, so reports do not silently stop.
- Confirm with your legal or privacy team how any future change to the Matomo or hosting setup affects your records.
