Uni-app:微信小程序与 H5 客服
Vue2 / Vue3 客服接入、客户资料传递与手机号授权;可视化选择字段并核对客户与智能体变量。
下载接入包
- Uniapp
Vue 2 / Vue 3 默认复用原版渠道页面,含可选原生文本替代;按目标编译并验收。
下载与运行
- 下载中心选择“Uni-app 微信小程序 / H5 文本示例”,解压进入 uniapp-text/。README 含完整发布步骤;默认 renderer: channel 直接打开原版客服页面,微信使用 web-view、H5 使用 iframe。
- 使用 Node 20.19+(推荐 22 LTS)。Vue3 在工程根目录用 pnpm 11 执行 pnpm install --frozen-lockfile;Vue2 进入 vue2/ 执行 npm ci。两套依赖各自锁定,不混装。
- Vue3 在根目录运行 pnpm run build:mp-weixin / build:h5;Vue2 在 vue2/ 运行 npm run build:mp-weixin / build:h5。Vue2 输出固定在 dist/build/vue2/ 下,Vue3 在 dist/build/ 下。构建不会自动发布或调用模型。
- 现有工程复制组件、support helper、sdk、static/yunfu-avatars 与 config,合并路由及 App 生命周期,不覆盖宿主文件;自包含 SDK 已在包内。兼容 Vue2 / Vue3;默认原版渠道界面,不能使用 WebView 时显式改为 renderer: native。原生文本方案不含语音和附件;不适用于 nvue、uni-app x。
Vue2 快速接入与旧包升级
- 如果组件中看到 <script setup> 或 defineProps,说明拿到的是旧版 Vue3 示例。请重新下载 Uni-app 接入包或 Uni-app 微信小程序 / H5 文本示例;新版使用 export default Options API,同一组件兼容 Vue2 和 Vue3,不需要 Composition API。
- 在解压后的 uniapp-text/vue2/ 目录依次运行 npm ci、npm run build:h5、npm run build:mp-weixin;可先阅读该目录的 README。微信开发者工具导入 dist/build/vue2/mp-weixin,H5 使用 dist/build/vue2/h5。
- 接入现有 Vue2 项目时同时复制组件、support/、sdk/、static/yunfu-avatars/ 和 config.js,按下文合并页面路由、App 前后台事件;保留宿主的 main.js、manifest.json 和依赖,不要仅复制旧版 Vue3 组件或覆盖宿主配置。
- 若重新下载后仍看到 script setup,检查浏览器缓存及解压目录,确认文件来自刚下载的包;旧包不会自动更新。可在下载中心核对文件摘要。构建通过后仍需自己的公开入口及真机联调。
与 JS 嵌入使用同一界面
- 默认 renderer: channel,由 YunfuChannel 打开 /support?surface=channel。消息、输入区、头像、主题和可用功能直接使用 JS 嵌入相同页面,渠道保存后重新进入即可读取配置。原版界面加载前须同意隐私说明并点击进入客服。
- H5 合并 style.h5.navigationStyle: custom 与 titleNView: false(兼容 Vue2),避免额外标题挤占聊天高度;进入前页面随系统明暗主题,进入后使用渠道主题。窗口关闭和缩放由宿主管理,原版整页模式不重复展示;微信原生导航栏、键盘及不同内核的字体渲染需要真机核对,不能用同浏览器像素结果替代所有设备验收。
- 无法满足 WebView 业务域名或平台要求时,显式使用 renderer: native。该方案同步标题、头像、欢迎语、推荐问题、品牌色与主题,但只是原生文本替代,不能声明与网页所有功能和像素完全一致。
- 升级时一并替换组件、support/、sdk/ 与 static/,保留公开参数和宿主 Vue 版本;合并 transformPx:false 前核对宿主其他页面。两种模式互斥,不会在页面加载失败后自动改用另一种身份连接。
选择宿主 Vue 版本
| 宿主 | 组件与构建 | 保留宿主设置 |
|---|---|---|
| Vue2 | 共用 Options API 组件;附带 Vue 2.6.14 + DCloud Vue CLI / webpack 锁定构建链,位于 vue2/。不需要 composition-api 插件。 | 已有工程保留自己的 package.json、路由、App 生命周期及 manifest 的 Vue 版本。不要覆盖为示例根目录的 Vue3 依赖。 |
| Vue3 | 同一组件;根目录继续使用 Vue 3.4.21 + DCloud Vite 构建链。 | 保留现有 Vue3 配置;不能用 Vue2 的 webpack 配置替换 Vite。 |
| 共用源码 | main.js 使用 VUE3 条件编译;销毁分别响应 beforeDestroy / beforeUnmount,页面离开也清理。 | HBuilderX 中按宿主 Vue 版本导入组件;所用 IDE、基座和真机仍需单独验收。不适用于 nvue / uni-app x。 |
双版本启动入口(新工程)
运行前
src/main.js · 完整源文件 · 接入包 0.3.15
- 新工程按 VUE3 条件编译选择启动入口;已有宿主只合并必要配置,不覆盖自己的 main.js。
完整代码 · 12 行
import App from './App.vue';
// #ifndef VUE3
import Vue from 'vue';
Vue.config.productionTip = false;
App.mpType = 'app';
const app = new Vue({ ...App });
app.$mount();
// #endif
// #ifdef VUE3
import { createSSRApp } from 'vue';
export function createApp() { return { app: createSSRApp(App) }; }
// #endif使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
新工程按 VUE3 条件编译选择启动入口;已有宿主只合并必要配置,不覆盖自己的 main.js。
- 在项目中使用
src/main.js · 完整源文件
- 核对结果
Vue2 使用 new Vue,Vue3 使用 createSSRApp;分别使用对应锁定构建链。
预期结果:Vue2 使用 new Vue,Vue3 使用 createSSRApp;分别使用对应锁定构建链。
第一步:入口配置
运行前
src/config.js · 完整源文件 · 接入包 0.3.15
- 从 uniapp-text 接入包复制相关 SDK、support helper 和组件;按 README 填写公开参数。
完整代码 · 22 行
// Only public locator values. Never put AppSecret, administrator or Open API keys here.
import { normalizeOrigin, assertTestEnvironment } from './sdk/yunfu-miniapp-client.mjs';
export const supportConfig = Object.freeze({
baseUrl: 'https://chat.ccgpt.net',
testMode: false, // Set true for HTTP/localhost testing; restore false before release.
key: 'YOUR_PUBLIC_KEY_UUID',
entryId: 'YOUR_ENTRY_ID',
renderer: 'channel', // Original channel page. Use 'native' only for the alternate text UI.
});
export function validateSupportConfig(config) {
const uuid = /^[a-f\d]{8}-[a-f\d]{4}-[1-5][a-f\d]{3}-[89ab][a-f\d]{3}-[a-f\d]{12}$/i;
// #ifdef MP-WEIXIN
if (typeof wx !== 'undefined') assertTestEnvironment(config?.testMode, wx);
// #endif
const origin = normalizeOrigin(config?.baseUrl, config?.testMode === true);
const validOrigin = !!origin && !/example\.com(?::\d+)?$/.test(origin);
if (!validOrigin || !uuid.test(config.key || '') ||
!/^[-\w]{1,100}$/.test(config.entryId || '') || config.entryId === 'YOUR_ENTRY_ID') {
throw Object.assign(new Error('CONFIGURE_ENTRY_FIRST'), { code: 'CONFIGURE_ENTRY_FIRST' });
}
}使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
从 uniapp-text 接入包复制相关 SDK、support helper 和组件;按 README 填写公开参数。
- 在项目中使用
src/config.js · 完整源文件
- 核对结果
合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN;真机收发、身份隔离和平台发布分别验收。
预期结果:合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN;真机收发、身份隔离和平台发布分别验收。
参数与身份
| 字段 | 来源与含义 |
|---|---|
| baseUrl | 默认 https://chat.ccgpt.net;私有部署填写客服服务的公开 HTTPS origin,不含路径或查询串 |
| key / entryId | 自建渠道公开 key(UUID)及其实际启用的入口 ID;不是企业 API Key 或 AppSecret |
| renderer | channel:原版页面(默认);native:原生文本替代方案 |
| userScope | 安全随机本地隔离串,同登录期稳定、换账号更换;不传手机号、会员ID或登录凭据 |
| mp-weixin.appid / manifest.appid | 分别填写宿主微信 AppID / DCloud 应用标识,不与渠道公开 key 混用 |
客户资料:字段与接入流程
- 选择字段
在上方入口配置中勾选姓名、公司、手机号、邮箱,复制资料示例到宿主。
- 取得同意
姓名由用户填写;手机号由用户点击授权。企业与邮箱可由宿主传入。
- 关联客户
native 模式连接或保存资料后关联当前访客;核对客户档案及智能体变量。
自动关联适用于 renderer: native 的 YunfuTextChat、原生微信和 Web 文字 SDK。将获同意的资料传给 config.visitorContext.customer 或组件 customer 属性,连接时即可建立当前访客的未核实客户档案;已连接后使用 identifyCustomer(customer, true)。不需要先发送消息或开启手动留资。
智能体在变量中选择“客户资料”及表内 profile 字段;自定义变量名按实际配置。资料不是指令或会员认证,不按手机号或宿主 id 合并客户,不开放其他账号历史;人工维护、解绑和重新关联优先,自动档案只补空字段。
默认 renderer: channel 使用独立 WebView 会话。进入前的手机号授权记录仅供回访,当前包不会把它自动关联到网页聊天或注入网页智能体变量。需要此关联时显式使用 native;不要把个人资料或访客令牌拼进 URL。
| 传递字段 | 客户来源字段 | 默认智能体变量 |
|---|---|---|
| customer.name · 姓名 / 昵称 | profile.name | {{customer_name}} |
| customer.company · 公司名称 | profile.company | {{customer_company}} |
| customer.phone · 手机号 | profile.phone | {{customer_phone}} |
| customer.email · 邮箱 | profile.email | {{customer_email}} |
第二步:合并页面路由
运行前
src/pages.json · 完整源文件 · 接入包 0.3.15
- 从 uniapp-text 接入包复制相关 SDK、support helper 和组件;按 README 填写公开参数。
完整代码 · 19 行
{
"pages": [
{
"path": "pages/support/index",
"style": {
"navigationBarTitleText": "在线客服",
"enablePullDownRefresh": false,
"h5": {
"navigationStyle": "custom",
"titleNView": false
}
}
}
],
"globalStyle": {
"navigationBarTextStyle": "black",
"navigationBarBackgroundColor": "#ffffff"
}
}使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
从 uniapp-text 接入包复制相关 SDK、support helper 和组件;按 README 填写公开参数。
- 在项目中使用
src/pages.json · 完整源文件
- 核对结果
合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN;真机收发、身份隔离和平台发布分别验收。
预期结果:合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN;真机收发、身份隔离和平台发布分别验收。
第三步:局部组件注册与页面生命周期
运行前
src/pages/support/index.vue · 完整源文件 · 接入包 0.3.15
- 从 uniapp-text 接入包复制相关 SDK、support helper 和组件;按 README 填写公开参数。
完整代码 · 65 行
<template>
<view>
<YunfuChannel v-if="scope && !identityError && supportConfig.renderer !== 'native'" :key="scope" ref="chat" :config="supportConfig" :user-scope="scope" :visible="visible"><template v-slot:account><button class="yf-account-action" :disabled="resetting" @click="resetIdentity">退出访客身份</button></template></YunfuChannel>
<YunfuTextChat v-if="scope && !identityError && supportConfig.renderer === 'native'" :key="scope" ref="chat" :config="supportConfig" :user-scope="scope" :visible="visible"><template v-slot:account><button class="yf-account-action" :disabled="resetting || !scope || !!identityError" @click="resetIdentity">退出访客身份</button></template></YunfuTextChat>
<text v-if="identityError" class="yf-host-error">{{ identityError }}。请恢复存储后重新进入;未创建新身份。</text>
</view>
</template>
<script>
// Options API local registration works in both Vue2 and Vue3 Uni-app hosts.
import YunfuChannel from '../../components/YunfuChannel.vue';
import YunfuTextChat from '../../components/YunfuTextChat.vue';
import { supportConfig } from '../../config.js';
import { getAnonymousScope, removeAnonymousScope } from '../../support/session.js';
import { safeError } from '../../support/session.js';
const lifetimes = new WeakMap();
export default {
components: { YunfuTextChat, YunfuChannel },
data() { return { supportConfig, scope: '', visible: false, identityError: '', resetting: false }; },
// Vue2 H5 dispatches onLoad from a framework created mixin, before user created.
beforeCreate() { lifetimes.set(this, { generation: 0, alive: true }); },
onLoad() { void this.loadIdentity(); },
onShow() { this.visible = true; },
onHide() { this.visible = false; },
onUnload() { this.disposePage(); },
beforeDestroy() { this.disposePage(); },
beforeUnmount() { this.disposePage(); },
methods: {
async loadIdentity() {
const state = lifetimes.get(this);
if (!state || !state.alive) return;
const current = ++state.generation;
const valid = () => state.alive && state.generation === current;
try { const next = await getAnonymousScope(undefined, undefined, valid); if (valid()) this.scope = next; }
catch (error) { if (valid()) this.identityError = safeError(error).code; }
},
disposePage() {
const state = lifetimes.get(this);
if (!state || !state.alive) return;
state.alive = false; state.generation += 1;
if (this.$refs.chat) this.$refs.chat.close();
},
resetIdentity() {
const state = lifetimes.get(this), requestedAt = state.generation;
let settled = false;
uni.showModal({ title: '退出访客身份', content: '将清除此设备上的客服续接凭据。服务器历史不会被删除;待确认请求也不会因此取消。是否继续?',
success: async result => {
if (settled) return;
settled = true;
if (!result.confirm || this.resetting || !state.alive || !this.visible || state.generation !== requestedAt) return;
this.resetting = true;
try {
// Forget before changing accounts; next login must use a new opaque scope.
if (this.$refs.chat) this.$refs.chat.forget();
removeAnonymousScope();
this.scope = '';
await this.loadIdentity();
} catch (error) { if (state.alive) { this.identityError = safeError(error).code; this.scope = ''; } }
finally { if (state.alive) this.resetting = false; }
} });
},
},
};
</script>
<style scoped>.yf-host-error { display: block; padding: 16px; color: #9a3412; }.yf-account-action { margin:0; font-size:12px; line-height:1.5; padding:7px 10px; border-radius:8px; background:var(--yf-surface,#fff); color:var(--yf-muted,#69788f); }.yf-account-action::after { border:0; }</style>聊天交互预览 · 本地示意
通用聊天交互示意,回复为固定演示内容;不执行此源码、不连接当前渠道或调用模型。
对应源码:src/pages/support/index.vue。实际效果请在自己的宿主中按下方验收项核对。
预期结果:合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN;真机收发、身份隔离和平台发布分别验收。
第四步:合并 App 前后台事件
运行前
src/App.vue · 完整源文件 · 接入包 0.3.15
- 从 uniapp-text 接入包复制相关 SDK、support helper 和组件;按 README 填写公开参数。
完整代码 · 7 行
<script>
import { setAppVisible } from './support/session.js';
export default {
onShow() { setAppVisible(true); },
onHide() { setAppVisible(false); },
};
</script>使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
从 uniapp-text 接入包复制相关 SDK、support helper 和组件;按 README 填写公开参数。
- 在项目中使用
src/App.vue · 完整源文件
- 核对结果
合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN;真机收发、身份隔离和平台发布分别验收。
预期结果:合并到 Vue2 或 Vue3 宿主后分别编译 H5 与 MP-WEIXIN;真机收发、身份隔离和平台发布分别验收。
微信与 H5 域名配置
| 目标 | 必须配置 | 发布与验收 |
|---|---|---|
| 微信原版渠道 | 具备 web-view 使用资格,并在微信后台配置 baseUrl 业务域名;嵌套页面按微信规则配置。request 域名不能替代业务域名。 | 真实 AppID、有效 HTTPS 证书、域名校验开启;分别编译 Vue2 / Vue3 的 mp-weixin 输出,微信体验版和真机验收。 |
| H5 原版渠道 | 宿主页面必须 HTTPS,渠道允许该宿主来源;iframe 的麦克风许可还受服务器 Permissions-Policy 与浏览器限制。 | 部署对应 H5 输出,默认路径 /yunfu-text/。检查加载、主题、键盘、关闭和账号切换;页面加载事件不等于真实接待成功。 |
| native 原生文本 | 微信配置 request 合法域名;H5 页面与 baseUrl 必须 HTTPS 同源。仅此模式使用独立消息 SDK。 | 无法使用 WebView 时主动选择,绝不自动降级;先编译再验证消息、转人工、历史与幂等恢复。 |
原版页面的身份与生命周期
按 baseUrl、key、entryId 与 userScope 保存随机 clientSession;这只是匿名续接标识,不是会员认证。公开参数不授予管理权限,不在 URL 放置 API Key 或登录凭据。
隐藏、卸载、切换账号或配置时移除旧网页。返回后由客户再次进入,不自动重新打开或恢复麦克风。账号退出先调用 forget 并卸载,再更换 scope;不会删除服务器历史。
下列 SDK 方法、文本收发和错误码专用于 renderer: native;原版页面由当前网页界面管理,目前尚未接线显式转人工按钮和更早历史翻页。
原生文本:身份、会话与历史
公开参数仅定位入口,服务端签发的访客 token 由 SDK 保管,不写到 URL 或日志。userScope 不是微信会员认证、openid 绑定或跨设备历史找回;当前包不包含可信会员 SSO。
小程序本地存储续接,H5 使用 sessionStorage;同标签页刷新可恢复,关闭标签页、清存储或跨设备不保证恢复。卸载 destroy 保留续接;退出必须先 forget 再换随机 scope 并通过 Vue key 重建组件。清理失败时阻止新身份进入。
connect 读取最近记录,loadEarlier 根据 hasMore/before 加载更早消息;refresh 合并记录。结束咨询要等服务端 closed 后 restart。清客户端凭据不会删除服务器历史,也不会取消已经送达的消息。
原生文本:收发与转人工
- 页面自动预检并加载渠道外观,更多中的检查入口也只 preflight;完成宿主隐私同意后点击开始咨询,调用 connect。示例勾选框不能代替宿主和微信完整隐私流程。
- subscribe 监听状态,sendText 发送最多 2000 字。组件渲染纯文本,不执行 v-html;发送中禁用重复提交。AI / 人工回复必须根据服务端消息实际确认。
- 已有 activeConversationId 后才 handoff;没有会话先发第一条问题。waiting 仅为人工排队,human 才接管;接待台必须实际回复并在客户端看到 service 消息。
- 断网/超时保留 pending。先 refresh 核对,再由用户确认 retryPending,沿用原请求编号,不能直接再次 sendText 相同内容。
原生文本:生命周期与错误恢复
| 场景 | 处理 |
|---|---|
| 页面 / 应用 / H5文档可见性 | 三者同时可见才轮询。H5使用manageVisibility:false由宿主管理;隐藏路由不能被标签页恢复事件唤醒。 |
| 卸载 / 账号切换 | 取消请求、订阅、轮询和监听;先隔离迟到回调。账号切换另清理续接凭据,不自动终止服务器会话。 |
| WX_DOMAIN_NOT_ALLOWED / WX_TLS_FAILED / WX_PRIVACY_REQUIRED | 分别核对微信request域名、证书链和宿主隐私授权。 |
| SAME_HTTPS_ORIGIN_REQUIRED | 按H5同源规则部署;不绕过检查。 |
| NETWORK_TIMEOUT / NETWORK_UNCERTAIN / PENDING_REQUEST_EXISTS | 先核对原请求,再幂等重试;不循环自动重发。 |
| NO_ACTIVE_CONVERSATION / RESTART_NOT_READY | 先发咨询;重新开始必须等待closed且无其他待确认请求。 |
| SESSION_STORAGE_UNAVAILABLE / SECURE_RANDOM_UNAVAILABLE | 恢复存储或安全随机能力,失败时阻止身份混用;不使用Math.random降级。 |
联调与验收步骤
- 首先核对原版模式的业务域名、显式进入、隐藏后关闭、切账号不串历史,并与同入口 JS 嵌入比对头像、品牌色、消息和输入区。原生文本按以下 SDK 动作另行验收。创建专用测试入口并设置可用智能体/人工组;按宿主 Vue 版本完成 H5 / MP-WEIXIN 编译后分别安装微信体验版与同源HTTPS站点。真实发消息可能计费,遵循测试预算。
- 入口只读检查→开始咨询→发送唯一测试文本→接待台找到同一会话编号和实际回复;再跑3轮,验证客户/AI/人工角色。
- 准备超过一页历史,验证更早记录、刷新后不丢失;转人工看到waiting,再由客服接管回复,核对human与service消息。
- 断网或丢响应后先核对再重试,确认只生成一条业务消息;切后台与路由隐藏不新发轮询,恢复沿用同会话。
- A账号退出后切B,延迟A的响应与回旧页,确认B不显示A历史;测试结束closed及重新开始,新旧记录可区分。
- 微信保持域名校验,在iOS/Android真机与体验版核对;H5在Safari/Chrome核对HTTPS、路由、键盘、刷新续接。记录版本、包摘要、时间、入口ID、会话编号和实际结果,不记录密钥。
- 编译、真机接待、平台审核和正式发布分别留证。示例没有预置真实账户,不提供虚构的通话/会话记录;管理员完成实际发布。
官方原始接入文档
先按云蝠指南完成入口、智能体和服务配置,再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力,不代表云蝠已开放其中全部接口;腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。
- DCloud · CLI 创建与构建 ↗:核对 Vue2 Vue CLI / webpack 与 Vue3 Vite 的不同构建入口、编译目标和输出目录;编译不等于平台发布。
- DCloud · web-view 原版网页承载 ↗:核对微信业务域名、全屏展示及宿主导航;原版页面和原生文本模式使用不同域名类别。
- DCloud · 页面与生命周期 ↗:合并页面与应用事件,防止隐藏路由继续轮询。
- DCloud · 小程序开发注意事项 ↗:区分 Vue 组件与原生微信组件注册,核对目标能力。
- 微信开放文档 · 小程序网络与合法域名 ↗:原生请求需配置 request、uploadFile、downloadFile 合法域名;WebView 另需业务域名,关闭校验不能代替正式配置。
实现依据 · 仓库内路径
sdk/client-kit/uniapp-text/README.mdsdk/client-kit/uniapp-text/src/components/YunfuChannel.vuesdk/client-kit/uniapp-text/src/components/YunfuTextChat.vuesdk/client-kit/uniapp-text/src/support/session.js
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。