Server-side GTM para Single-Page Applications (SPAs)

O que é uma Single-Page Application (SPA)?

Uma Single-Page Application (SPA) é um tipo de aplicação web que carrega uma única página HTML e atualiza o conteúdo dinamicamente sem recarregar a página inteira. Isso resulta em uma experiência mais fluida, similar a um app nativo.

Exemplos populares: Gmail, Google Maps, Facebook, Trello, aplicações React/Vue/Angular. A vantagem de performance é significativa — mas cria desafios únicos para rastreamento.

Por que SPAs são difíceis de rastrear?

Em sites tradicionais, cada navegação para uma nova página dispara um novo pageview — o GTM naturalmente captura cada mudança. Em SPAs, isso não acontece: o URL pode mudar, mas a página não é recarregada.

• Triggers padrão de pageview não funcionam da mesma forma
• Eventos de clique e formulário podem não ser detectados por auto-listeners
• É necessário configurar rastreamento específico para capturar mudanças de 'página' virtual
• Risco de não capturar pageviews ou capturá-los em duplicata se mal configurado

Método 1: GA4 Enhanced Measurement

1. No GA4, acesse Admin > Data Streams e selecione o stream desejado
2. Clique no ícone de configurações em Enhanced Measurement
3. Clique em Show Advanced Settings
4. Ative 'Page changes based on browser history events'
5. Desative ou configure outros eventos de Enhanced Measurement via GTM para evitar duplicatas
6. Salve e entre no Preview Mode do GTM para verificar

Método 2: History Change trigger no GTM

1. No GTM, vá em Triggers > Nova > selecione 'History Change' como tipo
2. Configure para disparar em 'All History Changes'
3. Salve e crie uma tag GA4 para disparar com esse trigger
4. Monitore duplicatas no Preview Mode — algumas SPAs disparam múltiplos eventos de history por navegação

Método 3: Data Layer Push (método recomendado)

O método mais confiável para SPAs é ter o desenvolvedor empurrando eventos customizados ao dataLayer quando ocorre uma navegação virtual. Isso dá controle total sobre quando e quais dados são rastreados.

1. O desenvolvedor configura um push ao dataLayer em cada navegação: `dataLayer.push({event: 'virtualPageview', pageUrl: window.location.href, pageTitle: document.title})`
2. No GTM, crie duas variáveis Data Layer (para pageUrl e pageTitle)
3. Crie um trigger Custom Event com nome 'virtualPageview'
4. Crie uma tag GA4 Event com event_name: page_view, parâmetros page_location e page_title usando as variáveis
5. Importante: não adicione page_location e page_title à tag GA4 Configuration — use uma tag Event separada
6. Desative 'Send a page view event when this configuration loads' na tag GA4 Configuration para evitar duplicatas

Desafios comuns e como resolver

• JavaScript desabilitado: sem JS, nenhum método de rastreamento funciona em SPAs. Server-side GTM captura apenas o pageload inicial, não as navegações subsequentes.
• URL com parâmetros e fragmentos: use `window.location.href` (não `document.location`) para capturar a URL completa incluindo query strings e hashes.
• Múltiplos eventos de history: investigue quais eventos estão sendo disparados e adicione filtros ao trigger para eliminar duplicatas.
• Rogue referral (falso referrer): o GA4 pode registrar o próprio site como referenciador. Configure exclusões de referral no GA4 para o seu próprio domínio.

Perguntas frequentes