hydrogen-analytics-tracking
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.
How do I install this agent skill?
npx skills add https://github.com/weaverse/shopify-hydrogen-skills --skill hydrogen-analytics-trackingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a comprehensive guide and reference implementation for setting up analytics and conversion tracking on Shopify Hydrogen storefronts. It covers browser-side tracking via GTM and server-side tracking via GA4 Measurement Protocol and Meta Conversions API, using best practices like PII hashing and shared event IDs for deduplication. No security issues were detected.
- Socketwarn
2 alerts: gptAnomaly
- Snykfail
Risk: CRITICAL · 3 issues
What does this agent skill do?
Hydrogen Analytics & Tracking — Agent Skill
Build a complete tracking pipeline on Shopify Hydrogen: client dataLayer → GTM → browser pixels, AND server
/api/track→ GA4 MP / Meta CAPI / Google Ads, with sharedevent_idfor cross-side deduplication. Covers consent mode v2, CSPstrict-dynamic, Oxygen full-page cache compatibility, and the surprising gotchas that bite every implementation.
This skill encodes hard-won lessons from production tracking work on Hydrogen storefronts. The reference files contain detailed implementations; this top page is the map.
When to use this skill
You need this if you're:
- Implementing GA4 / Meta / Google Ads / TikTok tracking on Hydrogen and the default Hydrogen Analytics components aren't enough.
- Adding server-side tracking (Measurement Protocol, Conversions API) for resilience against ad-blockers and ITP.
- Debugging "event X is in GTM Preview but not in GA4 / Meta".
- Wiring up conversion deduplication between browser pixel and server CAPI.
- Setting up tracking on a Hydrogen storefront with Weaverse as the CMS layer.
- Investigating why Oxygen full-page cache is being disabled despite a correct
Oxygen-Cache-Controlheader.
If you just want page_view + Hydrogen's cart events (<ShopifyScripts> + useCartAnalytics()) forwarded to GA4 via GTM, Shopify's packaged hydrogen-analytics skill (node_modules/@shopify/hydrogen/skills/hydrogen-analytics/) is enough. Come here when you need the full funnel.
Hydrogen 2026.10. This skill targets Hydrogen 2026.10 and
@weaverse/hydrogen6, with Pilotmainas the reference implementation. Classic analytics (Analytics.Provider,<Analytics.*View>,useAnalytics(),getShopAnalytics) andCartForm/context.cartare gone; seearchitecture.mdfor what replaces them. To migrate a classic storefront first, use thehydrogen-upgradesskill.
The mental model
Three layers of tracking
| Layer | Where it runs | Strengths | Weaknesses |
|---|---|---|---|
| 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 |
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 |
| 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 |
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).
Dual-send + event_id dedup
The cornerstone pattern. Every trackable event:
- Generates a UUID
event_idonce on the client. - Pushes to
dataLayerwith thatevent_id→ GTM → browser pixels send the hit withevent_idas the dedup key. - POSTs to
/api/trackvianavigator.sendBeaconwith the sameevent_id→ server forwards to GA4 MP / Meta CAPI / Google Ads with the same key. - Each vendor's backend dedupes on
(event_name, event_id)→ exactly one count, not two.
function trackEvent({ event_name, custom_data, user_data }) {
const event_id = crypto.randomUUID();
// (1) Browser side
window.dataLayer.push({ event: event_name, event_id, ...custom_data });
// (2) Server side, same event_id
const payload = { event_id, event_name, custom_data, user_data, consent };
navigator.sendBeacon("/api/track", new Blob([JSON.stringify(payload)]));
return event_id;
}
Why sendBeacon, why not fetch?
Add-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.
Why event_id can't come from the server
If 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.
Experiment exposure (A/B tests)
A/B tests on a Weaverse storefront use @weaverse/experiments — deterministic, project-level variant assignment. Exposure rides the same pipeline as every other event:
- Segment downstream events by variant. Pass the resolved assignments as bus config:
<ShopifyScripts analytics={{ channel, customData: { experiments: { '<id>': '<variant>' } } }} />. The bus copiescustomDatainto its cart events (cart_updated,product_added_to_cart,product_removed_from_cart) but not into events you publish, so your destination reads it withgetConfig().customData(from thesetupcontext) and attaches it to everydataLayerpush /trackEvent()payload. That tagsadd_to_cart/purchasewith the variant — this is what measures conversion impact, not just impressions. Keep the assignments per market or per experiment bucket, never per shopper, or the document stops being cacheable. - Fire an impression event. The bus accepts only its own event names (it warns and drops anything else), so don't publish
custom_experiment_viewedto it. From the experimentsonExposecallback, gated on your consent check (canTrack()), push it straight todataLayeror calltrackEvent({ event_name: 'experiment_viewed', custom_data: { experimentId, variantId } }). - Dedup. Exposure is an impression, not a conversion, so the
event_iddual-send is usually unnecessary. If you forward it to/api/track, reuse the storefronttrackEvent()helper.
Server-side getExperiments() wiring lives in the weaverse-hydrogen skill (Multi-Project Architecture → A/B Testing).
Reference files
Read these in order if you're implementing from scratch. Skip to the relevant one if you're debugging:
| Reference | Read if you're… |
|---|---|
architecture.md | Setting up the whole pipeline. Covers the dual-send pattern, dedup contract, vendor responsibilities, and how the pieces fit together. |
gtm-meta-implementation.md | Wiring up GTM dataLayer pushes, GA4 Event tags, Meta CAPI forwarder. Real code patterns. |
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. |
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 cart entry paths (POST /api/cart AND the /cart/<id>:<qty> permalink loader) that both need stash logic. |
oxygen-full-page-cache.md | Configuring FPC, why Set-Cookie disables it, keeping documents anonymous on Hydrogen 2026.10. |
csp-for-tracking.md | CSP directives that allow Google/Meta/Hotjar; nonce vs strict-dynamic; GTM Custom HTML tags and inline-script violations. |
gotchas.md | The bugs that bite every implementation. Read this first if something isn't working. |
Five things every Hydrogen tracking implementation gets wrong
-
Using the bus's
PRODUCT_ADD_TO_CARTevent foradd_to_cart.useCartAnalytics()publishes it only after the cart store confirms the change with Shopify, so a navigation that follows the click (Buy now, checkout redirect) often drops it — events miss GA4 DebugView entirely. Fix: fireadd_to_cartdirectly from the button onClick handler viasendBeacon(it survives the form submit / navigation). -
Loading GTM after hydration without a nonce (classic Hydrogen's
<Script waitForHydration>, or any DOM-injected loader). It hides GTM from Tag Assistant standalone scans and blocks the move to nonce-basedstrict-dynamicCSP. Fix: loadgtm.jsas a regular<script async nonce={nonce}>in<head>, with the inlinegtm.start+ Consent Mode v2 default-deny block before it. -
Pushing GA4-named events but configuring GTM triggers with legacy snake_case names (or vice versa). After "Custom Event" renaming there's a coverage gap. Fix: match GTM trigger filters to whatever the storefront actually pushes today; do code + GTM in one coordinated change.
-
Letting the product view tracker gate on
selectedVariant. For combined listings or any product where the variant resolves after hydration, the tracker that publishesPRODUCT_VIEWEDnever mounts andview_itemdoesn't fire. Fix: mount unconditionally and fall back toselectedOrFirstAvailableVariant. -
Treating "consent denied" as "send nothing". Meta CAPI's relaxed pattern (LDU flag + ip/ua/fbp/fbc only, no hashed PII) recovers a large chunk of optimisation signal compliantly. GA4 Consent Mode v2 modeled conversions work the same way. Fix: in the server forwarder, when
ad_storage !== "granted"drop hashed PII but still send the event withdata_processing_options: ["LDU"]. -
Pasting a Liquid
dataLayer.pushsnippet into Hydrogen. Merchants often bring an existing theme snippet using Liquid tags ({{ product.id }},{{ collection.title }},{{ product.price | money_without_currency }}). These do nothing in Hydrogen — it's React/SSR, there is no Liquid at runtime, so the braces render as literal text or break. Fix: rebuild the same object from Hydrogen data and push it in JS. Liquid → Hydrogen mapping:{{ product.id }}→product.id,{{ product.title }}→product.title,{{ product.price | money_without_currency }}→product.priceRange?.minVariantPrice?.amount(a string, no currency symbol),{{ collection.id/title }}→collection.id/title. -
Expecting
select_item/view_item_listfrom a built-in Hydrogen analytics event. GA4 list events don't map to cart events.select_itemis a click (user clicks a product card in a list) — fire it from the product card'sonClickon the collection/PLP, where you already hold the product + collection + index.view_item_listis a view — push it from theCOLLECTION_VIEWEDsubscription of your bus destination inapp/components/root/custom-analytics.tsx(and make sure the collection route renders a tracker that publishesCOLLECTION_VIEWED). Includeindex(list position) for GA4. Ensure the collection query returnsid,title,handle, andpriceRangeso the values exist to push.
The order to build it
If you're starting fresh on a new Hydrogen storefront:
<ShopifyScripts>first in the root<head>, route trackers publishingPAGE_VIEWED/PRODUCT_VIEWED/COLLECTION_VIEWED/SEARCH_VIEWED/CART_VIEWED, anduseCartAnalytics()insideCartProvider. Map bus events todataLayerin a<CustomAnalytics />component that registers a destination withwindow.Shopify.analytics.addDestination(). (Seearchitecture.md)- Inline
<head>Consent Mode v2 default-deny block + dataLayer + gtm.start marker. gtm.jsexternal script with nonce, async, in<head>after the inline block.trackEvent()helper that pushes dataLayer +sendBeacon('/api/track')with sharedevent_id./api/trackserver endpoint that validates the payload, hashes PII server-side, fans out to GA4 MP + Meta CAPI + Google Ads forwarders.- Shopify
orders/createwebhook that maps the order to apurchaseevent withevent_id = "purchase_" + orderId(deterministic for retries). - Shopify "Google & YouTube" sales channel + Customer Events Pixel for checkout-side events (Meta Pixel events, anything that needs to fire inside Shopify checkout where your GTM can't reach).
- GTM container with one GA4 Event tag per dataLayer event, plus Meta Pixel + TikTok + Google Ads conversion tags as needed.
- CSP updated to allow all vendor domains in
script-src,connect-src,img-src. Usestrict-dynamic+ nonce. - Oxygen full-page cache opted in for anonymous documents via
Oxygen-Cache-Control: public, max-age=N, ...+Varyinentry.server.tsx. Keep cart and customer data out of loaders so the documents carry noSet-Cookie.
Skill-level conventions
When working on a Hydrogen tracking implementation in this skill's scope:
- Server code lives under
app/.server/tracking/(forwarders, validators, hash util, audit log). - Client helper at
app/utils/track-client.ts(exportstrackEvent, consent listener, attribution capture). - Route trackers at
app/components/root/analytics-views.tsx(publish view events towindow.Shopify.analytics;useCartAnalytics()for cart events). - dataLayer bridge at
app/components/root/custom-analytics.tsx(a bus destination registered withaddDestination(), so delivery follows Customer Privacy consent). - Inline Consent Mode + GTM bootstrap in
app/root.tsx<head>, with nonce. - CSP config at
app/weaverse/csp.ts(Weaverse projects), passed to the localcreateContentSecurityPolicy()port inapp/utils/csp.tsfromentry.server.tsx(Hydrogen 2026.10 no longer ships the helper). - Per-vendor forwarder modules at
app/.server/tracking/forwarders/{ga4,meta-capi,google-ads}.ts— each returns{forwarder, ok, skipped?, reason?}so the audit log can show why an event was dropped.
When a question is broader than a single vendor, prefer the reference doc that addresses the architectural layer rather than one vendor's docs.
Live docs
Run these from this skill's own folder. The helpers ship inside the sibling
shopify-hydrogen skill, so ../shopify-hydrogen/scripts/ exists whenever the
whole pack is installed.
If you installed this skill on its own, that folder is absent and the commands
below fail with MODULE_NOT_FOUND. Add the helpers once:
npx skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogen
The references/ files in this skill remain a usable offline fallback if you
would rather not install it.
For up-to-date official sources:
# Shopify Hydrogen / Oxygen
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "oxygen full-page cache"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "consent mode"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "ShopifyScripts analytics"
# Weaverse (if using Weaverse CMS)
node ../shopify-hydrogen/scripts/search_weaverse_docs.mjs "csp"
Vendor docs (open in browser, no script):
- GA4 Measurement Protocol — https://developers.google.com/analytics/devguides/collection/protocol/ga4
- Meta Conversions API — https://developers.facebook.com/docs/marketing-api/conversions-api
- Google Ads Enhanced Conversions for Web — https://developers.google.com/google-ads/api/docs/conversions/enhanced-conversions-for-web
- Shopify "Customer Events" / Web Pixels — https://shopify.dev/docs/api/web-pixels-api
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/weaverse/shopify-hydrogen-skills/hydrogen-analytics-tracking">View hydrogen-analytics-tracking on skillZs</a>