logo hsb.horse

Registro de Decisão de Arquitetura

Política de integração Partytown + Google Analytics (GA4)

Introduzir GA4 (G-WZ3RT34EZZ) via Partytown para iniciar medição de pageviews minimizando impacto na main thread.

Aceito #analytics #ga4 #partytown #performance #privacy

Política de integração Partytown + Google Analytics (GA4)

Decisão

  • Adotar Google Analytics 4 (GA4) para análise de tráfego, usando measurement ID G-WZ3RT34EZZ.
  • Introduzir @astrojs/partytown e mover a execução do script GA para web worker via type="text/partytown".
  • Centralizar saída de tags de analytics em camada compartilhada (componente dedicado no Layout) em vez de embed por página.
  • Habilitar tracking apenas em URLs de produção; desabilitar em desenvolvimento local e preview.
  • Manter escopo inicial apenas em medição de pageview; definir taxonomia de eventos customizados em ADR separado.
  • No rollout inicial, não sobrescrever parâmetros de privacidade de gtag('config', ...) e operar produção com configurações padrão do GA4.

Convenções de implementação

ItemRegra
Execução de scriptCarregar gtag.js com type="text/partytown".
Gestão do Measurement IDNão hardcode em arquivos de página; injetar via PUBLIC_GA_MEASUREMENT_ID (valor inicial G-WZ3RT34EZZ).
Condição de saídaEmitir tags apenas quando PROD for true e o measurement ID estiver presente.
PosicionamentoCentralizado em Layout compartilhado, não por página.
Escopo de eventoEscopo inicial é apenas page_view. Sem eventos customizados arbitrários nesta fase.

Contexto

Analytics ainda não está implementado, então não conseguimos observar aquisição, popularidade de páginas nem alcance de conteúdo. Ao mesmo tempo, scripts de terceiros na main thread podem impactar negativamente TTI/FID/INP.

Este projeto já usa Layout compartilhado do Astro para responsabilidades de head, então analytics deve seguir o mesmo padrão. Como o site é multilíngue, implementação por página aumenta risco de inconsistência e deve ser evitada.

Opções

  • Opção A: carregar gtag.js padrão diretamente na main thread
  • Opção B: executar gtag.js via worker com @astrojs/partytown (escolhida)
  • Opção C: não adotar GA4 e trocar para outra ferramenta de analytics mais leve

Justificativa

  • Desempenho: Partytown move trabalho de scripts de terceiros para fora da main thread.
  • Segurança operacional: saída em camada compartilhada evita tags faltantes em páginas novas.
  • Rollout incremental: começar com pageviews e depois adicionar eventos com segurança em ADR futuro.
  • Auditabilidade: gate apenas para produção e premissa de “começar com defaults do GA” ficam explícitos e revisáveis.

Consequências

  • Adicionar dependência @astrojs/partytown e configurar integração em astro.config.mjs.
  • Adicionar componente compartilhado de analytics (ou responsabilidade equivalente) referenciado no Layout.
  • Definir e manter operação de variável de ambiente PUBLIC_GA_MEASUREMENT_ID.
  • Atualizar documentação de privacidade para informar uso do GA4 e finalidade de rastreamento.
  • Critérios de aceite:
    • Tags GA são emitidas apenas em produção
    • Pageviews são mensuráveis em todas as páginas públicas
    • Regressão de desempenho na main thread fica dentro de faixa aceitável no Lighthouse (ou equivalente)