工作原理
因为 Zonos Checkout 在不同源的 iframe 中运行，它无法直接访问您页面的 gtag 函数。中继系统通过两步握手（第 1-2 步）解决了这个问题，然后进行事件转发（第 3 步）：
- Checkout 向父页面 ping——当 checkout 在 iframe 中加载时，它向父窗口发送消息，表示已准备好中继事件。
- 父页面应答——您页面上的中继脚本接收 ping，检测您的现有 GA4 配置，并发信号回应已准备好接收事件。
- 事件被转发——当购物者通过 checkout 时，每个分析事件通过
postMessage发送到您的页面，其中中继脚本将其转发到gtag。
所有消息都针对受信任的 Zonos 源（zonos.com 和 iglobalstores.com）通过 HTTPS 验证。
先决条件
- 一个 GA4 属性，带有测量 ID（格式：
G-XXXXXXXXXX）。您可以在 Google Analytics 中创建一个。 - 一个 旧版 Checkout 集成，在您的页面上的 iframe 中加载 Zonos Checkout。
设置
步骤 1：将 GA4 标签添加到您的页面
如果您还没有在网站上安装 GA4，请将标准 Google Analytics 4 标签添加到托管 Checkout iframe 的页面的 <head>。将 G-XXXXXXXXXX 替换为您自己的测量 ID。
<!-- Google tag (gtag.js) --> <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script> <script> window.dataLayer = window.dataLayer || []; function gtag() { dataLayer.push(arguments); } gtag('js', new Date()); gtag('config', 'G-XXXXXXXXXX');</script>注意： 如果您的网站已经安装了 GA4 标签（例如，通过 Google Tag Manager 或直接代码片段），可以跳过此步骤。中继脚本将使用您现有的
gtag函数。
您可以在 GA4 属性中的 管理 -> 数据流 -> 选择您的流 -> 查看标签说明 -> 手动安装 找到此代码片段。
步骤 2：将您的测量 ID 传递给 Zonos Checkout
通过在 Checkout 的 customHTML 中设置 window.Zonos.googleAnalyticId 来告诉 Zonos Checkout 要使用哪个 GA4 测量 ID。Zonos 仪表板在 Checkout 设置中公开了 customHTML 编辑器——添加一个 <script> 标签，如下所示：
<script> window.Zonos.googleAnalyticId = 'G-XXXXXXXXXX';</script>此值在中继握手期间发送给父页面。如果您的父页面还没有加载 gtag，中继脚本将使用此 ID 为您注入 GA4 基础标签。
步骤 3：添加 Zonos 分析中继脚本
将以下脚本标签添加到同一页面，位于 GA4 标签之后。此脚本侦听来自 Zonos Checkout iframe 的分析事件，并将其转发到您的 gtag。
<script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"></script>完整示例
以下是在您页面的 <head> 中完整设置的样子：
<head> <!-- ... your existing head tags ... --> <!-- Google tag (gtag.js) --> <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX" ></script> <script> window.dataLayer = window.dataLayer || []; function gtag() { dataLayer.push(arguments); } gtag('js', new Date()); gtag('config', 'G-XXXXXXXXXX'); </script> <!-- Zonos analytics relay for iframe checkout --> <script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js" ></script></head>就这样。一旦这两个脚本都在您的页面上，中继脚本会自动与 checkout iframe 完成握手，并将所有 checkout 漏斗事件转发到您的 GA4 属性。
GA4 事件参考
Zonos Checkout 通过中继发出以下事件。所有事件都包括 isTestMode 标志和 checkoutSessionId。
| 事件↕ | 触发条件↕ | 额外元数据↕ |
|---|---|---|
zonos-checkout-start | Checkout 打开 | -- |
zonos-checkout-customer-info | 购物者输入客户信息 | -- |
zonos-checkout-shipping-info | 购物者选择运输方式 | serviceLevelId |
zonos-checkout-payment-info | 购物者输入付款详情 | paymentMethod |
zonos-checkout-payment-fail | 支付尝试失败 | -- |
zonos-checkout-success | 订单成功完成 | transaction_id, currency, value, items |
zonos-checkout-close | 购物者关闭 checkout | -- |
purchase | 订单完成（GA4 标准电子商务事件） | transaction_id, currency, value, items |
购买事件元数据
purchase 事件遵循 GA4 电子商务 purchase 事件方案：
| 字段↕ | 描述↕ |
|---|---|
transaction_id | Zonos 订单 ID 或 checkout 会话 ID |
currency | 三字母货币代码（例如，USD） |
value | 订单总价值 |
items | 购物车项目数组，每个项目包含 item_id、item_name、price 和 quantity |
调试
要为中继脚本启用调试日志，请将 zonosDebug=1 查询参数添加到您的页面 URL：
https://www.yourstore.com/checkout?zonosDebug=1在浏览器的开发者控制台中打开以查看中继握手和转发事件的详细日志。这对验证以下内容很有用：
- 中继脚本接收来自 checkout iframe 的 ping。
- GA4 配置了正确的测量 ID。
- 事件被转发到
gtag。
常见问题
我需要修改我的 createTempCart API 调用吗？
不需要。中继系统独立于 createTempCart API 工作。您只需将 GA4 标签和中继脚本添加到您的页面。
如果我已经对 Google Analytics 使用 footerHTML 怎么办？
createTempCart API 中的 footerHTML 参数在 checkout iframe 中注入脚本，这仅限于跟踪 iframe 源中的页面级事件。建议使用中继方法，因为它将事件发送到您在您的域上的 GA4 属性，为您提供单个属性中的完整漏斗可见性。
设置中继后，可以安全地从 footerHTML 中删除任何 GA4 脚本。
这是否适用于 Google Analytics 中的 GA4 调试模式？
是的。您可以使用 zonosDebug=1 在浏览器的开发者控制台中启用中继脚本日志，并在 Google Analytics 中使用 GA4 DebugView 实时验证事件。
测试订单是否被跟踪？
所有事件都包括一个 isTestMode 字段。当 Checkout 处于测试模式时，事件仍然被发送到 GA4，但用 isTestMode: true 标记。如果需要，可以在 GA4 中使用自定义维度过滤这些。
iframe Checkout 的 Google Analytics 4
使用基于 iframe 的旧版 Checkout 集成时，通过 GA4 跟踪完整的结账漏斗。
使用旧版 Checkout 集成（在
iglobalstores.com上托管的 iframe）的商家现在可以跨整个结账漏斗跟踪 GA4 分析事件。Zonos Checkout 使用轻量级中继脚本自动将分析事件从 iframe 中继到父页面，因此事件在您的 GA4 属性中显示时就像来自您自己的网站一样。