hydrogen-analytics-tracking

Hydrogen 分析与追踪 — Agent 技能

在 Shopify Hydrogen 上构建完整的追踪流水线：客户端 dataLayer → GTM → 浏览器像素，以及服务器 /api/track → GA4 MP / Meta CAPI / Google Ads，并使用共享的 event_id 进行跨端去重。涵盖 consent mode v2、CSP strict-dynamic、与 Oxygen 整页缓存的兼容性，以及每种实现都会遇到的意外陷阱。

这项技能总结了 Hydrogen 店面生产环境追踪工作中积累的宝贵经验。参考文件包含详细实现；本页是导航指南。

---

何时使用这项技能

以下情况适用：

• 在 Hydrogen 上实现 GA4 / Meta / Google Ads / TikTok 追踪，而 Hydrogen 默认的 Analytics 组件无法满足需求。
• 添加服务器端追踪（Measurement Protocol、Conversions API），以应对广告拦截器和 ITP。
• 排查“事件 X 出现在 GTM 预览中，但没有进入 GA4 / Meta”的问题。
• 配置浏览器像素与服务器 CAPI 之间的转化去重。
• 在以 Weaverse 作为 CMS 层的 Hydrogen 店面上设置追踪。
• 调查为何即使 Oxygen-Cache-Control 标头正确，Oxygen 整页缓存仍被禁用。

如果你只想将 page_view 和 Hydrogen 内置的 <Analytics.Provider> 购物车事件通过 GTM 转发到 GA4，Shopify 文档就足够了。需要完整漏斗时，请参考这里。

---

思维模型

追踪的三个层

层	运行位置	优势	劣势
浏览器（GTM → 像素）	dataLayer.push() → GTM 标签 → GA4、Meta Pixel、Google Ads、TikTok	丰富的用户上下文、fbp/fbc Cookie、即时的客户端电子商务事件	ITP、广告拦截器、页面导航竞争条件
服务器端（/api/track）	Hydrogen worker → GA4 MP、Meta CAPI、Google Ads Enhanced Conversions	不受广告拦截器影响，即使客户端卸载也会运行，可由 Webhook 触发	会丢失部分上下文（不转发就没有 fbp），需要 IP + UA + 匹配键
你无法控制的供应商管道	Shopify“Google & YouTube”销售渠道应用、Shopify Customer Events Pixel	可在 Shopify 结账中运行（商家的 GTM 无法进入），由 Shopify 认可	自定义能力有限；如果同一供应商配置了两次，可能与商家的 GTM 产生重复事件

组合使用很重要。 完整的流水线会用到这三者：GTM 用于店面页面，服务器端用于提高可靠性和去重，供应商管道用于结账页面（Shopify Plus 会锁定这些页面）。

双端发送 + event_id 去重

这是核心模式。每个可追踪事件：

1. 在客户端生成一次 UUID event_id。
2. 使用该 event_id 推送到 dataLayer → GTM → 浏览器像素发送带有 event_id 去重键的事件。
3. 通过 navigator.sendBeacon POST 到 /api/track，使用相同的 event_id → 服务器将事件转发到 GA4 MP / Meta CAPI / Google Ads，并使用相同的键。
4. 每个供应商的后端都根据 (event_name, event_id) 去重 → 只计数一次，而不是两次。

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;
}

为什么使用 sendBeacon，而不是 fetch？

添加到购物车、开始结账、“立即购买”——这些操作之后都会立即触发页面导航。页面卸载时，常规的 fetch() 会被取消，导致事件丢失。sendBeacon 正是为此设计的浏览器 API：浏览器会将请求加入队列，并保证即使发生导航也会发送。如果 sendBeacon 不可用，则回退到 fetch(..., {keepalive: true})。

为什么 event_id 不能由服务器生成

如果服务器生成 event_id，浏览器已经推送的 dataLayer 事件就会带有不同的 ID（或没有 ID），也就无法再补上。务必在客户端生成，并在两个方向发送相同的值。

---

实验曝光（A/B 测试）

Weaverse 店面的 A/B 测试使用 @weaverse/experiments — 确定性、项目级的变体分配。曝光与其他所有事件共用同一条流水线：

• 按变体细分下游事件。 将解析后的分配传递给 <Analytics.Provider customData={{ experiments: { '<id>': '<variant>' } }}>。customData 会合并到每个事件中，因此 add_to_cart / purchase 已带有变体标记 — 这样衡量的是转化的影响，而不只是展示次数。无需为每个事件重新附加实验信息。
• 触发展示事件。 在实验的 onExpose 回调中调用 useAnalytics().publish('custom_experiment_viewed', { experimentId, variantId })，并通过 canTrack() 控制是否触发。在 <CustomAnalytics> 订阅器中，将 custom_experiment_viewed 转发到 dataLayer/GA4，方式与其他自定义事件相同（必须使用 custom_ 前缀；调用 ready()）。
• 去重。 曝光是展示，而非转化，因此通常不需要 event_id 双重发送。如果将其转发到 /api/track，请复用店面的 trackEvent() 辅助函数。

服务端 getExperiments() 的接线方式位于 weaverse-hydrogen 技能中（Multi-Project Architecture → A/B Testing）。

---

参考文件

如果从头开始实现，请按顺序阅读这些文件。如果是在调试，请直接跳到相关文件：

参考文件	以下情况请阅读……
architecture.md	设置整个流水线。介绍双重发送模式、去重约定、供应商职责，以及各部分如何协同工作。
gtm-meta-implementation.md	配置 GTM dataLayer 推送、GA4 事件标签、Meta CAPI 转发器。包含实际代码模式。
webhook-forwarding-via-builder.md	**Weaverse 托管的店面：**介绍 Shopify Webhook 如何到达店面，同时避免泄露多租户应用客户端密钥。使用 builder WebhookForward 模型和每个商店单独的签名密钥。
cart-attribute-stash.md	弥补Webhook Cookie 缺口：介绍如何将 _fbp / _fbc / gclid / 联盟营销点击 ID 从浏览器传入 Shopify 订单 Webhook。涵盖两种购物车入口（POST action 和 /cart/<id>:<qty> loader），两者都需要暂存逻辑。
oxygen-full-page-cache.md	配置 FPC、说明 Set-Cookie 为何会禁用它，以及 entry.server.tsx 剥离技巧。
csp-for-tracking.md	允许 Google/Meta/Hotjar 的 CSP 指令；nonce 与 strict-dynamic；GTM Custom HTML 标签和内联脚本违规。
gotchas.md	每种实现都容易踩到的 Bug。如果遇到问题，请先阅读此文件。

---

每个 Hydrogen 跟踪实现都会犯错的五件事

1. 将 Hydrogen 的 PRODUCT_ADD_TO_CART analytics 事件用于 add_to_cart。 Hydrogen 会在重新验证后对比购物车状态，然后才发出该事件。时机并不可靠——事件经常完全无法出现在 GA4 DebugView 中。**修复方法：**通过 sendBeacon，直接在按钮的 onClick 处理程序中触发 add_to_cart（即使表单提交或页面导航，它也能发送）。

2. 通过 <Script waitForHydration> 在 hydration 后加载 GTM。 这会导致 Tag Assistant 独立扫描无法检测到 GTM，也会阻碍迁移到基于 nonce 的 strict-dynamic CSP。**修复方法：**在 <head> 中将 gtm.js 作为常规 <script async nonce={nonce}> 加载，并在它之前加入内联的 gtm.start 和 Consent Mode v2 默认拒绝代码块。

3. 推送 GA4 命名的事件，却在 GTM 中将触发器配置为旧版 snake_case 名称（反之亦然）。重命名为“Custom Event”后，会出现覆盖缺口。**修复方法：**将 GTM 触发器筛选条件与店面当前实际推送的名称保持一致；协调好代码和 GTM 的变更，一并完成。

4. 让 <Analytics.ProductView> 依赖 selectedVariant 才能运行。 对于组合商品列表，或任何在 hydration 后才解析变体的商品，analytics 组件都不会挂载，view_item 也不会触发。**修复方法：**无条件挂载，并为每个变体提供安全的回退值。

5. 把“拒绝同意”当作“什么都不发送”。 Meta CAPI 较宽松的模式（LDU 标记 + 仅发送 ip/ua/fbp/fbc，不发送哈希 PII）可以在合规的前提下挽回大量优化信号。GA4 Consent Mode v2 的建模转化也采用同样的方式。**修复方法：**在服务端转发器中，当 ad_storage !== "granted" 时，丢弃哈希 PII，但仍发送包含 data_processing_options: ["LDU"] 的事件。

6. 将 Liquid dataLayer.push 代码片段粘贴到 Hydrogen 中。 商家经常会带来现有主题代码片段，其中使用了 Liquid 标签（{{ product.id }}、{{ collection.title }}、{{ product.price | money_without_currency }}）。这些代码在 Hydrogen 中不起作用——它使用 React/SSR，运行时没有 Liquid，因此花括号会被渲染为字面文本或导致错误。**修复方法：**从 Hydrogen 数据中重新构建相同的对象，并用 JS 推送。Liquid → Hydrogen 映射：{{ product.id }} → product.id，{{ product.title }} → product.title，{{ product.price | money_without_currency }} → product.priceRange?.minVariantPrice?.amount（字符串，不含货币符号），{{ collection.id/title }} → collection.id/title。

7. 期望从 Hydrogen 内置 analytics 事件中获得 select_item / view_item_list。 GA4 列表事件不会映射到购物车事件。select_item 是一次点击（用户点击列表中的商品卡片）——在集合页/PLP 中的商品卡片 onClick 处理程序里触发，此时你已经持有商品、集合和索引。view_item_list 是一次浏览——在 app/components/root/custom-analytics.tsx 中的 COLLECTION_VIEWED 订阅器里推送。为 GA4 添加 index（列表位置）。确保集合查询返回 id、title、handle 和 priceRange，以便获取要推送的值。

---

构建顺序

如果你要从头搭建一个新的 Hydrogen 店面：

1. 在根目录接入 Hydrogen <Analytics.Provider>。 在 <CustomAnalytics /> 组件中订阅其事件。（参见 architecture.md）
2. 在 <head> 中内联添加 Consent Mode v2 默认拒绝代码块、dataLayer 和 gtm.start 标记。
3. 在内联代码块之后，在 <head> 中添加带 nonce 的 gtm.js 外部脚本，并设置为 async。
4. trackEvent() 辅助函数，将数据推送到 dataLayer，并通过 sendBeacon('/api/track') 发送，共用 event_id。
5. /api/track 服务端点，用于验证载荷、在服务端对 PII 进行哈希处理，并将事件分发到 GA4 MP、Meta CAPI 和 Google Ads 转发器。
6. Shopify orders/create webhook，将订单映射为 purchase 事件，并将 event_id 设为 "purchase_" + orderId（重试时保持确定性）。
7. Shopify「Google & YouTube」销售渠道 + Customer Events Pixel，用于结账侧事件（Meta Pixel 事件，以及任何需要在 GTM 无法触达的 Shopify 结账流程内触发的事件）。
8. GTM 容器，为每个 dataLayer 事件配置一个 GA4 Event 标签，并按需添加 Meta Pixel、TikTok 和 Google Ads 转化标签。
9. 更新 CSP，在 script-src、connect-src、img-src 中允许所有供应商域名。使用 strict-dynamic + nonce。
10. 按路由启用 Oxygen 全页缓存，通过 Oxygen-Cache-Control: public, max-age=N, ... 标头配置。在 entry.server.tsx 中从可缓存响应中剥离 Set-Cookie。

---

技能范围内的约定

在本技能范围内处理 Hydrogen 跟踪实现时：

• 服务端代码位于 app/.server/tracking/ 下（转发器、验证器、哈希工具、审计日志）。
• 客户端辅助函数位于 app/utils/track-client.ts（导出 trackEvent、同意状态监听器、归因信息采集）。
• dataLayer 桥接位于 app/components/root/custom-analytics.tsx（订阅 Hydrogen <Analytics.Provider> 事件）。
• 在 app/root.tsx 的 <head> 中内联添加 Consent Mode + GTM 引导代码，并设置 nonce。
• CSP 配置位于 app/weaverse/csp.ts（Weaverse 项目）或店面设置 CSP 的其他位置。
• 各供应商的转发器模块位于 app/.server/tracking/forwarders/{ga4,meta-capi,google-ads}.ts——每个模块都会返回 {forwarder, ok, skipped?, reason?}，以便审计日志说明事件被丢弃的原因。

如果问题涉及的范围不止单个供应商，请优先参阅介绍架构层的参考文档，而非某个供应商的文档。

---

在线文档

请在本技能所在文件夹中运行以下命令。辅助脚本随同级的 shopify-hydrogen 技能一起提供，因此只要安装了整个工具包， ../shopify-hydrogen/scripts/ 就会存在。

如果你单独安装了本技能，该文件夹将不存在，以下命令会因 MODULE_NOT_FOUND 失败。请添加一次这些辅助脚本：

npx skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogen

如果你不想安装它，本技能中的 references/ 文件仍可作为离线备用资料使用。

如需查阅最新的官方资料：

# 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 "analytics provider"

# Weaverse (if using Weaverse CMS)
node ../shopify-hydrogen/scripts/search_weaverse_docs.mjs "csp"

供应商文档（在浏览器中打开，无需脚本）：

• 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