@page-wright/recorder

Pagewright 浏览器 SDK，基于 [email protected] 录制用户会话并上报到 Pagewright 后端。

安装

pnpm add @page-wright/recorder

也可以直接通过 IIFE 构建物引入（见 dist/index.global.js）。

基本用法

import { start } from "@page-wright/recorder";

const handle = start({
  sessionId: "自生成或业务侧指定", // 可缺省，SDK 会 nanoid
  endpoint: "https://your-app.example.com/api/events",
  metadata: {
    appVersion: process.env.APP_VERSION,
    userId: currentUser.id,
  },
  // 可选：抽样、脱敏等
  sampling: { mousemove: 50 },
  maskAllInputs: true,
});

// 用户结束时显式停止
window.addEventListener("pagehide", () => handle.stop());

SDK 会：

1. 以批量方式 fetch(endpoint, { method: "POST" }) 上传 rrweb 事件。
2. 在页面关闭时回退 navigator.sendBeacon，保证最后一批事件不会丢。
3. 对表单输入、点击、keypress 事件附加自定义 semantic 事件，携带 primarySelector / backupSelectors / semantic.description，降低服务端降噪成本。

数据契约

上报的 body 为 EventBatch（见 @pagewright/schemas），核心字段：

interface EventBatch {
  sessionId: string;
  seq: number;           // 批次序号，服务端据此去重
  sentAt: number;        // 客户端毫秒时间戳
  events: RawRrwebEvent[];
  metadata?: Record<string, unknown>;
}

与后端交互

后端实现参考 apps/web/src/app/api/events/route.ts：

• POST /api/events：接收事件，同时支持 application/json 与 text/plain（sendBeacon 场景）。
• PATCH /api/events?sessionId=...：触发降噪 + LLM 转换。

注意事项

• 当前仅在 Chromium（Playwright 默认驱动）上做过端到端验证；Safari/WebKit 的 sendBeacon 兼容性请自行评估。
• maskAllInputs 默认关闭，生产环境请显式打开并配合 maskTextSelector / blockSelector 控制敏感数据。
• 若业务方希望离线缓存，可在 onQueueDrop 回调里接入自己的 IndexedDB/LocalStorage 兜底。