Skip to main content
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.

​
Built-in event categories

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

​
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. 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

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.