adding-analytics
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAdd 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
步骤
-
Detect the framework — check for,
next.config.*,vite.config.*scripts, orpackage.jsonto determine if this is Next.js, React (Vite/CRA), Vue, Svelte, or plain HTML.index.html -
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
- Next.js / React:
-
Create a provider / init module
-
For Next.js App Router, create:
app/providers.tsxtsx"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>; } -
Wrapin the root layout with
{children}.<PostHogProvider> -
For Pages Router, init ininside a
_app.tsx.useEffect
-
-
Add page-view tracking — for SPAs, create a component that callson route change using the framework's router events.
posthog.capture('$pageview') -
Addvariables — prompt the user for their PostHog project API key and host:
.envNEXT_PUBLIC_POSTHOG_KEY=phc_... NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.comAdd these keys toas well..env.example -
Add custom events — if the user specifies events to track (e.g. sign-up, purchase), addcalls in the relevant handlers.
posthog.capture("event_name", { ...properties }) -
Feature flags (optional) — if requested, show how to useor the
posthog.isFeatureEnabled("flag-name")hook.useFeatureFlagEnabled -
Session replay (optional) — enable by addingto the init config if requested.
session_recording: { maskAllInputs: false }
-
检测框架 — 检查、
next.config.*、vite.config.*脚本或package.json,以确定应用使用的是Next.js、React(Vite/CRA)、Vue、Svelte还是纯HTML。index.html -
安装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
- Next.js / React:
-
创建提供者/初始化模块
-
对于Next.js App Router,创建:
app/providers.tsxtsx"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
-
-
添加页面浏览追踪 — 对于单页应用(SPA),创建一个组件,利用框架的路由事件在路由变化时调用。
posthog.capture('$pageview') -
添加变量 — 提示用户提供他们的PostHog项目API密钥和主机地址:
.envNEXT_PUBLIC_POSTHOG_KEY=phc_... NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com同时将这些密钥添加到中。.env.example -
添加自定义事件 — 如果用户指定了要追踪的事件(例如注册、购买),在相关处理函数中添加调用。
posthog.capture("event_name", { ...properties }) -
功能标志(可选) — 如果用户要求,展示如何使用或
posthog.isFeatureEnabled("flag-name")钩子。useFeatureFlagEnabled -
会话重放(可选) — 如果用户要求,通过在初始化配置中添加来启用该功能。
session_recording: { maskAllInputs: false }
Notes
注意事项
- Never hardcode API keys — always use environment variables.
- Add to the Content Security Policy if the project has one.
posthog-js - For monorepos, install in the package that renders the UI, not the root.
- 切勿硬编码API密钥 — 始终使用环境变量。
- 如果项目有内容安全策略(CSP),将添加到其中。
posthog-js - 对于单仓库多项目(monorepos),在渲染UI的包中安装,而非根目录。