Uniapp:快速接入
App-vue 网页容器 源码示例,需加入自己的宿主工程编译。
下载接入包
- Uniapp
App-vue 容器与 Vue2 / Vue3 的 H5、微信示例默认加载当前原版渠道。原生文本为替代方案,按目标配置并完成真机验收。
先选择编译目标,再下载示例
| 目标 | 接入方案 | 开始位置与验收边界 |
|---|---|---|
| App-vue · Android / iOS | 本页 uniapp/ HTML5+ 容器,加载现有 /support 聊天与前台语音 | 按下方步骤合并到宿主工程;需 HBuilderX、自定义基座和真机验收 |
| H5 · Vue 2 / Vue 3 | uniapp-text/ 默认原版渠道页面,与 JS 嵌入共用渲染 | 打开 Uni-app 微信小程序 / H5 指南;HTTPS 宿主与入口来源许可,不调用 plus |
| MP-WEIXIN · Vue 2 / Vue 3 | uniapp-text/ 默认 web-view 原版渠道;显式 native 为原生文本替代 | 配置 AppID 与业务域名,编译后以体验版真机验收;request 域名不能替代业务域名 |
| nvue / uni-app x / App-Harmony | 当前 App-vue 容器和 H5 / 微信文本构建未覆盖 | 不要直接套用本页源码;需按目标宿主另行适配和验收 |
开始前准备
- 在“渠道 → 自建渠道 → 服务入口”创建专用 Web 入口,启用入口并绑定已发布智能体。需要渠道管理权限;没有入口时请企业管理员协助。
- 仅 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 不是管理授权;本地会话编号也不代表可信会员身份。
安装与配置
- 下载本页客户端接入包,将 uniapp/support.vue 及准备要求中的配套文件合并到宿主工程,不覆盖原有业务配置。
- 填写 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 行
// 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 };
}使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
替换 HTTPS origin、公开 key、entryId;不放 AppSecret 或管理密钥。
- 在项目中使用
pages/support/config.js · 配置文件
- 核对结果
打开前验证配置,配置错误显示可定位的说明。
预期结果:打开前验证配置,配置错误显示可定位的说明。
第二步:合并页面路由
运行前
pages.json(合并片段) · 路由片段 · 接入包 0.3.15
- 把 support.vue 重命名为 pages/support/index.vue;所有 helper 放在同目录。
- 仅合并 pages 数组中的新页面,不覆盖宿主 pages.json。
完整代码 · 11 行
{
"pages": [
{
"path": "pages/support/index",
"style": {
"navigationBarTitleText": "在线客服",
"enablePullDownRefresh": false
}
}
]
}使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
把 support.vue 重命名为 pages/support/index.vue;所有 helper 放在同目录。 仅合并 pages 数组中的新页面,不覆盖宿主 pages.json。
- 在项目中使用
pages.json(合并片段) · 路由片段
- 核对结果
保留原生导航栏和返回入口;禁用无意义的下拉刷新。
预期结果:保留原生导航栏和返回入口;禁用无意义的下拉刷新。
第三步:合并宿主权限并重新制作基座
| 位置 | 需要合并的内容 | 核对方法 |
|---|---|---|
| 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 出声和挂断停麦 |
第四步:接入业务按钮
- 宿主完成登录与隐私同意后提供随机 UUID;不要使用手机号、会员 ID 或 token。仅隔离本地会话,不代表可信会员认证。
- 从 pages/support/usage.js 导入 prepareSupportAccount、openSupport、beforeLogout;用户点击客服时 await openSupport(false)。传 true 会在页面加载前核对语音入口和 Android 系统权限,之后仍由用户在网页点击开始,不自动拨号。
- 调用端用 try/catch 展示失败说明;Promise 成功仅表示页面导航成功,接待、AI 回复、语音收音需在页面内分别确认。
- 登出前调用 beforeLogout() 关闭旧客服内容,并为下次登录创建新 UUID。旧客服页在栈顶时下次打开会替换它;若其上还有宿主页面,旧页失效并保留到正常返回。不要清理宿主全局存储。
宿主接入示例
运行前
uniapp/usage.js · 模块文件 · 接入包 0.3.15
- 仅 App-vue:复制 support.vue、config、usage、session/voice helper,合并 manifest 和 pages 片段。
- 宿主登录后先提供新的随机 UUID;不要在 App 启动时自动调用 openSupport。
完整代码 · 54 行
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)。失败保留文字,必要时接宿主原生插件。
怎样确认接入成功
- 从自己的 App 入口发送一条带唯一标记的测试问题,确认收到回复,并在接待台找到同一企业、入口和会话。仅页面打开或编译成功不能代替这一步。
- 在指定基座验收 Android/iOS 的首次授权、拒绝与设置恢复、网页实际收音和 AI 出声、授权中离开、后台/锁屏释放、耳机、导航及账号切换。
- 退出 A 账号后用 B 账号重新进入,确认 B 看不到 A 的内容;挂断或离开页面后确认录音指示消失。
没有成功时先检查
| 现象 | 下一步 |
|---|---|
| 页面打不开 / 连接被拒绝 | 先核对 HTTPS 证书、origin 与同一入口的 key / entryId,再检查入口是否启用及来源限制;不要关闭安全校验绕过问题。 |
| 页面打开但没有回复 | 检查入口接待方案是否绑定已发布智能体、模型是否可用;在接待台按测试标记查找会话,确认是否已转人工。 |
| 文字可用,但无法语音 | 检查企业和入口是否开启语音、系统录音权限与网页授权是否都满足;由用户主动点击开始,分别确认实际收音、AI 出声和挂断释放。 |
继续接入与配置
官方原始接入文档
先按云蝠指南完成入口、智能体和服务配置,再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力,不代表云蝠已开放其中全部接口;腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。
- DCloud · uni-app web-view 组件 ↗:区分 App-vue、H5 iframe 和微信目标;不同内核不能复用同一套原生权限假设。
- DCloud · manifest.json 配置 ↗:合并 Android 录音权限和 iOS 麦克风用途说明,并重新制作实际使用的自定义基座。
- DCloud · plus.android.requestPermissions ↗:分别检查 granted、deniedPresent、deniedAlways;系统授权成功不等于远端 WebView 已收音,需基座验收。
实现依据 · 仓库内路径
sdk/client-kit/uniapp/support.vuesdk/client-kit/README.md
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。