Product Analytics skill for Claude Code

Analytics is integrated well when one user is one person across devices and logins, events follow one naming convention and carry typed properties, business-critical events (signup, purchase, subscription change) are captured server-side, nothing fires before consent where consent is required, and the key funnel can be reproduced from raw events.

Ground rules

• One event taxonomy, enforced in code: a typed track() wrapper with an allow-list of event names, not scattered string literals. The tracking plan itself (who owns which event, naming spec, QA) is the analytics-tracking-plan skill; this skill implements it.
• Capture outcomes on the server, intent on the client. Ad blockers drop 10-30% of client events on developer audiences; payments must never depend on the browser.
• Identify with your stable internal user ID, never email (emails change and are PII).
• Call reset() on logout, or the next person on a shared device inherits the identity.
• Project API keys for PostHog/Mixpanel/GA4 are public by design; personal/admin API keys and GA4 Measurement Protocol api_secret stay server-side in env.
• Do not send PII (email, name, free text, full URLs with tokens) as event properties unless the privacy policy and DPA cover it. Strip query strings containing tokens.

Tool choice

Need	Default
Product analytics + flags + replay + experiments in one, self-host option	PostHog
Mature behavioral analytics, strong funnels/retention UI, warehouse sync	Mixpanel
Marketing attribution, Google Ads audiences, SEO landing reports	GA4 (often alongside one of the above)
Data warehouse is the source of truth	Send events to a CDP/warehouse first (Segment, RudderStack, or direct), fan out

Running GA4 for marketing plus PostHog or Mixpanel for product is common; keep event names aligned through one wrapper so both receive the same taxonomy.

Workflow

- [ ] 1. Read the tracking plan (or draft a minimal one: 10-20 events)
- [ ] 2. Build a typed track/identify wrapper
- [ ] 3. Initialize SDKs behind consent
- [ ] 4. Implement identity: anonymous -> identify -> reset
- [ ] 5. Add group/account analytics for B2B
- [ ] 6. Move revenue and lifecycle events server-side
- [ ] 7. Define funnels and verify against raw events

2. Typed wrapper

// analytics/events.ts
export type Events = {
  signup_completed: { method: "email" | "google" | "github"; plan: string };
  project_created: { project_id: string; template: string | null };
  invite_sent: { project_id: string; role: "admin" | "member" };
  checkout_started: { plan: string; billing_period: "monthly" | "annual" };
};

export function track<E extends keyof Events>(event: E, props: Events[E]) {
  if (!consent.analytics) return;
  posthog.capture(event, props);
  window.gtag?.("event", event, props);
}

Naming: object_action in snake_case past tense (project_created), properties in snake_case, IDs as strings, money in minor units plus currency. Read references/event-taxonomy.md when drafting or reviewing the event list, properties, or GA4 limits.

3. Init behind consent

PostHog:

import posthog from "posthog-js";

posthog.init(import.meta.env.VITE_POSTHOG_KEY, {
  api_host: import.meta.env.VITE_POSTHOG_HOST,   // or your reverse proxy path
  person_profiles: "identified_only",
  opt_out_capturing_by_default: requiresConsent(),  // EU/UK visitors
  capture_pageview: true,
});
// when the user accepts analytics cookies:
posthog.opt_in_capturing();

Mixpanel:

import mixpanel from "mixpanel-browser";
mixpanel.init(import.meta.env.VITE_MIXPANEL_TOKEN, {
  track_pageview: "url-with-path",
  persistence: "localStorage",
  opt_out_tracking_by_default: requiresConsent(),
});
// on consent: mixpanel.opt_in_tracking();

GA4 with Consent Mode v2 (defaults must run before the gtag config):

<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('consent', 'default', {
    ad_storage: 'denied', ad_user_data: 'denied', ad_personalization: 'denied',
    analytics_storage: 'denied', wait_for_update: 500
  });
</script>
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
<script>
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXX');
  // on consent: gtag('consent', 'update', { analytics_storage: 'granted' });
</script>

• Route client SDK traffic through your own domain (reverse proxy) to reduce blocker loss; PostHog documents proxy setups for common hosts.
• Consent must be revocable: call opt_out_capturing() / opt_out_tracking() / consent update denied when the user withdraws.

4. Identity

Moment	PostHog	Mixpanel	GA4
Anonymous visit	automatic anonymous ID	automatic device ID	client_id cookie
Signup or login	posthog.identify(user.id, { plan })	mixpanel.identify(user.id)	gtag('config', ID, { user_id })
Profile traits	$set via identify / posthog.setPersonProperties	mixpanel.people.set({...})	user properties via gtag('set', 'user_properties', {...})
Logout	posthog.reset()	mixpanel.reset()	clear user_id

• Identify immediately after auth succeeds on the client, and use the same ID in server events so they merge.
• Never call identify with a different user ID without reset first; most tools merge the two identities permanently.
• For server events right after signup, pass the anonymous/distinct ID from the client (header or form field) when the tool needs it to stitch the pre-signup journey.

5. B2B group analytics

• PostHog: posthog.group("company", org.id, { name, plan }); server: capture({ distinctId, event, groups: { company: org.id } }).
• Mixpanel: group analytics with a group key (mixpanel.set_group("company_id", id)), enabled per project.
• Always also put org_id as an event property; it survives tool migrations.

6. Server-side capture

PostHog Node:

import { PostHog } from "posthog-node";
const ph = new PostHog(process.env.POSTHOG_KEY!, { host: process.env.POSTHOG_HOST });

ph.capture({
  distinctId: user.id,
  event: "subscription_started",
  properties: { plan: "pro", amount_cents: 2900, currency: "USD" },
  groups: { company: user.orgId },
});
await ph.shutdown(); // in serverless/short-lived processes, flush before exit

GA4 Measurement Protocol (server secret from env; validate first against the debug endpoint):

curl -s "https://www.google-analytics.com/debug/mp/collect?measurement_id=$GA_MEASUREMENT_ID&api_secret=$GA_API_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"client_id":"123.456","user_id":"u_42","events":[{"name":"purchase","params":{"currency":"USD","value":29.0,"transaction_id":"inv_981"}}]}'

• Fire revenue events from the payment webhook (after signature verification), not from the success page. Use the invoice/charge ID as the dedupe key (transaction_id in GA4, $insert_id in Mixpanel, uuid in PostHog where supported).
• Batch and flush: SDKs queue events; in Lambda/edge functions flush or await shutdown, or events are lost.

7. Funnels and retention

• Define each funnel as an ordered list of events with a conversion window and the property breakdowns you need; write it down next to the taxonomy.
• Count users, not events, unless the question is volume.
• Retention needs a clear “active” event (a value action like report_viewed, not $pageview).
• Exclude internal users and test accounts with a person property or filter (is_internal).
• For statistical decisions on experiments, hand off to experiment-analysis.

Gotchas

• SPAs: pageviews on route change need the SDK’s history tracking or a manual capture in the router; otherwise every session looks like one page.
• Double-firing in React StrictMode/dev: effects run twice; guard init with a module-level flag and fire events from handlers, not effects.
• GA4 truncates and rejects: event names over 40 chars, parameter values over 100 chars, more than 25 parameters per event. Custom dimensions must be registered before they show in reports, and are not backfilled.
• Changing an event name splits history. Version with a new event and keep the old one until dashboards migrate.
• Timestamps: server events sent later must include the original timestamp, or funnels order them wrongly.

Verification

1. Open the tool’s live/debug view (PostHog activity, Mixpanel events, GA4 DebugView with debug_mode) and walk the core funnel: each step appears once, with typed properties.
2. Log in on a second browser as the same user: one person, both sessions merged. Log out and sign up as someone else: a new person, no merge.
3. Decline consent: confirm no network requests to analytics endpoints.
4. Trigger a test payment webhook: the revenue event arrives once, server-side, with the transaction ID.
5. Compare funnel step counts in the UI with a raw-event query (SQL/HogQL/export) for one day; they should match.