vf_react/docs/POSTHOG_INTEGRATION.md

# PostHog 集成完成总结

## ✅ 已完成的工作

### 1. 安装依赖
```bash
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`：
```jsx
<PostHogProvider>
  <ReduxProvider store={store}>
    <ChakraProvider theme={theme}>
      {/* 其他 Providers */}
    </ChakraProvider>
  </ReduxProvider>
</PostHogProvider>
```

### 4. 环境变量配置

`.env` 文件中添加了：
```bash
# 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](https://app.posthog.com)
2. 创建项目（或使用现有项目）
3. 在项目设置中找到 **API Key**
4. 复制 API Key 并填入 `.env` 文件：
   ```bash
   REACT_APP_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   ```

### 2. 自动追踪页面浏览

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

### 3. 追踪自定义事件

在任意组件中使用 `usePostHog` Hook：

```jsx
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` 中，登录成功后调用：

```jsx
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` 中，登出时调用：

```jsx
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 测试）
```jsx
const { getFlag, isEnabled } = usePostHog();

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

---

## 🔒 隐私和安全

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

### 用户隐私控制
用户可选择退出追踪：
```jsx
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 官方文档](https://posthog.com/docs)
- [PostHog React 集成](https://posthog.com/docs/libraries/react)
- [PostHog Feature Flags](https://posthog.com/docs/feature-flags)
- [PostHog Session Recording](https://posthog.com/docs/session-replay)

---

## ⚠️ 注意事项

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

---

**集成完成！** 🎉

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

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