Skip to content

Fix dspace-customers#1083 R23: load Matomo only after Klaro consent, never replay declined activity - #1668

Merged
milanmajchrak merged 2 commits into
dtq-devfrom
fix/r23-matomo-consent
Oct 28, 2026
Merged

milanmajchrak merged 2 commits into
dtq-devfrom
fix/r23-matomo-consent

Conversation

@vidiecan

Copy link
Copy Markdown

References

dspace-customers issue 1083, finding R23.

No upstream fix:

  • DSpace/dspace-angular has Matomo only from 9.0 (Add support for Matomo DSpace/dspace-angular#4018); src/app/statistics/matomo.service.ts does not exist on dspace-7_x/dspace-8_x. It is built on Orejime, ngx-matomo-client and Angular 18 standalone config, not Klaro, angulartics2 and NgModules, so nothing cherry-picks.
  • Upstream's approach also falls short of R23: it downloads matomo.js whatever the consent and toggles setConsentGiven/forgetConsentGiven, whose queue replays requests from a revoked period.
  • ufal/dspace-angular clarin-v7 still loads Matomo unconditionally in src/main.browser.ts; its PRs and issues for "matomo", "klaro" and "consent" contain no fix.

Description

main.browser.ts loaded matomo.js and queued page views on every page load, before and regardless of cookie consent. Klaro had no Matomo service, so declining did not stop it. Matomo's own consent API would not be enough: commands pushed to _paq run when the script loads, and requests made while consent is missing are queued in memory and sent on setConsentGiven.

Fix:

  • Klaro gets an opt-in matomo service (statistical). Its callback reports consent to the new MatomoConsentTracker.
  • The tracker loads matomo.js only with consent and a non-blank hostUrl and siteId. Without consent nothing is pushed to _paq. Only the current page (path and item dimension) is kept, and it is tracked once consent is given.
  • On revocation it calls forgetConsentGiven. A setCustomRequestProcessing hook empties every request built while consent is revoked, and Matomo never sends an empty request, so clicks from that period are not replayed after a later accept.
  • setConsentGiven is pushed as a function, so it keeps its queue position. As a string, Matomo would run it before an earlier queued forgetConsentGiven.

Behaviour changes:

  • Matomo is off until the visitor accepts it in the cookie notice or settings.
  • Existing visitors see the Klaro notice again, because their stored consent has no matomo entry. Until they save, all optional services count as declined.
  • After a re-accept, Matomo sends its own consent ping (ping=1), which carries the last consented page URL.

Unchanged:

  • info.enableCookieConsentPopup: false still tracks without consent.
  • No client-side Do-Not-Track handling, before or after.
  • Tracker URL, link tracking, and the per-item custom dimension on page views.

Instructions for Reviewers

Changes:

  • src/app/statistics/matomo-consent-tracker.ts (new): the consent gate. It holds the code previously in main.browser.ts and BrowserInitService.init().
  • src/main.browser.ts: unconditional addMatomoStatistics() removed. _paq is still initialised, because Angulartics2Matomo warns "Matomo not found" without it.
  • src/modules/app/browser-init.service.ts: routes Angulartics2Matomo.eventTrack/pageTrack through the tracker.
  • src/app/shared/cookies/klaro-configuration.ts: matomo Klaro service.
  • src/assets/i18n/en.json5, cs.json5: Klaro title and description for the new service. Without them the consent modal shows the raw keys.

Tests:

  • matomo-consent-tracker.spec.ts:
    • should load Matomo and track the current page only once the visitor consents: no script and no _paq command before consent. On accept, the current page and its item dimension are tracked.
    • should stop tracking on revocation and never send activity from the declined period: pages and dimensions seen while declined are not tracked after re-accept, and requests built while declined are emptied.
    • should not load Matomo without a tracker URL and site ID: "valid config and consent", including a blank siteId.
    • should track without Klaro consent when the consent popup is explicitly disabled: legacy mode is kept.
    • Klaro service should ask for individual opt-in consent and forward it to the tracker: the Klaro wiring.
  • browser-init.service.spec.ts:
    • should route Angulartics Matomo tracking through the consent gate: the real init() pushes nothing to _paq before consent.

How to test:

  1. With Matomo configured, open the UI in a clean browser profile. No request to matomo.js or matomo.php appears.
  2. Decline in the cookie notice and browse. Still no Matomo requests.
  3. Open cookie settings and enable Matomo. matomo.js loads and one page view for the current page is sent.
  4. Disable Matomo, click a bitstream download link, and navigate.
  5. Enable Matomo again. Only a page view for the current page (and Matomo's ping=1) is sent; no download or page from step 4.

Local run (Node 18):

  • Before the fix:
    • the new browser-init.service.spec.ts test fails on dtq-dev's BrowserInitService;
    • dtq-dev's main.browser.ts in headless Chrome requests matomo.js and gets a tracker cookie with no consent.
  • After:
    • the new specs and browser-klaro.service.spec.ts pass, 26/26;
    • eslint on changed files: 0 errors, no new warnings;
    • madge circular check: none;
    • ng build --configuration production: OK.
  • Mutation check: removing the legacy-mode branch makes the legacy test fail.
  • Outside the PR, a jsdom run against the official Matomo 4.16.2 and 5.2.2 builds:
    • no request before consent or while declined, and no declined click or page after re-accept;
    • with the request processor removed, the declined download is replayed;
    • accept, revoke, accept before matomo.js loads leaves tracking working;
    • after revocation no _pk_* cookie remains.

Not in scope:

  • Cookie cleanup beyond Matomo's own. On revocation, forgetConsentGiven already deletes Matomo's _pk_* cookies in its configured scope; parent-domain or other-path cookies set by other trackers are not touched.
  • Retry after a failed matomo.js load. This is unchanged and fails closed.
  • Hiding the toggle when Matomo is not configured.
  • Validating hostUrl.

jm added 2 commits October 27, 2026 14:53
main.browser.ts loaded matomo.js and queued tracking on every page load,
before and regardless of cookie consent; Klaro had no Matomo service.

- Klaro gets an opt-in "matomo" service whose callback drives
  MatomoConsentTracker.
- The tracker loads matomo.js only with consent and a configured
  hostUrl and siteId. Without consent nothing is pushed to _paq; only
  the current page is kept and tracked once consent is given.
- Revocation calls forgetConsentGiven, and a request processor empties
  requests built while consent is revoked, so Matomo's consent queue
  cannot replay them after a later accept.
- enableCookieConsentPopup: false keeps tracking without consent.
- Reset the pending item dimension on every consent change, and let
  each page_view event set or clear it, so an identifier seen in one
  consent period cannot be attached to a page view in another.
- Push setConsentGiven as a function: Matomo runs queued
  'setConsentGiven' names before other commands, so accept, revoke,
  accept before matomo.js loaded left Matomo in the revoked state.
- Treat a blank hostUrl or siteId as not configured.
- Test that BrowserInitService routes Angulartics Matomo tracking
  through the consent gate.
- Define MATOMO_KLARO_KEY next to the other Klaro service keys.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human production-browser verification is needed to confirm the Matomo/Klaro integration, network behavior, and accept/revoke/re-accept ordering under asynchronous callback semantics.

No open issues 🎉

What changed in this PR

This pull request gates Matomo analytics behind Klaro consent, preventing Matomo from loading or replaying activity from periods when consent was declined while preserving legacy tracking when the consent popup is disabled.

Changes:

  • Added MatomoConsentTracker for consent-aware loading, page tracking, custom dimensions, and request filtering.
  • Routed Angulartics Matomo tracking through the consent tracker and removed unconditional initialization.
  • Registered Matomo as an optional Klaro service.
  • Added English and Czech consent translations.
  • Added tests covering consent, revocation, configuration, legacy mode, and browser initialization.

Review note: the Matomo translation keys are currently provided only for English and Czech; other active locales may display raw translation keys in the consent dialog.

File Description
src/​modules/​app/​browser-init.service.ts Routes Angulartics Matomo events through the consent tracker.
src/​modules/​app/​browser-init.service.spec.ts Verifies browser initialization uses the consent gate.
src/​main.browser.ts Removes unconditional Matomo loading while preserving _paq initialization.
src/​assets/​i18n/​en.json5 Adds English Matomo consent labels.
src/​assets/​i18n/​cs.json5 Adds Czech Matomo consent labels.
src/​app/​statistics/​matomo-consent-tracker.ts Implements consent-aware Matomo loading, tracking, and request filtering.
src/​app/​statistics/​matomo-consent-tracker.spec.ts Tests consent transitions, deferred tracking, revocation, configuration, and Klaro wiring.
src/​app/​shared/​cookies/​klaro-configuration.ts Adds the optional Matomo Klaro service and consent callback.

Review effort: Lite

@milanmajchrak
milanmajchrak merged commit 7eddad8 into dtq-dev Oct 28, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants