uni-app 接入

uni-app SDK 为 App、小程序和 H5 提供内置访客聊天页。请使用访客 SDK 模块 uni_modules/99agent-visitor-sdk，不要只复制其中的单个 JavaScript 文件。

增值服务

uni-app 接入属于单独付费的项目。如需获取 uni-app SDK 源码包或安排接入支持，请联系我们。

安装并注册聊天页

将整个 uni_modules/99agent-visitor-sdk 目录复制到您的 uni-app 项目同一路径，然后在 pages.json 注册聊天页和预览页：

{
  "pages": [
    {
      "path": "uni_modules/99agent-visitor-sdk/pages/chat/chat",
      "style": {
        "navigationStyle": "custom",
        "disableScroll": true,
        "app-plus": {
          "softinputMode": "adjustResize",
          "background": "#F6F7F9"
        }
      }
    },
    {
      "path": "uni_modules/99agent-visitor-sdk/pages/image-preview/image-preview",
      "style": {
        "navigationStyle": "custom",
        "navigationBarTextStyle": "white",
        "pageOrientation": "portrait",
        "disableScroll": true,
        "app-plus": { "background": "#000000" }
      }
    },
    {
      "path": "uni_modules/99agent-visitor-sdk/pages/video-preview/video-preview",
      "style": {
        "navigationStyle": "custom",
        "navigationBarTextStyle": "white",
        "pageOrientation": "portrait",
        "disableScroll": true,
        "app-plus": { "background": "#000000" }
      }
    }
  ]
}

配置访客身份

在用户登录成功后进行配置。用户 ID 由业务服务端在访客令牌中确认；客户端配置昵称、头像，以及 attributes（即 visitor.attr 扩展信息）。业务服务端应根据当前用户生成访客令牌，客户端只获取令牌；签发方式请参阅用户基础信息对接。

import { Visitor, VisitorAuth } from '@/uni_modules/99agent-visitor-sdk'

Visitor.configure({
  config: {
    baseUrl: 'https://live.99kf.com',
    language: 'zh-CN'
  },
  auth: VisitorAuth.tokenProvider(async () => {
    const result = await yourApi.getVisitorToken()
    return result.visitor_token
  }),
  visitor: {
    nickname: '张三',
    avatar: 'https://www.99kf.com/avatar/12.jpg',
    attributes: [
      { key: 'phone', label: '电话', value: '13800138000' },
      { key: 'name', label: '姓名', value: '张三' }
    ]
  }
})

其中 phone、name 需与客服端的访客字段设置一致。

打开聊天页

await Visitor.openChat({
  groupId: 0,
  title: '在线客服'
})

传递业务上下文

可在打开聊天页时传入当前商品、订单或其他业务资料，客服可在会话中查看：

await Visitor.openChat({
  groupId: 0,
  contexts: [{
    key: 'order:ORDER-1001',
    type: 'order',
    title: '最近订单',
    fields: [
      { key: 'status', label: '订单状态', value: '待发货' }
    ]
  }]
})

字段格式和更多示例请参阅商品和订单对接。

未读计数

可用未读数更新 App 或小程序的红点、角标：

const unreadListener = {
  onUnreadCountChanged(count) {
    // 更新宿主应用的红点或数字
  }
}

Visitor.addUnreadListener(unreadListener)
const count = await Visitor.unreadCount() // 需要时立即取得当前未读数

首次成功取得未读数和后续数值变化都会通知监听器。不再需要时调用 Visitor.removeUnreadListener(unreadListener)。

小程序与 App 配置

微信小程序需要在小程序后台把客服服务域名加入 request、uploadFile、downloadFile 和 socket 的合法域名名单。App 和小程序如需发送图片、文件或语音，还需要按平台配置相册、麦克风和网络权限。