PostHog: Скилл для аналитики Next.js

--- name: posthog description: Implement PostHog analytics, feature flags, and session replay for Next.js apps. Use this skill for event tracking, user identification, A/B testing, experiments, and session recording setup. Also handles analytics reporting (funnel analysis, retention, SEO) with Google Search Console integration. allowed-tools: Read, Glob, Grep, Write, Edit, WebSearch, Bash --- # PostHog Implementation (Next.js 2025) ## What This Skill Covers 1. **Analytics** - Event tracking, user identification, group analytics 2. **Feature Flags** - Boolean flags, multivariate, A/B testing 3. **Session Replay** - Recording setup, privacy controls 4. **Analytics Queries** - HogQL, Query API, extracting insights 5. **Reporting** - Funnel analysis, retention, error reports, SEO ## Reference Files Load these files as needed based on the task: | File | Load When | |------|-----------| | `references/nextjs-implementation.md` | Setting up PostHog from scratch, detailed code patterns | | `references/event-taxonomy.md` | Designing event naming conventions, property patterns | | `references/feature-flags.md` | Implementing feature flags, A/B tests, experiments | ## Quick Setup ### Environment Variables ```bash # .env.local NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_key NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com ``` ### Reverse Proxy Setup (RECOMMENDED) **IMPORTANT:** Ad blockers block direct PostHog requests. Use a reverse proxy to route through your own domain. Add to `next.config.ts`: ```typescript const nextConfig: NextConfig = { async rewrites() { return [ { source: "/ingest/static/:path*", destination: "https://us-assets.i.posthog.com/static/:path*", }, { source: "/ingest/:path*", destination: "https://us.i.posthog.com/:path*", }, { source: "/ingest/decide", destination: "https://us.i.posthog.com/decide", }, ]; }, // ... rest of config }; ``` Also update CSP headers to allow PostHog connections: ```typescript "connect-src 'self' ... https://*.posthog.com https://us.i.posthog.com https://us-assets.i.posthog.com", ``` ### PostHog Provider (Client-Side) Create `app/providers.tsx`: ```typescript 'use client' import posthog from 'posthog-js' import { PostHogProvider as PHProvider } from 'posthog-js/react' import { useEffect } from 'react' export function PostHogProvider({ children }: { children: React.ReactNode }) { useEffect(() => { posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, { // Use reverse proxy to bypass ad blockers api_host: '/ingest', ui_host: 'https://us.i.posthog.com', defaults: '2025-05-24', capture_pageview: false, // We handle manually for accurate funnels person_profiles: 'identified_only', }) }, []) return <PHProvider client={posthog}>{children}</PHProvider> } ``` ### PostHog Server Client Create `lib/posthog-server.ts`: ```typescript import { PostHog } from 'posthog-node' let posthogClient: PostHog | null = null export function getPostHogServer(): PostHog { if (!posthogClient) { posthogClient = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, { host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com', flushAt: 1, flushInterval: 0, }) } return posthogClient } ``` ## Event Naming Convention | Pattern | Example | Use Case | |---------|---------|----------| | `category:object_action` | `signup:form_submit` | User actions | | `feature:action` | `dashboard:project_create` | Feature usage | | `lifecycle:event` | `user:signup_complete` | User journey | ### Property Naming | Pattern | Example | Type | |---------|---------|------| | `object_adjective` | `user_id`, `item_price` | Any | | `is_` prefix | `is_subscribed`, `is_first_time` | Boolean | | `has_` prefix | `has_seen_onboarding` | Boolean | | `_count` suffix | `item_count`, `generation_count` | Number | | `_at` suffix | `created_at`, `upgraded_at` | Timestamp | ## Server vs Client Decision Tree ``` Where to track? ├── User action in browser → Client (posthog-js) ├── API route / webhook → Server (posthog-node) ├── Server Component render → Server (posthog-node) ├── Need 100% accuracy → Server (no ad blockers) └── Real-time UI feedback → Client (posthog-js) ``` ## Common Pitfalls | Pitfall | Solution | |---------|----------| | **Ad blockers blocking PostHog** | Use reverse proxy (`/ingest` → PostHog). See setup above | | Events not appearing | Check ad blockers, verify API key, use reverse proxy | | Duplicate pageviews | Use `capture_pageview: false` and handle manually | | Feature flag flicker | Bootstrap flags via middleware | | Missing user data | Call `identify()` BEFORE `$pageview` for accurate funnels | | Inconsistent naming | Use `category:object_action` pattern | | `Failed to fetch` errors | Browser extension blocking - use reverse proxy | | 503 from `us-assets.i.posthog.com` | Ad blocker injecting fake response - use reverse proxy | ## Clarifying Questions Before implementing PostHog, ask: 1. **What events are most important to track?** (signups, conversions, feature usage) 2. **Do you need server-side tracking?** (for accuracy, API routes) 3. **Are you running A/B tests?** (need experiment setup) 4. **What's your auth provider?** (for user identification pattern) 5. **Do you need session replay?** (privacy considerations)