A VTEX IO é a espinha dorsal de grande parte dos maiores e-commerces da América Latina. No entanto, sua arquitetura avançada de microsserviços impõe barreiras estritas de segurança que confundem engenheiros de dados acostumados a plataformas monolíticas clássicas.
1. A Dualidade Arquitetural da VTEX IO: Storefront vs Checkout
Para desenhar uma arquitetura de tracking server-side robusta na VTEX, é indispensável compreender a divisão fundamental de dois ambientes que não compartilham o mesmo ciclo de execução:
- O Storefront VTEX IO (Render Server): Todas as páginas de catálogo (Home, Navegação de Departamentos, PLPs e PDPs) rodam sobre o framework Store Framework em React. As transições de página ocorrem como uma Single Page Application (SPA), onde a URL muda sem recarregar o navegador.
- O Checkout Seguro (vtex-checkout): As etapas de carrinho, identificação, entrega e pagamento rodam em uma aplicação isolada, sob regras severas de compliance com as normas mundiais de segurança de pagamentos PCI-DSS Nível 1.
Essa separação impede que variáveis globais instanciadas na página de produto transitem livremente para o checkout, exigindo persistência de identificadores em cookies de primeiro domínio e parâmetros de sessão compartilhados.
2. Implementação no Storefront via VTEX Pixel App
A melhor prática recomendada pelo time de engenharia da VTEX para o Storefront IO é o desenvolvimento de uma Pixel App customizada ou a utilização do aplicativo oficial vtex.google-tag-manager:
- No manifesto (
manifest.json) da sua app de pixel, declare as dependências de escuta de eventos do Store Framework. - No arquivo
react/index.ts, crie os ouvintes de eventos para as mensagens padronizadas da VTEX:vtex:pageView: Despacha o evento de visualização de tela.vtex:productView: Captura os atributos de SKU, ID do produto e preço para montar oview_item.vtex:addToCart: Intercepta adições de itens na mini-sacola.
- Mapeie a URL do seu subdomínio de GTM Server-Side (ex:
sgtm.sualoja.com.br) dentro das configurações do aplicativo no admin da VTEX, garantindo que as requisições fluam para o servidor de nuvem próprio.
3. Captura do Evento OrderPlaced no Checkout e Confirmação de Pedido
No ambiente de checkout, a integração do GTM Web deve ser inserida através das configurações de Checkout no admin da VTEX (módulo Checkout > Configurações > Código JavaScript do Checkout ou via GTM nativo do Checkout).
Quando a compra é finalizada, a VTEX renderiza a página de confirmação disparando o evento orderPlaced no dataLayer. O script deve traduzir o payload da VTEX para o padrão canônico do GA4:
// Exemplo de normalização no checkout da VTEX
$(window).on('orderPlaced', function(e, order) {
window.dataLayer.push({
event: 'purchase',
ecommerce: {
transaction_id: order.orderGroup || order.orders[0].orderId,
value: order.orders.reduce(function(acc, o) { return acc + (o.value / 100); }, 0),
currency: 'BRL',
shipping: order.orders.reduce(function(acc, o) { return acc + (o.shippingData.logisticsInfo[0].price / 100); }, 0),
items: order.orders[0].items.map(function(item) {
return {
item_id: item.id,
item_name: item.name,
price: item.price / 100,
quantity: item.quantity
};
})
}
});
});Atenção Crítica: A VTEX armazena os valores monetários em centavos de real (ex: R$ 150,00 é representado como 15000). É mandatório dividir por 100 antes de enviar para o GA4 e plataformas de mídia para evitar inflação de 100x no faturamento.
4. A Solução Definitiva: VTEX Order Hook para Tracking Server-to-Server Puro
Mesmo com uma excelente implementação no frontend, cerca de 10% a 20% dos compradores fecham o navegador ou perdem a conexão no redirecionamento do gateway bancário. Para atingir 100% de reconciliação fiscal:
Configure um VTEX Order Hook (Feed v3) no backend. Sempre que o status de um pedido mudar para payment-approved (pagamento aprovado), o backend da VTEX dispara uma requisição POST diretamente para o seu contêiner do GTM Server-Side ou endpoint de middleware, contendo os dados fiscais e os parâmetros de clique (gclid, fbclid) armazenados no checkout.
5. Checklist de Segurança e Validação na VTEX
Antes de publicar em produção:
- Verifique se nenhum script injetado interfere no tempo de resposta do botão 'Finalizar Compra' (atrasos superiores a 200ms reduzem a conversão do checkout).
- Certifique-se de que os cookies de sessão e identificadores First-Party possuem o atributo
SameSite=Laxe são acessíveis tanto no domínio da loja quanto nas rotas de checkout seguras. - Realize compras de homologação com cartão de teste e Pix para validar se o
transaction_idé transmitido de forma unívoca para o Meta CAPI e Google Ads.
Matriz Comparativa de Decisão e Governança
Artigos Complementares deste Topic Cluster
Aprofunde seus conhecimentos sobre Tracking Server-Side, CAPI & Infraestrutura First-Party com os guias técnicos e estratégicos relacionados:
- Digital Analytics & Tracking VTEX Pixel App vs GTM Customizado: Qual Garante Mais Precisão? →
- Digital Analytics & Tracking Google Tag Manager Server-Side: Guia de Implementação via Cloud Run e Stape →
- Digital Analytics & Tracking Implementação de TikTok Events API e Pinterest API via GTM Server-Side →
Perguntas Frequentes sobre tracking server side para vtex io guia completo
O que é uma Pixel App na VTEX IO?
É um aplicativo modular desenvolvido no framework VTEX IO que injeta scripts analíticos e escuta eventos nativos do Store Framework de forma padronizada, garantindo que o código não seja removido durante atualizações do tema.
Como funciona o evento OrderPlaced na VTEX?
É o evento acionado no dataLayer da página de confirmação de pedido (orderPlaced), contendo o objeto de e-commerce completo com dados de entrega, itens, valores e o OrderGroup da VTEX.
Por que o checkout da VTEX é isolado do Storefront IO?
O checkout da VTEX opera em um ambiente altamente seguro e certificado pelo padrão internacional PCI-DSS Nível 1 para proteger dados de cartão de crédito dos consumidores contra vazamentos e scripts maliciosos de terceiros.
Como contornar a perda de compras por fechamento da OrderPlaced?
Através da configuração de um webhook no Feed de Pedidos da VTEX (Order Hook), disparando o evento de purchase diretamente do backend para o GTM Server-Side no momento em que o status do pedido muda para 'Pagamento Aprovado'.
