Cómo funciona
Como Zonos Checkout se ejecuta dentro de un iframe en un origen diferente, no
puede acceder directamente a la función gtag de su página. El sistema de
retransmisión resuelve esto con un protocolo de enlace en dos pasos (pasos 1-2)
seguido del reenvío de eventos (paso 3):
- Checkout envía un ping a la página principal -- Cuando el checkout se carga dentro del iframe, envía un mensaje a la ventana principal indicando que está listo para retransmitir eventos.
- La página principal confirma -- El script de retransmisión en su página recibe el ping, detecta su configuración existente de GA4 y señala que está listo para recibir eventos.
- Los eventos se reenvían -- A medida que los compradores avanzan en el
checkout, cada evento de analítica se envía mediante
postMessagea su página, donde el script de retransmisión lo reenvía agtag.
Todos los mensajes se validan contra orígenes de confianza de Zonos
(zonos.com e iglobalstores.com) únicamente por HTTPS.
Requisitos previos
- Una propiedad de GA4 con un ID de medición (formato:
G-XXXXXXXXXX). Puede crear una en Google Analytics. - Una integración heredada de Checkout que cargue Zonos Checkout en un iframe en su página.
Configuración
Paso 1: Agregar la etiqueta de GA4 a su página
Si aún no tiene GA4 instalado en su sitio, agregue la etiqueta estándar de
Google Analytics 4 al <head> de la página que aloja el iframe de Checkout.
Reemplace G-XXXXXXXXXX por su propio ID de medición.
<!-- 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>Nota: Si su sitio ya tiene la etiqueta de GA4 instalada (p. ej., mediante Google Tag Manager o un fragmento directo), puede omitir este paso. El script de retransmisión utilizará su función
gtagexistente.
Puede encontrar este fragmento en su propiedad de GA4 en Admin -> Data Streams -> seleccione su flujo -> View tag instructions -> Install manually.
Paso 2: Pasar su ID de medición a Zonos Checkout
Indique a Zonos Checkout qué ID de medición de GA4 utilizar configurando
window.Zonos.googleAnalyticId dentro del customHTML de su Checkout. El
Dashboard de Zonos expone un editor de customHTML en la configuración de
Checkout -- agregue una etiqueta <script> como esta:
<script> window.Zonos.googleAnalyticId = 'G-XXXXXXXXXX';</script>Este valor se envía a la página principal durante el protocolo de enlace de
retransmisión. Si su página principal aún no tiene gtag cargado, el script de
retransmisión inyectará la etiqueta base de GA4 por usted utilizando este ID.
Paso 3: Agregar el script de retransmisión de analítica de Zonos
Agregue la siguiente etiqueta de script a la misma página, después de la
etiqueta de GA4. Este script escucha los eventos de analítica del iframe de
Zonos Checkout y los reenvía a su gtag.
<script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"></script>Ejemplo completo
Así es como se ve la configuración completa en el <head> de su página:
<head> <!-- ... sus etiquetas head existentes ... --> <!-- 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>Eso es todo. Una vez que ambos scripts estén en su página, el script de retransmisión completa automáticamente el protocolo de enlace con el iframe de checkout y reenvía todos los eventos del embudo de checkout a su propiedad de GA4.
Referencia de eventos de GA4
Zonos Checkout emite los siguientes eventos a través de la retransmisión. Todos
los eventos incluyen un indicador isTestMode y el checkoutSessionId.
| Evento↕ | Desencadenante↕ | Metadatos adicionales↕ |
|---|---|---|
zonos-checkout-start | Se abre el checkout | -- |
zonos-checkout-customer-info | El comprador ingresa la información del cliente | -- |
zonos-checkout-shipping-info | El comprador selecciona un método de envío | serviceLevelId |
zonos-checkout-payment-info | El comprador ingresa los datos de pago | paymentMethod |
zonos-checkout-payment-fail | El intento de pago falla | -- |
zonos-checkout-success | El pedido se completa correctamente | transaction_id, currency, value, items |
zonos-checkout-close | El comprador cierra el checkout | -- |
purchase | El pedido se completa (evento de comercio electrónico estándar de GA4) | transaction_id, currency, value, items |
Metadatos del evento purchase
El evento purchase sigue el esquema del
evento purchase de comercio electrónico de GA4:
| Campo↕ | Descripción↕ |
|---|---|
transaction_id | ID de pedido de Zonos o ID de sesión de checkout |
currency | Código de moneda de tres letras (p. ej., USD) |
value | Valor total del pedido |
items | Matriz de artículos del carrito, cada uno con item_id, item_name, price y quantity |
Depuración
Para habilitar el registro de depuración del script de retransmisión, agregue el
parámetro de consulta zonosDebug=1 a la URL de su página:
https://www.yourstore.com/checkout?zonosDebug=1Abra la consola de desarrollador de su navegador para ver registros detallados del protocolo de enlace de retransmisión y de los eventos reenviados. Esto es útil para verificar que:
- El script de retransmisión recibe el ping del iframe de checkout.
- GA4 está configurado con el ID de medición correcto.
- Los eventos se están reenviando a
gtag.
Preguntas frecuentes
¿Necesito modificar mi llamada a la API createTempCart?
No. El sistema de retransmisión funciona de forma independiente de la API
createTempCart. Solo necesita agregar la etiqueta de GA4 y el script de
retransmisión a su página.
¿Qué ocurre si ya utilizo footerHTML para Google Analytics?
El parámetro footerHTML en la API
createTempCart
inyecta scripts dentro del iframe de checkout, lo que se limita al seguimiento
de eventos a nivel de página dentro del origen del iframe. Se recomienda el
enfoque de retransmisión porque envía eventos a su propia propiedad de GA4 en su
dominio, lo que le ofrece visibilidad completa del embudo en una sola propiedad.
Puede eliminar de forma segura cualquier script de GA4 de footerHTML después
de configurar la retransmisión.
¿Funciona esto con el modo de depuración de GA4 en Google Analytics?
Sí. Puede utilizar zonosDebug=1 para habilitar los registros del script de
retransmisión en la consola de desarrollador de su navegador, y utilizar
GA4 DebugView en Google
Analytics para verificar los eventos en tiempo real.
¿Se realizan un seguimiento de los pedidos de prueba?
Todos los eventos incluyen un campo isTestMode. Cuando Checkout está en modo
de prueba, los eventos aún se envían a GA4 pero se marcan con
isTestMode: true. Puede filtrarlos en GA4 mediante dimensiones personalizadas
si lo necesita.
Google Analytics 4 para Checkout iframe
Realice un seguimiento del embudo completo de checkout con GA4 al utilizar una integración heredada de Checkout basada en iframe.
Los comerciantes que utilizan la integración heredada de Checkout (iframe alojado en
iglobalstores.com) pueden realizar un seguimiento de los eventos de analítica de GA4 en todo el embudo de checkout. Zonos Checkout retransmite automáticamente los eventos de analítica desde el iframe a la página principal mediante un script de retransmisión ligero, de modo que los eventos aparezcan en su propiedad de GA4 como si se hubieran originado en su propio sitio.