Cómo funciona
Como Zonos Checkout se ejecuta dentro de un iframe en un origen diferente, no
puede acceder directamente a la función fbq 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, incluido el Pixel ID.
- La página principal confirma -- El script de retransmisión en su página recibe el ping, detecta (o inyecta) su código base de Meta Pixel 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 afbqcon el modotrack/trackCustomcorrespondiente.
Todos los mensajes se validan contra orígenes de confianza de Zonos (zonos.com
e iglobalstores.com) únicamente por HTTPS.
Requisitos previos
- Un Meta Pixel con un Pixel ID (una cadena numérica, normalmente de 15-16 dígitos). Puede crear uno en Meta Events Manager.
- Una integración heredada de Checkout que cargue Zonos Checkout en un iframe en su página.
- Facebook Pixel habilitado en la configuración de Zonos Checkout (en el Dashboard de Zonos, en Checkout settings -> Tracking).
Configuración
Paso 1: Agregue el código base de Meta Pixel a su página
Si aún no tiene Meta Pixel instalado en su sitio, agregue el código base
estándar de Pixel al <head> de la página que aloja el iframe de Checkout.
Reemplace YOUR_PIXEL_ID por su propio Pixel ID numérico.
<!-- Meta Pixel Code --> <script> !(function (f, b, e, v, n, t, s) { if (f.fbq) return; n = f.fbq = function () { n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments); }; if (!f._fbq) f._fbq = n; n.push = n; n.loaded = !0; n.version = '2.0'; n.queue = []; t = b.createElement(e); t.async = !0; t.src = v; s = b.getElementsByTagName(e)[0]; s.parentNode.insertBefore(t, s); })( window, document, 'script', 'https://connect.facebook.net/en_US/fbevents.js', ); fbq('init', 'YOUR_PIXEL_ID'); fbq('track', 'PageView');</script>Nota: Si su sitio ya tiene Meta Pixel instalado (p. ej., mediante Google Tag Manager, la integración nativa de Shopify o un fragmento directo), puede omitir este paso. El script de retransmisión utilizará su función
fbqexistente.
Puede encontrar este fragmento en su Meta Events Manager en Settings -> Continue Pixel Setup -> Install code manually.
Paso 2: Pase su Pixel ID a Zonos Checkout
Indique a Zonos Checkout qué Pixel ID utilizar configurando
window.Zonos.facebookPixelId dentro del customHTML de su Checkout. El
Dashboard de Zonos expone un editor customHTML en Checkout settings; agregue
una etiqueta <script> como esta:
<script> window.Zonos.facebookPixelId = 'YOUR_PIXEL_ID';</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 fbq cargado, el script de
retransmisión inyectará el código base de Meta Pixel por usted utilizando este
ID.
Paso 3: Agregue el script de retransmisión de analítica de Zonos
Agregue la siguiente etiqueta <script> a la misma página que carga el iframe
de Checkout, después del código base de Meta Pixel. Este es el mismo script
utilizado para Google Analytics 4: una sola retransmisión gestiona ambos
proveedores, así que si ya lo agregó para GA4, omita este paso.
<script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"></script>Ejemplo completo
Así se ve la configuración completa en el <head> de su página:
<head> <!-- ... your existing head tags ... --> <!-- Meta Pixel Code --> <script> !(function (f, b, e, v, n, t, s) { if (f.fbq) return; n = f.fbq = function () { n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments); }; if (!f._fbq) f._fbq = n; n.push = n; n.loaded = !0; n.version = '2.0'; n.queue = []; t = b.createElement(e); t.async = !0; t.src = v; s = b.getElementsByTagName(e)[0]; s.parentNode.insertBefore(t, s); })( window, document, 'script', 'https://connect.facebook.net/en_US/fbevents.js', ); fbq('init', 'YOUR_PIXEL_ID'); fbq('track', 'PageView'); </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, Facebook Pixel esté
habilitado en su Dashboard de Zonos y customHTML configure el Pixel ID, la
retransmisión reenvía automáticamente todos los eventos del embudo de checkout
a Meta.
Referencia de eventos de Meta Pixel
Para cada paso del embudo, Zonos Checkout dispara tanto un evento personalizado
(para que pueda crear audiencias precisas) como el evento estándar de Meta
correspondiente (para que aparezca en la optimización y los informes de
conversión de Meta). Todos los eventos incluyen un indicador isTestMode y el
checkoutSessionId.
| Trigger↕ | Custom event (fbq('trackCustom', ...))↕ | Standard event (fbq('track', ...))↕ | Additional metadata↕ |
|---|---|---|---|
| Se abre el checkout | zonos-checkout-start | InitiateCheckout | -- |
| El comprador ingresa información del cliente | zonos-checkout-customer-info | none | -- |
| El comprador selecciona un método de envío | zonos-checkout-shipping-info | none | serviceLevelId |
| El comprador ingresa datos de pago | zonos-checkout-payment-info | AddPaymentInfo | paymentMethod |
| Falla el intento de pago | zonos-checkout-payment-fail | none | -- |
| El pedido se completa correctamente | zonos-checkout-success | none | order_id, currency, value, contents, content_ids |
| El pedido se completa (evento de comercio electrónico) | purchase | Purchase | order_id, currency, value, contents, content_ids |
| El comprador cierra el checkout | zonos-checkout-close | none | -- |
Los pasos sin un equivalente estándar de Meta (p. ej., información del cliente, información de envío) solo disparan el evento personalizado
zonos-checkout-.... Puede segmentarlos en Meta Ads Manager mediante audiencias personalizadas usando "Event =zonos-checkout-customer-info", etc.
Metadatos del evento Purchase
El evento estándar Purchase sigue el esquema del
evento Purchase de Meta Pixel.
Los artículos del carrito se mapean desde la matriz items al estilo GA hacia
la matriz contents de Meta:
| Field↕ | Description↕ |
|---|---|
value | Valor total del pedido |
currency | Código de moneda de tres letras (p. ej., USD) |
order_id | ID de pedido de Zonos o ID de sesión de checkout |
contents | Matriz de artículos del carrito, cada uno con id, quantity y item_price |
content_ids | Matriz de IDs de artículos (el SKU, ID de producto o nombre de producto alternativo) |
content_type | Siempre "product" |
num_items | Cantidad total en todos los artículos |
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.
- Meta Pixel está configurado con el Pixel ID correcto.
- Los eventos se reenvían a
fbqcon el modotrack/trackCustomesperado.
La extensión de Chrome Meta Pixel Helper también resulta útil para inspeccionar las llamadas a Pixel en tiempo real.
Preguntas frecuentes
¿Por qué se disparan dos eventos para el mismo paso (p. ej., zonos-checkout-start e InitiateCheckout)?
Los eventos estándar de Meta impulsan la optimización de conversiones, los
informes de anuncios y las audiencias similares de forma integrada. Los eventos
personalizados zonos-checkout-... le permiten crear audiencias personalizadas
más granulares en el paso exacto del embudo, incluso cuando no existe un
equivalente estándar de Meta (p. ej., información del cliente, información de
envío). Disparar ambos le ofrece lo mejor de ambos mundos sin perder ninguna
señal.
¿Qué ocurre si ejecuto Google Analytics y Facebook Pixel a la vez?
No necesita dos scripts de retransmisión: el mismo analyticsRelayOnInit.js
gestiona ambos proveedores en un solo protocolo de enlace. Agregue la etiqueta
base de GA4 y el código base de Meta Pixel a su <head>, configure tanto
window.Zonos.googleAnalyticId como window.Zonos.facebookPixelId en
customHTML y habilite ambos proveedores en su Dashboard de Zonos. Cada evento
se distribuye a los proveedores que estén habilitados.
¿Qué ocurre si mi página principal no tiene Meta Pixel instalado?
Si su customHTML configura window.Zonos.facebookPixelId y el script de
retransmisión detecta que no hay fbq en la página, inyectará el código base
de Meta Pixel por usted durante el protocolo de enlace utilizando el Pixel ID
que proporcionó. También puede instalar previamente el código base de Meta Pixel
por su cuenta si desea disparar PageView y otros eventos fuera del embudo de
checkout.
¿Se registran los pedidos de prueba?
Todos los eventos incluyen un campo isTestMode. Cuando Checkout está en modo
de prueba, los eventos aún se retransmiten a Meta pero se marcan con
isTestMode: true. Puede filtrarlos en Meta Ads Manager o excluirlos con
reglas de conversión personalizadas.
¿Conversions API (CAPI) reemplaza esto?
No: esta es una integración de Pixel del lado del navegador que se ejecuta en los navegadores de sus compradores. Meta Conversions API es un canal separado servidor a servidor que algunos comerciantes utilizan junto con Pixel para redundancia. Ambos son complementarios y la retransmisión de Zonos gestiona únicamente el Pixel del lado del navegador.
Facebook Pixel para Checkout iframe
Realice el seguimiento del embudo completo de checkout con Meta (Facebook) Pixel 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 el seguimiento de eventos de Meta Pixel a lo largo del embudo completo de checkout. Zonos Checkout retransmite automáticamente los eventos de analítica desde el iframe a la página principal mediante el mismo script de retransmisión ligero utilizado para Google Analytics 4, de modo que los eventos aparezcan en su Meta Events Manager como si se hubieran originado en su propio sitio.Para cada paso del embudo, se emiten dos eventos:
zonos-checkout-...(mediantefbq('trackCustom', ...)) para audiencias personalizadas de embudo completo.fbq('track', ...)) para la optimización integrada, p. ej.,InitiateCheckout,AddPaymentInfoyPurchase.