开发者文档中心

OpenAPI进入控制台

Uniapp · 2026-10-31

Uniapp:生命周期、权限与排错

核对账号切换、权限拒绝和容器能力。

下载接入包

生命周期

同一登录期复用 UUID,重复初始化不会关闭咨询;切换账号必须更换 UUID。退出 beforeLogout() 幂等关闭旧内容并作废旧授权,不擅自弹出其他业务页。pause/onHide 停语音,resume 不重拨,卸载移除页面订阅。不可只修改客户名称。

权限与功能边界

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

按这个顺序切换账号

  1. A 登录并完成隐私流程后生成随机 UUID,调用 prepareSupportAccount;同一登录期复用,不随每次打开客服更换。
  2. A 退出前调用 beforeLogout(),停止旧语音、关闭旧网页内容并作废旧授权回调。旧客服页在栈顶时重新打开会被替换;其他宿主页面不会被弹走,旧客服页会失效并等待正常返回。
  3. B 登录后用不同 UUID 调用 prepareSupportAccount,再由 B 点击打开。不得只修改昵称、手机号或 URL 标签来复用 A 的页面。
  4. 分别检查 B 的消息列表、后台接待记录和迟到回复。UUID 仅隔离本地会话,不是可信会员认证;退出不会删除服务端历史或审计。

错误处理与恢复

错误 / 场景处理方式
CONFIGURE_ENTRY_FIRST检查 config.js:只填 HTTPS origin、公开 UUID key 与入口 ID,不填完整聊天 URL
SUPPORT_SESSION_REQUIRED / SUPPORT_SESSION_CHANGED先登录初始化;旧账号页关闭内容,返回后重新进入
APP_VUE_REQUIRED / SUPPORT_ALREADY_OPEN选择正确编译目标;已有客服页时由宿主决定导航,不自动弹走其他页面
SUPPORT_NAVIGATION_FAILED检查 pages.json 与页面栈;失败后可由用户再次点击
加载失败或 15 秒超时页面提供重新加载;只重载页面,不自动重发客户消息或重拨
麦克风拒绝 / 永久拒绝继续文字咨询;由用户到系统设置授权,回前台不自动开麦

在目标真机逐项验收

操作通过条件
先初始化账号,不点击客服;再连续点击客服按钮初始化无客服请求和录音提示;点击后仅打开一个客服页面,不出现重复会话页
通过文字入口发送一条带唯一标记的问题页面收到真实回复,后台记录归属正确企业、入口和会话;导航成功或 loaded 事件不能代替此结果
首次开始语音并允许录音系统与网页授权分别满足,实际收音、AI 出声及打断正常;挂断后录音指示消失
拒绝录音、永久拒绝、到设置恢复授权拒绝后仍可文字咨询,不循环弹窗;恢复后由用户主动重试,回前台不自动开麦
授权弹窗期间离开;通话时切后台、锁屏、返回或关闭页面旧授权不会恢复已关闭内容;麦克风与连接停止,返回后需再次点击开始
A 聊天后退出,再以 B 登录;等待旧回复到达B 看不到 A 的消息,旧回调不更新 B 页面;后台保留各自会话记录
断网后恢复并手动重新加载;切换耳机,弹出键盘及返回失败可见、无自动重发或重拨;内容与返回入口可用;扬声器和目标耳机能实际收听

当前没有包含的能力

App-vue 交付是宿主源码片段,不是已编译的 App、插件或已完成真机验收的基座。当前没有可信会员身份交换、跨设备历史同步、离线未读、消息推送、后台通话、CallKit / ConnectionService 或原生听筒切换。网页文件选择与下载仍需目标设备验证,不能从无 UI SDK 的能力推断此容器已具备。

接入验收记录

按 Android / iOS 分别记录 HBuilderX / Vue 版本、自定义基座、系统与 WebView 版本、入口、测试时间、客服会话编号以及每项通过 / 失败 / 未测。不要把密钥写进日志。静态示例、控制测试和编译通过不等于真实接待或真机语音已接通。

连接被拒绝时

核对 HTTPS、key、entryId 与入口启用状态;网站渠道的 Referer 限制可能不适用于原生容器。为 App 创建专用入口评估策略,不伪造来源、不关闭旧网站的来源限制。

最小回归

  1. 在指定基座验收 Android/iOS 的首次授权、拒绝与设置恢复、网页实际收音和 AI 出声、授权中离开、后台/锁屏释放、耳机、导航及账号切换。
  2. A 账号聊天后退出,B 看不到 A 的历史;关闭后旧回调不再触发。
  3. 接收真实 AI 与人工回复;网络未知时保留待核对,不自动重复提交。

官方原始接入文档

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

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

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