Documentação

Analytics (PostHog)

Analytics de produto com PostHog — tracking no cliente e no servidor, eventos e o dashboard de analytics.

O Motoko Base usa PostHog para analytics de produto. O PostHog é separado do Sentry (erros) — não misture os dois.

Official docs: PostHog documentation

Setup

Crie um projeto PostHog
Copie a Project API key (captura no cliente)
Para o dashboard de Analytics (/dashboard/analytics), crie também uma Personal API key com Query Read
Defina as env vars:

Variable	Scope	Purpose
`NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN`	Client	Event capture
`NEXT_PUBLIC_POSTHOG_HOST`	Client	Ingest host (US/EU)
`POSTHOG_PERSONAL_API_KEY`	Server	HogQL queries
`POSTHOG_PROJECT_ID`	Server	Project ID for queries
`POSTHOG_HOST`	Server	API host for queries (not ingest)

Sem o project token, analytics fica desabilitado — o app funciona normalmente.

Client vs server tracking

Layer	Module	Use for
Client	`src/lib/analytics/client.ts`	Browser events (sign-in, sign-up)
Server	`src/lib/analytics/server.ts`	Server actions, webhooks (links, files, billing)

Init do cliente: src/instrumentation-client.ts. O servidor usa um singleton de módulo — fail-open, nunca lança.

Events

Os nomes de eventos ficam em src/lib/analytics/events.ts:

export const ANALYTICS_EVENTS = {
  userSignedUp: "user_signed_up",
  linkCreated: "link_created",
  fileUploaded: "file_uploaded",
  checkoutStarted: "checkout_started",
  // ...
} as const;

Convenção: {object}_{past_tense_verb} (minúsculas, underscores).

Add a custom event

Adicione o nome do evento a ANALYTICS_EVENTS em events.ts
Adicione propriedades tipadas a AnalyticsEventProperties (opcional)
Capture na camada correta:

// Client component
import { captureClientEvent } from "@/lib/analytics/client";
captureClientEvent(ANALYTICS_EVENTS.linkCreated, { link_id, slug, destination_host });

// Server action
import { captureServerEvent } from "@/lib/analytics/server";
captureServerEvent({ distinctId: userId, event: ANALYTICS_EVENTS.linkCreated, properties: { ... } });

As propriedades são limpas antes do envio (src/lib/analytics/scrub.ts) — sem senhas, tokens ou URLs brutas com segredos.

Analytics dashboard

/dashboard/analytics executa queries HogQL via src/lib/analytics/query.ts. Requer POSTHOG_PERSONAL_API_KEY + POSTHOG_PROJECT_ID. Os resultados são cacheados ~60s por usuário.

Where to change this

What	Where
Event taxonomy	`src/lib/analytics/events.ts`
Client capture	`src/lib/analytics/client.ts`
Server capture	`src/lib/analytics/server.ts`
Config & enable checks	`src/lib/analytics/config.ts`
Dashboard queries	`src/lib/analytics/query.ts`
Analytics UI	`src/features/analytics/`

Environment Variables — todas as env vars do PostHog.