ShopifyHeadlessHydrogen数据埋点AnalyticsConsentCustomer Privacy

Headless 事件追踪：离开主题之后，什么变了

2026年8月8日 ·约 4 分钟阅读

你转向了 Headless。店面更快了，设计自定义了，结账还是 Shopify 的。但当你看数据时，一半的事件都不见了。产品浏览？没了。加购？静默。购买？还在。这篇文章解释为什么——以及怎么修。

Headless 追踪的分裂

当你从 Shopify 主题转向 Headless 店面（比如 Hydrogen），事件追踪分裂成两套完全不同的系统：

会坏的：

  • 产品页浏览
  • 集合页浏览
  • 搜索事件
  • 加购
  • 购物车浏览
  • 任何自定义店面交互

能留的：

  • 结账开始
  • 支付信息提交
  • 结账完成（购买）

原因在于架构：Shopify 的 Customer Events（web pixels）只运行在 Shopify 托管的页面上——Online Store 主题和结账页。你的自定义 Hydrogen 店面是你自己的 React 应用，托管在别处，所以 Shopify 的像素系统根本不会在那里加载。

这意味着：

  • 如果你通过 Settings → Customer Events 装了像素，它们会在结账时触发，但不会在店面上触发
  • 店面事件需要完全不同的搭建——要么用 Hydrogen 内置的 Analytics 组件，要么手动嵌入像素脚本

事件如何传输：两条独立管道

Headless 追踪用两条独立管道，取决于事件发生在哪里：

管道 1：店面事件（你的 React 应用）

当顾客浏览你的 Hydrogen 店面时，事件这样流动：

Hydrogen 组件 → Analytics.Provider → Shopify Monorail → Shopify Analytics

触发什么：

  • page_rendered（所有页面）
  • collection_page_rendered
  • product_page_rendered
  • product_added_to_cart
  • search_submitted

发到哪里：

  • Shopify 内部分析（Monorail，schema custom_storefront_customer_tracking/1.2）
  • 显示在 Shopify 后台 Analytics 报表里
  • 不会自动发到 GA4、Meta、TikTok 或任何第三方平台

要把店面事件送进 GA4/Meta/TikTok，你有两个选择（下一节讲）。

管道 2：结账事件（Shopify 托管）

当顾客点「结账」时，他们离开你的 Hydrogen 店面，落到 Shopify 托管的结账域（checkout.yourstore.com）。从这里开始：

Shopify 结账 → Customer Events（Web Pixels）→ 你的像素（GA4、Meta 等）

触发什么：

  • checkout_started
  • checkout_contact_info_submitted
  • checkout_address_info_submitted
  • checkout_shipping_info_submitted
  • payment_info_submitted
  • checkout_completed（购买）

发到哪里：

  • 任何你通过 Settings → Customer Events 装的像素
  • 工作方式跟主题店铺完全一样
  • 购买归因完整保留——即使是 headless，你也能拿到完整的结账数据

这是好消息：你的转化追踪不会坏。坏消息是：结账之前的一切都需要重建。

发送店面事件的两种方式

你的 Hydrogen 店面是个没有沙盒限制的 React 应用。你有两种方式把事件送进第三方平台——而且可以混用：

方式 1：直接嵌入像素脚本（手动）

在你的 Hydrogen 应用里直接加载 Meta Pixel、gtag 或 TikTok Pixel，然后手动触发事件：

// 在产品页组件里
fbq('track', 'ViewContent', {
  content_ids: ['12345'],
  content_type: 'product',
  value: 29.99,
  currency: 'USD'
});

// 在加购处理器里
fbq('track', 'AddToCart', {
  content_ids: ['12345'],
  value: 29.99,
  currency: 'USD'
});

优点：

  • 完全控制事件时机和参数
  • 不依赖 Hydrogen 的 Analytics 组件
  • 适用于任何追踪搭建

缺点：

  • 每个事件调用都要手写
  • 容易漏事件或发送不一致的数据
  • consent 门控要自己处理

方式 2：订阅 Hydrogen 的事件总线（便利层）

Hydrogen 的 Analytics 组件（Analytics.ProductView、Analytics.CartView 等）自动采集标准事件。你可以订阅这个事件总线，把所有东西转发到你的平台：

import { useAnalytics } from '@shopify/hydrogen-react';

function AnalyticsListener() {
  const { subscribe } = useAnalytics();

  useEffect(() => {
    subscribe('product_page_rendered', (event) => {
      // 转发到 Meta
      fbq('track', 'ViewContent', {
        content_ids: [event.products[0].product_id],
        value: event.products[0].price,
        currency: event.currency
      });

      // 转发到 GA4
      gtag('event', 'view_item', {
        items: event.products,
        value: event.total_value,
        currency: event.currency
      });
    });
  }, []);
}

优点：

  • Hydrogen 替你采集数据（页面浏览、购物车内容、产品详情）
  • 一个集中位置转发事件到多个平台
  • 一致的事件结构

缺点：

  • 只有用了 Hydrogen 的 Analytics 组件才有效
  • 如果不用 Analytics.ProductView，就没有东西可订阅
  • 还是要处理 consent 门控

**最佳实践：**两个都用。标准事件（页面浏览、加购）走 subscribe()。自定义交互（视频播放、表单提交）手动触发。

不确定要追踪哪些事件？填写你的自定义事件需求表 →

Consent：硬门

这是大多数指南跳过的关键部分：Hydrogen 的 Analytics 组件在触发任何东西之前会检查 consent。

来自 Hydrogen 源码（analytics.ts）：

if (!payload.hasUserConsent) return Promise.resolve();

如果你没配置 consent，零事件触发。没有页面浏览，没有加购，什么都没有。这是设计使然——Shopify 在框架层面强制执行隐私合规。

Shopify 推荐的方案用 Customer Privacy API 加原生 Cookie 横幅：

  1. 分配结账子域名——把 checkout.yourdomain.com 指向你的 Online Store（Settings → Domains → Target: Online Store, Type: Primary）。这确保 consent cookie 在你的 Hydrogen 店面和 Shopify 结账之间共享。

  2. 添加环境变量——在 Storefront settings → Environments and variables，添加 PUBLIC_CHECKOUT_DOMAIN（不带 https://），应用到 Production。

  3. 配置 CSP——你的 Content Security Policy 必须包含商店和结账域名（Hydrogen skeleton 默认已包含）。

  4. 开启 Cookie 横幅——Settings → Customer Privacy → Cookie banner。选择地区，自定义外观和文案。

  5. 在代码里开启——给 Analytics.Provider 传 withPrivacyBanner: true：

<Analytics.Provider
  shopId="your-shop-id"
  consent={{
    withPrivacyBanner: true,
    country: 'US',
    language: 'en'
  }}
>
  {/* 你的应用 */}
</Analytics.Provider>

这是优雅的部分：consent 在你的 Hydrogen 店面和 Shopify 结账之间共享。当顾客在你的店面上接受 cookie 时，他们在结账时不会再看到横幅。

机制：

  • Shopify 把 consent 存在商店域名下的 HTTP-only cookie 里
  • 结账子域名配置（第 1 步）确保两个界面共享同一个 cookie
  • 地区设置（EEA、UK 等）对两个界面统一生效

如果你跳过结账子域名配置，consent 不会传递——顾客会看到两次横幅。这就是为什么 5 步配置不是可选项。

  • 第三方 CMP——Consentmo、Pandectes、Avada 都支持 Hydrogen + Customer Privacy API + Google Consent Mode v2
  • 自建横幅——自己实现同意采集 UI，手动设置 consent 状态，自己门控像素触发（完全灵活，完全合规责任）

Shopify 官方立场：「你负责确保从 Hydrogen 站点发出的所有分析都符合 consent 法规。」

Hydrogen 实际发送什么（源码级验证）

来自 hydrogen-react/src/analytics-schema-custom-storefront-customer-tracking.ts，这是 Hydrogen 的 Analytics 组件实际追踪的内容：

事件：

  • page_rendered——所有页面
  • collection_page_rendered——集合页
  • product_page_rendered——产品页
  • product_added_to_cart——加购
  • search_submitted——搜索

每个事件携带的字段：

页面上下文：

  • canonical_url
  • event_source_url（url、path、search 参数、title）
  • referrer
  • user_agent
  • navigation_type

商店/用户：

  • shop_id
  • customer_id
  • currency

产品（产品/购物车事件）：

  • products[] 数组，含 product_id、variant_id、variant_gid、sku、name、brand、category、price、quantity
  • total_value

购物车：

  • cart_token

隐私标志：

  • analytics_allowed
  • marketing_allowed
  • sale_of_data_allowed
  • gdpr_enforced
  • ccpa_enforced
  • is_persistent_cookie（= hasUserConsent）

目的地：https://{shopDomain}/.well-known/shopify/monorail/unstable/produce_batch（或 monorail-edge.shopifysvc.com），schema custom_storefront_customer_tracking/1.2。

这些数据进 Shopify 内部分析。要拿到 GA4/Meta/TikTok 里，你订阅并转发（上面的方式 2）或手动发送（方式 1）。

事件到达 GA4/Meta/TikTok 后，需要用对名字——看完整的事件对照表 →

常见问题

转向 headless 时需要重建所有追踪吗？

只需要重建店面追踪。结账事件（结账开始、支付提交、购买）跟主题店铺完全一样——它们由 Shopify 的 Customer Events 系统处理。但产品浏览、加购和搜索事件需要用 Hydrogen 的 Analytics 组件或手动像素脚本重建。

我能在 Hydrogen 上用 Google Tag Manager 吗？

能——GTM 在 Hydrogen 上工作正常。你可以在根布局里加载 GTM 脚本，用 GTM 的 data layer 触发事件。但你还是要自己处理 consent 门控，而且要手动推送事件到 data layer（或用 Hydrogen 的 useAnalytics().subscribe() 转发）。

如果不配置 consent 会怎样？

什么都不触发。Hydrogen 的 Analytics 组件在发送任何东西之前检查 hasUserConsent。如果没配置 consent，你得到零页面浏览、零加购、零搜索事件。这是故意的——Shopify 在框架层面强制执行隐私合规。

顾客会看到两次 cookie 横幅吗（店面 + 结账）？

如果配置正确就不会。当你分配结账子域名（checkout.yourdomain.com）并配置 Customer Privacy API 时，consent 存在共享 cookie 里。顾客在你的店面上接受一次，结账时横幅不会再出现。

能混用手动像素脚本和 Hydrogen 的 Analytics 组件吗？

当然。最佳实践是用 Hydrogen 的 Analytics 组件处理标准事件（页面浏览、加购），订阅并转发到你的平台。对于自定义交互（视频播放、表单提交），用 fbq()、gtag() 等手动触发事件。只要确保两条路都尊重 consent。

Headless 追踪架构已对照 Shopify Hydrogen 文档、Customer Privacy API 文档和 hydrogen-react 源码核实，核验时间 2026 年 8 月。Hydrogen 在活跃开发中——如果你发现任何过时内容，告诉我们，我们会更新文章。

信息核对

核查日期: 2026-08-08