adding-analytics

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Add Analytics (PostHog)

添加分析功能(PostHog)

Use this skill when the user asks to add analytics, event tracking, page views, feature flags, or session replay to a web application.
当用户要求为Web应用添加分析、事件追踪、页面浏览统计、功能标志或会话重放功能时,使用本技能。

Steps

步骤

  1. Detect the framework — check for
    next.config.*
    ,
    vite.config.*
    ,
    package.json
    scripts, or
    index.html
    to determine if this is Next.js, React (Vite/CRA), Vue, Svelte, or plain HTML.
  2. Install the SDK
    • Next.js / React:
      npm install posthog-js
    • Next.js (server-side):
      npm install posthog-js posthog-node
    • Python:
      pip install posthog
    • Node.js backend:
      npm install posthog-node
  3. Create a provider / init module
    • For Next.js App Router, create
      app/providers.tsx
      :
      tsx
      "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!, {
            api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST ?? "https://us.i.posthog.com",
            capture_pageview: false, // we capture manually for SPAs
          });
        }, []);
        return <PHProvider client={posthog}>{children}</PHProvider>;
      }
    • Wrap
      {children}
      in the root layout with
      <PostHogProvider>
      .
    • For Pages Router, init in
      _app.tsx
      inside a
      useEffect
      .
  4. Add page-view tracking — for SPAs, create a component that calls
    posthog.capture('$pageview')
    on route change using the framework's router events.
  5. Add
    .env
    variables
    — prompt the user for their PostHog project API key and host:
    NEXT_PUBLIC_POSTHOG_KEY=phc_...
    NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
    Add these keys to
    .env.example
    as well.
  6. Add custom events — if the user specifies events to track (e.g. sign-up, purchase), add
    posthog.capture("event_name", { ...properties })
    calls in the relevant handlers.
  7. Feature flags (optional) — if requested, show how to use
    posthog.isFeatureEnabled("flag-name")
    or the
    useFeatureFlagEnabled
    hook.
  8. Session replay (optional) — enable by adding
    session_recording: { maskAllInputs: false }
    to the init config if requested.
  1. 检测框架 — 检查
    next.config.*
    、
    vite.config.*
    、
    package.json
    脚本或
    index.html
    ,以确定应用使用的是Next.js、React(Vite/CRA)、Vue、Svelte还是纯HTML。
  2. 安装SDK
    • Next.js / React:
      npm install posthog-js
    • Next.js(服务端):
      npm install posthog-js posthog-node
    • Python:
      pip install posthog
    • Node.js后端:
      npm install posthog-node
  3. 创建提供者/初始化模块
    • 对于Next.js App Router,创建
      app/providers.tsx
      :
      tsx
      "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!, {
            api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST ?? "https://us.i.posthog.com",
            capture_pageview: false, // we capture manually for SPAs
          });
        }, []);
        return <PHProvider client={posthog}>{children}</PHProvider>;
      }
    • 在根布局中用
      <PostHogProvider>
      包裹
      {children}
      。
    • 对于Pages Router,在
      _app.tsx
      的
      useEffect
      中进行初始化。
  4. 添加页面浏览追踪 — 对于单页应用(SPA),创建一个组件,利用框架的路由事件在路由变化时调用
    posthog.capture('$pageview')
    。
  5. 添加
    .env
    变量
    — 提示用户提供他们的PostHog项目API密钥和主机地址:
    NEXT_PUBLIC_POSTHOG_KEY=phc_...
    NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
    同时将这些密钥添加到
    .env.example
    中。
  6. 添加自定义事件 — 如果用户指定了要追踪的事件(例如注册、购买),在相关处理函数中添加
    posthog.capture("event_name", { ...properties })
    调用。
  7. 功能标志(可选) — 如果用户要求,展示如何使用
    posthog.isFeatureEnabled("flag-name")
    或
    useFeatureFlagEnabled
    钩子。
  8. 会话重放(可选) — 如果用户要求,通过在初始化配置中添加
    session_recording: { maskAllInputs: false }
    来启用该功能。

Notes

注意事项

  • Never hardcode API keys — always use environment variables.
  • Add
    posthog-js
    to the Content Security Policy if the project has one.
  • For monorepos, install in the package that renders the UI, not the root.
  • 切勿硬编码API密钥 — 始终使用环境变量。
  • 如果项目有内容安全策略(CSP),将
    posthog-js
    添加到其中。
  • 对于单仓库多项目(monorepos),在渲染UI的包中安装,而非根目录。