Observabilidade de Frontend (lado do campo)

Quando Usar

Use esta habilidade quando precisar de um sistema de observabilidade portátil e independente de framework para qualquer aplicativo React ou React Native. Estabelece uma taxonomia de eventos tipada (constantes de nome de evento canônico, nunca strings inline), um fan-out de provedor de melhor esforço e não bloqueante para que um provedor de análise falho ou ausente nunca possa...

Habilidade portátil — legível por Claude Code, OpenCode, Codex, Cursor, Windsurf e outros. Esta habilidade descreve um sistema de observabilidade do lado do campo — taxonomia de eventos, fan-out de provedores, métricas de usuários reais, relatórios de erros, consentimento — não um painel ou um fornecedor específico. É o complemento de campo para a habilidade frontend-lighthouse: Lighthouse é o portão do laboratório (sintético, pré-merge); este é o campo (o que os usuários reais realmente experimentam). Ele reside em um módulo services/analytics/ conforme a habilidade frontend-architecture.

O objetivo: você pode responder "o que os usuários reais estão fazendo e o que eles estão experimentando?" — com um vocabulário de eventos tipado (sem track("clicked_thing") com tipagem de string espalhados por toda parte), um fan-out que é de melhor esforço (um provedor quebrado nunca quebra o aplicativo), Core Web Vitals reais do campo, e consentimento respeitado antes que qualquer coisa seja disparada.

0. As cinco ideias centrais

1. Eventos são um vocabulário tipado. Nomes de eventos são constantes canônicas com um tipo de união — nunca literais de string inline. A taxonomia pode ser revisada em um arquivo e o compilador rejeita erros de digitação.
2. Fan-out é de melhor esforço e não bloqueante. track() despacha para cada provedor, cada um em seu próprio try/catch. Um global ausente, um provedor lançado, um script não carregado — nenhum deles pode lançar para o chamador ou parar os outros provedores.
3. Um ponto de entrada, seguro para SSR. Um único track(event, props) é a única maneira de registrar. Ele é acessado através de um hook de contexto que não faz nada fora de um provedor e no servidor, para que componentes instrumentados renderizem com segurança em qualquer lugar.
4. Métricas de campo complementam orçamentos de laboratório. LCP/INP/CLS de usuários reais são relatados para o mesmo fan-out. Lighthouse prova que a compilação pode ser rápida; métricas de campo provam que é — juntos eles fecham o ciclo.
5. Consentimento bloqueia tudo. Nenhuma telemetria (eventos, métricas, relatórios de erros com PII) é disparada antes do opt-in. O estado de consentimento é verificado na fronteira do fan-out, não espalhado por chamadas.

1. Layout do diretório

O sistema é um módulo de serviço mais suas constantes (por frontend-architecture).

src/
├── constants/
│   └── analytics.ts           ← canonical event names + AnalyticsEvent union
├── services/analytics/
│   ├── index.ts               ← barrel: track, adapters, types
│   ├── track.ts               ← the best-effort fan-out (single entry point)
│   ├── adapters.ts            ← one (event, props) => void per provider, window-guarded
│   ├── web-vitals.ts          ← report real-user LCP/INP/CLS into track()
│   └── consent.ts             ← consent gate read by the fan-out
├── providers/
│   └── AnalyticsProvider.tsx  ← 'use client' context exposing useAnalytics().track
└── error/
    └── ErrorBoundary.tsx      ← reports caught render errors via the fan-out

2. A taxonomia de eventos (tipada, nunca inline)

Um arquivo possui todos os nomes de eventos. Componentes referenciam constantes; o tipo de união torna erros de digitação um erro de compilação e o catálogo uma única fonte de verdade.

// constants/analytics.ts
export const ANALYTICS_EVENTS = {
  PROJECT_CLICK: "project_click",
  GITHUB_CLICK: "github_click",
  RESUME_DOWNLOAD: "resume_download",
  CONTACT_SUBMISSION: "contact_submission",
} as const;

export type AnalyticsEvent =
  (typeof ANALYTICS_EVENTS)[keyof typeof ANALYTICS_EVENTS];

// CORRECT — typed constant, autocompletes, can't typo
track(ANALYTICS_EVENTS.GITHUB_CLICK, { url });

// WRONG — stringly-typed, drifts, no compile check
track("github-click"); // ❌ silently a different event from "github_click"

Regras rígidas:

• Nenhuma string de nome de evento inline em qualquer lugar; apenas ANALYTICS_EVENTS.*.
• Nomes de eventos são snake_case e estáveis — renomear um quebra dashboards históricos, então trate o catálogo como um contrato.
• Mantenha as formas props pequenas e com pouca PII (veja §6); prefira IDs em vez de nomes, nunca e-mails brutos.

3. Fan-out de melhor esforço e não bloqueante

track() é o único ponto de entrada. Ele itera o registro de adaptadores, protegendo cada chamada para que um provedor não possa afetar o chamador ou os outros.

// services/analytics/track.ts

…