开发者文档中心

OpenAPI进入控制台

Uniapp · 2026-10-31

Uniapp:快速接入

App-vue 网页容器 源码示例,需加入自己的宿主工程编译。

下载接入包

先选择编译目标,再下载示例

目标接入方案开始位置与验收边界
App-vue · Android / iOS本页 uniapp/ HTML5+ 容器,加载现有 /support 聊天与前台语音按下方步骤合并到宿主工程;需 HBuilderX、自定义基座和真机验收
H5 · Vue 2 / Vue 3uniapp-text/ 默认原版渠道页面,与 JS 嵌入共用渲染打开 Uni-app 微信小程序 / H5 指南;HTTPS 宿主与入口来源许可,不调用 plus
MP-WEIXIN · Vue 2 / Vue 3uniapp-text/ 默认 web-view 原版渠道;显式 native 为原生文本替代配置 AppID 与业务域名,编译后以体验版真机验收;request 域名不能替代业务域名
nvue / uni-app x / App-Harmony当前 App-vue 容器和 H5 / 微信文本构建未覆盖不要直接套用本页源码;需按目标宿主另行适配和验收

开始前准备

  1. 在“渠道 → 自建渠道 → 服务入口”创建专用 Web 入口,启用入口并绑定已发布智能体。需要渠道管理权限;没有入口时请企业管理员协助。
  2. 仅 App-vue:将 support.vue 改名为 pages/support/index.vue,config.js、usage.js、support-session.js、voice-access.js 放同目录;合并 pages.fragment.json 与 manifest.fragment.json,不覆盖宿主文件。H5 / 微信文本接入见“Uni-app:微信小程序与 H5 文本客服”,本页容器不用于这两个目标。

从哪里取得入口参数

参数填写内容获取位置
origin部署客服的公网 HTTPS 主机,不带 /support、路径或查询参数从“服务入口 → 皮肤与代码”的入口链接提取协议和主机
key / publicKey同一入口的公开 UUID key从该入口生成的链接或代码复制 key;Android 字段名为 publicKey
entryId同一入口的 ID从该入口生成的链接或代码复制 entryId,不填写智能体 ID

客户端只填公开参数

管理 API Key、AppSecret 和登录 token 不得放入 App 源码或入口链接。公开 key 不是管理授权;本地会话编号也不代表可信会员身份。

安装与配置

  1. 下载本页客户端接入包,将 uniapp/support.vue 及准备要求中的配套文件合并到宿主工程,不覆盖原有业务配置。
  2. 填写 config.js 的 origin、key、entryId,宿主登录且完成隐私流程后调用 prepareSupportAccount(随机 UUID)。用户点击时 await openSupport() 或 openSupport(true),捕获错误;先检查入口是否开启语音,再处理 Android 系统权限。iOS 保留网页 WebKit 提示。需指定自定义基座验收。

第一步:填写公开配置

运行前

pages/support/config.js · 配置文件 · 接入包 0.3.15

  • 替换 HTTPS origin、公开 key、entryId;不放 AppSecret 或管理密钥。
完整代码 · 15 行
pages/support/config.jsJavaScript
// Only public channel values. Never place an API secret, AppSecret or account token here.
export const supportConfig = {
  origin: 'https://YOUR_CUSTOMER_SERVICE_ORIGIN',
  key: 'YOUR_PUBLIC_KEY',
  entryId: 'YOUR_ENTRY_ID',
};
export const supportRoute = '/pages/support/index';
export function readSupportConfig() {
  const { origin, key, entryId } = supportConfig;
  if (typeof origin !== 'string' || !/^https:\/\/[a-z0-9.-]+(:[0-9]{1,5})?$/.test(origin) ||
      !/^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(key || '') ||
      !/^[-a-zA-Z0-9_]{1,100}$/.test(entryId || '') || entryId === 'YOUR_ENTRY_ID')
    throw Error('CONFIGURE_ENTRY_FIRST');
  return { origin, key, entryId };
}
使用流程预览 · 示意图

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

  1. 准备

    替换 HTTPS origin、公开 key、entryId;不放 AppSecret 或管理密钥。

  2. 在项目中使用

    pages/support/config.js · 配置文件

  3. 核对结果

    打开前验证配置,配置错误显示可定位的说明。

预期结果:打开前验证配置,配置错误显示可定位的说明。

第二步:合并页面路由

运行前

pages.json(合并片段) · 路由片段 · 接入包 0.3.15

  • 把 support.vue 重命名为 pages/support/index.vue;所有 helper 放在同目录。
  • 仅合并 pages 数组中的新页面,不覆盖宿主 pages.json。
完整代码 · 11 行
pages.json(合并片段)JSON
{
  "pages": [
    {
      "path": "pages/support/index",
      "style": {
        "navigationBarTitleText": "在线客服",
        "enablePullDownRefresh": false
      }
    }
  ]
}
使用流程预览 · 示意图

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

  1. 准备

    把 support.vue 重命名为 pages/support/index.vue;所有 helper 放在同目录。 仅合并 pages 数组中的新页面,不覆盖宿主 pages.json。

  2. 在项目中使用

    pages.json(合并片段) · 路由片段

  3. 核对结果

    保留原生导航栏和返回入口;禁用无意义的下拉刷新。

预期结果:保留原生导航栏和返回入口;禁用无意义的下拉刷新。

第三步:合并宿主权限并重新制作基座

位置需要合并的内容核对方法
manifest.json → app-plus.distribute.android.permissions合并 manifest.fragment.json 的 INTERNET、RECORD_AUDIO、MODIFY_AUDIO_SETTINGS;保留原有权限重新制作包含这些配置的自定义基座;真机首次开始语音时检查系统录音提示
manifest.json → app-plus.distribute.ios.privacyDescription填写 NSMicrophoneUsageDescription,说明用户主动语音咨询的用途使用更新后的基座;网页点击开始后检查 WebKit / getUserMedia 提示和实际收音
远端客服页与宿主保留 plusrequire:none、固定 HTTPS 地址和原生返回入口;渠道及企业须开启语音系统权限只是一层:还要分别验证网页授权、用户开始、AI 出声和挂断停麦

第四步:接入业务按钮

  1. 宿主完成登录与隐私同意后提供随机 UUID;不要使用手机号、会员 ID 或 token。仅隔离本地会话,不代表可信会员认证。
  2. 从 pages/support/usage.js 导入 prepareSupportAccount、openSupport、beforeLogout;用户点击客服时 await openSupport(false)。传 true 会在页面加载前核对语音入口和 Android 系统权限,之后仍由用户在网页点击开始,不自动拨号。
  3. 调用端用 try/catch 展示失败说明;Promise 成功仅表示页面导航成功,接待、AI 回复、语音收音需在页面内分别确认。
  4. 登出前调用 beforeLogout() 关闭旧客服内容,并为下次登录创建新 UUID。旧客服页在栈顶时下次打开会替换它;若其上还有宿主页面,旧页失效并保留到正常返回。不要清理宿主全局存储。

宿主接入示例

运行前

uniapp/usage.js · 模块文件 · 接入包 0.3.15

  • 仅 App-vue:复制 support.vue、config、usage、session/voice helper,合并 manifest 和 pages 片段。
  • 宿主登录后先提供新的随机 UUID;不要在 App 启动时自动调用 openSupport。
完整代码 · 54 行
uniapp/usage.jsJavaScript
import { setSupportSession, clearSupportSession, readSupportSession, onSupportSessionEnd } from './support-session.js';
import { readSupportConfig, supportRoute } from './config.js';
let opening = null;

// Call after host login/privacy consent. Reuse this random UUID until logout/account switch.
// This isolates local history; it does not authenticate a business member.
export function prepareSupportAccount(opaqueRandomUuid) {
  setSupportSession(opaqueRandomUuid);
}
// await from a click handler and catch errors. Importing this module makes no requests.
export function openSupport(voice = false) {
  try {
    if (typeof plus === 'undefined') throw Error('APP_VUE_REQUIRED');
    readSupportConfig();
    const scope = readSupportSession();
    if (opening) return opening.promise;
    const pages = getCurrentPages();
    const supportPages = pages.filter(page => '/' + page.route === supportRoute);
    const isClosed = page => (page.$vm || page).disposed === true;
    if (supportPages.some(page => !isClosed(page)))
      throw Error('SUPPORT_ALREADY_OPEN'); // Do not pop an unrelated page above support.
    // Replace a closed support page only when it is on top; never remove other host pages.
    const replaceClosedTop = supportPages.length && pages[pages.length - 1] === supportPages[supportPages.length - 1];
    const request = { promise: null };
    opening = request;
    request.promise = new Promise((resolve, reject) => {
      let settled = false;
      let unsubscribe = () => {};
      const finish = error => {
        if (settled) return;
        settled = true; unsubscribe();
        if (opening === request) opening = null;
        if (error) reject(Error(error)); else resolve();
      };
      unsubscribe = onSupportSessionEnd(() => finish('SUPPORT_SESSION_CHANGED'));
      try {
        uni[replaceClosedTop ? 'redirectTo' : 'navigateTo']({
          url: supportRoute + '?session=' + encodeURIComponent(scope) + (voice ? '&voice=1' : ''),
          success() {
            try {
              if (readSupportSession() !== scope) throw Error('SUPPORT_SESSION_CHANGED');
              finish(); // Navigation only; not a connection or voice-success receipt.
            } catch { finish('SUPPORT_SESSION_CHANGED'); }
          },
          fail() { finish('SUPPORT_NAVIGATION_FAILED'); },
        });
      } catch { finish('SUPPORT_NAVIGATION_FAILED'); }
    });
    return request.promise;
  } catch (error) { return Promise.reject(error); }
}
export function beforeLogout() {
  clearSupportSession(); // Close old content without navigating away from an unrelated page.
}
聊天交互预览 · 本地示意

通用聊天交互示意,回复为固定演示内容;不执行此源码、不连接当前渠道或调用模型。

客户服务助手欢迎咨询

您好,我是您的服务助手。有什么可以帮您?

对应源码:uniapp/usage.js。实际效果请在自己的宿主中按下方验收项核对。

预期结果:点击时 await openSupport(true) 并捕获错误;重复打开去重,后台不重拨,退出前 beforeLogout。WebView 媒体仍须指定基座验收。

实际接待范围

容器承载现有 /support 页面:当前读取最近 100 条消息,尚未接线显式转人工按钮与更早历史翻页。人工接待沿服务端路由进入。页面能打开不代表宿主、文件与真实接待已验收。

本平台能力边界

保持 plusrequire:none 与固定导航。DCloud 公共 API 不提供逐来源媒体授权 hook;系统权限不等于 WebView 授权成功。不能使用 App 不支持的 uni.authorize(scope.record)。失败保留文字,必要时接宿主原生插件。

怎样确认接入成功

  1. 从自己的 App 入口发送一条带唯一标记的测试问题,确认收到回复,并在接待台找到同一企业、入口和会话。仅页面打开或编译成功不能代替这一步。
  2. 在指定基座验收 Android/iOS 的首次授权、拒绝与设置恢复、网页实际收音和 AI 出声、授权中离开、后台/锁屏释放、耳机、导航及账号切换。
  3. 退出 A 账号后用 B 账号重新进入,确认 B 看不到 A 的内容;挂断或离开页面后确认录音指示消失。

没有成功时先检查

现象下一步
页面打不开 / 连接被拒绝先核对 HTTPS 证书、origin 与同一入口的 key / entryId,再检查入口是否启用及来源限制;不要关闭安全校验绕过问题。
页面打开但没有回复检查入口接待方案是否绑定已发布智能体、模型是否可用;在接待台按测试标记查找会话,确认是否已转人工。
文字可用,但无法语音检查企业和入口是否开启语音、系统录音权限与网页授权是否都满足;由用户主动点击开始,分别确认实际收音、AI 出声和挂断释放。

继续接入与配置

官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置,再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力,不代表云蝠已开放其中全部接口;腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

实现依据 · 仓库内路径
  • sdk/client-kit/uniapp/support.vue
  • sdk/client-kit/README.md

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