vf_react/docs/POSTHOG_REDUX_INTEGRATION.md

PostHog Redux 集成完成总结

✅ 已完成的工作

PostHog 已成功从 React Context 迁移到 Redux 进行全局状态管理！

1. 创建的核心文件

📦 Redux Slice (src/store/slices/posthogSlice.js)

完整的 PostHog 状态管理：

• State 管理: 初始化状态、用户信息、事件队列、Feature Flags
• Async Thunks:
  • initializePostHog() - 初始化 SDK
  • identifyUser() - 识别用户
  • resetUser() - 重置会话
  • trackEvent() - 追踪事件
  • flushCachedEvents() - 刷新离线事件
• Selectors: 提供便捷的状态选择器

⚡ Redux Middleware (src/store/middleware/posthogMiddleware.js)

自动追踪中间件：

• 自动拦截 Actions: 当特定 Redux actions 被 dispatch 时自动追踪
• 路由追踪: 自动识别页面类型并追踪浏览
• 离线事件缓存: 网络恢复时自动刷新缓存事件
• 性能追踪: 追踪耗时较长的操作

自动追踪的 Actions:

'auth/login/fulfilled' → USER_LOGGED_IN
'auth/logout' → USER_LOGGED_OUT
'communityData/fetchHotEvents/fulfilled' → NEWS_LIST_VIEWED
'payment/success' → PAYMENT_SUCCESSFUL
// ... 更多

🪝 React Hooks (src/hooks/usePostHogRedux.js)

提供便捷的 API：

• usePostHogRedux() - 完整功能 Hook
• usePostHogTrack() - 仅追踪功能（性能优化）
• usePostHogFlags() - 仅 Feature Flags（性能优化）
• usePostHogUser() - 仅用户管理（性能优化）

2. 修改的文件

Redux Store (src/store/index.js)

import posthogReducer from './slices/posthogSlice';
import posthogMiddleware from './middleware/posthogMiddleware';

export const store = configureStore({
  reducer: {
    communityData: communityDataReducer,
    posthog: posthogReducer, // ✅ 新增
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware({...})
      .concat(posthogMiddleware), // ✅ 新增
});

App.js

• ❌ 移除了 <PostHogProvider> 包装
• ✅ 在 AppContent 中添加 Redux 初始化：

useEffect(() => {
  dispatch(initializePostHog());
}, [dispatch]);

3. 保留的文件（仍然需要）

• ✅ src/lib/posthog.js - PostHog SDK 封装
• ✅ src/lib/constants.js - 事件常量（AARRR 框架）
• ✅ src/hooks/usePostHog.js - 原 Hook（可选保留，兼容旧代码）

4. 可以删除的文件（不再需要）

• ❌ src/components/PostHogProvider.js - 改用 Redux 管理
• ❌ src/hooks/usePageTracking.js - 改由 Middleware 处理

---

🎯 Redux 方案的优势

1. 集中式状态管理

PostHog 状态与其他应用状态统一管理，便于维护和调试。

2. 自动追踪

通过 Middleware 自动拦截 Redux actions，无需手动调用追踪。

// 旧方案（手动追踪）
const handleLogin = () => {
  // ... 登录逻辑
  track(ACTIVATION_EVENTS.USER_LOGGED_IN, { ... });
};

// 新方案（自动追踪）
const handleLogin = () => {
  dispatch(loginUser({ ... })); // ✅ Middleware 自动追踪
};

3. Redux DevTools 集成

可以在 Redux DevTools 中查看所有 PostHog 事件：

Action: posthog/trackEvent/fulfilled
Payload: {
  eventName: "News Article Clicked",
  properties: { article_id: "123" }
}

4. 离线事件缓存

自动缓存离线时的事件，网络恢复后批量发送。

5. 时间旅行调试

可以回放和调试用户行为，定位问题更容易。

---

📚 使用指南

1. 基础用法 - 追踪自定义事件

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

function NewsArticle({ article }) {
  const { track } = usePostHogRedux();

  const handleClick = () => {
    track(RETENTION_EVENTS.NEWS_ARTICLE_CLICKED, {
      article_id: article.id,
      article_title: article.title,
      source: 'community_page',
    });
  };

  return <div onClick={handleClick}>{article.title}</div>;
}

2. 用户识别（登录时）

在 AuthContext 或登录成功回调中：

import { usePostHogRedux } from 'hooks/usePostHogRedux';

function AuthContext() {
  const { identify, reset } = usePostHogRedux();

  const handleLoginSuccess = (user) => {
    // 识别用户
    identify(user.id, {
      email: user.email,
      username: user.username,
      subscription_tier: user.subscription_type || 'free',
      registration_date: user.created_at,
    });
  };

  const handleLogout = () => {
    // 重置用户会话
    reset();
  };

  return { handleLoginSuccess, handleLogout };
}

3. Feature Flags（A/B 测试）

import { usePostHogFlags } from 'hooks/usePostHogRedux';

function Dashboard() {
  const { isEnabled } = usePostHogFlags();

  if (isEnabled('new_dashboard_design')) {
    return <NewDashboard />;
  }

  return <OldDashboard />;
}

4. 自动追踪（推荐）

无需手动追踪，只需 dispatch Redux action，Middleware 会自动处理：

// ✅ 登录时自动追踪
dispatch(loginUser({ email, password }));
// → Middleware 自动追踪 USER_LOGGED_IN

// ✅ 获取新闻时自动追踪
dispatch(fetchHotEvents());
// → Middleware 自动追踪 NEWS_LIST_VIEWED

// ✅ 支付成功时自动追踪
dispatch(paymentSuccess({ amount, transactionId }));
// → Middleware 自动追踪 PAYMENT_SUCCESSFUL

5. 性能优化 Hook

如果只需要追踪功能，使用轻量级 Hook：

import { usePostHogTrack } from 'hooks/usePostHogRedux';

function MyComponent() {
  const { track } = usePostHogTrack(); // ✅ 只订阅追踪功能

  // 不会因为 PostHog 状态变化而重新渲染
  return <button onClick={() => track('Button Clicked')}>Click</button>;
}

---

🔧 配置自动追踪规则

在 src/store/middleware/posthogMiddleware.js 中添加新规则：

const ACTION_TO_EVENT_MAP = {
  // 添加你的 action
  'myFeature/actionName': {
    event: RETENTION_EVENTS.MY_EVENT,
    getProperties: (action) => ({
      property1: action.payload?.value1,
      property2: action.payload?.value2,
    }),
  },
};

---

🧪 调试技巧

1. Redux DevTools

打开 Redux DevTools，筛选 posthog/ actions：

posthog/initializePostHog/fulfilled
posthog/identifyUser/fulfilled
posthog/trackEvent/fulfilled

2. 查看 PostHog 状态

import { useSelector } from 'react-redux';
import { selectPostHog } from 'store/slices/posthogSlice';

function DebugPanel() {
  const posthog = useSelector(selectPostHog);

  return (
    <pre>{JSON.stringify(posthog, null, 2)}</pre>
  );
}

3. 控制台日志

开发环境下会自动输出日志：

[PostHog Middleware] 自动追踪事件: User Logged In { user_id: 123 }
[PostHog] 📍 Event tracked: News Article Clicked

---

📊 State 结构

{
  posthog: {
    // 初始化状态
    isInitialized: true,
    initError: null,

    // 用户信息
    user: {
      userId: "123",
      email: "user@example.com",
      subscription_tier: "pro"
    },

    // 事件队列（离线缓存）
    eventQueue: [
      { eventName: "...", properties: {...}, timestamp: "..." }
    ],

    // Feature Flags
    featureFlags: {
      new_dashboard_design: true,
      beta_feature: false
    },

    // 配置
    config: {
      apiKey: "phc_...",
      apiHost: "https://app.posthog.com",
      sessionRecording: false
    },

    // 统计
    stats: {
      totalEvents: 150,
      lastEventTime: "2025-10-28T12:00:00Z"
    }
  }
}

---

🚀 高级功能

1. 手动触发页面浏览

import { trackModalView, trackTabChange } from 'store/middleware/posthogMiddleware';

// Modal 打开时
dispatch(trackModalView('User Settings Modal', { source: 'nav_bar' }));

// Tab 切换时
dispatch(trackTabChange('Related Stocks', { from_tab: 'Overview' }));

2. 刷新离线事件

import { flushCachedEvents } from 'store/slices/posthogSlice';

// 网络恢复时自动触发，也可以手动触发
dispatch(flushCachedEvents());

3. 性能追踪

给 action 添加时间戳：

import { withTiming } from 'store/middleware/posthogMiddleware';

// 追踪耗时操作
dispatch(withTiming(fetchBigData()));
// → 如果超过 1 秒，会自动追踪性能事件

---

⚠️ 注意事项

1. 环境变量

确保 .env 文件中配置了 PostHog API Key：

REACT_APP_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
REACT_APP_POSTHOG_HOST=https://app.posthog.com
REACT_APP_ENABLE_SESSION_RECORDING=false

2. Redux Middleware 顺序

PostHog Middleware 应该在其他 middleware 之后：

.concat(otherMiddleware)
.concat(posthogMiddleware) // ✅ 最后添加

3. 避免循环依赖

不要在 Middleware 中 dispatch 会触发 Middleware 的 action。

4. 序列化检查

已经在 store 配置中忽略了 PostHog actions 的序列化检查。

---

🔄 从旧版本迁移

如果你的代码中使用了旧的 usePostHog Hook：

// 旧代码
import { usePostHog } from 'hooks/usePostHog';
const { track } = usePostHog();

// 新代码（推荐）
import { usePostHogRedux } from 'hooks/usePostHogRedux';
const { track } = usePostHogRedux();

兼容性: 旧的 usePostHog Hook 仍然可用，但推荐迁移到 Redux 版本。

---

📚 参考资料

• PostHog 官方文档
• Redux Toolkit 文档
• Redux Middleware 文档
• AARRR 框架

---

🎉 总结

PostHog 已成功集成到 Redux！主要优势：

1. ✅ 自动追踪: Middleware 自动拦截 actions
2. ✅ 集中管理: 统一的 Redux 状态管理
3. ✅ 调试友好: Redux DevTools 支持
4. ✅ 离线支持: 自动缓存和刷新事件
5. ✅ 性能优化: 提供多个轻量级 Hooks

现在你可以：

1. 启动应用：npm start
2. 打开 Redux DevTools 查看 PostHog 状态
3. 执行操作（登录、浏览页面、点击按钮）
4. 观察自动追踪的事件

Have fun tracking! 🚀