Matomo events reference and helper API

The consent-gated Matomo event helpers shipped in apps/storefront/src/lib/analytics, plus the PII rules that gate every payload.

Vulpy Commerce ships a built-in Matomo analytics pipeline in the storefront. The helpers live in apps/storefront/src/lib/analytics/ and are designed to fire only after the visitor opts in. This page lists every helper, the built-in event categories, the PII rules that protect customer data, and how to add a new event safely.

Ask Fox to add events for you. Fox knows the helper API, the naming convention, and where to drop the call in the storefront.

Try prompts like:

• “Add a Matomo custom event to the newsletter CTA.”
• “Which events are firing on my dev shop?”
• “Review my new event for PII leaks.”

Helper API

Import helpers from apps/storefront/src/lib/analytics/ and use them in your storefront components.

Helper	Signature	Purpose
trackCustomEvent	(category, action, name?, value?)	Fire a custom Matomo event with a category, action, and optional name and value.
trackProductImpression	(product)	Record a product impression when it appears in a listing or carousel.
trackSelectItem	(product)	Record a click into a product detail page from a listing.
applyCartResult	Bound to CartContext	Automatically fires cart add, remove, or update events when the cart mutates.
pushMatomoCommand	(command)	Low-level command pusher. No-ops safely if consent or config is missing.
useHasAnalyticsConsent	() => boolean	React hook that returns true only when the visitor has opted into analytics.

Built-in event categories

The storefront fires the following event types automatically when consent is granted:

Category	When it fires
Pageview	On every route change after opt-in.
Product impression	When a product card renders in a list or grid.
Product select	When a visitor clicks a product card to open its detail page.
Cart add	When an item is added to the cart via applyCartResult.
Cart remove	When an item is removed from the cart via applyCartResult.
Cart update	When item quantity changes via applyCartResult.
Checkout step	When the visitor progresses through checkout stages.
Purchase	Only on the order confirmation page, deduplicated so payment-return polling does not double-count.

Purchase event details

The purchase event follows stricter pseudonymization rules than other events:

• The Matomo payload uses a pseudonymized order id, never the raw backend identifier.
• If NEXT_PUBLIC_GTM_ID is configured, the GTM payload receives the merchant-facing display_id.
• For logged-in customers, user_id is a hashed customer id. It is never the raw id, email, or name.
• The event fires only on the order confirmation page. If the visitor refreshes or returns from a payment provider, deduplication prevents a second count.

PII rules

Every analytics payload is filtered before it leaves the browser. The following data is never sent to Matomo or GTM:

• Email addresses, names, or postal addresses
• Raw customer ids or raw order ids
• JWTs, session tokens, or authentication headers
• Card or payment instrument data
• Unrestricted query strings that may contain tokens or PII

If you write custom instrumentation, apply the same rules. Use pushMatomoCommand for low-level calls so the consent gate and filters remain active.

Consent gating

Matomo is completely disabled before opt-in:

• No Matomo tracking script loads.
• No tracking request fires.
• No _pk_* cookie is set.

If the visitor withdraws consent, existing cookies are cleared and all pending tracking stops. Global Privacy Control (GPC) signals are treated as an automatic denial.

For custom events, gate your code with useHasAnalyticsConsent() or rely on pushMatomoCommand, which no-ops safely when consent is missing.

Add an event for a new feature

1. Import the helper

   Import trackCustomEvent, pushMatomoCommand, or another helper from apps/storefront/src/lib/analytics/.

2. Gate on consent

   Wrap the call with useHasAnalyticsConsent() or use pushMatomoCommand, which no-ops automatically when consent is not granted.

3. Fire on user action

   Call the helper inside the event handler or effect that responds to the visitor interaction.

4. Verify in Matomo

   Open your Matomo real-time visits view and confirm the event appears after the action is performed.

Reference

• Matomo documentation
• Matomo JavaScript Tracking API reference

Storefront analytics

Overview of the Matomo integration, consent banner, and dashboard setup in Vulpy Commerce.

GTM and GA4

Layer Google Tag Manager and GA4 on top of the built-in Matomo pipeline.