API-Android
本页说明 Uniapp 七鱼插件在 Android 端暴露给 JS 的方法。以下示例默认已经完成插件接入,并通过插件名获取模块:
const qiyuModule = uni.requireNativePlugin("Netease-QiyuModule");Android 端插件基于七鱼 Android 原生 SDK 封装。开发者在 Uniapp 侧按本页说明调用 JS 方法并传入参数即可。
初始化 SDK
initSdk 用于启动七鱼 SDK。Android 端的 appKey 来自 manifest.json 的原生插件配置,不从 initSdk 参数读取。
qiyuModule.initSdk();建议在 App 启动后调用一次。完成初始化后,未读数、客服主动发送消息等能力才能正常工作。
注意事项
- Android 端
appKey必须在manifest.json的原生插件配置中填写。如果没有配置,运行时会提示“请在原生插件配置里面填入网易七鱼appKey”。 - 避免在调用
initSdk后立刻进入客服界面。建议至少间隔 2 秒,等待七鱼 SDK 初始化完成,否则可能出现聊天界面样式与后台配置不一致的问题。
设置用户信息
用户登录后调用 setUserInfo,把 App 用户身份和展示给客服的资料同步给七鱼。切换到另一个登录用户前,建议先调用 logout。
qiyuModule.setUserInfo({
userId: "user_001",
authToken: "token_from_your_server",
data: JSON.stringify([
{ key: "real_name", value: "张三" },
{ key: "mobile_phone", value: "13800000000", hidden: true },
{ key: "email", value: "zhangsan@example.com" },
{ index: 0, key: "account", label: "账号", value: "zhangsan" },
{ index: 1, key: "level", label: "会员等级", value: "VIP" },
{ index: 2, key: "order", label: "最近订单", value: "ORD123", href: "https://example.com/order/ORD123" }
])
}, (ret) => {
if (ret.code === 200) {
// 设置成功
} else {
// 设置失败,ret.code 为错误码,ret.errMsg 可能包含异常信息
}
});| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | string | 是 | App 用户唯一标识。相同 userId 会关联同一访客身份和会话记录 |
| authToken | string | 否 | 用户认证令牌。仅当管理后台开启 authToken 校验时需要传,由 App 服务端生成 |
| data | string | 否 | 用户资料 JSON 字符串。需要使用 JSON.stringify(array) 传入 |
data 数组元素字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 字段标识。real_name、mobile_phone、email 是七鱼保留字段 |
| value | string | 是 | 字段值 |
| label | string | 否 | 客服端展示名称。保留字段的展示名称固定,不受该字段影响 |
| index | number | 否 | 展示排序,越小越靠前 |
| href | string | 否 | 超链接地址。配置后客服端可点击跳转 |
| hidden | boolean | 否 | 是否隐藏字段。目前主要用于手机号、邮箱 |
注意事项
- 如果 App 需要指定登录用户,并避免展示默认匿名访客名称,必须传
userId。 authToken只有在管理后台开启用户认证校验时才需要传。该值应由 App 服务端生成,客户端负责透传。- 如果需要更新同一个用户的信息,保持
userId不变,只更新data即可。切换到另一个用户前,应先调用logout。
打开客服界面
openServiceActivity 打开 Android 客服页面。常用做法是在用户点击“联系客服”时调用;如果需要先上报用户信息,可以在 setUserInfo 成功回调后再打开。
qiyuModule.openServiceActivity({
title: "在线客服",
source: {
uri: "order_detail",
title: "订单详情页",
custom: "订单号:ORD123",
groupId: 123456,
robotFirst: true,
vipLevel: 3
}
});| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| title | string | 否 | 客服页面标题。实际展示会受管理后台配置影响 |
| source | object | 否 | 咨询来源、客服分配、商品卡片等配置 |
source 常用字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| uri | string | 咨询来源标识,可以是业务页面 URL,也可以是 order_detail 这类业务标识 |
| title | string | 咨询来源标题,客服端用于识别访客从哪里进入 |
| custom | string | 自定义透传信息,例如订单状态、商品摘要 |
| groupId | number | 指定客服组 ID。可在管理后台「服务中心 - 在线系统 - 设置 - 会话流程 - 会话分配 - 自定义链接分配」查询 |
| staffId | number | 指定客服 ID。设置后优先于 groupId |
| groupTmpId | number | 多入口分流模板 ID,由后台模板决定最终客服或客服组 |
| robotFirst | boolean | 是否先由机器人接待。通常和 groupId / staffId 一起使用,转人工后进入指定客服或客服组 |
| robotId | number | 指定机器人 ID。不传时使用后台默认机器人 |
| faqGroupId | number | 指定机器人热门问题组 ID |
| robotWelcomeMsgId | string | 指定机器人欢迎语 ID |
| shortcutTemplateId | number | 常见快捷入口模板 ID |
| vipLevel | number | 用户 VIP 等级。0 普通用户,1-10 VIP 等级,11 通用 VIP |
| shopId | string | 平台电商商家 ID。非平台电商不需要传 |
| productDetail | object | 打开会话时自动携带商品或订单卡片 |
| cardDetail | object | 打开会话时自动携带自定义卡片消息 |
| isSendProductonRobot | boolean | 机器人阶段是否发送商品卡片 |
| isSendProductionLeave | boolean | 留言阶段是否发送商品或卡片 |
| isEnableVideo | boolean | 是否开启视频客服 |
| forbidUseCleanTopStart | boolean | 是否禁止用 CLEAR_TOP 方式打开客服页,需要在当前客服页内再打开新客服页时可设为 true |
| clientIpAddress | string | 访客端 IP。对后台 IP 展示有要求时由 App 自行获取后传入 |
指定客服组并携带商品卡片的示例:
qiyuModule.openServiceActivity({
title: "商品咨询",
source: {
uri: "goods_detail",
title: "商品详情页",
groupId: 123456,
productDetail: {
title: "商品标题",
desc: "商品描述",
picture: "https://example.com/goods.png",
url: "https://example.com/goods/10001",
note: "¥99.00",
show: 1,
cardType: 0,
goodsId: "10001",
goodsCId: "category_001",
goodsCName: "生鲜食品",
sendByUser: true,
actionText: "发送商品",
tags: [
{ label: "查看订单", url: "https://example.com/order/ORD123" }
]
}
}
});注意事项
- 如需上报用户信息,建议在
setUserInfo成功回调后再调用openServiceActivity。 - 避免在
initSdk后立即打开客服界面。建议至少间隔 2 秒,避免 SDK 配置尚未完成导致界面样式与后台配置不一致。 staffId和groupId同时设置时,staffId优先,groupId会被忽略。groupId、staffId、groupTmpId、robotId等 ID 不是 App 自行业务 ID,需要在七鱼管理后台对应配置页查询后传入。
商品卡片字段
productDetail 可放在 openServiceActivity.source.productDetail 中进入会话时自动发送,也可以通过 sendProductMessage 在会话中主动发送。
| 字段 | 类型 | 说明 |
|---|---|---|
| title | string | 商品标题,建议不超过 100 字符 |
| desc | string | 商品描述,建议不超过 300 字符 |
| picture | string | 商品图片地址,需支持 file://、http:// 或 https:// |
| url | string | 商品详情页地址 |
| note | string | 商品备注,例如价格、套餐、订单号,建议不超过 100 字符 |
| show | number | 是否在访客端显示。1 显示,0 或不传则仅客服可见 |
| alwaysSend | boolean | 是否每次打开会话都尝试发送。相同商品链接不会重复发送 |
| sendByUser | boolean | 是否由用户点击按钮后手动发送 |
| actionText | string | 手动发送按钮文案 |
| actionTextColor | number | 手动发送按钮颜色,例如 0xFFDB7093 |
| actionTextSize | number | 手动发送按钮字体大小,单位 sp |
| reselectText | string | 重新选择按钮文案 |
| isOpenReselect | boolean | 是否展示重新选择按钮 |
| handlerTag | string | 点击重新选择时回传的标识 |
| ext | string | 扩展字段 |
| cardType | number | 卡片类型。0 商品,1 订单,2 自定义 |
| goodsCId | string | 商品类目 ID |
| goodsCName | string | 商品类目名称 |
| goodsId | string | 商品 ID。商品卡片推荐填写 |
| orderId | string | 订单 ID。订单卡片推荐填写 |
| intent | string | 一触即达意图名称 |
| params | string | 一触即达流程参数 |
| orderStageType | number | 订单阶段类型 |
| optionId | string | 选项 ID |
| info | string | 卡片附加信息,不展示在前端卡片中 |
| agentId | string | 大模型 ID |
| tags | array | 展示在客服端的操作入口 |
tags 数组元素字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| label | string | 操作入口显示名称 |
| url | string | 点击后的跳转地址 |
| focusIframe | string | 如果要定位客服工作台右侧 iframe,可传 iframe 标识 |
| data | string | 传给 iframe 的数据 |
注意事项
- 商品卡片用于把商品、订单等业务信息带给客服。
cardType为0时建议填写goodsId,为1时建议填写orderId。 show控制访客端是否可见。show: 1时访客端也能看到卡片;不传或传0时通常只有客服端可见。sendByUser: true表示卡片展示后由访客点击按钮发送,按钮文案可通过actionText配置。intent、params用于一触即达流程匹配,不展示在卡片 UI 上。
发送商品卡片
会话已打开后,如果用户切换了商品或订单,可以调用 sendProductMessage 主动发送新的卡片。
qiyuModule.sendProductMessage({
title: "商品标题",
desc: "商品描述",
picture: "https://example.com/goods.png",
url: "https://example.com/goods/10001",
note: "¥99.00",
show: 1,
cardType: 0,
goodsId: "10001"
});发送文本消息
Android 端方法签名为 sendTextMessage(text, isLocal)。
// 发送给客服
qiyuModule.sendTextMessage("测试文本消息", false);
// 仅保存为本地消息,客服不可见
qiyuModule.sendTextMessage("本地提示消息", true);| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| text | string | 是 | 文本内容 |
| isLocal | boolean | 是 | true 表示只展示在访客本地,false 表示发送给客服 |
注销用户
App 用户退出登录或切换账号时调用。否则前一个用户的客服消息可能仍然被当前设备收到。
qiyuModule.logout((ret) => {
if (ret.success) {
// 注销成功
} else {
// ret.errMsg 为失败原因或错误码
}
});也可以不传回调:
qiyuModule.logout();通知栏消息开关
控制七鱼通知栏提醒是否开启。
qiyuModule.toggleNotification(false);| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| on | boolean | 是 | true 开启通知栏提醒,false 关闭 |
更新配置 updateOptions
updateOptions 用于在运行时更新七鱼 SDK 配置。方法签名:
qiyuModule.updateOptions(options, urlCallback);| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| options | object | 是 | SDK 配置项,包含消息拉取、聊天界面样式等配置,字段见下表 |
| urlCallback | function | 否 | 聊天消息中 URL 点击回调 |
调用 updateOptions 会重新更新 SDK 配置。大多数配置项在下一次进入会话界面时才会生效。
示例
qiyuModule.updateOptions({
isPullMessageFromServer: true,
uiCustomization: {
titleBackgroundColor: "#337EFF",
titleBarStyle: 1,
titleCenter: true,
hideLeftAvatar: false,
hideRightAvatar: false,
inputTextColor: "#333333",
inputTextSize: 14,
textMsgColorLeft: "#333333",
textMsgColorRight: "#ffffff",
msgBackgroundColor: "#f5f7fa",
hideAudio: false,
hideEmoji: false
}
}, (url) => {
// 聊天消息中的链接点击回调
plus.runtime.openWeb(url);
});options 可配置字段如下:
| 字段 | 类型 | 说明 |
|---|---|---|
| templateId | number | 对话框内容样式模板 ID,来自管理后台「样式设置」。不传则使用后台默认样式 |
| isPullMessageFromServer | boolean | 切换账户时是否从服务端拉取历史消息,默认 false |
| pullMessageCount | number | 从服务端拉取历史消息数量,默认 20,最大 100。需 isPullMessageFromServer 为 true 时生效 |
| isDefaultLoadMsg | boolean | 会话开始时是否加载历史消息,默认 true |
| categoryDialogStyle | number | 咨询分类对话框样式:0 不弹出,1 从中间弹出,2 从底部弹出 |
| autoTrackUser | boolean | 是否自动记录用户访问轨迹,默认 false |
| isUseYsfNotificationConfig | boolean | 是否使用七鱼通知配置,默认 true |
| disableAwake | boolean | 是否禁止后台进程唤醒 UI 进程,默认 true |
| asyncInitSDK | boolean | 是否异步初始化 SDK,默认 false |
| isMixSDK | boolean | 是否使用云信融合 SDK 功能,默认 false |
| preLoadServers | boolean | 初始化后是否预加载服务,默认 false |
| isUseSAF | boolean | 是否使用 SAF(存储访问框架)模式。国内版默认 false,海外版默认 true |
| isConfigMediaVisualUserSelected | boolean | 是否配置了 Android 14 的已选照片访问权限(READ_MEDIA_VISUAL_USER_SELECTED),默认 false |
| isCaptureVideoRecordAudioPermission | boolean | 录制视频时是否需要录音权限,默认 true |
| captureVideoRecordTip | string | 录制视频无录音权限时的提示文案 |
| logSwitch | boolean | 是否输出调试日志,默认 true |
| openLog | boolean | 是否开启日志记录,默认 true |
| openFileSizeStatistics | boolean | 是否开启文件大小统计,默认 false |
| isOpenMoreLog | boolean | 是否开启更多日志(数据库日志),默认 false |
| isDisableNetworkTrace | boolean | 是否禁用网络检测,默认 false |
| messageCopyBtnSwitch | boolean | 是否允许长按复制写入剪切板,默认 true |
| proximitySensorEnable | boolean | 语音消息播放时是否使用距离传感器,默认 true |
| productOrderCardMessageWhiteBubbleEnabled | boolean | 商品/订单卡片消息是否使用白色气泡,默认 false |
| uiCustomization | object | 聊天界面样式配置,见下文 |
说明:
- 回调、监听类配置不通过
options传入,而是使用插件方法设置,例如setBotEventListener、setPermissionCallback。- 通知栏消息开关通过
toggleNotification控制,不通过options传入。
uiCustomization 聊天界面样式
options.uiCustomization 用于自定义聊天界面的主题、头像、气泡、输入框等样式。
uiCustomization 支持字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| titleBackgroundColor | string | 导航栏背景色,例如 #337EFF |
| titleBarStyle | number | 导航栏风格 |
| titleCenter | boolean | 标题是否居中 |
| titleBackgroundResId | number | 标题栏背景资源 ID |
| statusBarColor | string | 状态栏颜色 |
| isShowTitleAvatar | boolean | 是否在标题栏展示头像 |
| avatarShape | number | 头像形状。0 圆形,1 方形 |
| leftAvatar | string | 客服头像 URL |
| rightAvatar | string | 访客头像 URL |
| hideLeftAvatar | boolean | 是否隐藏客服头像 |
| hideRightAvatar | boolean | 是否隐藏访客头像 |
| priorityWebAvatar | boolean | 头像是否管理端优先 |
| hideLeftName | boolean | 是否隐藏客服名称 |
| msgBackgroundColor | string | 聊天背景色 |
| msgBackgroundUri | string | 聊天背景图片 |
| msgListViewDividerHeight | number | 消息竖直方向间距 |
| textMsgColorLeft | string | 客服文本消息字体颜色 |
| textMsgColorRight | string | 访客文本消息字体颜色 |
| textMsgSize | number | 消息文本字体大小 |
| textMsgLineSpacingExtra | number | 文本消息额外行间距,单位 dp |
| hyperLinkColorLeft | string | 客服消息中超链接颜色 |
| hyperLinkColorRight | string | 访客消息中超链接颜色 |
| tipsTextColor | string | 提示消息字体颜色 |
| tipsTextSize | number | 提示消息字体大小 |
| topTipBarTextColor | string | 会话顶部提示条文字颜色 |
| topTipBarTextSize | number | 会话顶部提示条文字大小 |
| topTipBarBackgroundColor | string | 会话顶部提示条背景色 |
| inputTextColor | string | 输入框文字颜色 |
| inputTextSize | number | 输入框文字大小 |
| editTextHint | string | 输入框占位文案 |
| buttonTextColor | string | 发送、选择等按钮文字颜色 |
| robotBtnTextColor | string | 机器人消息按钮文字颜色 |
| inputUpBtnTextColor | string | 输入框上方按钮文字颜色 |
| hideAudio | boolean | 是否关闭人工客服会话语音入口 |
| hideAudioWithRobot | boolean | 是否关闭机器人阶段语音入口 |
| hideEmoji | boolean | 是否关闭表情入口 |
| isRobotSendImage | boolean | 机器人阶段是否展示发送图片入口 |
| showRobotImageEntry | number | 机器人阶段相机按钮样式。0 展示相机图标,1 展示 “+” 图标,需 isRobotSendImage 为 true 时生效 |
| isRobotMessageFold | boolean | 机器人回复超长消息是否折叠 |
| hideKeyboardOnEnterConsult | boolean | 进入聊天界面时是否不自动弹出键盘 |
| disableKeyboardOnEnterConsult | boolean | 进入聊天界面时是否禁用键盘 |
| screenOrientation | number | 横竖屏。0 竖屏,1 横屏,2 重力感应 |
| isFullScreen | boolean | 是否全屏,仅横屏下生效 |
调用顺序与注意事项
调用 updateOptions 会重新更新 SDK 配置。如果之前已经调用过 setBotEventListener 或 setPermissionCallback,这些事件配置可能会被新的 SDK 配置覆盖。建议调用顺序为:
qiyuModule.updateOptions(options, urlCallback);
qiyuModule.setBotEventListener(botCallback);
qiyuModule.setPermissionCallback(permissionCallback);URL 点击或权限弹窗时关闭聊天页
Uniapp 弹窗层级可能低于 Android 原生聊天页。若需要在链接点击或权限申请时弹出 Uniapp 页面,可先打开该开关,让插件在回调前关闭聊天页。
qiyuModule.setFinishPageSwitch(true);| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| finish | boolean | 是 | true 表示触发 URL 点击或权限回调时关闭聊天页 |
注意事项
该开关主要用于 Uniapp 弹窗被 Android 原生聊天页遮挡的场景。开启后,点击 URL 或触发权限回调时会关闭当前聊天界面,再让 App 展示 Uniapp 弹窗或页面。
服务直达或机器人快捷入口点击回调
用于拦截聊天页中服务直达 URL、机器人快捷入口等点击事件。插件回调 URL 后会返回 true,表示点击事件由 App 自行处理。
qiyuModule.setBotEventListener((url) => {
plus.runtime.openWeb(url);
});如果已经调用 setFinishPageSwitch(true),插件会在回调后关闭当前聊天页。
获取未读数
qiyuModule.allUnreadCount((count) => {
console.log("七鱼未读数", count);
});清空未读数
qiyuModule.clearUnreadCount();监听未读数变化
qiyuModule.addUnreadCountChangeListener({
register: true
}, (count) => {
console.log("七鱼未读数变化", count);
});
// 不再监听时注销
qiyuModule.addUnreadCountChangeListener({
register: false
}, () => {});| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| register | boolean | 是 | true 注册监听,false 注销监听 |
| callback | function | 是 | 未读数变化时回调,参数为当前未读数 |
获取最后一条消息
onReceiveMessageCallback 查询当前最后一条客服消息。若最后一条消息有七鱼自定义附件,回调附件内容;否则回调普通消息内容。
qiyuModule.onReceiveMessageCallback((message) => {
console.log("最后一条消息", message);
});权限申请回调
Android SDK 在相机、麦克风、相册、通知栏等权限申请前会触发该回调。App 可以通过该回调展示自定义权限说明弹窗,再决定继续申请权限或拦截。
插件默认提供运行时权限说明弹窗。若 App 需要按自身业务场景展示权限用途说明,可以自行实现权限说明弹窗,例如说明“发送图片需要访问相册”“视频客服需要使用相机和麦克风”。
注意事项
- 如果自行实现运行时权限说明弹窗,建议先调用
setFinishPageSwitch(true)。由于 Uniapp 弹窗层级低于 Android 原生聊天页,不关闭聊天页时可能看不到 Uniapp 弹窗。 - 如果合规要求“用户点击允许后必须立即打开对应功能”,例如允许相机权限后马上打开相机,则不建议使用自定义 Uniapp 权限弹窗。因为 Uniapp 弹窗需要关闭聊天界面才能展示,可能和“授权后立即继续原功能”的要求冲突。这种场景建议使用插件默认运行时弹窗说明。
- 用户确认授权说明后,调用
onProcessEventSuccess()让 SDK 继续执行后续权限申请或功能动作;用户取消或 App 决定拦截时,调用onInterceptEvent()。
建议先设置:
qiyuModule.setFinishPageSwitch(true);然后注册权限回调:
qiyuModule.setPermissionCallback((ret) => {
const data = typeof ret === "string" ? JSON.parse(ret) : ret;
if (data.onDenyEvent) {
uni.showModal({
title: "权限被拒绝",
content: `${data.permissionList || "相关"}权限未开启,请在系统设置中允许后再使用`
});
return;
}
uni.showModal({
title: "权限申请说明",
content: `当前功能需要使用${data.permissionList}权限`,
success(res) {
if (res.confirm) {
qiyuModule.onProcessEventSuccess();
} else {
qiyuModule.onInterceptEvent();
}
}
});
});回调数据字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| scenesType | number | 权限申请场景 |
| permissionList | string | 权限名称,可能为 麦克风、相机、存储、多媒体文件、通知栏权限,多个权限用顿号拼接 |
| onDenyEvent | boolean | 是否为权限被拒绝后的回调 |
scenesType 取值:
| 值 | 场景 |
|---|---|
| 0 | 从本地选择媒体文件,包括图片和视频 |
| 1 | 拍摄视频 |
| 2 | 保存图片到本地 |
| 3 | 保存视频到本地 |
| 4 | 选择本地视频 |
| 5 | 选择本地文件 |
| 6 | 选择本地图片 |
| 7 | 拍照 |
| 8 | 录音 |
| 9 | 视频客服 |
| 10 | 通知栏权限 |
处理结果方法:
| 方法 | 说明 |
|---|---|
| onProcessEventSuccess() | App 已完成弹窗说明,允许 SDK 继续执行权限申请或后续动作 |
| onInterceptEvent() | App 拦截该事件,SDK 不继续执行后续动作 |
这篇文档有帮助吗?