Como configuro o Google Analytics 4 com o iframe Checkout legado da Zonos?

Adicione o snippet gtag.js padrão do GA4 à página que hospeda o iframe Checkout e, em seguida, adicione o script analyticsRelayOnInit.js da Zonos. O script de retransmissão lida automaticamente com a comunicação entre iframes e encaminha eventos de checkout para sua propriedade GA4.

Quais eventos GA4 o Zonos Checkout rastreia?

Zonos Checkout rastreia todo o funil de checkout, incluindo zonos-checkout-start, zonos-checkout-customer-info, zonos-checkout-shipping-info, zonos-checkout-payment-info, zonos-checkout-payment-fail, zonos-checkout-success, zonos-checkout-close e o evento de compra GA4 padrão com detalhes da transação.

Como depuro eventos GA4 de Zonos Checkout?

Adicione o parâmetro de consulta zonosDebug=true ao URL da sua página e abra o console do desenvolvedor do seu navegador para visualizar logs detalhados do handshake de retransmissão e eventos encaminhados. Você também pode usar o GA4 DebugView no Google Analytics para verificar eventos em tempo real.

Checkout•

InícioReferência da API Checkout REST API Google Analytics 4

Google Analytics 4 para iframe Checkout

Q: Preciso modificar minha chamada de API createTempCart para rastreamento GA4?

Não. O sistema de retransmissão funciona independentemente da API createTempCart. Você só precisa adicionar a tag GA4 e o script de retransmissão da Zonos à sua página.

Acompanhe todo o funil de checkout com o GA4 ao usar uma integração legada de Checkout baseada em iframe.

Os comerciantes que usam a integração legada do Checkout (iframe hospedado em iglobalstores.com) agora podem rastrear eventos de análise do GA4 em todo o funil de checkout. O Zonos Checkout retransmite automaticamente eventos de análise do iframe para a página principal usando um script de retransmissão leve, para que os eventos apareçam em sua propriedade GA4 como se tivessem se originado do seu próprio site.

Integrações nativas não precisam deste guia. Se <zonos-checkout> for renderizado diretamente em seu site (sem iframe), o Zonos chama o window.gtag da sua página no local -- basta ativar o Google Analytics no dashboard da Zonos em Configurações do Checkout → Rastreamento e garantir que a tag base GA4 padrão esteja carregada na página. A configuração de retransmissão abaixo só é necessária quando o Checkout está hospedado em um iframe em uma origem diferente.

Deseja rastrear conversões do Meta Ads em vez disso? Consulte o guia do Facebook Pixel -- ele usa o mesmo script de retransmissão e pode ser executado junto com o GA4.

Como funciona

Como o Zonos Checkout é executado dentro de um iframe em uma origem diferente, ele não pode acessar diretamente a função gtag da sua página. O sistema de retransmissão resolve isso com um handshake de duas etapas (etapas 1-2) seguido pelo encaminhamento de eventos (etapa 3):

O Checkout envia um ping para a página principal -- Quando o checkout carrega dentro do iframe, ele envia uma mensagem para a janela principal indicando que está pronto para retransmitir eventos.
A página principal confirma -- O script de retransmissão em sua página recebe o ping, detecta sua configuração GA4 existente e sinaliza de volta que está pronto para receber eventos.
Os eventos são encaminhados -- À medida que os compradores avançam pelo checkout, cada evento de análise é enviado via postMessage para sua página, onde o script de retransmissão o encaminha para o gtag.

Todas as mensagens são validadas em relação a origens confiáveis da Zonos (zonos.com e iglobalstores.com) somente via HTTPS.

Pré-requisitos

Uma propriedade GA4 com um ID de medição (formato: G-XXXXXXXXXX). Você pode criar uma em Google Analytics.
Uma integração legada de Checkout que carrega o Zonos Checkout em um iframe na sua página.

Configuração

Etapa 1: adicione a tag GA4 à sua página

Se você ainda não tem o GA4 instalado em seu site, adicione a tag padrão do Google Analytics 4 ao <head> da página que hospeda o iframe do Checkout. Substitua G-XXXXXXXXXX pelo seu próprio ID de medição.

1

3<script

4 async

5 src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"

6></script>

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>

Observação: Se o seu site já tiver a tag GA4 instalada (por exemplo, por meio do Google Tag Manager ou de um snippet direto), você pode pular esta etapa. O script de retransmissão usará sua função gtag existente.

Você pode encontrar esse snippet em sua propriedade GA4 em Administrador -> Fluxos de dados -> selecione seu fluxo -> Ver instruções da tag -> Instalar manualmente.

Etapa 2: passe seu ID de medição para o Zonos Checkout

Informe ao Zonos Checkout qual ID de medição do GA4 usar definindo window.Zonos.googleAnalyticId dentro do customHTML do seu Checkout. O dashboard da Zonos disponibiliza um editor de customHTML nas configurações do Checkout -- adicione uma tag <script> como esta:

1<script>

2 window.Zonos.googleAnalyticId = 'G-XXXXXXXXXX';

3</script>

Esse valor é enviado para a página principal durante o handshake de retransmissão. Se sua página principal ainda não tiver o gtag carregado, o script de retransmissão injetará a tag base do GA4 para você usando esse ID.

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

Adicione a seguinte tag de script à mesma página, após a tag GA4. Esse script escuta os eventos de análise do iframe do Zonos Checkout e os encaminha para o seu gtag.

1<script

2 async

3 src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"

4></script>

Exemplo completo

Veja como fica a configuração completa no <head> da sua página:

1<head>

2 

4 

6 <script

7 async

8 src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"

9 ></script>

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>

20 

22 <script

23 async

24 src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"

25 ></script>

26</head>

É isso. Assim que os dois scripts estiverem na sua página, o script de retransmissão conclui automaticamente o handshake com o iframe de checkout e encaminha todos os eventos do funil de checkout para sua propriedade GA4.

Referência de eventos do GA4

O Zonos Checkout emite os seguintes eventos por meio da retransmissão. Todos os eventos incluem um sinalizador isTestMode e o checkoutSessionId.

Evento↕	Gatilho↕	Metadados adicionais↕
`zonos-checkout-start`	O checkout é aberto	--
`zonos-checkout-customer-info`	O comprador insere as informações do cliente	--
`zonos-checkout-shipping-info`	O comprador seleciona um método de envio	`serviceLevelId`
`zonos-checkout-payment-info`	O comprador insere os detalhes de pagamento	`paymentMethod`
`zonos-checkout-payment-fail`	A tentativa de pagamento falha	--
`zonos-checkout-success`	O pedido é concluído com sucesso	`transaction_id`, `currency`, `value`, `items`
`zonos-checkout-close`	O comprador fecha o checkout	--
`purchase`	O pedido é concluído (evento padrão de e-commerce do GA4)	`transaction_id`, `currency`, `value`, `items`

Metadados do evento de compra

O evento purchase segue o esquema do evento de e-commerce purchase do GA4:

Campo↕	Descrição↕
`transaction_id`	ID do pedido Zonos ou ID da sessão de checkout
`currency`	Código de moeda de três letras (por exemplo, `USD`)
`value`	Valor total do pedido
`items`	Array de itens do carrinho, cada um com `item_id`, `item_name`, `price` e `quantity`

Depuração

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

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

Abra o console do desenvolvedor do seu navegador para ver os registros detalhados do handshake de retransmissão e dos eventos encaminhados. Isso é útil para verificar que:

O script de retransmissão recebe o ping do iframe de checkout.
O GA4 está configurado com o ID de medição correto.
Os eventos estão sendo encaminhados para o gtag.

Perguntas frequentes

Preciso modificar minha chamada de API `createTempCart`?

Não. O sistema de retransmissão funciona de forma independente da API createTempCart. Você só precisa adicionar a tag GA4 e o script de retransmissão à sua página.

E se eu já usar o `footerHTML` para o Google Analytics?

O parâmetro footerHTML na API createTempCart injeta scripts dentro do iframe de checkout, o que é limitado ao rastreamento de eventos no nível da página dentro da origem do iframe. A abordagem de retransmissão é recomendada porque envia eventos para sua própria propriedade GA4 em seu domínio, proporcionando visibilidade total do funil em uma única propriedade.

Você pode remover com segurança quaisquer scripts GA4 do footerHTML depois de configurar a retransmissão.

Isso funciona com o modo de depuração do GA4 no Google Analytics?

Sim. Você pode usar zonosDebug=1 para ativar os registros do script de retransmissão no console do desenvolvedor do seu navegador e usar o GA4 DebugView no Google Analytics para verificar os eventos em tempo real.

Os pedidos de teste são rastreados?

Todos os eventos incluem um campo isTestMode. Quando o Checkout está no modo de teste, os eventos ainda são enviados ao GA4, mas são sinalizados com isTestMode: true. Você pode filtrar esses eventos no GA4 usando dimensões personalizadas, se necessário.

Agendar uma demonstração