JSSDK 配置与签名

阅读指引：本篇是《开放平台服务端 API 指南》的第 8 部分。接口基础地址、通用约定与各接口请求限制，请先阅读《服务端 API 概览》。

11. JSSDK config 与受保护能力

JSSDK 已提供 ready、error、getAuthCode、config、closeWindow、chooseChat 和 openChat。getAuthCode/closeWindow 在 Bridge ready 后可直接调用；chooseChat/openChat 是受保护能力，必须先完成包含目标 JSAPI 的 config。

适用客户端类别为 Android、iOS 和 PC；实际可用能力以平台交付的客户端及 SDK 版本为准。JSSDK 最低版本为 1.0.0，Bridge 最低版本为 1.0。能力调用前仍会按当前客户端版本检查支持情况。

11.1 应用后端获取 jsapi_ticket

POST /openapi/v1/jssdk/ticket

curl -X POST "${OPENAPI_BASE_URL}/openapi/v1/jssdk/ticket" \
  -H "Authorization: Bearer ${APP_ACCESS_TOKEN}"

{
  "ticket": "jst_mim_xxx",
  "expires_in": 7200
}

有效期充足时，同一应用重复调用会复用当前 ticket；临近过期时平台轮换 ticket，并在短暂过渡期内接受仍有效的上一张 ticket。应用后端应按 expires_in 缓存，不要为每个页面请求一次 ticket。响应带有 Cache-Control: no-store 和 Pragma: no-cache，失败时返回 JSON 业务码而不返回 ticket。

请求体最大 1 MiB但不接收业务参数；同一应用与来源 IP 每分钟最多调用 60 次，并同时受来源 IP 每分钟 300 次的全局限制。

服务端专用app_secret、app access token 和 jsapi_ticket 都不能进入 H5、客户端包体、普通日志或错误响应。

11.2 应用后端计算签名

import crypto from "node:crypto"

const jsApis = [...new Set(["openChat"].map(v => v.trim()).filter(Boolean))].sort()
const signedUrl = pageUrl.trim().split("#")[0] // 保留 query 原顺序，不重编码
const canonical = `v=1&app_key=${appKey.trim()}` +
  `&js_api_list=${jsApis.join(",")}` +
  `&nonce=${nonce.trim()}&timestamp=${timestamp}&url=${signedUrl}`
const signature = crypto
  .createHmac("sha256", jsapiTicket)
  .update(Buffer.from(canonical, "utf8"))
  .digest("hex")

签名字符串必须严格按示例字段名和顺序构造，UTF-8 编码，字段值不额外 URL 编码，末尾不加换行。jsApiList 先 trim、去空、去重，再按区分大小写的字符串升序排序并用英文逗号连接；URL 只去掉 fragment，必须保留 query 的原值和顺序。

11.3 H5 调用 config

im.openPlatform.ready(() => {
  // config 成功且 Bridge ready 后触发。
})

im.openPlatform.error(err => console.error(err.code, err.message))

await im.openPlatform.config({
  appKey: "svc_app_xxx",
  timestamp: 1787366400000,
  nonce: "nonce_20260822_001",
  signature: "b4be79f21080926eb10e7c3f81a50090a897a2731a10ccfbf9cf9d18a2389e2c",
  url: location.href.split("#")[0],
  jsApiList: ["openChat"]
})

chooseChat 用于选择用户会话列表，选择数量由用户自行决定；对应应用权限默认授予，当前状态为可用。调用前须完成 ready/config，获得 chat:conversation:choose，并由已登录用户的点击触发。该选择器由客户端 SDK 提供；具体入参和返回对象须使用平台交付 SDK 的类型定义，不得自行假设返回字段或用组织用户 ID 代替会话 ID。

config 成功后，本页只能调用 jsApiList 中已批准的受保护 JSAPI。配置过期、页面 URL 变化或应用权限变化后，应重新取得签名并调用 config；具体能力仍会校验当前用户的资源访问权和必要的用户手势。

JSSDK config 用于启用客户端能力，不应当作应用后端的用户登录凭据或业务授权证明。后端识别当前用户时须完成 OAuth2 换码并验证用户 Token 对应的身份，不能信任 H5 自报的用户信息。

11.4 closeWindow

await im.openPlatform.closeWindow()

closeWindow() 无参数，需要 Bridge ready，不需要 config、Scope 或用户登录上下文。Promise resolve 表示关闭请求已由容器接受；它只能关闭当前应用 WebView，不能指定或关闭其他窗口。

11.5 openChat

await im.openPlatform.openChat({
  conversationId: "conversation_xxx"
})

// 只打开当前用户有权访问的会话；不读取消息，也不代替用户发送消息。

调用前必须满足：Bridge ready；当前 config 尚未过期且 jsApiList 包含 openChat；管理员已授予 chat:conversation:open；当前登录用户仍有权访问目标会话。每次调用都会重新检查用户手势和会话访问权。

11.6 统一 JSSDK 错误

所有返回 Promise 的 JSAPI 失败时 reject 以下对象；Bridge 初始化或 config 失败还会触发通过 error(callback) 注册的回调。