DOCS
Checkout•
HomeAPI reference Checkout REST API Google Analytics 4

Google Analytics 4 for iframe Checkout

Track the full checkout funnel with GA4 when using an iframe-based legacy Checkout integration.

Merchants using the legacy Checkout integration (iframe hosted on iglobalstores.com) can now track GA4 analytics events across the full checkout funnel. Zonos Checkout automatically relays analytics events from the iframe to the parent page using a lightweight relay script, so events appear in your GA4 property as if they originated from your own site.

Native integrations don't need this guide. If <zonos-checkout> renders directly on your site (no iframe), Zonos calls your page's window.gtag in place — just enable Google Analytics in the Zonos dashboard under Checkout settings → Tracking and make sure your usual GA4 base tag is loaded on the page. The relay setup below is only required when Checkout is hosted in an iframe on a different origin.

Looking to track Meta Ads conversions instead? See the Facebook Pixel guide -- it uses the same relay script and can run alongside GA4.

How it works 

Because the Zonos Checkout runs inside an iframe on a different origin, it cannot directly access your page's gtag function. The relay system solves this with a two-step handshake (steps 1-2) followed by event forwarding (step 3):

  1. Checkout pings the parent -- When the checkout loads inside the iframe, it sends a message to the parent window indicating it's ready to relay events.
  2. Parent acknowledges -- The relay script on your page receives the ping, detects your existing GA4 configuration, and signals back that it's ready to receive events.
  3. Events are forwarded -- As shoppers progress through checkout, each analytics event is sent via postMessage to your page, where the relay script forwards it to gtag.

All messages are validated against trusted Zonos origins (zonos.com and iglobalstores.com) over HTTPS only.

Prerequisites 

  • A GA4 property with a measurement ID (format: G-XXXXXXXXXX). You can create one in Google Analytics.
  • A legacy Checkout integration that loads Zonos Checkout in an iframe on your page.

Setup 

Step 1: Add the GA4 tag to your page

If you don't already have GA4 installed on your site, add the standard Google Analytics 4 tag to the <head> of the page that hosts the Checkout iframe. Replace G-XXXXXXXXXX with your own measurement ID.

1<!-- Google tag (gtag.js) -->
2 
3<script
4 async
5 src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"
6></script>
7 
8<script>
9 window.dataLayer = window.dataLayer || [];
10 function gtag() {
11 dataLayer.push(arguments);
12 }
13 gtag("js", new Date());
14 gtag("config", "G-XXXXXXXXXX");
15</script>

Note: If your site already has the GA4 tag installed (e.g., through Google Tag Manager or a direct snippet), you can skip this step. The relay script will use your existing gtag function.

You can find this snippet in your GA4 property under Admin -> Data Streams -> select your stream -> View tag instructions -> Install manually.

Step 2: Pass your measurement ID to Zonos Checkout

Tell Zonos Checkout which GA4 measurement ID to use by setting window.Zonos.googleAnalyticId inside your Checkout's customHTML. The Zonos dashboard exposes a customHTML editor under Checkout settings -- add a <script> tag like this:

1<script>
2 window.Zonos.googleAnalyticId = "G-XXXXXXXXXX";
3</script>

This value is sent to the parent during the relay handshake. If your parent page doesn't already have gtag loaded, the relay script will inject the GA4 base tag for you using this ID.

Step 3: Add the Zonos analytics relay script

Add the following script tag to the same page, after the GA4 tag. This script listens for analytics events from the Zonos Checkout iframe and forwards them to your gtag.

1<script
2 async
3 src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"
4></script>

Complete example

Here's what the full setup looks like in your page's <head>:

1<head>
2 <!-- ... your existing head tags ... -->
3 
4 <!-- Google tag (gtag.js) -->
5 
6 <script
7 async
8 src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"
9 ></script>
10 
11 <script>
12 window.dataLayer = window.dataLayer || [];
13 function gtag() {
14 dataLayer.push(arguments);
15 }
16 gtag("js", new Date());
17 gtag("config", "G-XXXXXXXXXX");
18 </script>
19 
20 <!-- Zonos analytics relay for iframe checkout -->
21 
22 <script
23 async
24 src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"
25 ></script>
26</head>

That's it. Once both scripts are on your page, the relay script automatically completes the handshake with the checkout iframe and forwards all checkout funnel events to your GA4 property.

GA4 events reference 

Zonos Checkout emits the following events through the relay. All events include an isTestMode flag and the checkoutSessionId.

Event↕Trigger↕Additional metadata↕
zonos-checkout-startCheckout opens--
zonos-checkout-customer-infoShopper enters customer information--
zonos-checkout-shipping-infoShopper selects a shipping methodserviceLevelId
zonos-checkout-payment-infoShopper enters payment detailspaymentMethod
zonos-checkout-payment-failPayment attempt fails--
zonos-checkout-successOrder completes successfullytransaction_id, currency, value, items
zonos-checkout-closeShopper closes checkout--
purchaseOrder completes (GA4 standard e-commerce event)transaction_id, currency, value, items

Purchase event metadata

The purchase event follows the GA4 e-commerce purchase event schema:

Field↕Description↕
transaction_idZonos order ID or checkout session ID
currencyThree-letter currency code (e.g., USD)
valueTotal order value
itemsArray of cart items, each with item_id, item_name, price, and quantity

Debugging 

To enable debug logging for the relay script, add the zonosDebug=1 query parameter to your page URL:

1https://www.yourstore.com/checkout?zonosDebug=1

Open your browser's developer console to see detailed logs of the relay handshake and forwarded events. This is useful for verifying that:

  • The relay script receives the ping from the checkout iframe.
  • GA4 is configured with the correct measurement ID.
  • Events are being forwarded to gtag.

Common questions 

Do I need to modify my createTempCart API call?

No. The relay system works independently of the createTempCart API. You only need to add the GA4 tag and the relay script to your page.

What if I already use footerHTML for Google Analytics?

The footerHTML parameter in the createTempCart API injects scripts inside the checkout iframe, which is limited to tracking page-level events within the iframe origin. The relay approach is recommended because it sends events to your own GA4 property on your domain, giving you full funnel visibility in a single property.

You can safely remove any GA4 scripts from footerHTML after setting up the relay.

Does this work with GA4 debug mode in Google Analytics?

Yes. You can use zonosDebug=1 to enable relay script logs in your browser's developer console, and use the GA4 DebugView in Google Analytics to verify events in real time.

Are test orders tracked?

All events include an isTestMode field. When Checkout is in test mode, events are still sent to GA4 but flagged with isTestMode: true. You can filter these out in GA4 using custom dimensions if needed.

Was this page helpful?

Get support·Legal docs·© 2026 Zonos
On this page:
  • Google Analytics 4 for iframe Checkout
  • How it works
  • Prerequisites
  • Setup
  • GA4 events reference
  • Debugging
  • Common questions