api-analytics-posthog-analytics

PostHog 分析模式

快速指南： 使用 PostHog 进行产品分析，采用结构化的事件命名（category:object_action）、通过服务端跟踪确保可靠性，并结合身份验证流程妥善识别用户。UI 交互使用客户端跟踪，业务事件使用服务端跟踪。务必在用户登出时调用 reset()，切勿在事件属性中存储个人身份信息（PII）；在无服务器环境中使用 captureImmediate() 或 await shutdown()。

详细资源：

• examples/core.md - 事件命名、用户识别、属性约定
• examples/client-tracking.md - React 钩子、Provider 配置、组件跟踪
• examples/server-tracking.md - posthog-node、无服务器模式、身份验证事件
• examples/group-analytics.md - B2B 组织跟踪
• examples/privacy-gdpr.md - GDPR 同意、无 Cookie 模式、PII 过滤
• reference.md - 决策框架、反模式、事件分类体系

---

<critical_requirements>

关键：使用此技能前

所有代码都必须遵循项目在 CLAUDE.md 中的约定（kebab-case、命名导出、导入顺序、import type、命名常量）

（仅当用户注册或登录时，才必须调用 posthog.identify()；切勿在每次页面加载时调用）

（所有服务端事件中，都必须将用户的数据库 ID 作为 distinct_id）

（用户登出时，必须调用 posthog.reset()，以解除后续事件与该用户的关联）

（所有自定义事件都必须使用 category:object_action 命名约定）

（绝不能在事件属性中包含 PII（电子邮件、姓名、电话号码）；只能使用用户 ID）

</critical_requirements>

---

自动检测： PostHog、posthog-js、posthog-node、usePostHog、PostHogProvider、capture、identify、群组分析、产品分析、事件跟踪、漏斗分析

适用场景：

• 跟踪用户行为和产品分析
• 设置转化漏斗和留存分析
• 为 B2B 多租户应用实现群组分析
• 了解功能采用情况和用户旅程
• A/B 测试分析（与功能标志结合使用）

不适用场景：

• 功能标志的实现（属于独立事项）
• 错误跟踪和日志记录（使用专用错误跟踪工具）
• 基础设施监控（使用可观测性工具）

涵盖的关键模式：

• 事件命名约定（category:object_action）
• 属性命名模式（object_adjective、is_/has_ 布尔值）
• 与身份验证流程集成的用户识别
• 使用 React 钩子进行客户端跟踪
• 使用 posthog-node 进行服务端跟踪
• 面向 B2B 组织的群组分析
• 隐私和 GDPR 同意模式
• 用于类型安全事件的 TypeScript 模式

---

理念

PostHog 分析采用结构化分类体系：保持命名约定一致、使用有意义的属性，并策略性地选择跟踪位置（客户端还是服务端）。跟踪对产品决策有意义的内容，而不是所有内容。

核心原则：

1. 业务事件使用服务端跟踪 - 用户注册、购买、订阅（可靠，不会被拦截）
2. UI 交互使用客户端跟踪 - 按钮点击、页面浏览、表单交互
3. 每个会话只识别一次 - 不要在每次页面加载时识别
4. 采用结构化命名 - 便于大规模查询和分析

---

核心模式

模式 1：事件命名规范

使用 category:object_action 框架，确保事件名称一致且可查询。

// category: Context (signup_flow, settings, dashboard)
// object: Component/location (password_button, pricing_page)
// action: Present-tense verb (click, submit, view)

"signup_flow:email_form_submit";
"dashboard:project_create";
"settings:billing_plan_upgrade";

// Simpler alternative: object_verb
"project_created";
"user_signed_up";

优点： 类别前缀会在 PostHog UI 中对相关事件进行分组，支持 signup_flow:* 这样的通配符查询；一致的命名方式能让大规模分析成为可能。

属性命名规则：

• object_adjective：project_id、plan_name、item_count
• 布尔值使用 is_ / has_：is_first_purchase、has_completed_onboarding
• 使用 _date / _timestamp 后缀：trial_end_date、last_login_timestamp

完整的命名示例请参阅 examples/core.md。

---

模式 2：通过身份验证识别用户

仅在身份验证状态变化时调用 identify()（而非每次渲染时调用）。使用数据库用户 ID 作为 distinct_id。用户登出时调用 reset()。

// Check _isIdentified() to prevent duplicate calls
useEffect(() => {
  if (session?.user && !posthog._isIdentified()) {
    posthog.identify(session.user.id, {
      plan: session.user.plan ?? "free",
      created_at: session.user.createdAt,
      is_verified: session.user.emailVerified ?? false,
    });
  }
}, [session?.user]);

// Always reset on logout
posthog?.capture("user_logged_out");
posthog?.reset(); // Unlink future events from this user

完整的身份识别 Hook 和登出处理程序请参阅 examples/core.md。

---

模式 3：服务端追踪

使用 posthog-node 从后端可靠地追踪业务事件。

// Serverless: use captureImmediate (guarantees HTTP completion)
await posthogServer.captureImmediate({
  distinctId: user.id,
  event: "subscription_created",
  properties: { plan: "pro", is_annual: true },
});

// Always call shutdown before returning in serverless
await posthogServer.shutdown();

关键规则：

1. 始终包含 distinctId（用户的数据库 ID）
2. 无服务器环境使用 captureImmediate()（确保 HTTP 请求完成）
3. 无服务器环境中，返回前始终调用 shutdown()
4. 无服务器环境中，将 flushAt: 1 和 flushInterval: 0 设为配置项

完整的服务端设置和路由示例请参阅 examples/server-tracking.md。

---

模式 4：群组分析（B2B）

使用 PostHog 群组将事件与组织关联，以进行 B2B 指标分析。

// Client-side: identify organization
posthog.group("company", org.id, {
  name: org.name,
  plan: org.plan ?? "free",
  member_count: org.memberCount,
});

// Server-side: include groups in event
posthogServer.capture({
  distinctId: user.id,
  event: "organization:member_invited",
  properties: { role: data.role },
  groups: { company: data.organizationId },
});

限制： 每个项目最多支持 5 种群组类型。每个事件中，每种类型只能关联一个群组。

完整的群组模式请参阅 examples/group-analytics.md。

---

模式 5：隐私和 GDPR 同意

PostHog 支持无 Cookie 追踪和同意管理。

// Cookieless mode: "always" (no consent needed) or "on_reject" (with banner)
posthog.init(POSTHOG_KEY, {
  cookieless_mode: "on_reject",
  person_profiles: "identified_only",
});

// Consent methods
posthog.opt_in_capturing(); // User accepts
posthog.opt_out_capturing(); // User rejects

关键规则： 切勿在事件属性中存储 PII（电子邮件、姓名、电话、IP、地址）。只能使用假名化 ID。

有关同意横幅集成和 before_send 过滤的内容，请参阅 examples/privacy-gdpr.md。

---

性能优化

Web 应用（默认批处理）： 使用默认设置即可——PostHog 开箱即用，能高效地批处理事件。

无服务器环境（立即发送）：

const posthogServer = new PostHog(POSTHOG_KEY, {
  flushAt: 1, // Flush after 1 event
  flushInterval: 0, // No interval batching
});
// Use captureImmediate() or capture() + await shutdown()

降低成本：

posthog.init(POSTHOG_KEY, {
  person_profiles: "identified_only", // Anonymous events 4x cheaper
  autocapture: false, // Disable for high-traffic sites
});

---

<red_flags>

严重问题

高优先级问题：

• 使用电子邮件作为 distinct_id——PII 不应作为标识符
• 用户登出时未调用 posthog.reset()——不同用户的数据会混在一起
• 无服务器环境中未调用 await shutdown()——事件会丢失
• 事件属性中包含 PII——存在违反 GDPR 的风险
• 每次渲染时都调用 identify()——会降低性能

常见错误：

• 在 React 中直接导入 posthog，而不是使用 usePostHog Hook
• 未设置反向代理（api_host: "/ingest"）——事件会被广告拦截器阻止
• 前端和后端对同一操作使用不同的事件名称
• 未使用 person_profiles: "identified_only"——匿名事件的成本会高出 4 倍
• 在无服务器环境中使用 capture()，而不是 captureImmediate()——事件可能无法完成发送

注意事项和边缘情况：

• 所有服务端事件都必须提供 distinct_id（与会自动生成 ID 的客户端不同）
• 每个事件调用 group() 时都必须包含群组 ID（不会像 identify() 那样持久保存）
• 每个项目最多支持 5 种群组类型
• cookieless_mode: "always" 会完全禁用 identify()——这是隐私与功能之间的取舍
• PostHog Web SDK 仅适用于客户端——无法在服务端组件中运行
• 必须手动将会话 ID 传递给服务端事件，才能关联会话

</red_flags>

---

<critical_reminders>

重要提醒

所有代码都必须遵循 CLAUDE.md 中的项目规范（kebab-case、命名导出、导入顺序、import type、命名常量）

（你必须仅在用户注册或登录时调用 posthog.identify()——绝不能在每次页面加载时调用）

（你必须在所有服务端事件中将用户的数据库 ID 作为 distinct_id）

（用户退出登录时，你必须调用 posthog.reset()，以解除与后续事件的关联）

（所有自定义事件都必须遵循 category:object_action 命名规范）

（绝不能在事件属性中包含个人身份信息（PII），例如电子邮件、姓名、电话号码——只能使用用户 ID）

不遵循这些规则将导致分析数据质量问题、隐私违规或事件丢失。

</critical_reminders>