99客服开发文档

Appearance

访客 SDK 总览 ​

99 客服访客 SDK 用于在网站、App 或跨端应用中接入访客聊天能力。普通接入直接打开 SDK 内置聊天页；需要自定义界面时，使用各平台的 Core API 实现消息、实时同步和上传。

选择接入方式 ​

平台适用场景
Web / H5网站悬浮入口、嵌入式咨询页或独立窗口。
Android原生 Android App 的完整聊天页或自定义界面。
iOS原生 iOS App 的完整聊天页或自定义界面。
uni-appApp 与小程序项目。
FlutterFlutter App。
React NativeReact Native / Expo Development Client 项目。

统一生命周期 ​

除 Web Widget 外，各原生与跨端 SDK 使用相同的生命周期：

text
Visitor.configure(config, auth, visitor?)
        ↓
Visitor.openChat(options)
        ↓
SDK 按需取得 visitor_token、分配客服、加载数据并连接实时服务
        ↓
Visitor.logout()
  • configure 只保存本地配置，不会立即请求网络。
  • 首个业务请求、Token 即将过期或服务端拒绝 Token 时，SDK 调用宿主提供的 tokenProvider。
  • logout 清除当前 Token、会话和实时连接，不向服务端发起退出请求。

身份与安全边界 ​

SDK 有两种认证方式：

方式适用环境说明
VisitorAuth.tokenProvider(...)正式生产宿主 App 向自己的服务端取得短期 visitor_token。推荐且必须用于公开发布的应用。
VisitorAuth.apiKey(apiKey, bid, uid)本地联调、内部可信环境在客户端本地签名 Token；会把商户密钥置入安装包，不得用于公开应用。

完整规则和服务端签发格式见认证与 Token。

平台一致性 ​

各 SDK 保持相同的身份、路由、字段和实时语义：

  • 所有 SDK 业务请求使用 Authorization: Bearer <visitor_token> 调用 /sdk/visitor/*。
  • 身份由 Token 中的 bid、uid 确认，业务请求不重复传递这两个字段。
  • groupId 对应 HTTP 字段 group_id；channel 是客服可见的业务来源标签，不是实时订阅频道。
  • 消息按 mid 去重；断线后重新订阅，并通过消息历史补齐。
  • contexts 不传表示保留已有咨询上下文，显式传空数组表示清空。

下一步 ​

  1. 阅读认证与 Token，准备正式环境的 Token Provider。
  2. 选择目标平台完成安装与 configure。
  3. 使用 openChat() 快速验证会话、客服分配和实时消息。

Copyright © 99客服