adding-analytics

添加 Analytics（PostHog）

当用户要求为 Web 应用添加 Analytics、事件跟踪、页面浏览量、功能标志或会话回放时，使用此技能。

步骤

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. 创建 provider / 初始化模块

   • 对于 Next.js App Router，创建 app/providers.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 hook。

8. 会话回放（可选） — 如果用户提出要求，在初始化配置中添加 session_recording: { maskAllInputs: false } 以启用此功能。

说明

• 切勿将 API 密钥硬编码；始终使用环境变量。
• 如果项目设置了内容安全策略，请将 posthog-js 添加到其中。
• 对于 monorepo，请在渲染 UI 的包中安装，而不是安装在根目录。