XHIM 用户与群聊二维码

XHIM 二维码用于在客户端之间安全地传递“查看用户资料”或“查看群聊”的入口，不把内部 user_id、group_id、登录 Token 或管理密钥直接编码到图片中。

编码格式

text

xhim://qr/v1/<opaque-token>

v1 是二维码协议版本，客户端必须校验后再解析；
opaque-token 由 Server 使用 AES-256-GCM 生成，包含 App 隔离、目标类型、目标 ID、签发时间和过期时间；
默认有效期 30 天，可配置为 5 分钟到 365 天；
二维码只能由登录用户创建和解析，服务端会重新校验用户、群聊和成员关系；
图片本身只是传输载体，不能代替登录态、好友关系或入群审批。

创建二维码

http

POST /v1/qrcodes:create
Authorization: Bearer <user-access-token>
Content-Type: application/json

{
  "type": "user",
  "expires_in_seconds": 2592000
}

创建群聊二维码时传入当前用户有权访问的群聊：

json

{
  "type": "group",
  "conversation_id": "<internal-conversation-id>",
  "expires_in_seconds": 2592000
}

成功响应：

json

{
  "schema_version": 1,
  "type": "user",
  "payload": "xhim://qr/v1/...",
  "expires_at_ms": 1788256800000,
  "preview": {
    "display_name": "测试用户",
    "public_user_id": "XH12345678",
    "avatar_url": "https://cdn.example.com/avatar.png"
  }
}

扫码解析

http

POST /v1/qrcodes:resolve
Authorization: Bearer <user-access-token>
Content-Type: application/json

{
  "payload": "xhim://qr/v1/..."
}

用户二维码返回可展示的公开资料和 SDK 内部操作所需的 user_id；普通界面只展示 public_user_id，不展示内部 ID。群聊二维码返回：

json

{
  "schema_version": 1,
  "type": "group",
  "expires_at_ms": 1788256800000,
  "group": {
    "conversation_id": "group-conversation-id",
    "title": "项目协作群",
    "avatar_url": "https://cdn.example.com/group.png",
    "member_count": 12,
    "is_joined": false,
    "join_approval_required": true
  }
}

客户端必须以服务端解析结果为准：

用户二维码：进入资料页，非好友显示“添加好友”，好友显示“发送消息”；
is_joined = true：显示“进入群聊”并直接打开该会话；
未加入且 join_approval_required = false：执行 SDK 入群请求，成功后进入群聊；
未加入且 join_approval_required = true：提交入群申请，等待群管理员审批。

客户端不自行解密或信任二维码中的内容，好友关系、群成员关系和入群权限均由服务端与 SDK 再次校验。

iOS Demo 入口

我的 → 个人资料 → 我的二维码：生成并展示本人二维码；
通讯录 → 右上角加号 → 扫一扫：相机扫码或从相册识别；
群聊 → 右上角更多 → 群二维码：生成当前群聊二维码；
扫描后先进入用户资料页或群聊预览页，不会未经确认直接加好友或入群。

二维码请求属于 Demo 的业务 HTTP 接口，使用 Alamofire；消息收发、同步、关系链和媒体传输仍由 XHIM SDK 负责。本能力没有改变 C++ Core 的公开 ABI。

服务端配置与轮换

当前 Server 使用带专用域分离字符串的 SHA-256 从稳定的 Server Admin Key 派生二维码 AES-256-GCM 密钥，不会把 Admin Key 写入载荷。私有化部署时必须先配置高强度、稳定且至少 32 字符的 XHIM_ADMIN_KEY；直接更换该值会使已签发二维码失效，应在变更窗口内通知客户端刷新二维码。解析失败统一返回稳定错误码，不向客户端暴露密钥或密文解析细节。

常见错误：

错误码	含义
`invalid_qr_code`	格式、版本、密文或认证标签无效
`expired_qr_code`	二维码已过期，需要重新生成
`qr_target_not_found`	目标已删除或当前 App 不可见
`forbidden`	当前用户无权为目标生成或查看二维码

XHIM 用户与群聊二维码 ​

编码格式 ​

创建二维码 ​

扫码解析 ​

iOS Demo 入口 ​

服务端配置与轮换 ​

XHIM 用户与群聊二维码

编码格式

创建二维码

扫码解析

iOS Demo 入口

服务端配置与轮换