Pular para o conteúdo

Builder OS

&
Builder · OS
L04 · Analytics real
PRÓXIMA L05
~14 MIN DE LEITURA

Lição 4 de 9: Analytics real

lição 4/9 do Módulo 4
AO FIM, VOCÊ VAI TER
  • PostHog (ou Plausible) instalado e rodando em produção
  • 4-6 eventos disparando: pelo menos landing_view, signup_started (se houver), wedge_consumed (já existia da L06/M3), weekly_return (placeholder)
  • Dashboard mostrando os primeiros eventos chegando em produção
  • Commit feat(analytics): real provider wired + funnel events live

Até agora analytics.track() só escrevia console.log (M3/L06). Esta lição troca isso por um provider real, com os eventos chegando num dashboard.

De console.log pra "X pessoas atravessaram o funil"

No M3/L06 você instalou analytics.track() como no-op (só console.log). Esta lição substitui o no-op por chamada real ao ou . No helper, muda só uma linha, e os eventos começam a aparecer no dashboard. Depois, você instala os outros 3-5 eventos do funil que listou no M2/L07 e adiou, porque ainda não tinha contexto pra dispará-los.

A pergunta que esta lição responde: quantas pessoas atravessam cada estágio do funil? Com os eventos chegando no dashboard, você mede cada estágio em vez de supor.

Vai passar por:

  1. Decidir PostHog ou Plausible com critério (free tier maior vs privacidade-first)
  2. Criar conta + instalar o SDK (~10 min)
  3. Configurar o helper do M3/L06 pra chamar a ferramenta real
  4. Instalar 3-5 eventos do funil (landing_view, signup_started, weekly_return)
  5. Boas práticas LGPD: desligar captura de IP, nunca passar PII, aviso no rodapé

Passo 1 — Decida PostHog ou Plausible

Antes de instalar, decide. Esta lição usa PostHog como default: o free tier cobre os primeiros meses, e funil + session replay é onde o valor mora. Se você prefere Plausible, ajuste os comandos. O pattern é igual.

prompt · text
Quero decidir entre PostHog e Plausible. Responde:

1. Vou querer ver session replay (gravação de sessão pra entender bug ou friction)? Se sim, PostHog.
2. Privacidade é argumento de venda do produto (público B2B europeu, ou compliance LGPD agressivo)? Se sim, Plausible (sem cookies, sem PII).
3. Quero feature flags integrados com analytics (testar variação A/B)? Se sim, PostHog.
4. Quero menor custo total nos primeiros 6 meses? PostHog free tier é maior, mas o painel é mais complexo. Se tempo é mais escasso que dinheiro, Plausible (5 min de setup).

Não responde por mim — só dá guidance. Eu decido.

Esta lição assume PostHog daqui em diante. Se você escolheu Plausible, a única diferença é o SDK e a função; o resto (eventos, propriedades, LGPD) é idêntico.

Passo 2 — Crie conta + projeto no PostHog

  1. Vai em posthog.com, cria conta (free tier)
  2. Cria projeto novo. Anota a Project API Key (formato phc_xxxxxxxxxxxxx) e o Host (geralmente https://app.posthog.com)
  3. Adiciona ao .env.example (e ao .env.local com o valor real, e ao Vercel via vercel env add):
NEXT_PUBLIC_POSTHOG_KEY=<<chave-do-posthog>>
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

Note o prefixo NEXT_PUBLIC_: analytics é Client Component, precisa estar disponível no JS do browser.

Passo 3 — Instale o SDK + atualize o helper

Cole no Claude:

prompt · text
Instala o PostHog SDK e atualiza o helper de analytics. Requisitos:

1. `npm install posthog-js`
2. Cria um `PostHogProvider` (Client Component) que faz `posthog.init(...)` na primeira render usando `NEXT_PUBLIC_POSTHOG_KEY` e `NEXT_PUBLIC_POSTHOG_HOST`. Encapsula com `'use client'`.
3. Adiciona o provider no `app/layout.tsx` envolvendo o `children`.
4. Atualiza o `lib/analytics.ts` (criado no M3/L06): `analytics.track(name, props)` agora chama `posthog.capture(name, props)` em vez de só `console.log`. Mantém o `console.log` em desenvolvimento (`if (process.env.NODE_ENV !== 'production') console.log(...)`) pra você continuar vendo no terminal local.
5. **NÃO captura nenhum dado pessoal** (regra LGPD da L06). Adiciona um comentário no topo do `lib/analytics.ts` lembrando: "Nunca passe CPF, CNPJ, email, nome ou telefone como propriedade de evento."

Mostre o diff antes de aplicar.

Aprove. Roda local pra confirmar que não quebrou:

prompt · text
Roda `npm run dev`. Abre o browser e clica no fluxo da fatia 1 — submete um recibo. Confere:
1. No terminal: `[analytics] recibo_emitido { ... }` aparece (dev fallback)
2. No browser DevTools Console: sem erros vermelhos
3. No PostHog dashboard (app.posthog.com → projeto → Events): evento "recibo_emitido" chega em ~30s

Se os 3 itens passam, o pipeline está funcionando. Próximo passo: cobrir o funil inteiro.

Passo 4 — Instale os 3-5 eventos restantes do funil

No M2/L07 você listou 4 eventos: landing_view, signup_started, wedge_consumed, weekly_return. O wedge_consumed já existe (M3/L06). Os outros 3:

prompt · text
Adiciona os 3 eventos restantes do funil:

1. **landing_view** — dispara quando a página inicial pública carrega. Adiciona em `app/page.tsx` (ou rota equivalente da landing). Use `useEffect` ou `PostHog`'s autocapture.

2. **signup_started** — dispara quando o usuário começa o signup (clica no botão "começar", ou abre o modal de signup). Se não há signup ainda (fatia 1 sem autenticação), pula este evento por agora e me avisa.

3. **weekly_return** — dispara quando um usuário que já criou conta volta após 7 dias da última visita. Implementa via flag no localStorage (`last_visit` timestamp) + comparação na primeira render do app. Se `last_visit` passou de 7 dias, dispara `weekly_return`. (Atenção: localStorage é por-dispositivo e some se o usuário limpa o cache, então isso é um proxy de retenção, não a métrica exata. Quando tiver auth/conta, troca por `last_visit` no banco.)

Propriedades de cada evento: documentar em `docs/analytics.md` (já criado no M3/L06). Sem PII. Mostre o diff antes de aplicar.

Aprove. Testa cada um:

  • landing_view: recarrega a página principal, confere PostHog
  • signup_started: se aplicável, clica no fluxo de signup
  • weekly_return: manipula localStorage.last_visit (com Date.now() - 8 * 24 * 3600 * 1000) e recarrega; deve disparar

Se um evento depende de contexto que ainda não existe (ex: signup), marca como "instalado mas não dispara ainda" em docs/analytics.md e segue.

Passo 5 — Configure o funil no dashboard do PostHog

No PostHog: Insights → Funnels → New funnel. Adiciona os 4 eventos em ordem (landing_view → signup_started → wedge_consumed → weekly_return). Salva como "Funil principal".

Esse é o dashboard que você vai abrir todo dia/semana pra ver:

  • Quantas pessoas viram a landing
  • Que % delas começou signup
  • Que % concluiu o wedge
  • Que % voltou em 7 dias

O funil que você desenhou no M2/L07 era hipótese; agora cada estágio tem um número medido em produção.

Passo 6 — Deploy e faça o commit

prompt · text
Roda `npm run doctor` pra confirmar 6/6 OK. Faça commit das mudanças. Mensagem: `feat(analytics): real provider wired + funnel events live`. Depois roda `vercel --prod` pra publicar (skill `deploy-and-verify` ajuda).

Aprove. Depois do deploy, espera 5 minutos e abre o dashboard do PostHog; eventos de produção devem começar a chegar.

Build Diary — o CEAP mediu só o que respondia à pergunta do produto

O CEAP é puro front-end estático (zero auth, zero forma, conforme ADR-001), então o analytics dele é mais simples: Cloudflare Web Analytics no site. A parte interessante é a decisão do que medir. Trecho real do MAINTENANCE.md:

Cloudflare Analytics

  • Real-time visitors
  • Page views
  • Top pages
  • Referrers
  • Browser/device breakdown

Update Frequency: real-time

Note o que não está medindo: tempo médio na sessão, bounce rate, conversion rate (não há conversão, o produto não vende nada). O autor pegou só os eventos que respondem à pergunta central do produto ("essa análise está sendo lida e por quem") e deixou os outros 20 disponíveis no painel da Cloudflare como ruído ignorável.

O mesmo critério vale pro seu PostHog: se você instalou 4 eventos no funil e não vai abrir o dashboard ao menos semanalmente, instala 2, ou nenhum, e adia até ter tração. PostHog cobra (eventualmente) por volume, e coletar evento que ninguém olha custa dinheiro e atenção sem retorno. Pra estimar quando esse custo começa a pesar, veja o apêndice Quando começa a custar.

Takeaways

  • PostHog default (free tier 1M/mês, funil + session replay). Plausible se privacy-first é argumento de venda.
  • posthog.init({ ip: false }) + privacy disclosure no rodapé = LGPD trivial.
  • Nunca PII como propriedade de evento. Use IDs internos e contagens agregadas.
  • Só instale eventos que você vai consultar (cada um custa volume e atenção). Comece com 2-4, não 10.

Você terminou quando

Quatro coisas:

  1. PostHog (ou Plausible) instalado em produção
  2. Pelo menos wedge_consumed + landing_view disparando no dashboard
  3. docs/analytics.md atualizado listando os eventos instalados + privacidade (LGPD)
  4. Funil principal criado no dashboard do provider