Shopify Unified Tracking：安装

转化追踪把店面浏览、加购和购买事件送到你配置的广告平台，浏览器和服务端各发一份，用同一个事件 id 让平台去重。

先建一个店铺

在 Gatekeepers 页面开通 Shopify Tracking。
打开侧栏 Apps 里的 Tracking，点 New store，填名称并选择店面类型：
- Hydrogen：npm 包 + 结账像素，购买事件会被验证；
- Online Store theme：只贴一个像素，不需要改代码，但无法验证购买。
创建后会得到这个店铺的 key（sut_…）。它是公开标识，会出现在页面源码里，只用来标识店铺，不代表权限。

Hydrogen 店铺

安装页（Setup 标签）会给出填好 key 的代码。Gosper 不会替你改代码，三处改动由你自己完成。

1. 安装 npm 包

npm install @gosper/hydrogen-tracking

2. `server.ts`：接管 `/api/gosper/*`

import {withGosperTracking} from '@gosper/hydrogen-tracking/server';

export default withGosperTracking({
  async fetch(request, env, executionContext) {
    // …原有 handler，不变
  },
}, {trackingKey: 'sut_…'});

事件先发到你自己的域名，再由你的服务器转给 Gosper。好处是：同源请求不容易被广告拦截器挡下，cookie 是一方 cookie，Safari 的跨站限制也不适用。

3. `app/root.tsx`：放进 `<Analytics.Provider>`

import {GosperTracking} from '@gosper/hydrogen-tracking';

<Analytics.Provider cart={data.cart} shop={data.shop} consent={data.consent}>
  <GosperTracking />
  {/* …原有布局 */}
</Analytics.Provider>

它订阅 Hydrogen 已经发布的标准事件：页面浏览、商品浏览、系列浏览、搜索、购物车浏览、购物车变化、加购和移出购物车。

4. 内容安全策略（开启浏览器像素时）

Hydrogen 用 createContentSecurityPolicy 管理 CSP，这部分仍然是你的代码。管理页会按你已启用的平台列出需要放行的域名，加进你原有的配置即可：

const {nonce, header, NonceProvider} = createContentSecurityPolicy({
  shop: {
    checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
    storeDomain: context.env.PUBLIC_STORE_DOMAIN,
  },
  defaultSrc: ['https://connect.facebook.net', 'https://www.facebook.com'],
  connectSrc: ['https://connect.facebook.net', 'https://www.facebook.com'],
});

只用服务端 API（关闭浏览器像素）时，不需要改 CSP。

5. 部署，然后贴结账像素

部署店面后，在 Shopify 后台 Settings → Customer events → Add custom pixel，粘贴管理页给出的结账像素代码，Customer privacy 选择需要 Marketing 权限，保存并连接。

结账页不运行 Hydrogen 代码，所以购买事件来自这个像素。

6. 检查

npx gosper-tracking check https://你的店铺域名

它只访问店铺的公开页面，检查：处理器有没有应答、Gosper 认不认这个 key、CSP 有没有放行已启用平台的域名。管理页的 Setup 清单也会显示每一步是否已经完成。

主题店

在 Shopify 后台 Settings → Customer events → Add custom pixel 粘贴管理页给出的完整像素代码即可，店面事件和结账事件都由它发送。

主题店没有自己的服务器，无法登记购物车，所以购买事件不带证明，默认不做验证（见订单排查）。

接下来

配置广告平台后数据才会真正推送：配置广告平台。