Flutter 从零接入晞晗IM

本页面向 Flutter 应用。完成后，你可以在 Android、iOS 或 macOS 工程中连接账号， 监听数据变化并发送第一条文字消息。

1. 准备接入信息

向服务端负责人领取：

Server URL       例如 https://im-test.example.com
当前用户 ID      例如 alice
对端用户 ID      例如 bob

正式环境还需要应用自己的后台提供短期 XHIM 凭证。

2. 添加 Flutter 包

在 pubspec.yaml 中使用团队提供的固定版本：

dependencies:
  xhim_flutter:
    git:
      url: git@git.xihansoftware.com:laowang/xhimsdk.git
      path: platforms/flutter/xhim_flutter
      ref: <团队锁定的版本标签>

然后执行：

flutter pub get

Android 工程还需配置团队提供的 Maven 地址；iOS/macOS 工程需配置团队提供的 CocoaPods Specs。应用开发者只需引用对应版本的 Flutter 包和原生依赖。

3. 连接账号并监听变化

onEvent 会在 Native 开始连接前安装，因此不会漏掉连接早期事件：

final client = await XHIMFlutterClient.connect(
  server: 'https://im.example.com',
  userId: currentUserId,
  credentialProvider: accountService.fetchXHIMCredential,
  onEvent: (event) {
    imStore.handleXHIMEvent(event);
  },
);

每个登录账号只创建一个 XHIMFlutterClient，放在账号级 Service 或 Store 中。 页面不要重复连接，也不要保存访问凭证。

Development Server 已启用测试登录时，可以暂时省略 credentialProvider。

4. 发送第一条消息

final conversationId = await client.directConversation('bob');

await client.sendText(
  conversationId: conversationId,
  text: '你好，晞晗IM',
);

让 Bob 使用同一个 Server 登录。收到事件后，由 imStore 重新查询当前会话和消息， 即可显示新消息。

5. 登出和换号

普通页面销毁时不要关闭账号 Client。用户真正登出时：

await client.logout();
await client.close();

切换账号后，使用新用户 ID 创建新的 Client，不复用旧账号对象。

6. 使用可选 UI Kit

如果不想从零编写会话列表和聊天页，可继续使用 xhim_flutter_ui。它提供会话列表、聊天页、 通讯录、好友申请、群组、消息气泡、输入框和媒体入口。

UI Kit 是可选包。你可以只使用 xhim_flutter，在现有 Bloc、Provider、Riverpod 或 MVVM 项目中编写自己的页面。

完整页面和目录组织可直接运行 Flutter UI Kit 示例应用查看。

7. 常用功能入口

任务	方法
查询消息历史	client.getMessageHistory(...)
标记会话已读	client.markConversationRead(...)
发送图片	client.sendImage(...)
发送业务消息	client.sendMessage(...)
查询用户资料	client.currentUserProfile()
查询好友和群组	client.friendships() / client.groups()
创建群	client.createGroup(...)
查询在线状态	client.queryPresence(...)
取消长请求	传入 XHIMCancellationToken

参数、返回值、错误和完整示例见 SDK API Reference。

8. 运行 Demo

cd platforms/flutter/xhim_flutter/example
flutter pub get
flutter run

先在两个模拟器或设备上使用 Alice、Bob 验证文字消息，再继续接媒体、群组和自定义 消息。Demo 的账号容器、Store、页面和资源目录可以直接作为二次开发参考。

9. 原生工程最低配置

• iOS 15.0 或更高；
• macOS 12.0 或更高；
• Android 使用当前发行包声明的最低 SDK；
• Flutter 插件版本必须与 Android AAR 和 Apple XHIM 包保持一致。

版本不一致时不要通过手工复制动态库绕过检查，应更换为同一版本的完整制品。

10. 常见问题

找不到 Android 的 xhim-sdk

宿主工程尚未配置团队提供的 Maven 仓库，或仓库凭证无效。检查 settings.gradle(.kts) / build.gradle(.kts) 的仓库配置。

iOS 或 macOS 执行 pod install 失败

确认私有 Specs 源可访问，且 Podfile 最低版本分别不低于 iOS 15、macOS 12。

能发送但页面不刷新

确认连接时传入了 onEvent，并在数据变化后由 Store 重新查询当前会话。

如何确认实际加载的 SDK 版本

final metadata = await XHIMSDK.metadata();
debugPrint('${metadata.version} ${metadata.sourceCommit}');

该方法只读取本机 SDK 信息，不访问服务端。