Documentación

Analytics (PostHog)

Analytics de producto con PostHog — tracking cliente y servidor, eventos y el dashboard de analytics.

Motoko Base usa PostHog para analytics de producto. PostHog es independiente de Sentry (errores) — no los mezcles.

Official docs: PostHog documentation

Setup

Crea un proyecto PostHog
Copia la Project API key (captura en el cliente)
Para el dashboard de Analytics (/dashboard/analytics), crea también una Personal API key con Query Read
Define las 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)

Sin el project token, analytics está deshabilitado — la app funciona con normalidad.

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 del cliente: src/instrumentation-client.ts. El servidor usa un singleton de módulo — fail-open, nunca lanza.

Events

Los nombres de eventos viven en src/lib/analytics/events.ts:

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

Convención: {object}_{past_tense_verb} (minúsculas, guiones bajos).

Add a custom event

Añade el nombre del evento a ANALYTICS_EVENTS en events.ts
Añade propiedades tipadas a AnalyticsEventProperties (opcional)
Captura desde la capa correcta:

// 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: { ... } });

Las propiedades se limpian antes del envío (src/lib/analytics/scrub.ts) — sin contraseñas, tokens ni URLs crudas con secretos.

Analytics dashboard

/dashboard/analytics ejecuta consultas HogQL vía src/lib/analytics/query.ts. Requiere POSTHOG_PERSONAL_API_KEY + POSTHOG_PROJECT_ID. Los resultados se cachean ~60s por usuario.

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 las env vars de PostHog.