登录与 IM Session

业务登录态负责进入你的产品，IM Session 负责访问通信服务。两者分别签发和管理；客户端不持有 Server API 签名密钥。

登录链路

1. 客户端向客户业务服务完成登录。
2. 业务服务校验用户身份、账号状态和访问权限。
3. 业务服务签名调用 IM 的 POST /external/auth/token。
4. 业务服务把当前用户的 IM Session 返回客户端。
5. SDK 使用 Session 直连 IM REST 与 WebSocket，开始连接与同步。

签名接口由业务后端调用；取得 Session 后，SDK 直接连接 IM 服务收发消息。签名方法见 Server API 鉴权。

签发请求

以下是发送给 IM 服务的请求体示例，Header 必须由业务后端生成。示例账号仅用于说明字段。

{
  "userId": 90001,
  "account": "demo-user-a",
  "nickname": "测试用户 A",
  "status": "enabled",
  "deviceCode": "demo-device-a",
  "deviceType": "android"
}

成功结果的 data 包含 userId、access_token、expire_in、expires_at、deviceCode、deviceType。expires_at 是 Unix 毫秒时间戳，转换成 Flutter DateTime 时使用毫秒单位。示例中的设备标识替换为宿主维护的稳定值。

deviceType 使用对应平台接入说明约定的值，并在签发、连接和续签时保持一致。

Flutter 连接与续期

import 'package:mixinim_sdk/mixinim_sdk.dart';

Future<void> connectIm({
  required MixinImSession session,
  required Future<MixinImSession> Function(MixinImSession) renew,
}) async {
  final sdk = MixinImSdk.instance;
  await sdk.initialize(MixinImConfig(
    apiBaseUrl: Uri.parse('https://im.example.com/'),
    websocketUrl: Uri.parse('wss://im.example.com/websocket'),
    storageNamespace: 'example_app',
    websocketTicketRequired: true,
    refreshSession: renew,
  ));
  await sdk.connect(session);
}

session 和 renew 由宿主提供：renew 调用客户业务服务获取新 Session，签名在业务后端完成。客户端票据配置与服务端保持一致，并使用配套组件版本。

传入 expiresAt 后，Flutter SDK 在过期前五分钟触发续签。刷新结果保持同一用户、设备与平台。每次新续期使用新的业务幂等键；同一次签发的网络重试复用原幂等键。

主动退出与撤销

业务后端调用 POST /external/auth/revoke，请求含 userId；指定 deviceCode 只撤销目标设备，不指定则撤销该用户全部设备。随后客户端调用 disconnect()。若产品要求删除本机历史，再显式清理本地数据。

服务端明确撤销 Session 后，SDK 进入需要重新认证的状态，不自动续签重新登录。业务后端也应撤销目标业务登录态，防止旧业务 Token 再次换取 IM Session。

获取 IM Session 失败时，保留业务登录并展示通信连接提示；取得有效 Session 后再连接 SDK。后续阅读 连接与生命周期。