连接与生命周期

一个 Flutter IM SDK 实例维护一个活动用户。将实例放在应用或账号会话层管理，聊天页面复用同一连接与数据状态。

初始化顺序

普通 IM：初始化 SDK → 取得 IM Session → connect → 展示连接与同步状态。需要通话时：初始化 IM → 初始化 Call SDK → IM connect，详见 音视频接入。

API	使用时机	结果
initialize(config)	应用准备 IM 时	建立配置；同一实例不能换一套配置重复初始化
connect(session)	首次登录	建立用户上下文与连接
switchUser(session)	切换账号	先收尾旧账号操作，再连接新账号
disconnect()	暂时退出 IM	断开连接和内存 Session，保留磁盘缓存
dispose()	永久释放实例	释放资源；不能再把它作为活动实例使用
clearLocalData(userId)	用户确认清理本机数据	清理指定用户的本地数据

区分连接与同步

connected 表示连接已建立，历史同步进度单独呈现。连接状态使用 connectionStateStream，同步过程使用 syncProgressStream；聊天内容和摘要从共享控制器读取。

final sdk = MixinImSdk.instance;
final connectionSubscription = sdk.connectionStateStream.listen((state) {
  // 由宿主根据 state 更新连接提示，不在此输出 Token。
});
final syncSubscription = sdk.syncProgressStream.listen((progress) {
  // 由宿主呈现同步进度，业务登录态单独管理。
});

// 持有这些订阅的宿主组件释放时执行。
await connectionSubscription.cancel();
await syncSubscription.cancel();

这是订阅与释放的片段；实际应用应在组件生命周期内持有订阅，而非创建后立即取消。

断线与恢复

SDK 负责心跳和带抖动的退避重连，持续处理可恢复的网络故障。宿主订阅连接状态即可，无需额外轮询 connect。主动退出、永久释放和鉴权终止后停止自动重连。

应用回到前台时可调用 await sdk.syncNow() 补齐状态。该入口会合并同一时刻的同步请求。进入聊天页使用 sdk.setActiveConversation(conversationId)，离开时传 null，让恢复过程优先处理当前会话。

账号隔离

切号时等待 switchUser 完成，再切换界面中的用户上下文。取消旧用户的页面订阅和异步回调，使消息、未读、群资料和续签始终归属对应账号。

账号退出由业务后端撤销 Session，并由客户端结束连接；磁盘缓存按产品的数据保留策略单独处理。详见 登录与 IM Session。网络诊断见 故障排查。