Add Fides.matomo() integration helper by gilluminate · Pull Request #7991 · ethyca/fides

gilluminate · 2026-04-21T22:04:37Z

Description Of Changes

New Fides.matomo() integration helper that automatically syncs Fides consent decisions with Matomo's tracking consent and cookie consent APIs via _paq.push(). Follows the same Gen 2 integration pattern as Fides.gcm(), Fides.aep(), and Fides.blueconic().

Key design decisions:

Conditional requireConsent: Rather than always calling Matomo's requireConsent() on init (which would block tracking for users in non-consent regions), the integration defers this call until the first consent event where the analytics or performance key is present in the Fides consent object. This follows GCM's in check pattern and correctly handles both OMIT (default) and INCLUDE non-applicable flag modes without any user configuration.
No requireConsent option: Unlike the original PRD spec, this option was removed. All other Fides integrations (GCM, AEP, BlueConic, Shopify) let Fides handle jurisdiction awareness rather than exposing a toggle. The conditional activation approach achieves the same goal automatically.
rememberConsent defaults to true: Uses Matomo's rememberConsentGiven() to persist consent via Matomo's mtm_consent cookie, so tracking can resume on page loads before Fides initializes.

Public API:

Fides.matomo({
  consentMode: "tracking" | "cookie" | "both",  // default: "tracking"
  rememberConsent: true | false,                  // default: true
})

Code Changes

New clients/fides-js/src/integrations/matomo.ts - core integration
New clients/fides-js/__tests__/integrations/matomo.test.ts - 26 unit tests
Modified clients/fides-js/src/lib/consent-types.ts - add matomo to FidesGlobal
Modified clients/fides-js/src/lib/init-utils.ts - wire matomo into getCoreFides()
Modified clients/fides-js/src/docs/fides.ts - JSDoc for Fides.matomo()
New Cypress E2E tests in consent-third-party.cy.ts for the Matomo integration
Added _paq stub to Cypress visitConsentDemo command
Added Fides.matomo() call to fides-js-components-demo.html

Steps to Confirm

Automated:

cd clients/fides-js && npx jest __tests__/integrations/matomo.test.ts - 26 unit tests pass
cd clients/fides-js && npm run check - lint, format, typecheck all pass
cd clients/fides-js && npm run build - build succeeds
Cypress E2E: consent-third-party.cy.ts Matomo tests pass

Manual (demo page):
Use https://developer.matomo.org/guides/tracking-consent for reference

Start the local backend and privacy center
Visit http://localhost:3001/fides-js-demo.html
Open browser DevTools console
Call Fides.matomo() in the console
Inspect window._paq - should contain ["requireConsent"] followed by a grant or revoke command depending on the default consent state
Interact with the consent banner (accept/reject) and re-inspect window._paq - should see ["rememberConsentGiven"] after accepting or ["forgetConsentGiven"] after rejecting
Test with options: Fides.matomo({ consentMode: "both" }) - should see both tracking and cookie consent commands
Test with Fides.matomo({ rememberConsent: false }) - should see ["setConsentGiven"] instead of ["rememberConsentGiven"]

Pre-Merge Checklist

vercel · 2026-04-21T22:04:42Z

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
fides-plus-nightly	Ignored	Preview	Apr 22, 2026 8:47pm
fides-privacy-center	Ignored		Apr 22, 2026 8:47pm

New integration that syncs Fides consent with Matomo's tracking consent and cookie consent APIs via _paq.push(). Follows the Gen 2 integration pattern (same as GCM, AEP, BlueConic). Key behavior: requireConsent is conditionally activated based on the presence of the consent key in the Fides consent object, matching GCM's pattern. This correctly handles both OMIT and INCLUDE non-applicable flag modes without any user configuration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add _paq stub to Cypress visitConsentDemo command - Add Fides.matomo() call to fides-js-components-demo.html - Add Matomo test section to consent-third-party.cy.ts covering: - _paq exists on window - No commands pushed when analytics key is absent - requireConsent + forgetConsentGiven on init with opt-out default - rememberConsentGiven after user opts in via banner Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

gilluminate · 2026-04-21T22:10:29Z

/code-review

github-actions · 2026-04-21T22:14:41Z

Title	Statements	Branches	Functions
admin-ui	6.33% (2799/44197)	5.57% (1402/25139)	4.43% (579/13069)
fides-js	79.4% (2012/2534)	65.99% (1238/1876)	73.09% (345/472)
privacy-center	85.97% (331/385)	81.36% (179/220)	78.87% (56/71)

gilluminate · 2026-04-21T23:15:02Z

Re: missing test for consentMode: "both" + rememberConsent: false — added the test case. It asserts setConsentGiven and setCookieConsentGiven are pushed (not the remember* variants).

- Capture _paq reference once, remove non-null assertions - Document hardcoded consent key limitation in customer-facing docs - Use optional chaining in demo HTML - Remove tautological Cypress test - Add missing test for consentMode "both" + rememberConsent false - Regenerate typedoc markdown Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

gilluminate · 2026-04-21T23:22:44Z

/code-review

claude

Code Review: `Fides.matomo()` integration helper

The core implementation in matomo.ts is clean and well-structured. It follows the established Gen 2 integration pattern accurately, the module decomposition (pushRequireConsent / pushConsentUpdate / findConsentKey) is clear, and the 26 unit tests cover the key behavioral paths well. The JSDoc examples are thorough and the changelog entry is correct.

Must Fix

Misleading Cypress test name (inline comment on consent-third-party.cy.ts:531): The test is named "pushes requireConsent on FidesReady when analytics key is present" but asserts the opposite — no calls when the key is absent. Quick one-line rename.

Should Address

Unconditional matomo() call in demo page (inline comment on fides-js-components-demo.html:223): The previous gtm() call used an explicit falsy guard (!!window.fides_overrides && window.fides_overrides.gtmOptions) that passed false when the option was absent. Both gtm() and matomo() now receive undefined via optional chaining, which causes them to apply defaults and run unconditionally. For matomo() this silently initializes _paq and pushes requireConsent on every page load even without intent. The demo page is a reference pattern for integrators; guarding with if (window.fides_overrides?.matomoOptions) would restore the original semantics.

Test isolation fragility (inline comment on matomo.test.ts:67): The comment documents a real, unresolved ordering dependency — subscribeToConsent listeners cannot be cleaned up, so each matomo() call in tests accumulates permanent window event handlers. The current suite is safe only because this describe block runs first. Adding any new matomo() call above it would silently corrupt the assertion. If returning an unsubscribe function from subscribeToConsent is feasible, it would fix this for all integrations. At minimum the comment should be more explicit about the file-level ordering invariant.

Suggestions

requireConsentPushed is per-instance, not per-_paq (inline comment on matomo.ts:124): If matomo() is called twice, both closures push requireConsent and both consent commands on each event. Worth a doc note or a single-call guard.
DEFAULT_CONSENT_KEYS is not configurable (inline comment on matomo.ts:45): Sites with non-standard consent key names silently fall to free-tracking mode. An optional consentKeys override in MatomoOptions would be additive and non-breaking.
EMPTY_BUNDLE suppression lacks a comment (inline comment on rollup.config.mjs:316): A one-line comment explaining why the warning is expected would prevent future confusion.

🔬 Codegraph: unavailable

💡 Write /code-review in a comment to re-run this review.

- Fix misleading Cypress test name (says "present", tests "absent") - Use module-level WeakSet guard for requireConsentPushed to prevent double-push when matomo() is called multiple times - Add explanatory comment for EMPTY_BUNDLE rollup suppression Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

tvandort · 2026-04-22T19:46:23Z

+
+const DEFAULT_CONSENT_KEYS = ["analytics", "performance"];
+
+const paqsWithRequireConsent = new WeakSet<unknown[][]>();


I'm curious what the rationale behind both WeakSet and this not being some sort of flag-like value is?

Good question. The WeakSet came from a Claude Code review suggestion - it flagged that the original per-closure boolean would allow duplicate requireConsent pushes if matomo() was called more than once. I moved the guard to module scope per that review, and went with WeakSet keyed on the _paq array reference so it auto-resets if window._paq is ever replaced.

That said, none of our other integrations (GCM, AEP, BlueConic, GTM, Shopify) use this kind of guard or worry about the global array being swapped out. A simple let requireConsentPushed = false boolean would be more consistent with the rest of the codebase and easier to grok. Happy to simplify if you'd prefer that.

tvandort · 2026-04-22T19:54:08Z

+      paq.push([command]);
+      fidesDebugger(`[Fides Matomo] Pushed ${command}`);
+    } else {
+      paq.push(["forgetConsentGiven"]);


Should we always push forgetConsentGiven when analytics is false? I'd need to check Matomo's behavior but I can imagine a scenario in which a client using this extension could swap it's default behavior to just cookie for instance, deploy that change. Then a data subject could go opt out of analytics and we'd never push forgetConsentGiven I also wonder if Fides sees tracking as false whether it should also push forgetConsentGiven?

Good catch. Matomo's forgetConsentGiven/forgetCookieConsentGiven are safe no-ops when consent was never granted, so I'll always push both revoke commands regardless of consentMode and only gate the grant path.

tvandort · 2026-04-22T19:54:38Z

+    if (granted) {
+      const command = rememberConsent
+        ? "rememberCookieConsentGiven"
+        : "setCookieConsentGiven";
+      paq.push([command]);
+      fidesDebugger(`[Fides Matomo] Pushed ${command}`);
+    } else {
+      paq.push(["forgetCookieConsentGiven"]);
+      fidesDebugger("[Fides Matomo] Pushed forgetCookieConsentGiven");
+    }


Roughly same question as here: https://github.com/ethyca/fides/pull/7991/changes#r3126548623

Addressed in the same change as the tracking side fix above. Revoke commands will always push for both consent types regardless of consentMode.

tvandort · 2026-04-22T19:56:41Z

+  paq: unknown[][],
+  consentMode: MatomoConsentMode,
+): void => {
+  if (consentMode === "tracking" || consentMode === "both") {


This is a small file and I don't think it's likely to change but IMO these checks would be better packaged into something like

object MatomoDecisions(consentMode) { ctor() { this.consentMode = consentMode } isTracking() { return consentMode === "tracking" || consentMode === "both"; } /* etc */ } // Usage /* initialize matomoDecision object */ if (matomoDecision.isTracking()) { /* dostuff */ }

Done! Extracted consentModeChecks(consentMode) with isTracking() and isCookie() helpers, used in both pushRequireConsent and pushConsentUpdate.

- Always push both forgetConsentGiven and forgetCookieConsentGiven on revoke regardless of consentMode to clean up stale consent cookies - Extract consentModeChecks() helper for isTracking/isCookie checks Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

gilluminate and others added 3 commits April 21, 2026 16:09

Add changelog entry for Fides.matomo() integration

5411855

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

gilluminate force-pushed the gill/matomo-integration/fides-matomo-helper branch from bc3b9c2 to 5411855 Compare April 21, 2026 22:09

This comment was marked as outdated.

Sign in to view

gilluminate marked this pull request as ready for review April 21, 2026 23:22

gilluminate requested a review from a team as a code owner April 21, 2026 23:22

gilluminate requested review from lucanovera and removed request for a team April 21, 2026 23:22

gilluminate requested review from tvandort and removed request for lucanovera April 21, 2026 23:22

claude Bot reviewed Apr 21, 2026

View reviewed changes

tvandort reviewed Apr 22, 2026

View reviewed changes

gilluminate and others added 2 commits April 22, 2026 14:40

Apply prettier formatting to matomo.ts

fbe7a8b

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

gilluminate requested a review from tvandort April 22, 2026 21:23


		const DEFAULT_CONSENT_KEYS = ["analytics", "performance"];

		const paqsWithRequireConsent = new WeakSet<unknown[][]>();

Conversation

gilluminate commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description Of Changes

Code Changes

Steps to Confirm

Pre-Merge Checklist

Uh oh!

vercel Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gilluminate commented Apr 21, 2026

Uh oh!

github-actions Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

gilluminate commented Apr 21, 2026

Uh oh!

gilluminate commented Apr 21, 2026

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Code Review: Fides.matomo() integration helper

Must Fix

Should Address

Suggestions

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tvandort Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

gilluminate Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

tvandort Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

gilluminate Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

tvandort Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

gilluminate Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

tvandort Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gilluminate Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gilluminate commented Apr 21, 2026 •

edited

Loading

vercel Bot commented Apr 21, 2026 •

edited

Loading

github-actions Bot commented Apr 21, 2026 •

edited

Loading

Code Review: `Fides.matomo()` integration helper

tvandort Apr 22, 2026 •

edited

Loading