公共 API & API 密钥

1. 概览

MousePlayer API 可将工作区数据获取到自有仪表板、数据仓库或内部工具。除为会话附加客户 ID（identify，需要写入范围的密钥，见“密钥范围”）外，它是 只读的：无法通过 API 修改或删除数据。

• 基础 URL： https://www.mouseplayer.com/api/v1/
• 所有响应均为 JSON。
• 每个请求均通过 API 密钥认证，并自动限定为该密钥所属工作区 — 某个工作区的密钥绝不可能看到其他工作区的数据，即使误操作也不会。
• 完整会话回放录制（鼠标移动、DOM 快照） 不会 通过 API 提供。可获取会话元数据、页面浏览、自定义事件与细分 — 足以构建报告和仪表板，无需传送原始回放载荷。

2. 认证

在账户菜单中的 API 密钥 （/api-keys）下创建和管理密钥。仅工作区所有者与管理员可以创建或撤销密钥。

每个请求都应在 Authorization 请求头中以 Bearer 令牌发送密钥：

缺失、格式错误或已撤销的密钥将收到 401 响应：

套餐要求

REST API 属于 Business 和 Enterprise 套餐。套餐以工作区 所有者 为准，因此受邀团队成员继承该套餐。检查会在 每个请求执行，而非仅在创建密钥时执行 — 工作区降级后，现有密钥停止工作并返回 403。

密钥范围

每个密钥的前缀都携带范围，因此只需看一眼，就能在 .env、工单或终端中判断其能力。

3. 速率限制

每个 API 密钥限制为 每分钟 60 个请求，采用滚动窗口计数。超限后，请求会收到 429 响应，直到窗口释放：

4. 端点

GET/api/v1/projects

列出工作区内全部项目（已跟踪媒体资源）。

GET/api/v1/projects/{channelid}/sessions

列出项目中录制的访客会话，最新优先，支持分页。

GET/api/v1/sessions/{session_id}

单次会话的元数据及其页面浏览。刻意不包含完整回放载荷 — 请使用仪表板的播放器查看。

GET/api/v1/sessions/{session_id}/events

会话期间触发的自定义事件（即通过 mp('event', ...)发送的同一批事件），包含其参数。

GET/api/v1/projects/{channelid}/segments

列出为项目定义的访客细分（包括项目专属与工作区范围的细分）。

5. 从后端附加客户 ID

浏览器往往不知道使用者是谁。B2B 产品的身份在登录后于后端确定 — 商店则在订单确认时确定。此端点正是为那一刻准备的。

POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json

{"user_id": "customer-4711"}

// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
          "changed": true, "previous": null, "webhook_queued": true}}

ID 随后显示在会话列表中且可搜索，同时触发 session_identified Webhook — 从而传入 CRM。

6. Webhook：验证签名

Webhook 按项目在 集成下配置，签名密钥也在其中。每次投递都携带以下请求头：

签名是针对 timestamp + "." + raw body计算的 HMAC-SHA256，以项目签名密钥为键。

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; }

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
                                     .update(timestamp + '.' + rawBody).digest('hex');

投递与重试

投递失败后，将在 1 分钟、5 分钟、15 分钟、1 小时和 6 小时后重试，随后放弃。 4xx 响应中，除 408 和 429 以外的均 不会 重试 — 它们表示 "不能这样请求"，而非 "暂时不能请求"。请快速返回 2xx ，再处理工作；投递会在 10 秒后超时。

可用事件

7. 错误 & 状态码

8. 安全说明

• 只读密钥（mp_ro_）不能更改任何内容。写入密钥（mp_rw_）只能附加客户 ID；任何密钥都无法删除数据或导出原始回放数据。
• 每个请求自动限定在密钥所属工作区 — 无法传入其他工作区 ID 查看他人数据。
• 可随时在 /api-keys撤销密钥，立即生效。
• 将 API 密钥视作密码。如果意外提交到公共仓库，请立即撤销并新建。