Integrar o Google Analytics com a VTEX parece simples — instala o Pixel App do GA4 e está pronto. Na prática, a maioria das implementações que encontro em projetos tem eventos faltando, parâmetros incorretos ou dados de receita que não batem com o painel da VTEX.
A diferença entre um GA4 instalado e um GA4 configurado corretamente é a diferença entre ter sessões e ter um funil de compra completo, com dados acionáveis para CRO e decisões de mídia.
Trabalho com Google Analytics e VTEX há 10 anos. Este guia documenta o que funciona, o que não funciona e o que é frequentemente ignorado.
Como o Google Analytics se integra com VTEX IO?
Existem três formas de integrar o GA4 com VTEX IO, com trade-offs diferentes:
Opção 1: Pixel App oficial do GA4
A VTEX oferece um Pixel App nativo para o GA4 (vtex.google-tag-manager). É a forma mais rápida de instalar, mas tem limitações:
- Envia os eventos básicos de e-commerce, mas raramente com todos os parâmetros corretos
- A configuração de parâmetros customizados requer conhecimento de como o dataLayer do VTEX funciona
- Updates da VTEX podem mudar o comportamento dos eventos sem aviso
Quando usar: projetos simples onde a prioridade é velocidade de implementação e os relatórios básicos são suficientes.
Opção 2: Google Tag Manager + dataLayer customizado
A abordagem mais robusta para a maioria dos projetos sérios:
- Instalar o Pixel App do GTM (
vtex.google-tag-manager) - Configurar o GA4 via tag de configuração no GTM (Measurement ID)
- Escutar os eventos nativos da VTEX ou disparar eventos customizados via scripts no Store Theme
- Configurar os triggers e tags de cada evento de e-commerce no GTM
Vantagens: controle total sobre quais dados são enviados, flexibilidade para adicionar parâmetros customizados, sem dependência de updates da VTEX.
Opção 3: Implementação via Custom App
Para lojas com requisitos avançados: desenvolver uma Custom App VTEX IO que escuta os eventos da plataforma (add_to_cart, purchase, etc.) e injeta os dados corretos no dataLayer com todos os parâmetros necessários.
Quando usar: lojas enterprise onde a precisão dos dados é crítica e o dataLayer padrão do VTEX não é suficiente.
Quais eventos de e-commerce são obrigatórios no GA4 para VTEX?
Para ter um funil de compra completo no GA4, esses eventos precisam ser rastreados:
| Evento GA4 | Quando dispara na VTEX | Parâmetro crítico |
|---|---|---|
| view_item_list | Listagem de produtos / prateleiras | item_list_name, index |
| view_item | Página de produto (PDP) | price, item_id |
| add_to_cart | Clique em "Comprar" ou "Adicionar" | value (preço × quantidade) |
| view_cart | Visualização do carrinho | value total do carrinho |
| begin_checkout | Início do checkout VTEX | value, currency |
| add_payment_info | Seleção da forma de pagamento | payment_type |
| purchase | Confirmação de pedido | transaction_id, value, tax, shipping |
O erro mais crítico: disparar o evento purchase duas vezes para o mesmo pedido. Isso acontece quando o evento é configurado no carregamento da página de agradecimento e a página é carregada mais de uma vez (refresh, ou redirect com abertura em nova aba). O resultado é receita inflada no GA4 que não bate com o painel da VTEX.
Solução: deduplicação via transaction_id e, preferencialmente, rastreamento do evento de purchase via server-side (VTEX Order Hook).
Os erros mais comuns na integração GA4 + VTEX
1. Receita no GA4 diverge da VTEX
Causas: evento purchase disparado com valor incorreto (preço sem descontos, frete somado duas vezes), pedidos cancelados não sendo excluídos, ou disparos duplos do evento.
Verificação: compare o número de transações e a receita total no GA4 vs no painel VTEX para o mesmo período. Uma diferença acima de 5% indica problema de implementação.
2. Parâmetros de item incompletos
Enviar view_item apenas com item_id e item_name sem price, item_category e quantity resulta em relatórios de produto sem análise de receita potencial e sem segmentação por categoria.
3. Eventos de funil faltando
Muitas implementações capturam view_item e purchase mas perdem add_to_cart e begin_checkout. Sem esses dois, o relatório de Jornada de Compra no GA4 fica incompleto e você não sabe onde o abandono acontece.
4. Ad blockers bloqueando eventos
Rastreamento client-side (via JavaScript no navegador) pode ser bloqueado por ad blockers e iOS ITP. Estudos indicam 20–40% de perda de eventos dependendo do perfil do público. Para o evento purchase, a solução é rastreamento server-side via VTEX Order Hook.
Como usar o VTEX Order Hook para rastreamento server-side
O VTEX Order Hook é um webhook nativo da VTEX que dispara uma notificação toda vez que um pedido muda de status. Usando esse hook:
- Configuro um endpoint (Lambda, Vercel Function ou servidor próprio) que recebe o webhook
- O endpoint consulta a API de Pedidos da VTEX para obter os detalhes completos do pedido
- Os dados são enviados ao GA4 via Measurement Protocol (API server-side do GA4)
O resultado é 100% de captura dos eventos de purchase, independente de ad blocker, iOS ITP ou qualquer bloqueio client-side. Os dados de receita no GA4 passam a bater exatamente com o painel VTEX.
Como validar a implementação
- GA4 DebugView — ative o modo debug e navegue pela loja. Cada evento deve aparecer em tempo real com todos os parâmetros corretos.
- GTM Preview — se usando GTM, use o Preview Mode para ver quais tags disparam em cada página.
- Comparação de transações — após 7 dias, compare o número de pedidos e receita total no GA4 vs na VTEX. A diferença deve ser menor que 5%.
- Relatório de Jornada de Compra — verifique se todas as etapas aparecem com dados coerentes (nenhuma etapa com mais usuários que a etapa anterior).
Trabalho com Google Analytics e VTEX há anos, incluindo configurações avançadas com server-side tracking. Se quiser uma auditoria da implementação atual da sua loja, conheça o serviço de especialista em GA4 ou entre em contato.