How it works
因為 Zonos Checkout 在不同來源上的 iframe 內執行，它無法直接存取您頁面的 gtag 函式。中繼系統透過兩步驟握手（步驟 1-2）解決此問題，然後進行事件轉發（步驟 3）：
- Checkout ping 父級 -- 當 checkout 在 iframe 內載入時，它會傳送訊息到父視窗，指示它已準備好中繼事件。
- 父級確認 -- 您頁面上的中繼指令碼收到 ping，偵測您現有的 GA4 設定，並信號回它已準備好接收事件。
- 事件被轉發 -- 當購物者在結帳中進行時，每個分析事件都會透過
postMessage傳送到您的頁面，中繼指令碼將其轉發到gtag。
所有訊息都針對受信任的 Zonos 來源（zonos.com 和 iglobalstores.com）進行驗證，僅透過 HTTPS。
Prerequisites
- 帶有測量 ID（格式：
G-XXXXXXXXXX）的 GA4 資源。您可以在 Google Analytics 中建立一個。 - 在您的頁面上載入 Zonos Checkout 的 iframe 的 舊版 Checkout 整合。
Setup
Step 1: Add the GA4 tag to your page
如果您的網站上還沒有安裝 GA4，請將標準 Google Analytics 4 標籤新增到託管 Checkout iframe 的頁面的 <head> 中。使用您自己的測量 ID 替換 G-XXXXXXXXXX。
<!-- 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 資源中找到此程式碼片段，位於 管理 -> 資料串流 -> 選擇您的串流 -> 檢視標籤指令 -> 手動安裝。
Step 2: Pass your measurement ID to 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 基礎標籤。
Step 3: Add the Zonos analytics relay script
將以下指令碼標籤新增到同一頁面，在 GA4 標籤之後。此指令碼監聽來自 Zonos Checkout iframe 的分析事件，並將其轉發到您的 gtag。
<script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"></script>Complete example
以下是您的頁面 <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 events reference
Zonos Checkout 透過中繼發出以下事件。所有事件都包括 isTestMode 旗標和 checkoutSessionId。
| Event↕ | Trigger↕ | Additional metadata↕ |
|---|---|---|
zonos-checkout-start | Checkout opens | -- |
zonos-checkout-customer-info | Shopper enters customer information | -- |
zonos-checkout-shipping-info | Shopper selects a shipping method | serviceLevelId |
zonos-checkout-payment-info | Shopper enters payment details | paymentMethod |
zonos-checkout-payment-fail | Payment attempt fails | -- |
zonos-checkout-success | Order completes successfully | transaction_id, currency, value, items |
zonos-checkout-close | Shopper closes checkout | -- |
purchase | Order completes (GA4 standard e-commerce event) | transaction_id, currency, value, items |
Purchase event metadata
purchase 事件遵循 GA4 電子商務 purchase 事件 結構：
| Field↕ | Description↕ |
|---|---|
transaction_id | Zonos order ID or checkout session ID |
currency | Three-letter currency code (e.g., USD) |
value | Total order value |
items | Array of cart items, each with item_id, item_name, price, and quantity |
Debugging
若要啟用中繼指令碼的偵錯日誌，請將 zonosDebug=1 查詢參數新增到您的頁面 URL：
https://www.yourstore.com/checkout?zonosDebug=1開啟您的瀏覽器開發人員主控台以查看中繼握手和轉發事件的詳細日誌。這對驗證以下內容很有用：
- 中繼指令碼接收來自 checkout iframe 的 ping。
- GA4 設定了正確的測量 ID。
- 事件被轉發到
gtag。
Common questions
Do I need to modify my createTempCart API call?
否。中繼系統獨立於 createTempCart API 工作。您只需要將 GA4 標籤和中繼指令碼新增到您的頁面。
What if I already use footerHTML for Google Analytics?
createTempCart API 中的 footerHTML 參數會在 checkout iframe 內注入指令碼，僅限於追蹤 iframe 來源內的頁面層級事件。建議使用中繼方法，因為它會將事件傳送到您自己網域上的 GA4 資源，讓您在單一資源中完整查看漏斗。
設定中繼後，您可以安全地從 footerHTML 中移除任何 GA4 指令碼。
Does this work with GA4 debug mode in Google Analytics?
是的。您可以使用 zonosDebug=1 在瀏覽器開發人員主控台中啟用中繼指令碼日誌，並在 Google Analytics 中使用 GA4 DebugView 即時驗證事件。
Are test orders tracked?
所有事件都包括 isTestMode 欄位。當 Checkout 處於測試模式時，事件仍會傳送到 GA4，但標記為 isTestMode: true。如果需要，您可以在 GA4 中使用自訂維度篩選這些事件。
Google Analytics 4 for iframe Checkout
在使用以 iframe 為基礎的舊版 Checkout 整合時，使用 GA4 追蹤完整結帳漏斗。
使用舊版 Checkout 整合的商家（iframe 託管於
iglobalstores.com）現在可以在完整結帳漏斗中追蹤 GA4 分析事件。Zonos Checkout 會自動使用輕量級中繼指令碼將分析事件從 iframe 中繼到父頁面，因此事件會在您的 GA4 資源中顯示為源自您自己網站的事件。