運作方式
由於 Zonos Checkout 在不同來源的 iframe 內運行，無法直接存取您頁面上的 gtag 函式。中繼系統透過兩步握手（步驟 1-2）解決此問題，然後進行事件轉發（步驟 3）：
- Checkout 對父級發送訊號 -- 當 checkout 在 iframe 內加載時，它會傳送訊息到父視窗，表示已準備好中繼事件。
- 父級確認 -- 您頁面上的中繼指令碼收到訊號，偵測您現有的 GA4 配置，並發回訊號表示已準備好接收事件。
- 事件被轉發 -- 當購物者通過結帳進行時，每個分析事件都會透過
postMessage傳送到您的頁面，中繼指令碼再將其轉發到gtag。
所有訊息均根據受信任的 Zonos 來源（zonos.com 和 iglobalstores.com）透過 HTTPS 驗證。
先決條件
- 具有測量 ID（格式：
G-XXXXXXXXXX）的 GA4 屬性。您可以在 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 屬性中找到此片段，方法是進入 Admin -> Data Streams -> 選擇您的串流 -> View tag instructions -> Install manually。
步驟 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 完成握手，並將所有結帳漏斗事件轉發到您的 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 收到訊號。
- 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 屬性中顯示為來自您自己的網站。