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

# GTM and GA4 alongside Matomo in Vulpy

> Configure NEXT_PUBLIC_GTM_ID to layer Google Tag Manager and GA4 on top of the built-in Matomo pipeline in Vulpy Commerce.

Matomo is the default behavioural analytics for Vulpy Commerce. You can optionally layer Google Tag Manager and GA4 on top by setting a single environment variable. This page explains the setup, the data flow, and the consent and PII rules that apply to both pipelines.

<Tip>
  **Ask Fox to wire GTM.** Fox knows which env vars are bake-time and which containers rebuild when you change them.

  Try prompts like:

  * "Explain how GTM coexists with Matomo."
  * "Draft the GTM tag setup for GA4."
  * "What has to rebuild if I change `NEXT_PUBLIC_GTM_ID`?"
</Tip>

## Setup

<Steps>
  <Step title="Set your GTM ID">
    Add `NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX` to `environments/<name>/.env` for the target environment.
  </Step>

  <Step title="Rebuild the storefront">
    Because `NEXT_PUBLIC_*` variables are baked at build time in Next.js, you must rebuild the storefront image after changing the value.
  </Step>

  <Step title="Configure your GTM container">
    Open the Google Tag Manager UI for that container and create your tags, triggers, and variables. If you use GA4, add a GA4 configuration tag and any event tags you need.
  </Step>
</Steps>

## Data flow

The same storefront events that feed Matomo can also feed GTM. The pipelines differ in one field:

* Matomo receives a pseudonymized order id for purchase events.
* GTM receives the merchant-facing `display_id` via `NEXT_PUBLIC_GTM_ID`.

Everything else follows the same PII rules. See [Events Reference](/analytics/events) for the full list of built-in events and helper APIs.

## Consent gating

GTM should load only after the visitor opts into analytics. Vulpy exposes `useHasAnalyticsConsent()` in the storefront so you can gate GTM injection the same way Matomo is gated.

If the visitor withdraws consent or sends a Global Privacy Control signal, both Matomo and GTM must stop. Any custom vendor tags you add inside GTM are your responsibility to gate on consent.

## Vendor responsibility

You can use GTM without GA4, for example to load a Meta pixel or another third-party script. Any vendor you add is your responsibility to:

* Gate loading on the same analytics consent state.
* Keep PII out of payloads (no emails, names, raw ids, or card data).
* Respect withdrawal and GPC signals.

## Important: bake-time variable

<Warning>
  `NEXT_PUBLIC_GTM_ID` is a bake-time environment variable in Next.js. Changing it requires rebuilding the storefront Docker image and redeploying the environment. It is not enough to restart the container.
</Warning>

For a full list of environment variables and their bake-time vs runtime behaviour, see [Environment Variables](/reference/env-vars).

## Reference

* [Google Tag Manager documentation](https://developers.google.com/tag-platform/tag-manager)
* [GA4 collection guides](https://developers.google.com/analytics/devguides/collection/ga4)

<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="Events Reference" icon="list" href="/analytics/events">
    Matomo event helpers, built-in categories, PII rules, and how to add custom events safely.
  </Card>
</CardGroup>