Dokumentation

Analytics (PostHog)

PostHog-Produktanalyse — Client- und Server-Tracking, Events und das Analytics-Dashboard.

Motoko Base nutzt PostHog für Produktanalyse. PostHog ist getrennt von Sentry (Fehler) — vermische sie nicht.

Official docs: PostHog documentation

Setup

Erstelle ein PostHog-Projekt
Kopiere den Project API key (Client-Capture)
Für das Analytics-Dashboard (/dashboard/analytics) erstelle zusätzlich einen Personal API key mit Query Read
Setze 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)

Ohne Project-Token ist Analytics deaktiviert — die App funktioniert normal.

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)

Client-Init: src/instrumentation-client.ts. Der Server nutzt ein Modul-Singleton — fail-open, wirft nie.

Events

Event-Namen liegen in src/lib/analytics/events.ts:

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

Konvention: {object}_{past_tense_verb} (Kleinbuchstaben, Unterstriche).

Add a custom event

Füge den Event-Namen zu ANALYTICS_EVENTS in events.ts hinzu
Füge typisierte Properties zu AnalyticsEventProperties hinzu (optional)
Capture von der richtigen Schicht:

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

Properties werden vor dem Senden bereinigt (src/lib/analytics/scrub.ts) — keine Passwörter, Tokens oder Roh-URLs mit Secrets.

Analytics dashboard

/dashboard/analytics führt HogQL-Queries über src/lib/analytics/query.ts aus. Erfordert POSTHOG_PERSONAL_API_KEY + POSTHOG_PROJECT_ID. Ergebnisse werden ~60s pro Benutzer gecacht.

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 — alle PostHog-Env-Vars.