Documentation

Analytics (PostHog)

Analytics produit PostHog — tracking client et serveur, événements et le dashboard analytics.

Motoko Base utilise PostHog pour l'analytics produit. PostHog est distinct de Sentry (erreurs) — ne les mélangez pas.

Official docs: PostHog documentation

Setup

Créez un projet PostHog
Copiez la Project API key (capture client)
Pour le dashboard Analytics (/dashboard/analytics), créez aussi une Personal API key avec Query Read
Définissez les variables d'environnement :

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)

Sans le project token, l'analytics est désactivé — l'app fonctionne normalement.

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 client : src/instrumentation-client.ts. Le serveur utilise un singleton de module — fail-open, ne lance jamais.

Events

Les noms d'événements vivent dans src/lib/analytics/events.ts :

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

Convention : {object}_{past_tense_verb} (minuscules, underscores).

Add a custom event

Ajoutez le nom d'événement à ANALYTICS_EVENTS dans events.ts
Ajoutez des propriétés typées à AnalyticsEventProperties (optionnel)
Capturez depuis la bonne couche :

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

Les propriétés sont nettoyées avant l'envoi (src/lib/analytics/scrub.ts) — pas de mots de passe, tokens ni URLs brutes avec secrets.

Analytics dashboard

/dashboard/analytics exécute des requêtes HogQL via src/lib/analytics/query.ts. Nécessite POSTHOG_PERSONAL_API_KEY + POSTHOG_PROJECT_ID. Les résultats sont mis en cache ~60s par utilisateur.

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 — toutes les variables PostHog.