SDK 认证与 Token

原生与跨端访客 SDK 使用 visitor_token 认证。正式环境由宿主业务服务端签发 Token；客户端只负责通过 tokenProvider 获取并交给 SDK 使用。

正式环境流程

宿主 App 已登录用户
        ↓
SDK 调用 tokenProvider
        ↓
宿主 App 请求自己的业务后端
        ↓
业务后端使用商户 apiKey 签发 visitor_token
        ↓
SDK 调用 /sdk/visitor/*（Authorization: Bearer <visitor_token>）

apiKey 不得下发到公开客户端

商户 apiKey 是签名密钥。正式 App、小程序和 Web 前端必须使用 tokenProvider，不得把 apiKey 写进源码、配置文件或浏览器脚本。

Token 格式

visitor_token 为 HS256 三段式 JWT：

base64url(header) + "." + base64url(payload) + "." + base64url(signature)

Header 固定为：

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload 只包含以下字段：

{
  "bid": "<商户 ID>",
  "uid": "<宿主系统中的稳定访客 ID>",
  "exp": 1784000000
}

字段	说明
bid	商户 ID，必须为当前有效商户。
uid	在同一商户下稳定唯一的访客 ID。
exp	Unix 秒级过期时间戳。

签名计算：

signature = HMAC_SHA256(base64url(header) + "." + base64url(payload), apiKey)

不要向 Payload 加入昵称、头像、属性、设备信息或其他自定义字段。访客资料由 SDK 的 VisitorProfile 同步，服务端只信任签名校验后的 bid、uid 和 exp。

各平台的 Token Provider

平台	Provider 形式
Android Kotlin	suspend () -> String
iOS Swift	() async throws -> String
Flutter	Future<String> Function()
React Native	() => Promise<string>
uni-app	() => Promise<string>

Token Provider 每次被调用时都应返回当前有效的 Token。SDK 会在首次业务请求、Token 距离过期不足 60 秒或服务端明确拒绝当前 Token 时自动刷新；并发请求会合并为一次 Provider 调用。

平台无关示例

Visitor.configure(
  config: { baseUrl: "https://<客服系统域名>" },
  auth: VisitorAuth.tokenProvider(() => appApi.fetchVisitorToken()),
  visitor: { nickname: "当前用户显示名" }
)

其中 appApi.fetchVisitorToken() 只能访问宿主自身的后端接口。SDK 不提供、也不需要单独的“登录 SDK”接口。

调试方式

本地联调可使用 VisitorAuth.apiKey(apiKey, bid, uid)。它在客户端生成一小时有效的 Token，业务请求与生产 Token 完全相同；仅适用于商户明确认可的可信调试环境。

调试完成后必须切换回 tokenProvider，并检查构建产物、日志和错误上报中不包含 API Key 或完整 Token。