Analytics - Coleta Interna e GTM no Painel

Objetivo

Este guia explica como a camada de analytics foi encaixada no projeto com configuração administrativa em arquivo ou PostgreSQL e, agora, com eventos também podendo operar em files, hybrid ou database.

O foco foi:

• manter a coleta operacional dentro do próprio sistema;
• permitir leitura rápida no admin;
• preservar opção futura de migrar para banco e app mobile;
• habilitar GTM e GA4 por configuração do painel.

Blocos principais

Configuração

• src/features/analytics/server/configStore.ts
• src/data/ecommpanel/analytics/config.json
• src/data/site-runtime/analytics/config.published.json

Esse domínio controla:

• coleta interna ligada ou desligada;
• intervalo de heartbeat;
• janela de usuários ativos;
• retenção;
• tamanho do lote;
• ativação de GTM;
• ativação de GA4.

Persistência atual:

• a configuração administrativa pode operar em files, hybrid ou database via ECOM_PANEL_SETTINGS_PERSISTENCE_MODE;
• mesmo quando o admin usa banco, a loja continua lendo o snapshot publicado de analytics.

Coleta de eventos

• src/features/analytics/client/runtime.ts
• src/features/analytics/components/StorefrontAnalyticsClient.tsx
• src/app/api/analytics/collect/route.ts

Fluxo:

1. a loja inicializa a identidade de sessão e visitante no client;
2. cada troca de rota envia page_view;
3. um heartbeat periódico mantém a sessão viva;
4. cliques relevantes entram por delegação no documento;
5. o carrinho emite cart_update;
6. o checkout emite checkout_step;
7. o endpoint de compra grava purchase_complete.

Armazenamento

• src/features/analytics/server/eventStore.ts
• src/features/analytics/server/analyticsDatabaseStore.ts
• src/data/ecommpanel/analytics/events/YYYY-MM-DD.ndjson

Os modos atuais são:

• files: append por dia em ndjson;
• hybrid: PostgreSQL como leitura preferida + arquivos como espelho/fallback;
• database: PostgreSQL como leitura e escrita principal do domínio.

No modo hybrid, o runtime também consegue reimportar os arquivos recentes para o banco em segundo plano administrativo, o que reduz risco de defasagem após indisponibilidade temporária do banco.

Dashboard administrativo

• src/app/ecommpanel/admin/analytics/page.tsx
• src/features/ecommpanel/components/AnalyticsDashboardManager.tsx

Essa tela agrega:

• sessões ativas e totais;
• visitantes únicos;
• duração média por sessão;
• páginas vistas;
• buscas;
• cliques;
• mudanças no carrinho;
• sessões que chegaram ao checkout;
• compras;
• receita;
• ticket médio;
• abandono de carrinho;
• top páginas;
• top buscas;
• top cliques;
• top métodos de pagamento;
• top localizações;
• distribuição por dispositivo;
• eventos recentes.

Injeção de Google tags

Arquivo responsável:

• src/features/analytics/components/GoogleTagScripts.tsx

Integração com a loja:

• src/app/e-commerce/layout.tsx

Regras práticas:

• google.enabled = false impede qualquer script externo;
• google.gtmEnabled = true + gtmContainerId válido injeta o GTM;
• google.gaEnabled = true + gaMeasurementId válido injeta o gtag;
• a loja lê o snapshot publicado, então o admin continua sendo a fonte de verdade.

Checkout e dado comercial

Arquivo-chave:

• src/app/api/checkout/route.ts

Quando o pedido é criado, o backend registra:

• orderId
• valor total
• quantidade de itens
• método de pagamento
• frete
• desconto
• cidade / estado / país

Isso é importante porque receita e pagamento mais usado não dependem só do client.

Segurança e isolamento

Admin

Nova área protegida por permissão:

• analytics.read
• analytics.manage

Endpoint público de coleta

• aceita apenas eventos da própria origem;
• normaliza payload;
• limita o tamanho do lote;
• corta campos longos;
• evita guardar IP bruto, trabalhando apenas com contexto coarse quando existir.

Por que essa estrutura facilita a migração futura

Hoje o contrato principal já existe:

• config separada;
• evento bruto com tipos consistentes;
• dashboard que lê agregações;
• compra fechada como evento de servidor.

Ao migrar para banco, a tendência é trocar só o armazenamento e a agregação, mantendo:

• a UI do painel;
• os tipos de evento;
• os endpoints;
• a leitura do storefront.

Próximos passos naturais

• criar projeções próprias para storefront, BI e app mobile;
• separar melhor analytics de navegação e analytics comercial;
• incluir funil de checkout por etapa e por campanha;
• correlacionar analytics com catálogo, promoções e estoque.