Tracking de Single Page Applications (SPA): Rastreamento em React e Vue

1. O Desafio Arquitetural das SPAs no Rastreamento Digital

O desenvolvimento de aplicações web modernas migrou massivamente para arquiteturas baseadas em Single Page Applications (SPAs) utilizando ecossistemas como React, Next.js, Vue.js, Nuxt e Angular. A principal vantagem dessa abordagem é a velocidade de resposta: após o carregamento inicial do shell HTML/JavaScript, todas as transições de tela ocorrem de forma assíncrona via chamadas de API (AJAX/Fetch) e manipulação dinâmica do Virtual DOM, sem que o navegador execute uma recarga tradicional de página (Full Page Reload).

Para os mecanismos analíticos convencionais, essa eficiência é catastrófica. O Google Tag Manager e o Google Analytics foram historicamente projetados para reagir aos eventos de carregamento do navegador (window.onload ou gtm.js). Em uma SPA, o visitante pode navegar por dez produtos, alterar o carrinho e preencher três etapas do checkout sem que um único recarregamento físico ocorra, fazendo com que o GA4 registre apenas a página inicial e considere a visita inteira como uma sessão estática e monótona.

2. History Change Nativo vs Evento Personalizado no dataLayer

Para contornar a ausência de recargas físicas, existem duas abordagens no mercado:

Abordagem Frágil: Acionador "Alteração do Histórico" (History Change): O analista configura o GTM para ouvir as APIs nativas pushState e replaceState do navegador. O problema crônico é o descasamento temporal (race conditions): o roteador da aplicação altera a URL antes que os componentes visuais tenham terminado de renderizar. O resultado são pageviews registradas com o título antigo da página anterior ou parâmetros vazios.

Abordagem de Elite: Emissão Controlada de Virtual Pageviews: O time de desenvolvimento integra a emissão de eventos ao ciclo de vida do roteador da aplicação (ex.: useEffect em React ou hook afterEach no Vue Router), disparando um evento explícito no dataLayer assim que o DOM da nova rota está totalmente montado e garantido.

3. O Efeito Memória e a Poluição do dataLayer

Outra armadilha clássica em SPAs é a persistência indesejada do estado do dataLayer. Em sites convencionais, a troca de página limpa a memória RAM do navegador e recria o window.dataLayer do zero.

Em uma SPA, uma variável enviada na página de produto (por exemplo, ecommerce.items[0].price = 499) permanece gravada na memória do GTM indefinidamente. Se a próxima tela for um artigo institucional do blog que não declare um objeto de e-commerce, qualquer tag subsequente pode acidentalmente herdar os dados do produto anterior, poluindo as métricas.

A solução técnica mandatória é executar o reset explícito do nó de e-commerce antes de qualquer novo push:

// Reset obrigatório de estado em SPAs
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({ 'ecommerce': null });

4. Infográfico Vetorial: Ciclo de Navegação e Emissão de Eventos

5. Implementação de Código em React / Next.js

Em aplicações React utilizando Next.js (App Router ou Pages Router), crie um componente dedicado de monitoramento de rota:

// Exemplo de Hook de Rota em Next.js (App Router)
'use client';
import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';

export function AnalyticsListener() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    const url = `${pathname}${searchParams ? `?${searchParams.toString()}` : ''}`;
    
    // 1. Limpeza preventiva de estado
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({ ecommerce: null });

    // 2. Disparo do Virtual Pageview
    window.dataLayer.push({
      event: 'virtual_page_view',
      page_location: window.location.origin + url,
      page_path: pathname,
      page_title: document.title
    });
  }, [pathname, searchParams]);

  return null;
}

6. Implementação de Código em Vue / Nuxt.js

No Vue.js com Vue Router, adicione o disparador dentro do gancho de ciclo global afterEach:

// Implementação no Vue Router
router.afterEach((to, from) => {
  Vue.nextTick(() => {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({ ecommerce: null });
    window.dataLayer.push({
      event: 'virtual_page_view',
      page_location: window.location.origin + to.fullPath,
      page_path: to.path,
      page_title: document.title
    });
  });
});

7. Configuração Avançada no Google Tag Manager

No painel do GTM:

1. Crie um Acionador do tipo Evento Personalizado com o nome do evento virtual_page_view.
2. Crie Variáveis de Camada de Dados para page_location, page_path e page_title.
3. Configure a Tag do GA4 de Evento com o nome page_view, mapeando os parâmetros de evento para as variáveis criadas.
4. Nas configurações do fluxo web do GA4, desative a captura de histórico do navegador na Medição Aprimorada para eliminar pageviews duplicadas.

8. Checklist de QA para Single Page Applications

Perguntas Frequentes sobre tracking spa single page application gtm

Por que o acionador nativo 'Alteração do Histórico' (History Change) do GTM às vezes falha em SPAs?

O History Change dispara no evento window.onpopstate ou pushState do navegador. No entanto, em muitos frameworks React/Vue, o evento do histórico é disparado antes que o novo título da página (document.title) ou os dados da nova rota tenham sido renderizados no DOM, gerando pageviews com títulos e metadados da página anterior.

Como resetar o objeto ecommerce no dataLayer em uma SPA?

Antes de empurrar os dados do novo produto ou carrinho, deve-se disparar: 'dataLayer.push({ ecommerce: null });'. Isso apaga os nós herdados da rota anterior, impedindo que dados residuais contaminem o evento da nova tela.

O GA4 possui medição otimizada automática para SPAs?

Sim, a Medição Aprimorada (Enhanced Measurement) do GA4 possui a opção 'Alterações de página com base em eventos de histórico do navegador'. Porém, em aplicações corporativas complexas, ela costuma gerar pageviews duplicadas ou com parâmetros ausentes. O padrão ouro é desativar a opção automática e disparar virtual pageviews explicitamente via código.

Como medir o tempo gasto em cada tela de uma SPA?

O GA4 calcula o tempo de engajamento automaticamente através do parâmetro '_et' nos pings periódicos. Contudo, ao usar virtual pageviews controlados, é recomendável enviar o evento explícito 'page_view' a cada troca de rota para que o GA4 encerre a contagem da tela anterior e inicie a próxima.