JavaScript API

从宿主网页打开、关闭挂件，并为访客附加身份信息

安装挂件脚本后，宿主页面会获得 window.Bubblo。

方法

`open()`

打开聊天面板。挂件会在第一次打开时建立聊天连接。

window.Bubblo.open()

`close()`

隐藏聊天面板。关闭面板不会清除访客 ID、身份 metadata 或现有对话。

window.Bubblo.close()

`identify(payload)`

为之后发送的访客消息附加由业务系统提供的可选身份字段：

window.Bubblo.identify({
  userId: "u_123",
  email: "ada@acme.com",
  name: "Ada",
})

三个字段都是可选的。userId 在消息 metadata 中会以 user_id 发送。身份数据保存在访客浏览器中，刷新后仍然可用。

不传参数调用 identify()，会清除之前保存的身份字段，影响之后发送的消息：

window.Bubblo.identify()

在挂载完成前调用

脚本会先安装 window.Bubblo，然后再完成可视挂件的挂载。在这段间隔内发出的命令会进入队列，并在挂件准备好后按原顺序执行。因此，可以紧跟安装标签调用：

<script src="https://cdn.bubblo.ai/widget.js" cid="YOUR_CHANNEL_ID"></script>
<script>
  window.Bubblo.identify({ userId: "u_123" })
  window.Bubblo.open()
</script>

队列只能在 widget.js 已执行后工作。如果 window.Bubblo 是 undefined，说明脚本尚未加载完成或被浏览器拦截。

Metadata 与隐私

挂件会生成一个随机访客 ID，并保存在访客浏览器的 localStorage 中，让同一浏览器刷新后可以恢复会话。通过 identify() 设置的身份字段也会单独保存在该浏览器中。

每条访客消息都会自动附带以下页面上下文 metadata：

location.href 提供的完整页面 URL
页面标题
Referrer
浏览器语言

通过 identify() 提供的 user_id、email 和 name 会加入同一份 metadata，并随访客消息持久化。

上线前请检查网站 URL 和隐私说明。完整页面 URL 可能带有查询参数，身份字段也可能包含个人信息。不要把密码、会话令牌、API Key 或其他秘密放入 URL 或 identify()。

identify() 只是客户端 metadata，不是身份认证。访客可以查看或修改浏览器发送的值。任何情况下都不能用这些字段授权动作、开放访问权限，或判断能否返回敏感信息。