vf_react/docs/POSTHOG_INTEGRATION.md

PostHog 集成完成总结

✅ 已完成的工作

1. 安装依赖

npm install posthog-js@^1.280.1

2. 创建核心文件

📦 PostHog SDK 封装 (src/lib/posthog.js)

• 提供完整的 PostHog API 封装
• 包含函数：
  • initPostHog() - 初始化 SDK
  • identifyUser() - 识别用户
  • trackEvent() - 追踪自定义事件
  • trackPageView() - 追踪页面浏览
  • resetUser() - 重置用户会话（登出时调用）
  • optIn() / optOut() - 用户隐私控制
  • getFeatureFlag() - 获取 Feature Flag（A/B 测试）

📊 事件常量定义 (src/lib/constants.js)

基于 AARRR 框架的完整事件体系：

• Acquisition（获客）: Landing Page, CTA, Pricing
• Activation（激活）: Login, Signup, WeChat QR
• Retention（留存）: Dashboard, News, Concept, Stock, Company
• Referral（推荐）: Share, Invite
• Revenue（收入）: Payment, Subscription

🪝 React Hooks

• usePostHog (src/hooks/usePostHog.js) - 在组件中使用 PostHog
• usePageTracking (src/hooks/usePageTracking.js) - 自动页面浏览追踪

🎁 Provider 组件 (src/components/PostHogProvider.js)

• 全局初始化 PostHog
• 自动追踪页面浏览
• 根据路由自动识别页面类型

3. 集成到应用

App.js 修改

在最外层添加了 PostHogProvider：

<PostHogProvider>
  <ReduxProvider store={store}>
    <ChakraProvider theme={theme}>
      {/* 其他 Providers */}
    </ChakraProvider>
  </ReduxProvider>
</PostHogProvider>

4. 环境变量配置

.env 文件中添加了：

# PostHog API Key（需要填写你的 PostHog 项目 Key）
REACT_APP_POSTHOG_KEY=

# PostHog API Host
REACT_APP_POSTHOG_HOST=https://app.posthog.com

# Session Recording 开关
REACT_APP_ENABLE_SESSION_RECORDING=false

---

🎯 如何使用

1. 配置 PostHog API Key

1. 登录 PostHog
2. 创建项目（或使用现有项目）
3. 在项目设置中找到 API Key
4. 复制 API Key 并填入 .env 文件：

   REACT_APP_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   

2. 自动追踪页面浏览

✅ 无需额外配置，PostHogProvider 会自动追踪所有路由变化和页面浏览。

3. 追踪自定义事件

在任意组件中使用 usePostHog Hook：

import { usePostHog } from 'hooks/usePostHog';
import { RETENTION_EVENTS } from 'lib/constants';

function MyComponent() {
  const { track } = usePostHog();

  const handleClick = () => {
    track(RETENTION_EVENTS.NEWS_ARTICLE_CLICKED, {
      article_id: '12345',
      article_title: '市场分析报告',
      source: 'community_page',
    });
  };

  return <button onClick={handleClick}>阅读文章</button>;
}

4. 用户识别（登录时）

在 AuthContext 中，登录成功后调用：

import { identifyUser } from 'lib/posthog';

// 登录成功后
identifyUser(user.id, {
  email: user.email,
  username: user.username,
  subscription_tier: user.subscription_type || 'free',
  registration_date: user.created_at,
});

5. 重置用户会话（登出时）

在 AuthContext 中，登出时调用：

import { resetUser } from 'lib/posthog';

// 登出时
resetUser();

---

📊 PostHog 功能

1. 页面浏览分析

• 自动追踪所有页面访问
• 分析用户访问路径
• 识别热门页面

2. 用户行为分析

• 追踪用户点击、搜索、筛选等行为
• 分析功能使用频率
• 了解用户偏好

3. 漏斗分析

• 分析用户转化路径
• 识别流失点
• 优化用户体验

4. 队列分析（Cohort Analysis）

• 按注册时间、订阅类型等分组用户
• 分析不同用户群体的行为差异

5. Session Recording（可选）

• 录制用户操作视频
• 可视化用户体验问题
• 需要在 .env 中开启：REACT_APP_ENABLE_SESSION_RECORDING=true

6. Feature Flags（A/B 测试）

const { getFlag, isEnabled } = usePostHog();

// 检查功能开关
if (isEnabled('new_dashboard_design')) {
  return <NewDashboard />;
} else {
  return <OldDashboard />;
}

---

🔒 隐私和安全

自动隐私保护

• 自动屏蔽密码、邮箱、手机号输入框
• 不追踪敏感 API 端点（/api/auth/login, /api/payment 等）
• 尊重浏览器 Do Not Track 设置

用户隐私控制

用户可选择退出追踪：

const { optOut, optIn, isOptedOut } = usePostHog();

// 退出追踪
optOut();

// 重新加入
optIn();

// 检查状态
if (isOptedOut()) {
  console.log('用户已退出追踪');
}

---

🚀 下一步建议

1. 在关键页面添加事件追踪

例如在 Community、Concept、Stock 等页面添加：

• 搜索事件
• 点击事件
• 筛选事件

2. 在 AuthContext 中集成用户识别

登录成功时调用 identifyUser()，登出时调用 resetUser()

3. 设置 Feature Flags

在 PostHog 后台创建 Feature Flags，用于 A/B 测试新功能

4. 配置 Dashboard 和 Insights

在 PostHog 后台创建：

• 用户活跃度 Dashboard
• 功能使用频率 Insights
• 转化漏斗分析

---

📚 参考资料

• PostHog 官方文档
• PostHog React 集成
• PostHog Feature Flags
• PostHog Session Recording

---

⚠️ 注意事项

1. 开发环境下会自动启用调试模式，控制台会输出详细的追踪日志
2. PostHog API Key 为空时，SDK 会发出警告但不会影响应用运行
3. Session Recording 默认关闭，需要时再开启以节省资源
4. 所有事件常量已定义在 src/lib/constants.js，使用时直接导入

---

集成完成！ 🎉

现在你可以：

1. 填写 PostHog API Key
2. 启动应用：npm start
3. 在 PostHog 后台查看实时数据

如有问题，请参考 PostHog 官方文档或联系技术支持。