无 UI Web 客户端快速接入
下载 ESM 客户端,在同源 HTTPS 页面接入自定义聊天界面。
下载接入包
- Web / H5
含原版渠道 iframe 示例及无 UI 客户端。复用完整渠道外观请选择 web/voice-example.html 或渠道嵌入代码;无 UI 客户端需自行绘制界面。
安装
- 下载本页 Web 接入包,将 web/ 整个目录发布到你的同源静态资源目录。包内包含已打包的 ESM 客户端、类型声明和示例。
- 将示例占位值替换为自己的公开 key 与 entryId。baseUrl 使用当前 HTTPS origin。
- 订阅状态并以 textContent 渲染消息,用户点击时再 connect;不要把 AI 消息作为未过滤的 HTML 注入。
最小示例
运行前
web/example.mjs · 模块文件 · 接入包 0.3.15
- 从 Web 包复制 web/ 目录并保留同目录 yunfu-web-client.mjs。
- 填写自己的公开 key 和 entryId,仅在同源 HTTPS 页面使用。
完整代码 · 31 行
import { createWebVisitorClient } from './yunfu-web-client.mjs';
// Serve on the same HTTPS origin as Yunfu. Cross-origin sites should use widget.js / iframe instead.
const options = {
baseUrl: location.origin,
key: 'YOUR_PUBLIC_KEY',
entryId: 'YOUR_ENTRY_ID',
userScope: crypto.randomUUID(),
};
let client;
export async function openSupport(render) {
if (!client) {
client = createWebVisitorClient(options);
client.subscribe(render); // render text as textContent, never inject message HTML
}
client.setChatVisible(true);
await client.connect(); // errors/pending writes are exposed; do not automatically replay sends
return client;
}
export function closeSupport() {
client?.setChatVisible(false);
}
export function logout() {
// Host must call before replacing the signed-in user, then use a fresh scope for that user.
try {
client?.forgetSession();
} finally {
client?.destroy();
client = undefined;
options.userScope = crypto.randomUUID();
}
}使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
从 Web 包复制 web/ 目录并保留同目录 yunfu-web-client.mjs。 填写自己的公开 key 和 entryId,仅在同源 HTTPS 页面使用。
- 在项目中使用
web/example.mjs · 模块文件
- 核对结果
在点击事件中调用 openSupport(render);返回 client 后按发送事件调用 sendText,退出前调用 logout。
预期结果:在点击事件中调用 openSupport(render);返回 client 后按发送事件调用 sendText,退出前调用 logout。
Vue2 与 Vue3 宿主
Web 客户端不依赖 Vue。Vue2 在 mounted 中创建并订阅实例,在 beforeDestroy 中取消订阅并 destroy;Vue3 对应使用 onMounted / onBeforeUnmount。将 SDK 实例保存在组件外的私有引用中,仅把可展示的状态复制到响应式数据。退出或切换账号先执行 forget 再创建新实例,不能只更换界面名称。Uni-app 请使用专用 Vue2 / Vue3 共用组件,合并页面与 App 的隐藏、恢复、卸载事件。
页面刷新与会话续接
上例每次加载创建随机 userScope,仅演示当前页面生命周期。需要刷新后恢复聊天与 pending 时,由宿主在当前登录会话内持久化并复用随机 UUID;退出或切换账号先清理旧实例与存储,再更换编号。存储失败应停止,不自动生成新身份继续发送。
失败处理
请捕获 Promise 拒绝并展示 code / status / retryAfter。sessionStorage 被禁用时不要自动换身份;验证码要求转现有完整网页入口处理。所有示例中的网络动作都由宿主明确触发。
官方原始接入文档
先按云蝠指南完成入口、智能体和服务配置,再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力,不代表云蝠已开放其中全部接口;腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。
- MDN · getUserMedia 麦克风采集 ↗:核对 HTTPS、用户授权、设备和浏览器兼容性;打开页面不等于麦克风可用。
- MDN · Permissions-Policy: microphone ↗:配置父站点允许的客服来源并配合 iframe allow;响应头限制仍生效,不能用放开 CORS 解决麦克风拒绝。
实现依据 · 仓库内路径
sdk/client-kit/web/example.mjssdk/client-kit/web/client.d.mts
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。