故障排查

检查挂件脚本、CID、网络请求、配置和 JavaScript API

修改业务代码前，先使用浏览器开发者工具检查实际安装结果。

没有出现聊天气泡

1. 确认页面只包含一个安装标签，并且 cid 不是空值：

   <script src="https://cdn.bubblo.ai/widget.js" cid="YOUR_CHANNEL_ID"></script>

2. 在 Network 中确认 https://cdn.bubblo.ai/widget.js 加载成功。

3. 在 Console 中检查宿主 API 是否存在：

   typeof window.Bubblo?.open === "function"

4. 在 Elements 中查找 #bubblo-widget-host。脚本执行后会创建这个元素。

5. 将 cid 与同一组织 集成 → Widget 安装代码下方的 Widget CID 逐字比较。

6. 在 Network 中检查 GET https://chat.bubblo.ai/v1/chat/{cid}/config。可用的配置响应应为 HTTP 成功状态，并且 JSON code 为 200。

如果 widget.js 或聊天请求被拦截，请在 Console 中检查是否有指向 cdn.bubblo.ai 或 chat.bubblo.ai 的 Content Security Policy 错误。

面板能打开，但消息不能正常发送

在 Console 中执行 window.Bubblo.open()，然后查看 Network：

• 指向 /v1/chat/{cid}/visitor/event 的 EventSource 请求应保持连接。
• 发送消息时应产生指向 /v1/chat/{cid}/visitor/message 的 POST 请求，并返回 HTTP 成功状态。

哪一个请求报错，就从该请求的响应和对应浏览器控制台错误继续定位。

外观修改没有立即生效

已安装的挂件会在挂载时获取配置，配置响应最长可能缓存 60 秒。

1. 确认已经在 集成 → Widget 外观表单底部点击保存更改。
2. 等待最多 60 秒。
3. 刷新已安装页面，让挂件重新挂载并获取配置。

可以对照自定义聊天挂件确认目前支持的配置项。

window.Bubblo 是 undefined

window.Bubblo 会在 widget.js 执行时创建，请先检查 CDN 请求。脚本执行后、可视挂件完成挂载前发出的调用，会由挂载前队列处理。

没有收到身份 metadata

调用 identify() 后，在浏览器中检查：

JSON.parse(localStorage.getItem("bubblo_visitor_identity"))

然后发送一条新的访客消息，检查其 /visitor/message 请求体。身份字段只会附加到之后发送的消息，不会追溯写入之前的消息。