开发者文档中心

OpenAPI进入控制台

Web / H5 · 2026-10-31

无 UI Web 客户端快速接入

下载 ESM 客户端,在同源 HTTPS 页面接入自定义聊天界面。

下载接入包

安装

  1. 下载本页 Web 接入包,将 web/ 整个目录发布到你的同源静态资源目录。包内包含已打包的 ESM 客户端、类型声明和示例。
  2. 将示例占位值替换为自己的公开 key 与 entryId。baseUrl 使用当前 HTTPS origin。
  3. 订阅状态并以 textContent 渲染消息,用户点击时再 connect;不要把 AI 消息作为未过滤的 HTML 注入。

最小示例

运行前

web/example.mjs · 模块文件 · 接入包 0.3.15

  • 从 Web 包复制 web/ 目录并保留同目录 yunfu-web-client.mjs。
  • 填写自己的公开 key 和 entryId,仅在同源 HTTPS 页面使用。
完整代码 · 31 行
web/example.mjsJavaScript
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();
  }
}
使用流程预览 · 示意图

帮助理解此示例的使用顺序,不执行代码或验证连接。

  1. 准备

    从 Web 包复制 web/ 目录并保留同目录 yunfu-web-client.mjs。 填写自己的公开 key 和 entryId,仅在同源 HTTPS 页面使用。

  2. 在项目中使用

    web/example.mjs · 模块文件

  3. 核对结果

    在点击事件中调用 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 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

实现依据 · 仓库内路径
  • sdk/client-kit/web/example.mjs
  • sdk/client-kit/web/client.d.mts

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。