Consent and redaction
The default posture is the private one: no cookies, Do-Not-Track and Sec-GPC
honored, URLs scrubbed before they leave your application, and bots excluded. You opt
into more identification, never out of it.
'privacy' => [
'honor_dnt' => true, // skip on DNT:1 / Sec-GPC:1
'cookieless' => true, // JS: disableCookies before trackPageView
'consent' => 'none', // none|cookie|full; any other value is read as full
'browser_feature_detection' => false, // JS: disableBrowserFeatureDetection while false
],
Cookieless by default
privacy.cookieless pushes disableCookies before the page view, so the client-side
tracker sets none. Server-side identification is cookieless by construction — see
how a visitor is identified.
Storing a cookie is one of two things that need consent. Reading information on the
visitor's device is the other (Art. 5(3) of the ePrivacy Directive, § 25 TDDDG in
Germany), and matomo.js does it unless told not to: it reads the screen resolution, the
browser plugins and the client hints of the device, and builds its visitor hash from
them. privacy.browser_feature_detection is false by default, so the snippet pushes
disableBrowserFeatureDetection too, and the tracker reads none of it. Matomo's reports
then show no screen resolution and no plugins, and its device detection works from the
user agent alone. The server side asks for client hints only under
middleware.client_hints, which is off by default as well.
Matomo knows disableBrowserFeatureDetection since 4.7. An older matomo.js stops at the
command and tracks nothing, so update such an instance, or set
browser_feature_detection to true there.
With no cookies, no device features and a rotating, salted identifier, nothing is stored on or read from the visitor's device and there is no cross-site identifier — which is what makes a consent banner unnecessary in the default configuration. Whether that holds for your jurisdiction and your configuration is a question for your own legal advice, not for this page; what the package guarantees is the technical posture.
Do-Not-Track
honor_dnt covers both signals — the legacy DNT: 1 header and Sec-GPC: 1, the
Global Privacy Control. It is checked server-side, in the
tracking gate, before anything about identity is evaluated. The
client-side tracker is told about it too, via setDoNotTrack.
Honoring it server-side is the part that matters: a DNT header cannot be respected
by JavaScript that has already run.
Consent postures
'consent' => 'none', // none | cookie | full
| Value | The snippet emits | Use when |
|---|---|---|
none | No consent call | The cookieless default — nothing to consent to |
cookie | requireCookieConsent | You track with cookies and gate only the cookies on consent |
full | requireConsent | You gate all tracking on consent |
With cookie or full, Matomo holds hits back until your consent manager calls
setCookieConsentGiven or setConsentGiven. Wiring that call is your consent
manager's job — the package emits the requirement, not the grant.
Matomo 5 lets the tracker read the device again once the visitor consents:
setConsentGiven, rememberConsentGiven and setCookieConsentGiven each turn the
detection back on. Matomo 4 does not, so there your consent manager pushes
enableBrowserFeatureDetection along with the grant, a command Matomo knows since 4.8.
Any other value is read as full. A typo such as 'Full' or 'required', or a boolean,
therefore asks for consent rather than tracking without it. php artisan matomo:test
names such a value, since the tracker records nothing until consent is granted.
Under full the server side waits as well. The tracking gate lets a server-side hit through
only when the request carries mtm_consent, the cookie in which matomo.js remembers a consent,
so your consent manager has to call rememberConsentGiven rather than setConsentGiven alone.
Until then the page views, the beacons and the hits from your code are refused as no_consent,
and the <noscript> pixel is left out of the page, because a visitor without JavaScript cannot
give that consent.
A job or a command has no visitor and no cookie, and is not asked: send from there only what
you may. none and cookie leave server-side tracking alone, because it sets no cookie.
A publishable privacy-policy partial
php artisan vendor:publish --tag=matomo-analytics-views
That publishes a small partial describing the cookieless Matomo setup, which you can include in your privacy policy and edit freely:
@include('matomo-analytics::privacy-policy')
@include('matomo-analytics::privacy-policy', ['heading' => 'Analytics'])
Read it before you publish it. It describes the package's default configuration, so if you changed the defaults — enabled cookies, stopped anonymizing — the text needs changing too.
The partial calls the IP addresses anonymized. For every hit the package sends from your
server, that is anonymize_ip, on by default: an IPv4 address leaves your application with
its last octet zeroed (a /24), an IPv6 address with only its first 48 bits, and
anonymize_ip_bytes cuts more of both
(details). The cookieless visitor id is
derived from the same truncated address. A page that loads matomo.js sends
its hits from the browser straight to Matomo, so for those Matomo's own IP anonymization
decides. Turn it on there as well if your policy says the addresses are anonymized.
The paragraph ships in English, German, Spanish, French, Italian, Dutch and Portuguese.
A regional locale such as pt_BR, de_AT or fr-CA reads its language, which Laravel's
own lookup never falls back to. To change the wording, publish the lang files with
--tag=matomo-analytics-lang; a file you add for the region itself is read first.
URL redaction
On by default. Secrets and PII are stripped out of tracked URLs before they reach Matomo:
?token=abc123&page=2 -> ?token=REDACTED&page=2
#access_token=eyJ…&token_type=bearer -> #access_token=REDACTED&token_type=bearer
'privacy' => [
'redact' => [
'enabled' => true,
'replacement' => 'REDACTED',
'query_params' => [
'token', 'api_key', 'apikey', 'api-key', 'access_token', 'refresh_token',
'id_token', 'jwt', 'code', 'state', 'auth', 'auth_token', 'password',
'passwd', 'pwd', 'secret', 'client_secret', 'signature', 'sig', '_token',
'session', 'session_id', 'sessionid', 'email',
'X-Amz-Signature', 'X-Amz-Credential', 'X-Amz-Security-Token',
'X-Goog-Signature', 'X-Goog-Credential',
],
'base_domains' => env('MATOMO_REDACT_BASE_DOMAINS', []),
'patterns' => [],
'keys' => ['url', 'urlref', 'link', 'download', 'c_t', 'c_p'],
],
],
Eight things worth understanding about it.
The key survives, the value does not. A redacted parameter keeps its name and
loses its value, so a report still tells you "a password-reset link was opened"
without the token being in your analytics, your Matomo access logs, or a dashboard
someone shares in a meeting. Parameter matching is case-insensitive, and it covers
the array forms token[]=, token[0]= and token[a][b]= with the brackets written
out or percent-encoded as %5B and %5D. Laravel reports the URL of a request in
the encoded form. A listed name counts only as the parameter's own name, never as a
key inside another parameter: user[password]= is left alone, and so is
filter[state]=open, where the name describes the page. The patterns example below
catches a secret nested that way.
A token in a path is covered by the route that carries it. Laravel's reset links carry the
token in the path, as in /reset-password/{token}?email=…, and so does the confirmation page of
a magic link, /magic-link/verify/{token}, where no parameter name reaches it. Every route the
application registers whose URI names a parameter from path_params has that segment redacted,
on the server and in the browser, in the page address and in the referrer of the page that
follows. The list holds token by default, and a config you published earlier reads the
shipped list. The token of the route password.reset, and of the paths the starter kits use,
reset-password/{token} and password/reset/{token}, is redacted whatever the list says; only
enabled => false switches it off. The address in ?email= is redacted by the email entry in
query_params.
A parameter can stand in the first segment of a route, as the slug of a workspace does in
{workspace}/members. Put it on the list, and only a path of that route's shape loses it:
https://app.example.test/acme/members reaches Matomo as
https://app.example.test/REDACTED/members, while the host, the rest of the path and a page such
as /login stay. The pattern starts behind the host and the path the application is served
under. A route with several parameters from the list has each of them redacted, and a route that
is nothing but the parameter redacts the first segment of every path.
A tenant's subdomain loses its name. An application that serves each tenant on a subdomain of
its own, <slug>.example.test, sends that slug with every page view, and the referrer of the next
page sends it again. Matomo needs none of it to count. Name the base domain, and every label in
front of it is redacted, on the server and in the browser, in each field keys lists:
MATOMO_REDACT_BASE_DOMAINS=example.test
https://northwind.example.test/instances/42 -> https://REDACTED.example.test/instances/42
The domain itself, example.test, stays, and so does every host that does not end in it, so an
external referrer still shows where a visit came from. Several domains go in as a comma-separated
list, or as 'base_domains' => ['example.test', 'example.org'] in a published config. A leading
*. is dropped, and an entry that is still no domain name, a URL or a host with a port, is refused
with its own wording. The replacement stands in the host, so keep it a word a host may hold: the
default REDACTED is one. Where Matomo tracks only the URLs of the site, REDACTED.example.test
has to be one of them, which an entry *.example.test already covers.
The application's own hosts keep their name. Where the application itself answers on a host
under the same domain, such as app.example.test for the product and api.example.test for its
API, those hosts would arrive as REDACTED.example.test like every tenant, and the reports could no
longer tell them apart. Name what stands in front of the domain in them, and they stay:
MATOMO_REDACT_BASE_DOMAINS=example.test
MATOMO_REDACT_KEPT_LABELS=app,api
https://app.example.test/settings -> https://app.example.test/settings
https://northwind.example.test/ -> https://REDACTED.example.test/
An entry has to match everything in front of the domain, so app keeps app.example.test and not
app.northwind.example.test, and eu.app keeps eu.app.example.test. The browser applies the same
patterns as the server. In a published config the entries go in as 'kept_labels' => ['app', 'api'],
and one that is no label is refused with its own wording.
A presigned storage URL loses its signature. Storage::temporaryUrl() on an
S3-compatible disk, such as S3, R2, MinIO or Spaces, writes X-Amz-Signature and
X-Amz-Credential into the URL, and X-Amz-Security-Token as well when the application
signs with role credentials, as on Vapor or EC2. GCS writes X-Goog-Signature and
X-Goog-Credential.
Anyone holding such a URL can download the file until it expires, and matomo.js reports
one as a download or an outlink when a visitor clicks it, or as the piece of a content block
that shows it. Those names are redacted; the algorithm, date and lifetime stay, so a report
still shows that the link was a presigned one.
The fragment is read like the query. OAuth, OpenID Connect and magic-link flows
put their tokens after the #, and the page-view and Web Vitals beacons send the
page's whole address, fragment included. A parameter there is redacted the same way.
patterns handles what a parameter list cannot. Any regular expression here is
applied to the URL. This is how you scrub an identifier that lives in a path segment
rather than a query parameter, or a secret nested inside another parameter:
'patterns' => [
'/\b[\w.+-]+@[\w-]+\.[\w.-]+\b/', // email addresses anywhere in the URL
'#/invoices/\d+#', // numeric invoice ids in the path
'/(?<=password%5D=|password\]=)[^&#]*/i', // a password nested as user[password]
],
keys decides which payload fields are scrubbed. By default the page URL, the
referrer, link and download targets, and the target and piece of a tracked content block
(c_t, c_p). matomo.js fills the piece with the address of the image, video or audio in
the block when it carries no data-content-piece, so a piece is often a URL.
The referrer is included, and that is worth knowing in both directions: the parameters of
an incoming URL are scrubbed, while its host is left intact — which is what keeps referrer
reports, and the AI Assistants acquisition channel, working. Only a host under
one of your base_domains loses its tenant label. urlref
stands for both copies of it that matomo.js sends: the referrer of the page, and _ref, the
one it keeps in a cookie for conversion attribution and adds to every request.
The client-side tracker is redacted in the browser. A page that loads matomo.js
sends its hits from the browser straight to Matomo, so @matomoScript installs the
redaction as the tracker's request processing: before a request leaves the page, the
tenant labels under base_domains, the secret of a route path and the names in query_params are
redacted in the fields keys lists. patterns are PHP
regular expressions and apply to server-side hits and the beacons only. A Tag Manager
container configures its own tracker, and nothing is installed there. Matomo keeps a
single request-processing function, so a setCustomRequestProcessing of your own
replaces this one when it runs after the snippet, and is replaced by it when it runs
before.
Redaction is not a substitute for not putting secrets in URLs. It is the safety net for the ones that are already there — a password-reset link, a signed download URL, an OAuth callback.
Server-side opt-out
Matomo's own opt-out widget sets a cookie on the Matomo domain, which your server-side tracker cannot see. So an application that tracks server-side needs a first-party cookie, and the gate honors one:
use MatomoAnalytics\Privacy\OptOut;
return back()->withCookie(OptOut::enable()); // stop tracking this browser
return back()->withCookie(OptOut::disable()); // opt back in
'privacy' => [
'opt_out' => [
'respect' => true,
'cookie' => 'matomo_opt_out',
],
],
enable() returns a permanent cookie; disable() returns the forget-cookie that
clears it. Attach either to a response from your own opt-out control.
Set it server-side. These are Laravel cookies, so they pass through the
EncryptCookiesmiddleware. A plaintext cookie of the same name written by client-side JavaScript is dropped as invalid and will not opt anyone out. If you want a JavaScript control, have it hit a small endpoint that returnsOptOut::enable().
@matomoOptOut is the control a visitor
uses in the browser. Its cookie, mtm_consent_removed, stops matomo.js, and the gate reads it
as well, so one click opts a visitor out of both sides. privacy.opt_out.respect switches
both cookies off together.