How it works
Zonos Checkout은 다른 origin의 iframe에서 실행되므로 페이지의 gtag 함수에 직접 액세스할 수 없습니다. relay 시스템은 2단계 handshake(1–2단계) 후 이벤트 전달(3단계)로 이를 해결합니다:
- Checkout이 부모에 ping — checkout이 iframe에서 로드되면 이벤트 relay 준비가 되었음을 부모 창에 메시지로 보냅니다.
- 부모가 확인 — 페이지의 relay 스크립트가 ping을 수신하고 기존 GA4 구성을 감지한 뒤 이벤트 수신 준비가 되었음을 응답합니다.
- 이벤트 전달 — 구매자가 checkout을 진행하면 각 analytics 이벤트가
postMessage로 페이지에 전송되고, relay 스크립트가gtag로 전달합니다.
All messages are validated against trusted Zonos origins (zonos.com and
iglobalstores.com) over HTTPS only.
Prerequisites
- measurement ID(
G-XXXXXXXXXX형식)가 있는 GA4 속성. Google Analytics에서 생성할 수 있습니다. - A legacy Checkout integration that loads Zonos Checkout in an iframe on your page.
Setup
1단계: 페이지에 GA4 태그 추가
사이트에 GA4가 없으면 Checkout iframe을 호스팅하는 페이지의 <head>에 표준 Google Analytics 4 태그를 추가하세요. G-XXXXXXXXXX를 본인의 measurement 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>Note: 사이트에 GA4 태그가 이미 설치되어 있으면(Google Tag Manager 또는 직접 스니펫) 이 단계를 건너뛸 수 있습니다. relay 스크립트가 기존
gtag함수를 사용합니다.
GA4 속성의 Admin → Data Streams → 스트림 선택 → View tag instructions → Install manually에서 이 스니펫을 찾을 수 있습니다.
2단계: Zonos Checkout에 measurement ID 전달
Checkout의 customHTML에서 window.Zonos.googleAnalyticId를 설정하여 Zonos Checkout에 사용할 GA4 measurement ID를 알려 주세요. Zonos Dashboard의 Checkout settings에 customHTML 편집기가 있습니다. 다음과 같이 <script> 태그를 추가하세요:
<script> window.Zonos.googleAnalyticId = "G-XXXXXXXXXX";</script>이 값은 relay handshake 중 부모에 전송됩니다. 부모 페이지에 gtag가 없으면 relay 스크립트가 이 ID로 GA4 기본 태그를 주입합니다.
Step 3: Add the Zonos analytics relay script
GA4 태그 다음, 동일 페이지에 다음 script 태그를 추가하세요. 이 스크립트는 Zonos Checkout iframe의 analytics 이벤트를 수신하여 gtag로 전달합니다.
<script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"></script>Complete example
Here's what the full setup looks like in your page's <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>완료입니다. 두 스크립트가 페이지에 있으면 relay 스크립트가 checkout iframe과 handshake를 자동 완료하고 모든 checkout 퍼널 이벤트를 GA4 속성으로 전달합니다.
GA4 이벤트 참조
Zonos Checkout은 relay를 통해 다음 이벤트를 발생시킵니다. 모든 이벤트에 isTestMode 플래그와 checkoutSessionId가 포함됩니다.
| Event↕ | Trigger↕ | Additional metadata↕ |
|---|---|---|
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 표준 e-commerce 이벤트) | transaction_id, currency, value, items |
Purchase event metadata
purchase 이벤트는 GA4 e-commerce purchase event 스키마를 따릅니다:
| Field↕ | Description↕ |
|---|---|
transaction_id | Zonos order ID 또는 checkout session ID |
currency | 3자리 통화 코드(예: USD) |
value | 주문 총액 |
items | item_id, item_name, price, quantity를 포함하는 장바구니 품목 배열 |
Debugging
To enable debug logging for the relay script, add the zonosDebug=1 query
parameter to your page URL:
https://www.yourstore.com/checkout?zonosDebug=1Open your browser's developer console to see detailed logs of the relay handshake and forwarded events. This is useful for verifying that:
- relay 스크립트가 checkout iframe의 ping을 수신합니다.
- GA4가 올바른 measurement ID로 구성되어 있습니다.
- 이벤트가
gtag로 전달됩니다.
Common questions
createTempCart API 호출을 수정해야 하나요?
아니요. relay 시스템은 createTempCart API와 독립적으로 동작합니다. 페이지에 GA4 태그와 relay 스크립트만 추가하면 됩니다.
Google Analytics에 이미 footerHTML을 사용 중인 경우?
createTempCart API의 footerHTML 매개변수는 checkout iframe 내부에 스크립트를 주입하며, iframe origin 내 페이지 수준 이벤트 추적에 한정됩니다. relay 방식은 귀하의 도메인 GA4 속성으로 이벤트를 전송하여 단일 속성에서 전체 퍼널 가시성을 제공하므로 권장됩니다.
relay 설정 후 footerHTML의 GA4 스크립트는 안전하게 제거할 수 있습니다.
Google Analytics의 GA4 debug mode와 호환되나요?
예. zonosDebug=1로 브라우저 개발자 콘솔에서 relay 스크립트 로그를 활성화하고, Google Analytics의 GA4 DebugView로 실시간 이벤트를 확인할 수 있습니다.
Are test orders tracked?
모든 이벤트에 isTestMode 필드가 포함됩니다. Checkout이 테스트 모드일 때도 이벤트는 GA4로 전송되지만 isTestMode: true로 표시됩니다. 필요하면 GA4 맞춤 dimension으로 필터링할 수 있습니다.
iframe Checkout용 Google Analytics 4
iframe 기반 레거시 Checkout 통합 시 GA4로 전체 checkout 퍼널을 추적합니다.
iglobalstores.com에서 호스팅되는 iframe 레거시 Checkout 통합을 사용하는 판매자는 전체 checkout 퍼널에서 GA4 analytics 이벤트를 추적할 수 있습니다. Zonos Checkout은 경량 relay 스크립트로 iframe의 analytics 이벤트를 부모 페이지로 자동 전달하므로, 이벤트가 자체 사이트에서 발생한 것처럼 GA4 속성에 표시됩니다.