Как это работает
Поскольку Zonos Checkout работает внутри iframe на другом домене, он не может напрямую получить доступ к функции gtag вашей страницы. Система трансляции решает эту задачу с помощью двухэтапного handshake (шаги 1-2), за которым следует пересылка событий (шаг 3):
- Checkout связывается с родительским окном — когда Checkout загружается внутри iframe, он отправляет сообщение в родительское окно, указывая, что готов передавать события.
- Родительское окно подтверждает — скрипт трансляции на вашей странице получает ping, определяет вашу существующую конфигурацию GA4 и сигнализирует о готовности получать события.
- События пересылаются — когда покупатели проходят через оформление заказа, каждое событие аналитики отправляется через
postMessageна вашу страницу, где скрипт трансляции пересылает его наgtag.
Все сообщения проверяются на соответствие доверенным источникам Zonos (zonos.com и
iglobalstores.com) только через HTTPS.
Предварительные требования
- Свойство GA4 с идентификатором измерения (формат:
G-XXXXXXXXXX). Вы можете создать свойство в Google Analytics. - Интеграция legacy Checkout, которая загружает Zonos Checkout в iframe на вашу страницу.
Настройка
Шаг 1: добавьте тег GA4 на вашу страницу
Если у вас еще нет GA4 на вашем сайте, добавьте стандартный тег Google Analytics 4 в раздел <head> страницы, на которой размещен iframe Checkout. Замените 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 в разделе Admin -> Data Streams -> выберите свой поток -> View tag instructions -> Install manually.
Шаг 2: передайте идентификатор измерения Zonos Checkout
Скажите Zonos Checkout, какой идентификатор измерения GA4 использовать, установив window.Zonos.googleAnalyticId внутри customHTML вашего Checkout. Панель управления Zonos предоставляет редактор customHTML в параметрах Checkout — добавьте тег <script> как здесь:
<script> window.Zonos.googleAnalyticId = 'G-XXXXXXXXXX';</script>Это значение отправляется на родителя во время handshake трансляции. Если на родительской странице еще не загружен gtag, скрипт трансляции введет базовый тег GA4 для вас, используя этот идентификатор.
Шаг 3: добавьте скрипт трансляции аналитики Zonos
Добавьте следующий тег скрипта на ту же страницу, после тега GA4. Этот скрипт прослушивает события аналитики из iframe Checkout Zonos и пересылает их на ваш 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>Это все. Как только оба скрипта находятся на вашей странице, скрипт трансляции автоматически завершает handshake с iframe Checkout и пересылает все события процесса оформления заказа вашему свойству 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 e-commerce purchase event:
| Поле↕ | Описание↕ |
|---|---|
transaction_id | ID заказа Zonos или ID сеанса оформления заказа |
currency | Трехбуквенный код валюты (например, USD) |
value | Общая стоимость заказа |
items | Массив товаров корзины, каждый с item_id, item_name, price и quantity |
Отладка
Чтобы включить отладочное логирование для скрипта трансляции, добавьте параметр запроса zonosDebug=1 к URL вашей страницы:
https://www.yourstore.com/checkout?zonosDebug=1Откройте консоль разработчика вашего браузера, чтобы увидеть подробные журналы handshake трансляции и пересланных событий. Это полезно для проверки:
- Скрипт трансляции получает ping из iframe Checkout.
- GA4 настроена с правильным идентификатором измерения.
- События пересылаются на
gtag.
Часто задаваемые вопросы
Нужно ли мне изменить мой вызов API createTempCart?
Нет. Система трансляции работает независимо от API createTempCart. Вам нужно только добавить тег GA4 и скрипт трансляции на вашу страницу.
Что если я уже использую footerHTML для Google Analytics?
Параметр footerHTML в API
createTempCart внедряет скрипты внутри iframe Checkout, что ограничено отслеживанием событий на уровне страницы в пределах домена iframe. Подход трансляции рекомендуется, поскольку он отправляет события на ваше собственное свойство GA4 на вашем домене, обеспечивая полный обзор воронки в одном свойстве.
Вы можете безопасно удалить любые скрипты GA4 из footerHTML после настройки трансляции.
Работает ли это с режимом отладки GA4 в Google Analytics?
Да. Вы можете использовать zonosDebug=1 для включения журналов скрипта трансляции в консоли разработчика вашего браузера и использовать
GA4 DebugView в Google Analytics для проверки событий в реальном времени.
Отслеживаются ли тестовые заказы?
Все события включают поле isTestMode. Когда Checkout находится в режиме тестирования, события все еще отправляются в GA4, но помечены как isTestMode: true. При необходимости вы можете отфильтровать их в GA4, используя пользовательские измерения.
Google Analytics 4 для Checkout в iframe
Отследите весь процесс оформления заказа с GA4 при использовании интеграции iframe-based legacy Checkout.
Торговцы, использующие интеграцию legacy Checkout (iframe размещен на
iglobalstores.com), теперь могут отслеживать события аналитики GA4 на всех этапах оформления заказа. Zonos Checkout автоматически передает события аналитики из iframe на родительскую страницу с использованием упрощенного скрипта трансляции, поэтому события появляются в вашем свойстве GA4 так, как будто они исходят с вашего сайта.