Add Analytics

Problem this prompt solves

Pageview-only analytics will not tell you whether the AI workflow works. Founders either skip instrumentation until “after launch” or dump PII into a third party. You need a thin event taxonomy — identity, activation, generation outcomes — with server-side events for anything tied to billing or AI cost.

When to use it

• You are weeks from public beta and cannot answer “how many users completed a generation?”
• You want PostHog, Plausible, or similar wired in a way that respects cookie consent if you need it for your audience.
• You need server-side events for AI success/failure, not only client clicks.
• You are preparing for Stripe and want activation metrics before you optimise paywalls.

Add product analytics to this Next.js App Router AI SaaS with a minimal, decision-useful event set.

Prefer PostHog if no analytics exists yet (next.js integration). If the repo already chose Plausible/GA/another tool, extend that instead of adding a second platform.

Event taxonomy (implement these names unless the project already has a convention — then map to it):
- user_signed_up
- user_signed_in
- project_created (or the primary resource name)
- ai_generation_started
- ai_generation_succeeded (properties: model, latency_ms, token totals if available — no raw prompt/response)
- ai_generation_failed (properties: error_code, model)
- billing_checkout_started / billing_subscription_active (stubs ok if Stripe not present)
- page_view for key marketing + /app pages if not automatic

Implementation requirements:
1) lib/analytics.ts (or similar) with typed track() helpers usable from client and server.
2) Identify users on login (distinct id = Supabase user id). Never use email as the only distinct id in code samples if avoidable; attach email as a property only if the privacy posture allows.
3) Fire AI outcome events on the server where the OpenAI call happens (source of truth).
4) Gate client analytics on consent if the project already has a cookie banner; otherwise document GDPR/consent follow-ups for EU traffic.
5) Env: NEXT_PUBLIC_POSTHOG_KEY / HOST (or equivalent) in .env.example; disable or no-op when unset so local dev stays quiet.
6) Do not send prompt contents, documents, API keys, or Authorization headers to the analytics vendor.

Also add a short ANALYTICS.md or README section: what each event means, and the 3 charts to create first (signups, activation rate = first successful generation / signup, generation failure rate).

Expected result

Typed analytics helpers, identity on auth, server-side AI success/failure events without prompt payloads, env-based configuration, and a tiny playbook for the first three dashboards.

Implementation notes

• Activation > vanity traffic: instrument the first successful AI result before adding heatmaps.
• Keep property dictionaries small and stable — renaming events later breaks funnels.
• Server-side events avoid adblockers missing your most important AI outcomes.
• Use a no-op analytics client when keys are missing so tests and OSS clones do not crash.
• If you serve EU users, plan consent before enabling detailed session replay.
• Align event names with future Stripe webhooks so you can build revenue funnels without renaming everything.

Testing checklist

• Sign up a fresh user and see user_signed_up (or equivalent) in the analytics debugger.
• Create the primary resource and confirm project_created fires once.
• Run a successful AI action — ai_generation_succeeded appears with model/latency properties only.
• Force an AI failure — ai_generation_failed fires with error_code, not stack traces or prompts.
• Confirm with Network tab that request bodies do not include document/prompt text.
• With analytics env vars unset, the app still runs and AI flows succeed.
• If consent gating exists, no non-essential events fire before acceptance.

Common mistakes

• Only installing a pageview snippet — no product funnel.
• Tracking raw prompts/responses — privacy and vendor retention risk.
• Client-only AI events that never fire when the server fails before responding.
• Using randomly generated client ids that reset every session — retention looks broken.
• Dozens of events for every hover — noise you will never read.
• Hard-crashing the app when the analytics key is missing in development.