Google Tag Manager e VTEX: Como Configurar GTM em Lojas VTEX IO

O Google Tag Manager na VTEX é a camada que conecta a loja aos sistemas de analytics, rastreamento de conversão e pixels de mídia — sem precisar alterar código diretamente para cada novo requisito. Quando bem configurado, o GTM é a espinha dorsal de todo o rastreamento de marketing da loja.

Quando mal configurado, é a fonte dos problemas mais frustrantes de analytics: eventos duplicados, dados de conversão incorretos no GA4, campanhas de mídia otimizando para o pixel errado e relatórios de funil incompletos.

Trabalho com Google Tag Manager e VTEX há 10 anos. Este guia documenta o que funciona na prática.

Como o GTM se instala no VTEX IO?

A VTEX disponibiliza o Pixel App oficial do GTM: vtex.google-tag-manager. A instalação é feita pelo VTEX Admin:

Acesse o VTEX Admin → Apps → App Store
Instale o app vtex.google-tag-manager
Configure o GTM Container ID (formato GTM-XXXXXXX) nas configurações do app

Isso injeta automaticamente o snippet do GTM nas páginas da loja, incluindo o <noscript> fallback.

Importante: diferente de sites genéricos, o VTEX IO usa Server-Side Rendering (SSR). Isso significa que cada navegação de página no VTEX IO é uma nova requisição ao servidor — não há necessidade de disparar o evento de pageview manualmente via GTM, pois o snippet é reinjetado a cada página.

O dataLayer da VTEX: o que é injetado automaticamente

O Pixel App do GTM da VTEX injeta um dataLayer com dados da sessão, produto e transação. Os dados disponíveis incluem:

Na página de produto (PDP):

dataLayer.push({
  event: 'productView',
  ecommerce: {
    detail: {
      products: [{
        id: 'SKU-001',
        name: 'Nome do Produto',
        price: '299.90',
        category: 'Categoria',
        brand: 'Marca'
      }]
    }
  }
})

No add_to_cart:

dataLayer.push({
  event: 'addToCart',
  ecommerce: {
    add: { products: [...] }
  }
})

Na confirmação de pedido:

dataLayer.push({
  event: 'orderPlaced',
  transactionId: 'ORDEM-123',
  transactionTotal: 599.80,
  transactionProducts: [...]
})

Atenção: esses são os eventos do formato Universal Analytics (UA), não do formato GA4. Para usar com o GA4, é necessário configurar tags no GTM que transformam esses eventos UA em eventos GA4 com a estrutura correta (add_to_cart, purchase, etc. com arrays items[]).

Configuração recomendada no GTM para VTEX IO

Passo 1: Tag de configuração GA4

Crie uma tag do tipo Google Analytics: configuração GA4 com o Measurement ID da propriedade. Configure o trigger como All Pages.

Passo 2: Variáveis de camada de dados

Crie variáveis DataLayer no GTM para capturar os dados injetados pelo VTEX:

dlv - ecommerce.add.products (para add_to_cart)
dlv - ecommerce.purchase.products (para purchase)
dlv - transactionId
dlv - transactionTotal

Passo 3: Tags de eventos GA4

Para cada evento de e-commerce, crie uma tag Google Analytics: evento GA4 com o nome do evento correto (add_to_cart, purchase, etc.) e configure os parâmetros mapeando as variáveis de dataLayer para a estrutura de items[] do GA4.

Passo 4: Triggers específicos

Configure os triggers baseados nos eventos do dataLayer da VTEX:

addToCart → dispara a tag ga4_add_to_cart
orderPlaced → dispara a tag ga4_purchase

Os 5 erros mais comuns no GTM com VTEX IO

1. Usar o formato UA em vez do formato GA4

O VTEX IO injeta eventos no formato Universal Analytics (addToCart, productView). Para o GA4, esses eventos precisam ser transformados no GTM para o formato correto (add_to_cart com items[]). Muitas implementações pulam essa conversão e os eventos chegam ao GA4 sem os parâmetros necessários.

2. Evento de purchase disparando duas vezes

A página de confirmação de pedido da VTEX pode carregar mais de uma vez (refresh, múltiplas abas). Se a tag de purchase for configurada para disparar em orderPlaced sem deduplicação, a receita é dobrada no GA4.

Solução: configure uma variável de First Party Cookie ou use o GTM Server-Side com lógica de deduplicação por transaction_id.

3. Sequência incorreta de tags

Algumas tags dependem de variáveis definidas por outras tags (ex: o Meta Pixel depende de dados do GA4 ou vice-versa). No GTM, a ordem de execução de tags do mesmo trigger não é garantida sem configuração explícita de sequência.

4. Tags disparando em ambiente de desenvolvimento (workspace VTEX)

Workspaces de desenvolvimento da VTEX têm URLs no formato workspace--storename.myvtex.com. Se as tags do GTM não tiverem uma condição de exclusão para esses domínios, os testes de desenvolvimento contaminam os dados de produção.

Solução: adicione uma exceção no trigger principal: Page Hostname does not contain myvtex.com.

5. Meta CAPI não configurado para eventos de purchase

O Meta Pixel via GTM captura eventos client-side, que são bloqueados por ad blockers e iOS ITP em 20–40% dos casos. Para otimização de campanhas de Facebook/Instagram, o Meta CAPI (Conversions API) deve ser configurado via server-side para complementar o pixel client-side — a estratégia de "web + CAPI" garante maior cobertura de eventos de conversão.

GTM Server-Side: quando vale a pena na VTEX?

O Google Tag Manager Server-Side adiciona uma camada intermediária entre o navegador e os destinos de analytics e mídia. Os benefícios para lojas VTEX:

Cookies first-party com maior vida útil (contorna o bloqueio do iOS ITP)
Dados de purchase mais confiáveis — eventos processados no servidor não são bloqueados por ad blockers
Consolidação de tags — um único hit do navegador alimenta GA4, Meta CAPI, Criteo, Bing e outros destinos

O custo é o provisionamento de um servidor (App Engine, Cloud Run ou instância EC2). Para lojas com investimento significativo em mídia, o ROI é alto — melhor precisão de dados resulta em melhor otimização de campanhas.

Trabalho com GTM e VTEX em implementações de todos os níveis de complexidade, incluindo GTM Server-Side. Conheça o serviço de especialista em GTM ou entre em contato.

Google Tag Manager e VTEX: Como Configurar GTM em Lojas VTEX IO do Jeito Certo