跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
数据与分析

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

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-Control header.

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

LayerWhere it runsStrengthsWeaknesses
Browser (GTM → pixels)dataLayer.push() → GTM tags → GA4, Meta Pixel, Google Ads, TikTokRich user context, fbp/fbc cookies, instant client-side ECommerce eventsITP, ad-blockers, page-navigation race conditions
Server-side (/api/track)Hydrogen worker → GA4 MP, Meta CAPI, Google Ads Enhanced ConversionsSurvives ad-blockers, runs even when client unloads, can be triggered by webhooksLoses some context (no fbp without forwarding), needs IP + UA + match keys
Vendor pipes you don't controlShopify "Google & YouTube" sales channel app, Shopify Customer Events PixelWorks inside Shopify checkout (where merchant GTM can't go), Shopify-blessedLimited 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:

  1. Generates a UUID event_id once on the client.
  2. Pushes to dataLayer with that event_id → GTM → browser pixels send the hit with event_id as the dedup key.
  3. 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.
  4. 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>' } }}>. 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.
  • 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 <CustomAnalytics> subscriber like any other custom event (custom_ prefix required; call ready()).
  • 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.

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:

ReferenceRead if you're…
architecture.mdSetting up the whole pipeline. Covers the dual-send pattern, dedup contrac
阅读完整来源 ↗