> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulpy.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tip>
  **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."
</Tip>

## 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

<Steps>
  <Step title="Import the helper">
    Import `trackCustomEvent`, `pushMatomoCommand`, or another helper from `apps/storefront/src/lib/analytics/`.
  </Step>

  <Step title="Gate on consent">
    Wrap the call with `useHasAnalyticsConsent()` or use `pushMatomoCommand`, which no-ops automatically when consent is not granted.
  </Step>

  <Step title="Fire on user action">
    Call the helper inside the event handler or effect that responds to the visitor interaction.
  </Step>

  <Step title="Verify in Matomo">
    Open your Matomo real-time visits view and confirm the event appears after the action is performed.
  </Step>
</Steps>

## Reference

* [Matomo documentation](https://matomo.org/docs/)
* [Matomo JavaScript Tracking API reference](https://developer.matomo.org/api-reference/tracking-javascript)

<CardGroup cols={2}>
  <Card title="Storefront analytics" icon="chart-bar" href="/shop/analytics">
    Overview of the Matomo integration, consent banner, and dashboard setup in Vulpy Commerce.
  </Card>

  <Card title="GTM and GA4" icon="code" href="/analytics/gtm-ga4">
    Layer Google Tag Manager and GA4 on top of the built-in Matomo pipeline.
  </Card>
</CardGroup>