七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入

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 启动后调用一次。完成初始化后,未读数、客服主动发送消息等能力才能正常工作。

注意事项

  1. Android 端 appKey 必须在 manifest.json 的原生插件配置中填写。如果没有配置,运行时会提示“请在原生插件配置里面填入网易七鱼appKey”。
  2. 避免在调用 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 可能包含异常信息
  }
});
参数类型必填说明
userIdstring是App 用户唯一标识。相同 userId 会关联同一访客身份和会话记录
authTokenstring否用户认证令牌。仅当管理后台开启 authToken 校验时需要传,由 App 服务端生成
datastring否用户资料 JSON 字符串。需要使用 JSON.stringify(array) 传入

data 数组元素字段:

字段类型必填说明
keystring是字段标识。real_name、mobile_phone、email 是七鱼保留字段
valuestring是字段值
labelstring否客服端展示名称。保留字段的展示名称固定,不受该字段影响
indexnumber否展示排序,越小越靠前
hrefstring否超链接地址。配置后客服端可点击跳转
hiddenboolean否是否隐藏字段。目前主要用于手机号、邮箱

注意事项

  1. 如果 App 需要指定登录用户,并避免展示默认匿名访客名称,必须传 userId。
  2. authToken 只有在管理后台开启用户认证校验时才需要传。该值应由 App 服务端生成,客户端负责透传。
  3. 如果需要更新同一个用户的信息,保持 userId 不变,只更新 data 即可。切换到另一个用户前,应先调用 logout。

打开客服界面

openServiceActivity 打开 Android 客服页面。常用做法是在用户点击“联系客服”时调用;如果需要先上报用户信息,可以在 setUserInfo 成功回调后再打开。

qiyuModule.openServiceActivity({
  title: "在线客服",
  source: {
    uri: "order_detail",
    title: "订单详情页",
    custom: "订单号:ORD123",
    groupId: 123456,
    robotFirst: true,
    vipLevel: 3
  }
});
参数类型必填说明
titlestring否客服页面标题。实际展示会受管理后台配置影响
sourceobject否咨询来源、客服分配、商品卡片等配置

source 常用字段:

字段类型说明
uristring咨询来源标识,可以是业务页面 URL,也可以是 order_detail 这类业务标识
titlestring咨询来源标题,客服端用于识别访客从哪里进入
customstring自定义透传信息,例如订单状态、商品摘要
groupIdnumber指定客服组 ID。可在管理后台「服务中心 - 在线系统 - 设置 - 会话流程 - 会话分配 - 自定义链接分配」查询
staffIdnumber指定客服 ID。设置后优先于 groupId
groupTmpIdnumber多入口分流模板 ID,由后台模板决定最终客服或客服组
robotFirstboolean是否先由机器人接待。通常和 groupId / staffId 一起使用,转人工后进入指定客服或客服组
robotIdnumber指定机器人 ID。不传时使用后台默认机器人
faqGroupIdnumber指定机器人热门问题组 ID
robotWelcomeMsgIdstring指定机器人欢迎语 ID
shortcutTemplateIdnumber常见快捷入口模板 ID
vipLevelnumber用户 VIP 等级。0 普通用户,1-10 VIP 等级,11 通用 VIP
shopIdstring平台电商商家 ID。非平台电商不需要传
productDetailobject打开会话时自动携带商品或订单卡片
cardDetailobject打开会话时自动携带自定义卡片消息
isSendProductonRobotboolean机器人阶段是否发送商品卡片
isSendProductionLeaveboolean留言阶段是否发送商品或卡片
isEnableVideoboolean是否开启视频客服
forbidUseCleanTopStartboolean是否禁止用 CLEAR_TOP 方式打开客服页,需要在当前客服页内再打开新客服页时可设为 true
clientIpAddressstring访客端 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" }
      ]
    }
  }
});

注意事项

  1. 如需上报用户信息,建议在 setUserInfo 成功回调后再调用 openServiceActivity。
  2. 避免在 initSdk 后立即打开客服界面。建议至少间隔 2 秒,避免 SDK 配置尚未完成导致界面样式与后台配置不一致。
  3. staffId 和 groupId 同时设置时,staffId 优先,groupId 会被忽略。
  4. groupId、staffId、groupTmpId、robotId 等 ID 不是 App 自行业务 ID,需要在七鱼管理后台对应配置页查询后传入。

商品卡片字段

productDetail 可放在 openServiceActivity.source.productDetail 中进入会话时自动发送,也可以通过 sendProductMessage 在会话中主动发送。

字段类型说明
titlestring商品标题,建议不超过 100 字符
descstring商品描述,建议不超过 300 字符
picturestring商品图片地址,需支持 file://、http:// 或 https://
urlstring商品详情页地址
notestring商品备注,例如价格、套餐、订单号,建议不超过 100 字符
shownumber是否在访客端显示。1 显示,0 或不传则仅客服可见
alwaysSendboolean是否每次打开会话都尝试发送。相同商品链接不会重复发送
sendByUserboolean是否由用户点击按钮后手动发送
actionTextstring手动发送按钮文案
actionTextColornumber手动发送按钮颜色,例如 0xFFDB7093
actionTextSizenumber手动发送按钮字体大小,单位 sp
reselectTextstring重新选择按钮文案
isOpenReselectboolean是否展示重新选择按钮
handlerTagstring点击重新选择时回传的标识
extstring扩展字段
cardTypenumber卡片类型。0 商品,1 订单,2 自定义
goodsCIdstring商品类目 ID
goodsCNamestring商品类目名称
goodsIdstring商品 ID。商品卡片推荐填写
orderIdstring订单 ID。订单卡片推荐填写
intentstring一触即达意图名称
paramsstring一触即达流程参数
orderStageTypenumber订单阶段类型
optionIdstring选项 ID
infostring卡片附加信息,不展示在前端卡片中
agentIdstring大模型 ID
tagsarray展示在客服端的操作入口

tags 数组元素字段:

字段类型说明
labelstring操作入口显示名称
urlstring点击后的跳转地址
focusIframestring如果要定位客服工作台右侧 iframe,可传 iframe 标识
datastring传给 iframe 的数据

注意事项

  1. 商品卡片用于把商品、订单等业务信息带给客服。cardType 为 0 时建议填写 goodsId,为 1 时建议填写 orderId。
  2. show 控制访客端是否可见。show: 1 时访客端也能看到卡片;不传或传 0 时通常只有客服端可见。
  3. sendByUser: true 表示卡片展示后由访客点击按钮发送,按钮文案可通过 actionText 配置。
  4. 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);
参数类型必填说明
textstring是文本内容
isLocalboolean是true 表示只展示在访客本地,false 表示发送给客服

注销用户

App 用户退出登录或切换账号时调用。否则前一个用户的客服消息可能仍然被当前设备收到。

qiyuModule.logout((ret) => {
  if (ret.success) {
    // 注销成功
  } else {
    // ret.errMsg 为失败原因或错误码
  }
});

也可以不传回调:

qiyuModule.logout();

通知栏消息开关

控制七鱼通知栏提醒是否开启。

qiyuModule.toggleNotification(false);
参数类型必填说明
onboolean是true 开启通知栏提醒,false 关闭

更新配置 updateOptions

updateOptions 用于在运行时更新七鱼 SDK 配置。方法签名:

qiyuModule.updateOptions(options, urlCallback);
参数类型必填说明
optionsobject是SDK 配置项,包含消息拉取、聊天界面样式等配置,字段见下表
urlCallbackfunction否聊天消息中 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 可配置字段如下:

字段类型说明
templateIdnumber对话框内容样式模板 ID,来自管理后台「样式设置」。不传则使用后台默认样式
isPullMessageFromServerboolean切换账户时是否从服务端拉取历史消息,默认 false
pullMessageCountnumber从服务端拉取历史消息数量,默认 20,最大 100。需 isPullMessageFromServer 为 true 时生效
isDefaultLoadMsgboolean会话开始时是否加载历史消息,默认 true
categoryDialogStylenumber咨询分类对话框样式:0 不弹出,1 从中间弹出,2 从底部弹出
autoTrackUserboolean是否自动记录用户访问轨迹,默认 false
isUseYsfNotificationConfigboolean是否使用七鱼通知配置,默认 true
disableAwakeboolean是否禁止后台进程唤醒 UI 进程,默认 true
asyncInitSDKboolean是否异步初始化 SDK,默认 false
isMixSDKboolean是否使用云信融合 SDK 功能,默认 false
preLoadServersboolean初始化后是否预加载服务,默认 false
isUseSAFboolean是否使用 SAF(存储访问框架)模式。国内版默认 false,海外版默认 true
isConfigMediaVisualUserSelectedboolean是否配置了 Android 14 的已选照片访问权限(READ_MEDIA_VISUAL_USER_SELECTED),默认 false
isCaptureVideoRecordAudioPermissionboolean录制视频时是否需要录音权限,默认 true
captureVideoRecordTipstring录制视频无录音权限时的提示文案
logSwitchboolean是否输出调试日志,默认 true
openLogboolean是否开启日志记录,默认 true
openFileSizeStatisticsboolean是否开启文件大小统计,默认 false
isOpenMoreLogboolean是否开启更多日志(数据库日志),默认 false
isDisableNetworkTraceboolean是否禁用网络检测,默认 false
messageCopyBtnSwitchboolean是否允许长按复制写入剪切板,默认 true
proximitySensorEnableboolean语音消息播放时是否使用距离传感器,默认 true
productOrderCardMessageWhiteBubbleEnabledboolean商品/订单卡片消息是否使用白色气泡,默认 false
uiCustomizationobject聊天界面样式配置,见下文

说明:

  • 回调、监听类配置不通过 options 传入,而是使用插件方法设置,例如 setBotEventListener、setPermissionCallback。
  • 通知栏消息开关通过 toggleNotification 控制,不通过 options 传入。

uiCustomization 聊天界面样式

options.uiCustomization 用于自定义聊天界面的主题、头像、气泡、输入框等样式。

uiCustomization 支持字段:

字段类型说明
titleBackgroundColorstring导航栏背景色,例如 #337EFF
titleBarStylenumber导航栏风格
titleCenterboolean标题是否居中
titleBackgroundResIdnumber标题栏背景资源 ID
statusBarColorstring状态栏颜色
isShowTitleAvatarboolean是否在标题栏展示头像
avatarShapenumber头像形状。0 圆形,1 方形
leftAvatarstring客服头像 URL
rightAvatarstring访客头像 URL
hideLeftAvatarboolean是否隐藏客服头像
hideRightAvatarboolean是否隐藏访客头像
priorityWebAvatarboolean头像是否管理端优先
hideLeftNameboolean是否隐藏客服名称
msgBackgroundColorstring聊天背景色
msgBackgroundUristring聊天背景图片
msgListViewDividerHeightnumber消息竖直方向间距
textMsgColorLeftstring客服文本消息字体颜色
textMsgColorRightstring访客文本消息字体颜色
textMsgSizenumber消息文本字体大小
textMsgLineSpacingExtranumber文本消息额外行间距,单位 dp
hyperLinkColorLeftstring客服消息中超链接颜色
hyperLinkColorRightstring访客消息中超链接颜色
tipsTextColorstring提示消息字体颜色
tipsTextSizenumber提示消息字体大小
topTipBarTextColorstring会话顶部提示条文字颜色
topTipBarTextSizenumber会话顶部提示条文字大小
topTipBarBackgroundColorstring会话顶部提示条背景色
inputTextColorstring输入框文字颜色
inputTextSizenumber输入框文字大小
editTextHintstring输入框占位文案
buttonTextColorstring发送、选择等按钮文字颜色
robotBtnTextColorstring机器人消息按钮文字颜色
inputUpBtnTextColorstring输入框上方按钮文字颜色
hideAudioboolean是否关闭人工客服会话语音入口
hideAudioWithRobotboolean是否关闭机器人阶段语音入口
hideEmojiboolean是否关闭表情入口
isRobotSendImageboolean机器人阶段是否展示发送图片入口
showRobotImageEntrynumber机器人阶段相机按钮样式。0 展示相机图标,1 展示 “+” 图标,需 isRobotSendImage 为 true 时生效
isRobotMessageFoldboolean机器人回复超长消息是否折叠
hideKeyboardOnEnterConsultboolean进入聊天界面时是否不自动弹出键盘
disableKeyboardOnEnterConsultboolean进入聊天界面时是否禁用键盘
screenOrientationnumber横竖屏。0 竖屏,1 横屏,2 重力感应
isFullScreenboolean是否全屏,仅横屏下生效

调用顺序与注意事项

调用 updateOptions 会重新更新 SDK 配置。如果之前已经调用过 setBotEventListener 或 setPermissionCallback,这些事件配置可能会被新的 SDK 配置覆盖。建议调用顺序为:

qiyuModule.updateOptions(options, urlCallback);
qiyuModule.setBotEventListener(botCallback);
qiyuModule.setPermissionCallback(permissionCallback);

URL 点击或权限弹窗时关闭聊天页

Uniapp 弹窗层级可能低于 Android 原生聊天页。若需要在链接点击或权限申请时弹出 Uniapp 页面,可先打开该开关,让插件在回调前关闭聊天页。

qiyuModule.setFinishPageSwitch(true);
参数类型必填说明
finishboolean是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
}, () => {});
参数类型必填说明
registerboolean是true 注册监听,false 注销监听
callbackfunction是未读数变化时回调,参数为当前未读数

获取最后一条消息

onReceiveMessageCallback 查询当前最后一条客服消息。若最后一条消息有七鱼自定义附件,回调附件内容;否则回调普通消息内容。

qiyuModule.onReceiveMessageCallback((message) => {
  console.log("最后一条消息", message);
});

权限申请回调

Android SDK 在相机、麦克风、相册、通知栏等权限申请前会触发该回调。App 可以通过该回调展示自定义权限说明弹窗,再决定继续申请权限或拦截。

插件默认提供运行时权限说明弹窗。若 App 需要按自身业务场景展示权限用途说明,可以自行实现权限说明弹窗,例如说明“发送图片需要访问相册”“视频客服需要使用相机和麦克风”。

注意事项

  1. 如果自行实现运行时权限说明弹窗,建议先调用 setFinishPageSwitch(true)。由于 Uniapp 弹窗层级低于 Android 原生聊天页,不关闭聊天页时可能看不到 Uniapp 弹窗。
  2. 如果合规要求“用户点击允许后必须立即打开对应功能”,例如允许相机权限后马上打开相机,则不建议使用自定义 Uniapp 权限弹窗。因为 Uniapp 弹窗需要关闭聊天界面才能展示,可能和“授权后立即继续原功能”的要求冲突。这种场景建议使用插件默认运行时弹窗说明。
  3. 用户确认授权说明后,调用 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();
      }
    }
  });
});

回调数据字段:

字段类型说明
scenesTypenumber权限申请场景
permissionListstring权限名称,可能为 麦克风、相机、存储、多媒体文件、通知栏权限,多个权限用顿号拼接
onDenyEventboolean是否为权限被拒绝后的回调

scenesType 取值:

值场景
0从本地选择媒体文件,包括图片和视频
1拍摄视频
2保存图片到本地
3保存视频到本地
4选择本地视频
5选择本地文件
6选择本地图片
7拍照
8录音
9视频客服
10通知栏权限

处理结果方法:

方法说明
onProcessEventSuccess()App 已完成弹窗说明,允许 SDK 继续执行权限申请或后续动作
onInterceptEvent()App 拦截该事件,SDK 不继续执行后续动作

这篇文档有帮助吗?

目录