DOCS
Checkout•
InícioReferência da API Checkout REST API Facebook Pixel

Facebook Pixel para o Checkout em iframe

Acompanhe todo o funil de checkout com o Meta (Facebook) Pixel quando utiliza uma integração do Checkout legado baseada em iframe.

Os comerciantes que utilizam a integração do Checkout legado (iframe alojado em iglobalstores.com) podem rastrear eventos do Meta Pixel ao longo de todo o funil de checkout. O Zonos Checkout retransmite automaticamente os eventos de análise do iframe para a página principal, utilizando o mesmo script de retransmissão leve usado para o Google Analytics 4, pelo que os eventos aparecem no seu Meta Events Manager como se tivessem origem no seu próprio site.

Para cada etapa do funil, são emitidos dois eventos:

  • Um evento personalizado com o nome zonos-checkout-... (através de fbq('trackCustom', ...)) para públicos personalizados de funil completo.
  • O evento padrão correspondente do Meta (através de fbq('track', ...)) para a otimização integrada, por exemplo, InitiateCheckout, AddPaymentInfo e Purchase.

As integrações nativas não precisam deste guia. Se o <zonos-checkout> for apresentado diretamente no seu site (sem iframe), a Zonos chama o window.fbq da sua página no próprio local — basta ativar o Facebook Pixel no Dashboard da Zonos em Definições do Checkout → Rastreio e garantir que o código base habitual do Meta Pixel está carregado na página. A configuração de retransmissão abaixo só é necessária quando o Checkout está alojado num iframe de uma origem diferente.

Como funciona 

Como o Zonos Checkout é executado dentro de um iframe numa origem diferente, não consegue aceder diretamente à função fbq da sua página. O sistema de retransmissão resolve isto com um handshake em dois passos (passos 1-2), seguido do reencaminhamento de eventos (passo 3):

  1. O Checkout envia um ping à página principal -- Quando o checkout é carregado dentro do iframe, envia uma mensagem à janela principal a indicar que está pronto para retransmitir eventos, incluindo o Pixel ID.
  2. A página principal confirma -- O script de retransmissão na sua página recebe o ping, deteta (ou injeta) o código base do seu Meta Pixel e sinaliza de volta que está pronto para receber eventos.
  3. Os eventos são reencaminhados -- À medida que os compradores avançam no checkout, cada evento de análise é enviado através de postMessage para a sua página, onde o script de retransmissão o reencaminha para o fbq com o modo track / trackCustom adequado.

Todas as mensagens são validadas em relação às origens fidedignas da Zonos (zonos.com e iglobalstores.com), exclusivamente através de HTTPS.

Pré-requisitos 

  • Um Meta Pixel com um Pixel ID (uma cadeia numérica, normalmente com 15-16 dígitos). Pode criar um no Meta Events Manager.
  • Uma integração do Checkout legado que carregue o Zonos Checkout num iframe na sua página.
  • O Facebook Pixel ativado nas definições do seu Zonos Checkout (no Dashboard da Zonos, em Definições do Checkout -> Rastreio).

Configuração 

Passo 1: adicione o código base do Meta Pixel à sua página

Se ainda não tem o Meta Pixel instalado no seu site, adicione o código base padrão do Pixel ao <head> da página que aloja o iframe do Checkout. Substitua YOUR_PIXEL_ID pelo seu próprio Pixel ID numérico.

1<!-- Meta Pixel Code -->
2 
3<script>
4 !(function (f, b, e, v, n, t, s) {
5 if (f.fbq) return;
6 n = f.fbq = function () {
7 n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments);
8 };
9 if (!f._fbq) f._fbq = n;
10 n.push = n;
11 n.loaded = !0;
12 n.version = '2.0';
13 n.queue = [];
14 t = b.createElement(e);
15 t.async = !0;
16 t.src = v;
17 s = b.getElementsByTagName(e)[0];
18 s.parentNode.insertBefore(t, s);
19 })(
20 window,
21 document,
22 'script',
23 'https://connect.facebook.net/en_US/fbevents.js',
24 );
25 fbq('init', 'YOUR_PIXEL_ID');
26 fbq('track', 'PageView');
27</script>

Nota: Se o seu site já tem o Meta Pixel instalado (por exemplo, através do Google Tag Manager, da integração nativa do Shopify ou de um snippet direto), pode saltar este passo. O script de retransmissão utilizará a sua função fbq existente.

Pode encontrar este snippet no seu Meta Events Manager, em Definições do seu Pixel -> Continuar a configuração do Pixel -> Instalar o código manualmente.

Passo 2: transmita o seu Pixel ID ao Zonos Checkout

Indique ao Zonos Checkout qual o Pixel ID a utilizar, definindo window.Zonos.facebookPixelId no customHTML do seu Checkout. O Dashboard da Zonos disponibiliza um editor de customHTML nas definições do Checkout -- adicione uma tag <script> como esta:

1<script>
2 window.Zonos.facebookPixelId = 'YOUR_PIXEL_ID';
3</script>

Este valor é enviado à página principal durante o handshake de retransmissão. Se a sua página principal ainda não tiver o fbq carregado, o script de retransmissão injetará o código base do Meta Pixel por si, utilizando este ID.

Passo 3: adicione o script de retransmissão de análise da Zonos

Adicione a seguinte tag de script à mesma página que carrega o iframe do Checkout, a seguir ao código base do Meta Pixel. Este é o mesmo script utilizado para o Google Analytics 4 -- uma única retransmissão trata dos dois fornecedores, por isso, se já o adicionou para o GA4, salte este passo.

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

Exemplo completo

Eis o aspeto da configuração completa no <head> da sua página:

1<head>
2 <!-- ... your existing head tags ... -->
3 
4 <!-- Meta Pixel Code -->
5 
6 <script>
7 !(function (f, b, e, v, n, t, s) {
8 if (f.fbq) return;
9 n = f.fbq = function () {
10 n.callMethod
11 ? n.callMethod.apply(n, arguments)
12 : n.queue.push(arguments);
13 };
14 if (!f._fbq) f._fbq = n;
15 n.push = n;
16 n.loaded = !0;
17 n.version = '2.0';
18 n.queue = [];
19 t = b.createElement(e);
20 t.async = !0;
21 t.src = v;
22 s = b.getElementsByTagName(e)[0];
23 s.parentNode.insertBefore(t, s);
24 })(
25 window,
26 document,
27 'script',
28 'https://connect.facebook.net/en_US/fbevents.js',
29 );
30 fbq('init', 'YOUR_PIXEL_ID');
31 fbq('track', 'PageView');
32 </script>
33 
34 <!-- Zonos analytics relay for iframe checkout -->
35 
36 <script
37 async
38 src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"
39 ></script>
40</head>

E pronto. Assim que ambos os scripts estiverem na sua página, o Facebook Pixel estiver ativado no Dashboard da Zonos e o customHTML definir o Pixel ID, a retransmissão reencaminha automaticamente todos os eventos do funil de checkout para o Meta.

Referência de eventos do Meta Pixel 

Em cada etapa do funil, o Zonos Checkout dispara tanto um evento personalizado (para que possa criar públicos precisos) como o evento padrão correspondente do Meta (para que apareça nos relatórios de otimização e de conversões do Meta). Todos os eventos incluem um indicador isTestMode e o checkoutSessionId.

Acionador↕Evento personalizado (fbq('trackCustom', ...))↕Evento padrão (fbq('track', ...))↕Metadados adicionais↕
O checkout é abertozonos-checkout-startInitiateCheckout--
O comprador introduz os dados do clientezonos-checkout-customer-infonenhum--
O comprador seleciona um método de enviozonos-checkout-shipping-infonenhumserviceLevelId
O comprador introduz os dados de pagamentozonos-checkout-payment-infoAddPaymentInfopaymentMethod
A tentativa de pagamento falhazonos-checkout-payment-failnenhum--
A encomenda é concluída com sucessozonos-checkout-successnenhumorder_id, currency, value, contents, content_ids
A encomenda é concluída (evento de e-commerce)purchasePurchaseorder_id, currency, value, contents, content_ids
O comprador fecha o checkoutzonos-checkout-closenenhum--

As etapas sem um evento padrão equivalente do Meta (por exemplo, dados do cliente, dados de envio) disparam apenas o evento personalizado zonos-checkout-.... Pode segmentá-las no Meta Ads Manager através de públicos personalizados, utilizando "Event = zonos-checkout-customer-info", etc.

Metadados do evento Purchase

O evento padrão Purchase segue o esquema do evento Purchase do Meta Pixel. Os artigos do carrinho são mapeados a partir do array items ao estilo do GA para o array contents do Meta:

Campo↕Descrição↕
valueValor total da encomenda
currencyCódigo de moeda de três letras (por exemplo, USD)
order_idID da encomenda Zonos ou ID da sessão de checkout
contentsArray de artigos do carrinho, cada um com id, quantity e item_price
content_idsArray de IDs dos artigos (o SKU, o ID do produto ou, em alternativa, o nome do produto)
content_typeSempre "product"
num_itemsQuantidade total de todos os artigos

Depuração 

Para ativar o registo de depuração do script de retransmissão, adicione o parâmetro de consulta zonosDebug=1 ao URL da sua página:

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

Abra a consola de programador do seu navegador para ver registos detalhados do handshake de retransmissão e dos eventos reencaminhados. Isto é útil para verificar que:

  • O script de retransmissão recebe o ping do iframe do checkout.
  • O Meta Pixel está configurado com o Pixel ID correto.
  • Os eventos estão a ser reencaminhados para o fbq com o modo track / trackCustom esperado.

A extensão do Chrome Meta Pixel Helper também é útil para inspecionar as chamadas do Pixel em tempo real.

Perguntas frequentes 

Porque são disparados dois eventos para a mesma etapa (por exemplo, zonos-checkout-start e InitiateCheckout)?

Os eventos padrão do Meta alimentam, de origem, a otimização de conversões, os relatórios de anúncios e os públicos semelhantes. Os eventos personalizados zonos-checkout-... permitem criar públicos personalizados mais granulares na etapa exata do funil, mesmo quando não existe um equivalente padrão do Meta (por exemplo, dados do cliente, dados de envio). Disparar ambos oferece o melhor dos dois mundos, sem perder qualquer sinal.

E se estiver a utilizar o Google Analytics e o Facebook Pixel em simultâneo?

Não precisa de dois scripts de retransmissão -- o mesmo analyticsRelayOnInit.js trata dos dois fornecedores num único handshake. Adicione a tag base do GA4 e o código base do Meta Pixel ao seu <head>, defina window.Zonos.googleAnalyticId e window.Zonos.facebookPixelId no customHTML e ative ambos os fornecedores no Dashboard da Zonos. Cada evento é distribuído pelos fornecedores que estiverem ativados.

E se a minha página principal não tiver o Meta Pixel instalado?

Se o seu customHTML definir window.Zonos.facebookPixelId e o script de retransmissão não detetar nenhum fbq na página, injetará o código base do Meta Pixel por si durante o handshake, utilizando o Pixel ID que forneceu. Também pode pré-instalar o código base do Meta Pixel por conta própria, caso pretenda disparar PageView e outros eventos fora do funil de checkout.

As encomendas de teste são rastreadas?

Todos os eventos incluem um campo isTestMode. Quando o Checkout está em modo de teste, os eventos continuam a ser retransmitidos para o Meta, mas são assinalados com isTestMode: true. Pode filtrá-los no Meta Ads Manager ou excluí-los com regras de conversão personalizadas.

A Conversions API (CAPI) substitui isto?

Não -- esta é uma integração do Pixel do lado do navegador, que é executada nos navegadores dos seus compradores. A Meta Conversions API é um canal separado, de servidor para servidor, que alguns comerciantes utilizam em conjunto com o Pixel para redundância. Os dois são complementares e a retransmissão da Zonos trata apenas do Pixel do lado do navegador.

Esta página foi útil?

Obter apoio·Documentos legais·© 2026 Zonos
Nesta página:
  • Facebook Pixel para o Checkout em iframe
  • Como funciona
  • Pré-requisitos
  • Configuração
  • Referência de eventos do Meta Pixel
  • Depuração
  • Perguntas frequentes