Matomo Consent Mode: What CookieBeam Actually Sends
Matomo consent mode is a consent signaling integration that connects your cookie banner to Matomo's cookie consent layer through the _paq tracker queue. Matomo distinguishes between tracking consent (whether any data collection is allowed) and cookie consent (whether Matomo may store cookies on the visitor's device). CookieBeam's Matomo bridge operates at the cookie consent layer: when a visitor accepts the analytics category, the bridge calls _paq.push(['setCookieConsentGiven']), which tells Matomo it may set _pk_id and _pk_ses cookies. When the visitor rejects or withdraws, it calls _paq.push(['forgetCookieConsentGiven']), which clears those cookies and prevents new ones. The key distinction is that Matomo can continue tracking visits without cookies, using cookieless mode. The bridge tells Matomo whether cookies are allowed, not whether tracking itself is allowed. If you need to stop tracking entirely for rejected visitors, you'll need Matomo's separate requireConsent layer. This guide covers the mapping, behavior at each stage, and how to verify it.
TL;DR
CookieBeam listens for cookiebeam:consentUpdate (consent changes) and cookiebeam:consentRestored (returning visitors). If analytics_storage is granted (mapped from your banner's analytics category), the bridge calls _paq.push(['setCookieConsentGiven']). If denied, it calls _paq.push(['forgetCookieConsentGiven']). Matomo continues tracking cookieless either way, unless you've separately required tracking consent. No code changes needed beyond enabling the Matomo vendor bridge.
Matomo's Two-Layer Consent Model
Matomo distinguishes between tracking consent and cookie consent. Tracking consent (requireConsent) stops all tracking until the visitor agrees. Cookie consent (requireCookieConsent) lets Matomo track visits but withholds cookies until consent. Without either requirement, Matomo tracks fully and sets cookies immediately.
CookieBeam's bridge operates at the cookie consent layer. It calls setCookieConsentGiven and forgetCookieConsentGiven, which are Matomo's cookie consent API. It does not call setConsentGiven or forgetConsentGiven (the tracking consent API). This means if your Matomo instance uses requireCookieConsent, the bridge is exactly what you need. If it uses requireConsent, the bridge alone won't be enough. For the full picture of which Matomo configurations need consent at all, see Does Matomo Need Consent? It Depends on the Config. The official reference is Matomo's tracking consent documentation.
How CookieBeam Maps Categories to Matomo's Signal
The bridge reads the analytics_storage key from the resolved Consent Mode v2 state. That key maps from your banner's analytics category. It does not read ad_storage or marketing-related keys, because Matomo is an analytics platform, not an ad network. A visitor who rejects marketing but accepts analytics will still have Matomo cookie consent active. This is correct: Matomo's cookies (_pk_id, _pk_ses) serve analytics, not advertising.
| Banner Category | Consent Mode v2 Key | Matomo Signal |
|---|---|---|
| Analytics (accepted) | analytics_storage = granted | _paq.push(['setCookieConsentGiven']) |
| Analytics (rejected) | analytics_storage = denied | _paq.push(['forgetCookieConsentGiven']) |
| Marketing | ad_storage, ad_user_data, ad_personalization | Not used by Matomo bridge |
| Preferences | personalization_storage | Not used by Matomo bridge |
| Necessary | security_storage (always granted) | Not relevant |
Behavior at Each Stage
Before consent (first visit, banner untouched): The bridge hasn't fired yet. Whether Matomo tracks at this point depends on your Matomo configuration. If you've called _paq.push(['requireCookieConsent']) in your Matomo setup, it waits for the bridge to signal. If you haven't, Matomo tracks and sets cookies by default. CookieBeam's script blocking can prevent the Matomo tracker from loading at all if you've tagged it as analytics.
Visitor accepts analytics: CookieBeam dispatches cookiebeam:consentUpdate with analytics_storage: 'granted'. The bridge calls _paq.push(['setCookieConsentGiven']). Matomo sets its _pk_id (visitor ID, 13 months) and _pk_ses (session, 30 minutes) cookies.
Visitor rejects analytics: The bridge calls _paq.push(['forgetCookieConsentGiven']). Matomo clears its cookies. If requireCookieConsent is active, Matomo continues tracking but without cookies (cookieless mode). Each page view is treated as a new visitor.
Returning visitor: On later page views, the runtime re-announces the stored explicit choice as cookiebeam:consentRestored, and the bridge re-applies the matching Matomo call. A consent change on the current page fires cookiebeam:consentUpdate. This restatement ships with the runtime release that includes the vendor bridge fix. Machine-written defaults (such as US opt-out auto-grants) are not restated.
Consent withdrawal: Revoking analytics in the preferences panel fires forgetCookieConsentGiven immediately.
Cookieless Tracking: What Rejection Actually Means
This is the part that trips people up. When the bridge denies cookie consent, Matomo doesn't stop tracking. It stops using cookies. Page views, events, and goals still flow to your Matomo instance. The difference is accuracy: without cookies, Matomo can't link page views across sessions or recognize returning visitors. Each session appears as a new unique visitor. Your total visit count stays accurate, but visitor counts inflate and session duration drops to single-page averages.
If you want Matomo to stop tracking entirely when a visitor rejects, you need tracking consent (requireConsent), not cookie consent. The bridge doesn't send setConsentGiven, so you'd need to handle that separately. But for most GDPR implementations, cookie consent is the right layer: the Matomo FAQ on cookieless tracking notes that cookieless Matomo may not require consent at all under many interpretations of the ePrivacy Directive, since no data is stored on the device. Your legal team decides; the bridge gives you the technical mechanism.
How to Verify in Your Browser
Clear cookies and open DevTools
Open DevTools (F12), go to Application, and clear all cookies. Reload the page.
Check the pre-consent state
With the banner visible, look for _pk_id and _pk_ses cookies. If your Matomo uses requireCookieConsent and the script is loaded, these should be absent. Check the Network tab for requests to your Matomo instance (typically matomo.php): tracking requests may still fire, but without cookie parameters.
Accept analytics and check again
Accept cookies (or just analytics). _pk_id and _pk_ses should appear in the Application tab. Network requests to matomo.php should now include cookie-based visitor IDs.
Withdraw consent and verify
Open preferences and deselect analytics. The _pk_id and _pk_ses cookies should be cleared. Subsequent matomo.php requests should lack visitor ID parameters, confirming Matomo has fallen back to cookieless mode.
Common Mistakes
Not calling requireCookieConsent in your Matomo setup. The bridge sends setCookieConsentGiven, but Matomo ignores it unless you've first told it to wait. Add _paq.push(['requireCookieConsent']) before the Matomo tracker loads. Without it, Matomo sets cookies immediately and the bridge's grant is redundant.
Confusing cookie consent with tracking consent. Cookie consent lets Matomo track without cookies until the visitor agrees to cookie storage. Tracking consent stops all tracking until the visitor agrees. The bridge operates at the cookie layer. If your privacy policy promises zero tracking without consent, you need the tracking layer.
Assuming rejected visitors are invisible. Cookieless Matomo still tracks page views and events. The data is less accurate (no cross-session linking) but it's not absent. If your analytics reports show unexpected visit counts after implementing consent, that's cookieless visits being counted.
Frequently Asked Questions
Does Matomo track visitors without cookies by default?
It depends on your configuration. Out of the box, Matomo tracks with cookies. If you call _paq.push(['requireCookieConsent']), it tracks without cookies until consent is given. If you call _paq.push(['requireConsent']), it doesn't track at all until consent. CookieBeam's bridge handles the cookie consent layer.
What is the difference between tracking consent and cookie consent in Matomo?
Cookie consent (requireCookieConsent) lets Matomo track visits but stores no cookies until the visitor agrees. Tracking consent (requireConsent) stops all tracking entirely. The bridge uses cookie consent: setCookieConsentGiven and forgetCookieConsentGiven.
Does the CookieBeam Matomo bridge work with Matomo Cloud and self-hosted?
Yes. The bridge uses Matomo's standard _paq queue, which works identically in both Matomo Cloud and self-hosted installations. The _paq array is part of the JavaScript tracker, not the server.
Will I lose all analytics data if visitors reject cookies?
No. Matomo continues tracking in cookieless mode when cookie consent is denied. You lose cross-session visitor identification and accurate returning-visitor counts, but page views, events, and goals are still recorded. For a comparison with fully cookieless analytics tools, see Plausible and Fathom: do cookieless tools need consent?
Can Matomo run entirely cookieless with CookieBeam?
Yes. If you set requireCookieConsent in your Matomo config and a visitor rejects analytics in CookieBeam, Matomo tracks without cookies for that visitor. Some privacy lawyers argue this doesn't require consent at all under the ePrivacy Directive, since nothing is stored on the device.
Next Steps
For all vendor bridges in one place, see the consent mode integrations overview. If you also run HubSpot, the HubSpot consent bridge shares the same analytics_storage key and follows a similar pattern. For the difference between Google's Advanced and Basic consent modes, see Consent Mode v2: Advanced vs Basic. For a broader look at Google's consent mode implementation, see Google Consent Mode v2: Complete Implementation Guide.