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.
Weaverse · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Weaverse/shopify-hydrogen-skills --skill 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."
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 built-in <Analytics.Provider> cart events forwarded to GA4 via GTM, the Shopify docs are enough. Come here when you need the full funnel.
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 to
<Analytics.Provider customData={{ experiments: { '<id>': '<variant>' } }}>.customDatais merged into every event, soadd_to_cart/purchaseare already tagged with the variant — this is what measures conversion impact, not just impressions. No need to re-attach the experiment per event. - Fire an impression event. Call
useAnalytics().publish('custom_experiment_viewed', { experimentId, variantId })from the experimentsonExposecallback, gated oncanTrack(). Bridgecustom_experiment_viewed→ dataLayer/GA4 in your<CustomAnalytics>subscriber like any other custom event (custom_prefix required; callready()). - 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 contrac |