Web SDK 接入

BugCapturer Web SDK 通过一个 <script> 标签即可在任意网站中注入悬浮反馈组件，专为 UAT / 预发环境设计：测试人员点击悬浮球，立即截图标注，报告自动进入 BugCapturer「反馈记录」和团队飞书多维表格 —— 访客无需安装任何浏览器插件。

工作方式

• 悬浮球可拖拽 — 可拖到页面任意边缘（位置跨页记忆），点击打开反馈窗口
• 即时截图 — 窗口打开瞬间即完成截图，瞬时错误不丢失；随时可重新截图或框选裁剪
• 单步编辑器 — 标注（画笔 / 矩形 / 撤销）、填写问题描述、查看诊断明细、提交，一屏完成
• 自动诊断 — 控制台错误与失败请求（级别、状态码、方法、URL、耗时）静默采集并随报告同步
• 反馈人身份 — 在配置的 reporter 里填入登录用户（或在登录回调里调 BugCapturer.identify()），每条报告自动带上测试人员姓名 / 邮箱，协作时能快速定位到人
• 同步到多维表格 — 将项目绑定飞书多维表格集成后，SDK 报告自动派发，反馈人字段一并写入
• 样式隔离 — 组件渲染在 Shadow DOM 内，绝不与宿主站点样式冲突

第一步：创建项目

1. 登录 app.bugcapturer.com，打开「设置 → 项目」
2. 按三步向导完成创建：
   • 项目名称（如「结算 UAT」）
   • 域名白名单 — 填写允许加载组件的域名，支持精确（uat.example.com）或一级通配（*.example.com）
   • 路由与组件 — 可选绑定集成（飞书多维表格 / 通用 Webhook）、选择悬浮球默认位置、开启匿名提交时联系方式必填

每个项目会生成一个以 bcpk_ 开头的公开 SDK Key。Key 本身公开无妨 —— 真正的访问控制由域名白名单和限流承担。

第二步：嵌入代码

在项目卡片上复制接入代码，粘贴到需要展示组件的每个页面（</body> 之前）：

<script>
  window.BugCapturerConfig = {
    key: "bcpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    position: "bottom-right",
    requireContact: false,
    // 留空 = 匿名提交；记录提交人请在登录后调用 BugCapturer.identify()，
    // 不要在这里写死姓名 —— 否则所有人都会署同一个名字（见「第三步」）
    reporter: { uid: "", name: "", email: "" }
  };
</script>
<script src="https://api.bugcapturer.com/sdk/bugcapturer.js" async></script>

完成 —— 悬浮球即刻出现在你的站点上。

第三步：让报告知道”是谁提交的”（推荐）

悬浮球是一个公共组件：你贴一次，全站所有登录用户共用它。但它自己并不知道当前登录的是谁 —— BugCapturer 不会去读取你站点的 Cookie 或 localStorage 来猜测身份（这是隐私红线，也与 Capture.dev、Shakebugs 等友商一致；友商的 Web/移动 SDK 同样要求你显式调用 identify / registerUser）。

所以「当前用户是谁」必须由你的站点在页面里显式告诉 SDK。

不做这一步也能用：报告会以匿名方式提交，此时建议在项目设置里开启「匿名提交必须填写联系方式」兜底，保证每条报告都有办法联系到提交人。

⚠️ 最常见的错误：把某一个人的姓名 / 邮箱写死在接入代码里。 这样会让所有登录用户提交的报告都署同一个人的名字。正确做法是用当前登录用户动态填充。

怎么做，取决于你的网站类型

情况 A：服务端渲染的站点（后台管理系统 / PHP / JSP / Thymeleaf / 模板引擎）

你的页面本来就是服务器按「当前登录用户」渲染出来的，所以直接把用户信息写进配置块即可 —— 把下面的 ${...} 换成你实际使用的模板语法：

<script>
  window.BugCapturerConfig = {
    key: "bcpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    reporter: {
      uid:   "${user.id}",     // 你的模板变量
      name:  "${user.name}",
      email: "${user.email}"
    }
  };
</script>
<script src="https://api.bugcapturer.com/sdk/bugcapturer.js" async></script>

这段代码要放在需要显示悬浮球的页面模板里（通常就是公共布局 / 页头页脚模板）。服务器会为每个登录用户渲染出属于他自己的那一份配置，因此每个人提交的报告都带上各自的身份。

情况 B：前后端分离 / 单页应用（Vue / React / Angular）

用户信息通常不在页面 HTML 里，而是登录后由前端持有。在登录成功之后调用一次即可；如果要在「页面加载时」尽早调用（此时 SDK 可能还没加载完），用下面这个官方推荐的封装，它会自动处理时序：

function identifyReporter(user) {
  if (!user) return;
  var apply = function () {
    // 真正要记的调用只有这一行，与登录回调里的写法完全一致
    BugCapturer.identify({ uid: user.id, name: user.name, email: user.email });
  };
  if (window.BugCapturer && BugCapturer.ready) BugCapturer.ready(apply);     // SDK 已加载：等它就绪
  else window.addEventListener('bugcapturer:ready', apply, { once: true });  // 还没加载：等就绪事件
}

Vue（在路由守卫里）：

router.afterEach(() => identifyReporter(store.state.user));

React（在根组件 useEffect 里）：

useEffect(() => { identifyReporter(user); }, [user]);

几个要点：

• 登录后才调用：此时才拿得到用户信息。
• 时机交给 SDK 兜底：ready() 会「已就绪则立即执行、未就绪则排队」；bugcapturer:ready 事件连「SDK 还没开始加载」也覆盖。不要写成 if (window.BugCapturer) { ... } —— SDK 没加载好时它会静默跳过，身份就悄悄丢了。
• 切换账号后要重新调用：用户登出再登录另一个账号时，再调一次覆盖即可。
• 重复调用会覆盖：始终以最后一次调用为准。

情况 C：没有登录的站点（宣传页 / 甲方验收）

不需要做这一步。保持匿名提交，并在项目设置中开启「匿名提交必须填写联系方式」，让访客留个邮箱或 IM。

身份字段规则

字段	说明	限制
uid	你系统里的用户唯一 ID	≤ 64 字符
name	显示名 / 姓名	≤ 100 字符
email	邮箱	≤ 254 字符，服务端会校验格式

• 三个字段至少填一个才会被视为「已登录」（全空 = 匿名）。
• 超长或格式非法的字段会被自动丢弃，但不会阻断提交。
• 一旦身份生效，表单里的「联系方式」字段会自动隐藏（因为已经知道是谁了）。

如何确认身份已经生效

1. 用登录账号打开已嵌入的页面，点开悬浮球；
2. 如果窗口顶部显示「✓ 将以 xxx 的身份提交」，说明生效；显示「匿名提交」，说明没有传进来；
3. 提交后到「反馈记录」或绑定的飞书多维表格里查看该条报告，确认「反馈人 / 反馈人邮箱」列已填充。

排查提示：如果一直显示匿名—— ① 确认 identify() 是在登录之后调用的； ② 在浏览器控制台打印 window.BugCapturer，确认 SDK 已加载； ③ 确认账号确实有姓名 / 邮箱字段、不是空字符串； ④ 多维表格未配置「反馈人」列时不会报错，只是那一列不显示。

配置参考

所有配置项位于 window.BugCapturerConfig：

配置项	类型	默认值	说明
key	string	—（必填）	项目 SDK Key（bcpk_ 前缀）
api	string	https://api.bugcapturer.com	API 域名；仅自部署时需要修改
position	string	bottom-right	悬浮球初始位置：bottom-right / bottom-left / top-right / top-left
requireContact	boolean	false	匿名提交时联系方式必填（需与项目配置一致）
reporter	object	{ uid: "", name: "", email: "" }	随每条报告提交的用户身份。服务端渲染站点可用模板变量按当前用户渲染；SPA 请改用 identify()。切勿写死固定值，留空即匿名
lang	string	跟随浏览器	组件语言：zh 或 en
tipDelay	number	5	悬浮球提示气泡在页面停留多少秒后弹出；0 为加载后立即弹出
tipDuration	number	5	提示气泡显示时长（秒）
tipOnce	boolean	true	提示气泡是否每个访客只弹一次；设为 false 则每次页面加载都弹

JS API

方法	说明
BugCapturer.identify({ uid, name, email })	注入反馈人身份（登录后调用，重复调用以最后一次为准）；三个字段至少填一个，非法字段由服务端剔除
BugCapturer.ready(fn)	SDK 就绪后执行 fn（已就绪则立即执行）。页面加载即需注入身份时用它避开时序问题
window 事件 bugcapturer:ready	与 ready() 等价的信号；脚本可能先于 SDK 执行时，用 window.addEventListener('bugcapturer:ready', fn) 更稳妥
BugCapturer.open()	手动打开反馈窗口
BugCapturer.close()	手动关闭反馈窗口

按 Esc 键始终可以关闭窗口。

安全与限制

• 域名白名单 — 请求 Origin / Referer 不在项目白名单内一律拒绝；组件端同样会在未授权页面拒绝提交
• 双维限流 — 每项目 30 条 / 天、每 IP 10 条 / 天；达到上限时组件会给出友好提示
• 截图格式 — 仅 PNG，10 MB 以内；URL 中的敏感参数值（如 token）入库前自动脱敏

常见问题

组件会拖慢我的网站吗？

脚本体积极小且以 async 加载，渲染在 Shadow DOM 内。诊断采集完全被动（错误监听器）—— 不轮询、不发包，直到用户提交报告。

访客没装 Chrome 插件也能用吗？

可以 —— 这正是 SDK 的意义。若访客恰好装有 BugCapturer 插件，SDK 会委托插件完成像素级截图；否则自动回退到页面内截图。

修改域名白名单后需要重新嵌入吗？

不需要。白名单、路由和组件配置即时生效，接入代码永远不变。

SDK 报告在哪里查看？

在「反馈记录」（带 SDK 标签，可按项目筛选）以及项目绑定的任意集成中查看。报告按项目所有者口径保留 90 天。

SDK Key 需要保密吗？

不需要。它只用于标识项目；安全性由域名白名单与限流保障。如需轮换，删除并重建项目即可。

为什么 SDK 不能自动识别登录用户？

因为 SDK 运行在访客的浏览器里，而你站点的登录信息在你自己的服务器 / 前端状态里，两者并没有标准约定。BugCapturer 也不会去读取你站点的 Cookie 或 localStorage 来”猜”身份——这既是隐私红线，也能让你的站点在安全评审时更放心。身份由你显式传入，是最稳妥、最可控的做法（Capture.dev、Shakebugs、Sentry 等同类工具都是这个模式）。

我可以在接入代码里把我的名字填进 reporter 吗？

不要。那会让所有登录用户提交的报告都署同一个人的名字。正确做法见上面的「第三步」：服务端渲染站点用模板变量按当前用户渲染 reporter；SPA 在登录后调用 BugCapturer.identify()。

SPA 应该在什么时机调用 identify()？

在登录成功之后，以及每次页面（重新）加载、用户信息就绪时；切换账号后再调一次覆盖即可。如果调用时机可能早于 SDK 加载完成，请用 BugCapturer.ready(fn) 或 bugcapturer:ready 事件包一层（见「第三步 · 情况 B」的 identifyReporter 封装）。不要只用 if (window.BugCapturer) 判断——SDK 没加载好时它会静默跳过，身份不会生效。

只填 name 不填 email 可以吗？

可以。uid / name / email 三个字段至少填一个即视为已登录，缺失的字段会留空。填 email 时表单的「联系方式」字段会自动隐藏。

身份一直显示为匿名，怎么排查？

① 确认 identify() 是在登录之后调用的；② 在控制台执行 window.BugCapturer 确认 SDK 已加载；③ 确认传入的字段不是空字符串；④ 到绑定的飞书多维表格确认是否配置了「反馈人 / 反馈人邮箱」列（未配置不会报错，只是不显示）。