{"slug":"weaverse-hydrogen-analytics-tracking","name":"hydrogen-analytics-tracking","description":"End-to-end analytics & conversion tracking on Shopify Hydrogen — GTM, GA4 (browser + Measurement Protocol), Meta Pixel + CAPI, Google Ads, consent mode, CSP, Oxygen full-page cache. Real-world patterns from production deployments.","long_description":"---\nname: hydrogen-analytics-tracking\ndescription: \"End-to-end analytics & conversion tracking on Shopify Hydrogen — GTM, GA4 (browser + Measurement Protocol), Meta Pixel + CAPI, Google Ads, consent mode, CSP, Oxygen full-page cache. Real-world patterns from production deployments.\"\n---\n\n# Hydrogen Analytics & Tracking — Agent Skill\n\n> Build a complete tracking pipeline on Shopify Hydrogen: client dataLayer → GTM → browser pixels, AND server `/api/track` → GA4 MP / Meta CAPI / Google Ads, with shared `event_id` for cross-side deduplication. Covers consent mode v2, CSP `strict-dynamic`, Oxygen full-page cache compatibility, and the surprising gotchas that bite every implementation.\n\nThis skill encodes hard-won lessons from production tracking work on Hydrogen storefronts. The reference files contain detailed implementations; this top page is the map.\n\n---\n\n## When to use this skill\n\nYou need this if you're:\n\n- Implementing GA4 / Meta / Google Ads / TikTok tracking on Hydrogen and the default Hydrogen Analytics components aren't enough.\n- Adding **server-side tracking** (Measurement Protocol, Conversions API) for resilience against ad-blockers and ITP.\n- Debugging \"event X is in GTM Preview but not in GA4 / Meta\".\n- Wiring up **conversion deduplication** between browser pixel and server CAPI.\n- Setting up tracking on a Hydrogen storefront with **Weaverse** as the CMS layer.\n- Investigating why **Oxygen full-page cache** is being disabled despite a correct `Oxygen-Cache-Control` header.\n\nIf you just want page_view + Hydrogen's built-in `` cart events forwarded to GA4 via GTM, the Shopify docs are enough. Come here when you need the full funnel.\n\n---\n\n## The mental model\n\n### Three layers of tracking\n\n| Layer | Where it runs | Strengths | Weaknesses |\n|---|---|---|---|\n| **Browser (GTM → pixels)** | `dataLayer.push()` → GTM tags → GA4, Meta Pixel, Google Ads, TikTok | Rich user context, fbp/fbc cookies, instant client-side ECommerce events | ITP, ad-blockers, page-navigation race conditions |\n| **Server-side (`/api/track`)** | Hydrogen worker → GA4 MP, Meta CAPI, Google Ads Enhanced Conversions | Survives ad-blockers, runs even when client unloads, can be triggered by webhooks | Loses some context (no fbp without forwarding), needs IP + UA + match keys |\n| **Vendor pipes you don't control** | Shopify \"Google & YouTube\" sales channel app, Shopify Customer Events Pixel | Works inside Shopify checkout (where merchant GTM can't go), Shopify-blessed | Limited customization, can DUPLICATE merchant GTM if same vendor set up twice |\n\n**The combination matters.** A complete pipeline uses all three: GTM for storefront pages, server-side for resilience and dedup, vendor pipes for checkout pages (which Shopify Plus locks down).\n\n### Dual-send + event_id dedup\n\nThe cornerstone pattern. Every trackable event:\n\n1. **Generates a UUID `event_id` once** on the client.\n2. **Pushes to `dataLayer`** with that `event_id` → GTM → browser pixels send the hit with `event_id` as the dedup key.\n3. **POSTs to `/api/track`** via `navigator.sendBeacon` with the same `event_id` → server forwards to GA4 MP / Meta CAPI / Google Ads with the same key.\n4. Each vendor's backend dedupes on `(event_name, event_id)` → exactly one count, not two.\n\n```ts\nfunction trackEvent({ event_name, custom_data, user_data }) {\n const event_id = crypto.randomUUID();\n\n // (1) Browser side\n window.dataLayer.push({ event: event_name, event_id, ...custom_data });\n\n // (2) Server side, same event_id\n const payload = { event_id, event_name, custom_data, user_data, consent };\n navigator.sendBeacon(\"/api/track\", new Blob([JSON.stringify(payload)]));\n\n return event_id;\n}\n```\n\n### Why sendBeacon, why not fetch?\n\nAdd-to-cart, begin_checkout, \"Buy now\" — these all trigger page navigation immediately after. A regular `fetch()` gets cancelled when the page unloads, losing the event. `sendBeacon` is the browser API designed exactly for this: the request is queued by the browser and guaranteed to be sent even after navigation. Fall back to `fetch(..., {keepalive: true})` if sendBeacon isn't available.\n\n### Why event_id can't come from the server\n\nIf the server generates `event_id`, the browser already pushed its dataLayer event with a *different* (or no) id, and there's no way to backfill. Always generate client-side, send both directions with the same value.\n\n---\n\n## Experiment exposure (A/B tests)\n\nA/B tests on a Weaverse storefront use [`@weaverse/experiments`](https://www.npmjs.com/package/@weaverse/experiments) — deterministic, project-level variant assignment. Exposure rides the **same** pipeline as every other event:\n\n- **Segment downstream events by variant.** Pass the resolved assignments to `': '' } }}>`. `customData` is merged into every event, so `add_to_cart` / `purchase` are already tagged with the variant — this is what measures conversion *impact*, not just impressions. No need to re-attach the experiment per event.\n- **Fire an impression event.** Call `useAnalytics().publish('custom_experiment_viewed', { experimentId, variantId })` from the experiments `onExpose` callback, gated on `canTrack()`. Bridge `custom_experiment_viewed` → dataLayer/GA4 in your `` subscriber like any other custom event (`custom_` prefix required; call `ready()`).\n- **Dedup.** Exposure is an impression, not a conversion, so the `event_id` dual-send is usually unnecessary. If you forward it to `/api/track`, reuse the storefront `trackEvent()` helper.\n\nServer-side `getExperiments()` wiring lives in the `weaverse-hydrogen` skill (Multi-Project Architecture → A/B Testing).\n\n---\n\n\n## Reference files\n\nRead these in order if you're implementing from scratch. Skip to the relevant one if you're debugging:\n\n| Reference | Read if you're… |\n|---|---|\n| [`architecture.md`](./references/architecture.md) | Setting up the whole pipeline. Covers the dual-send pattern, dedup contract, vendor responsibilities, and how the pieces fit together. |\n| [`gtm-meta-implementation.md`](./references/gtm-meta-implementation.md) | Wiring up GTM dataLayer pushes, GA4 Event tags, Meta CAPI forwarder. Real code patterns. |\n| [`webhook-forwarding-via-builder.md`](./references/webhook-forwarding-via-builder.md) | **Weaverse-hosted storefronts:** how Shopify webhooks reach your storefront without leaking the multi-tenant app client secret. Uses the builder `WebhookForward` model + per-store signing secrets. |\n| [`cart-attribute-stash.md`](./references/cart-attribute-stash.md) | Bridging the **webhook cookie gap**: how to get `_fbp` / `_fbc` / `gclid` / affiliate click IDs from the browser into the Shopify orders webhook. Covers the two cart entry paths (POST action AND `/cart/:` loader) that both need stash logic. |\n| [`oxygen-full-page-cache.md`](./references/oxygen-full-page-cache.md) | Configuring FPC, why `Set-Cookie` disables it, the `entry.server.tsx` strip trick. |\n| [`csp-for-tracking.md`](./references/csp-for-tracking.md) | CSP directives that allow Google/Meta/Hotjar; nonce vs strict-dynamic; GTM Custom HTML tags and inline-script violations. |\n| [`gotchas.md`](./references/gotchas.md) | The bugs that bite every implementation. Read this first if something isn't working. |\n\n---\n\n## Five things every Hydrogen tracking implementation gets wrong\n\n1. **Using Hydrogen's `PRODUCT_ADD_TO_CART` analytics event for `add_to_cart`.** Hydrogen diffs cart state after revalidation and emits the event then. The timing is unreliable — events often miss GA4 DebugView entirely. **Fix:** fire `add_to_cart` directly from the button onClick handler via `sendBeacon` (it survives the form submit / navigation).\n\n2. **Loading GTM after hydration via `