仕組み
Zonos Checkoutは別オリジンのiframe内で動作するため、ページのgtag関数に直接アクセスできません。リレーシステムは2段階のハンドシェイク（ステップ1〜2）と、その後のイベント転送（ステップ3）でこれを解決します:
- Checkoutが親にpingする -- iframe内でチェックアウトが読み込まれると、イベントリレーの準備ができたことを示すメッセージを親ウィンドウに送信します。
- 親が応答する -- ページ上のリレースクリプトがpingを受け取り、既存のGA4構成を検出し、イベント受信の準備ができていることを返信します。
- イベントが転送される -- ショッパーがチェックアウトを進めるにつれ、各アナリティクスイベントが
postMessage経由でページに送られ、リレースクリプトがgtagに転送します。
すべてのメッセージは、信頼できるZonosオリジン（zonos.comとiglobalstores.com）に対してHTTPSのみで検証されます。
前提条件
- 測定ID（形式:
G-XXXXXXXXXX）を持つGA4プロパティ。Google Analyticsで作成できます。 - ページ上のiframeでZonos Checkoutを読み込むレガシーCheckout連携。
セットアップ
ステップ1: ページにGA4タグを追加する
サイトにまだGA4がインストールされていない場合は、Checkout iframeをホストするページの<head>に標準のGoogle Analytics 4タグを追加してください。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を設定し、使用するGA4測定IDをZonos Checkoutに伝えます。ZonosダッシュボードはCheckout settings配下に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>以上です。両方のスクリプトがページにあれば、リレースクリプトはチェックアウトiframeとのハンドシェイクを自動完了し、すべてのチェックアウトファネルイベントをGA4プロパティへ転送します。
GA4イベントリファレンス
Zonos Checkoutはリレー経由で次のイベントを発行します。すべてのイベントにisTestModeフラグとcheckoutSessionIdが含まれます。
| Event↕ | Trigger↕ | Additional metadata↕ |
|---|---|---|
zonos-checkout-start | チェックアウトが開く | -- |
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 | ショッパーがチェックアウトを閉じる | -- |
purchase | 注文完了（GA4標準eコマースイベント） | transaction_id, currency, value, items |
Purchaseイベントのメタデータ
purchaseイベントはGA4 eコマースpurchaseイベントスキーマに従います:
| Field↕ | Description↕ |
|---|---|
transaction_id | Zonos注文IDまたはチェックアウトセッションID |
currency | 3文字の通貨コード（例: USD） |
value | 注文合計金額 |
items | カート品目の配列。各要素にitem_id、item_name、price、quantity |
デバッグ
リレースクリプトのデバッグログを有効にするには、ページURLにzonosDebug=1クエリパラメータを追加します:
https://www.yourstore.com/checkout?zonosDebug=1ブラウザの開発者コンソールを開き、リレーハンドシェイクと転送イベントの詳細ログを確認します。次の検証に役立ちます:
- リレースクリプトがチェックアウトiframeからのpingを受信していること。
- GA4が正しい測定IDで構成されていること。
- イベントが
gtagに転送されていること。
よくある質問
createTempCart API呼び出しを変更する必要がありますか？
いいえ。リレーシステムはcreateTempCart APIとは独立して動作します。ページにGA4タグとリレースクリプトを追加するだけで十分です。
Google AnalyticsにすでにfooterHTMLを使っている場合は？
createTempCart APIのfooterHTMLパラメータはチェックアウトiframe内にスクリプトを注入しますが、iframeオリジン内のページレベルイベント追跡に限定されます。リレー方式は自ドメインのGA4プロパティへイベントを送るため、1つのプロパティでファネル全体の可視性を得られるため推奨されます。
リレー設定後は、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プロパティに表示されます。