PostHog、Mixpanel & Amplitude 桥接

1. 问题所在：只有数字，看不到人

产品分析为您提供一个漏斗：1,000 名用户到达结账环节，620 名放弃。测量虽精确，问题却仍不可见。通常只需观看这 620 个录制中的几个，就能在几分钟内找到答案 — 前提是能从图表找到正确会话，无需导出 ID 并手动搜索。

此 产品分析桥接 消除了这道鸿沟。它在以下组件内运行： mp.js ，并自动连接两个系统：

• 出站： 分析工具记录的每个事件都携带 mouseplayer_session_url 属性。打开任意事件，点击链接，即可观看会话。
• 入站： 访客的 distinct_id 会被读回并存储在 MousePlayer 会话上，因而可使用 PostHog、Mixpanel 或 Amplitude 中已有的同一身份标识搜索录制。

2. 启用

方法 A：仪表板（无代码）

1. 打开项目，转到 集成 标签页。
2. 将 PostHog、Mixpanel & Amplitude 桥接 切换为 ON。
3. 选择使用的平台。更改会自动保存。

设置在网站下次加载页面时生效，不会追溯影响已有会话。

方法 B：手动配置脚本

如需硬编码，请在 window.mp_config中设置以下两个值：

3. 各平台的处理方式

每个平台提供不同的 API，因此桥接会映射到该平台惯用的调用方式。无需配置 — 它会根据所选提供商处理。

平台	出站（回放 URL）	入站（身份标识）
PostHog	posthog.register() — 注册为超级属性，因而附加到此后的每个事件	posthog.get_distinct_id()
Mixpanel	mixpanel.register() — 同样采用超级属性行为	mixpanel.get_distinct_id()
Amplitude	setUserProperties() — 设置为用户属性	getDeviceId()，在旧版 SDK 中回退至 getInstance().options.deviceId （旧版 SDK）

4. 身份标识：从 distinct_id 到具名会话

入站部分最容易被团队低估。没有它，MousePlayer 会话就是匿名的：可以观看，却无法回答 “请显示上周流失账户的录制。”

启用桥接后，分析工具中的 distinct_id 会写入会话的 custom_user_id 字段 — 手动 SDK 调用写入的也是同一个字段：

如果已经自行调用 mp('set') ，请继续。显式提供的身份标识更可靠，因为它是您自己的主键，而非按浏览器生成的分析标识。

5. 技术行为

分析 SDK 通常异步加载，往往晚于 mp.js 开始运行。因此，仅在启动时尝试一次，在多数真实网站上都会失败。

• 桥接每隔 1.5 秒重试一次，最多十次，双向处理一旦全部完成便停止。
• 两个方向各自独立完成，因此等待身份标识出现时，不会重复发送回放 URL。
• 若 SDK 始终未出现，桥接会在约 15 秒后静默放弃。不向控制台写入任何内容，会话录制不受影响地继续。
• 超过 128 个字符的标识符会被忽略，而非截断，以免存储永远无法匹配的半截标识符。

6. 验证是否生效

1. 在普通浏览器标签页打开网站，进行简短交互。
2. 在分析工具中打开最新事件，查找 mouseplayer_session_url 属性。打开它应直接进入录制。
3. 在 MousePlayer 中打开 用户探索器。带有身份标识的会话会显示该标识，替代自动生成的访客昵称。

没有显示任何内容时

• 所有事件都缺少此属性： 检查页面是否实际加载分析 SDK，以及是否选择了匹配的平台。选择 PostHog 不会读取 Mixpanel。
• 属性仅出现在后续事件中： 这是预期行为，参见第 3 节的说明。
• 有 URL，但没有身份标识： SDK 尚未分配 distinct_id ，这在用户尚未被识别时属正常情况。它会在后续页面加载时被获取。
• 正以已登录管理员身份测试： 某些设置会排除内部流量。请尝试隐私窗口。