晞晗IM（XHIM）客户端 SDK 接入总览

适用范围：当前公开 SDK
本页面向所有客户端开发者。每个平台只设一个主接入页，安装方式、可选 UI 和高级用法都从该页面继续进入。

先选你的阅读路径

你现在要做什么	从哪里开始	读到哪里可以停
第一次接入	本页第 1～4 节 + 当前平台 QuickStart	两个账号互发第一条消息
开发聊天/通讯录/群页面	SDK API Reference	当前业务模块对应章节
改 UI、加业务消息或接公司账号	使用 Demo 进行二次开发	完成对应功能并通过双账号验证
排查连接、收不到消息或旧版本兼容	当前平台“排错” + 生命周期	拿到 stableCode/traceID 和复现步骤
做服务端部署或管理员功能	Server 文档	不需要继续读客户端内部实现

文档采用“先跑通、再理解、最后扩展”的顺序。第一次接入从选择平台、连接账号和发送第一条消息开始。

如果你是第一次接入，先完成这七步：

text

1. 领取 Server URL 和测试账号
2. 按当前平台安装 SDK
3. 在账号层创建并连接 Client
4. 注册连接和数据变化监听
5. 等待连接成功
6. 发送第一条消息，并在变化通知后重新查询
7. 验证登出、换号和断网恢复

你不需要自行部署服务端，也不需要先理解 SDK 内部实现。

1. 选择你的平台

平台	从空白工程开始	可选 UI
iOS	iOS 接入	CocoaPods / Swift Package；`XHIMSwiftUI` 可选
macOS	macOS QuickStart	`XHIMSwiftUI`
Android	Android Java 接入	Java/XML 为默认；SDK 总览列出 Kotlin/Compose 兼容选项
Windows	Windows QuickStart	`XHIM.UI.Wpf`
HarmonyOS	HarmonyOS QuickStart	ArkUI 组件
Web	Web QuickStart	React/Vue/Svelte/原生 DOM 自定义 UI
Electron	Electron QuickStart	Renderer 自定义 UI
Flutter	Flutter QuickStart	页内可继续选择 Flutter UI Kit
React Native	React Native 接入	React Native UI 自定义
Unity	Unity 接入	Unity UI 自定义
uni-app	uni-app 接入	页内选择 H5、App 或小程序运行时
微信/通用小程序	小程序接入	微信内置 Adapter；其他平台按页内说明映射

选择对应平台后，先完成它的“安装”“连接”“监听变化”和 “发送第一条消息”。好友、群组、媒体、自定义消息和高级诊断可以在基础收发通过后再接。

需要和服务端负责人确认地址、账号与凭证时，查看客户端与服务端交接清单。

2. 客户端开始前领取四项信息

向服务端负责人领取：

text

Server URL       例如 https://im-test.customer.com
App ID           由服务端提供；平台 QuickStart 未要求时使用 Server 默认值
测试 User ID     例如 alice
对端 User ID     例如 bob

客户端不需要领取数据库密码、对象存储密钥、Endpoint 私钥或服务器配置文件。公开的 Endpoint 验签信息由 SDK 从 Server 自动发现。完整交接边界见客户端与服务端交接清单。

3. 按统一步骤跑通

在 Development/演示环境中，服务端会提前准备测试账号。下面是 iOS 示例； macOS 使用自己 QuickStart 中的独立示例：

swift

import XHIM

XHIMClient.connect(
    server: "https://im-test.customer.com",
    userID: "alice",
    onConnecting: {
        print("正在连接")
    },
    onConnectSuccess: { client in
        client.directConversation(
            with: "bob",
            onSuccess: { conversation in
                client.sendText(
                    conversationID: conversation.conversationID,
                    text: "你好，晞晗IM",
                    onSuccess: { _ in print("消息已入队") },
                    onFailure: { error in print(error.message) }
                )
            },
            onFailure: { error in print(error.message) }
        )
    },
    onConnectFailure: { error in
        print(error.code, error.message)
    }
)

其他平台使用对应主接入页中的 connect/ConnectAsync。SDK 自动完成公开配置读取、账号存储、内核启动、登录、实时连接、增量同步和断线恢复。

统一流程是：

text

创建账号 Client → 监听连接/数据变化 → 等待连接成功
  → 查询或创建会话 → 发送文字消息 → 收到变化后重新查询

4. 正式业务登录也只增加一个回调

Development 环境允许用测试 User ID 快速登录。应用正式上线时，为了防止任何人伪造 User ID，需要在 App 的账号会话层增加一个业务鉴权回调：

text

XHIM SDK 需要登录
  → 调用这个回调
  → 回调使用 App 已有登录态请求业务后端
  → SDK 获得登录票据并继续连接

iOS 示例：

swift

XHIMClient.connect(
    server: AppConfig.xhimServerURL,
    userID: accountSession.userID,
    authentication: .business(accountSession.fetchXHIMCredential),
    onConnecting: {},
    onConnectSuccess: { client in
        accountSession.xhimClient = client
    },
    onConnectFailure: { error in
        accountSession.show(error.message)
    }
)

macOS、Android、Windows、HarmonyOS、Flutter、Electron 和 Web QuickStart 都提供各自语言与生命周期对应的示例。普通页面只持有 client，不读取、保存或刷新登录票据；过期续期和并发合并由 SDK 完成。

如果当前只做功能验收，可以先使用 Development 模式。正式开放公网用户前，再把凭证提供器接到业务后台。

5. 客户端与服务端的职责边界

客户端负责	服务端负责
添加固定版本 SDK 包	部署 XHIM Server
填写公开 Server URL	配置域名、证书和网络
传入当前业务 User ID	校验业务用户身份
调用会话、消息和媒体 API	PostgreSQL、对象存储和审核
相机、相册、文件等系统权限	Push 厂商凭证和消息投递
UI、主题、路由、自定义消息展示	管理后台、备份、监控和容量

客户端工程中不要放服务端密钥、数据库地址或管理员凭证，也不要直接修改 XHIM 本地数据库。

如果要改聊天页面、消息样式或自定义消息，再进入使用 Demo 进行二次开发。首次接入不需要阅读内核实现。

6. 两个客户端互发

两台设备使用同一个 Server URL 和 App ID。
分别使用 alice、bob 两个测试用户。
两端进入 ready。
双方打开同一个 Conversation ID。
依次验证文字、图片、视频、文件、自定义消息和已读。
关闭网络后发送一条消息，再恢复网络验证自动重试。
退出 Alice 并登录 Bob，确认本地数据按账号隔离。

常见问题：

找不到包：确认 SDK 已加入当前 App Target/Module/RID；
无法连接：确认设备能访问 Server URL；
登录被拒绝：确认 Server 已启用 Development 登录或业务鉴权回调有效；
登录成功但看不到会话：确认服务端已经把用户加入该 Conversation；
可以发送但对方不刷新：确认对方在消费 SDK 事件并重新查询时间线；
BACKEND_NOT_CONFIGURED：当前包不是包含 Server Adapter 的客户发行包。

7. 客户端发布前检查

使用 XHIM 交付的固定版本包，不混用不同版本的 SDK 文件；
把 Development 地址替换为正式 HTTPS/WSS Server URL；
使用当前业务 User ID，并在账号层安装业务鉴权回调；
删除测试账号、局域网明文例外和演示开关；
接入对应平台 Push；
验证登录、退出、换号、分页、收发、媒体、自定义消息和已读；
验证断网、切网、前后台、重启和升级；
确认相机、相册、麦克风、文件等权限文案属于当前 App；
确认 Release 包不包含管理员凭证或服务端密钥。

这些是 App 上线前检查，不影响前期先用测试账号跑通首条消息。

8. 继续开发

完整公开 API、事件、模型和错误：SDK API Reference
服务端部署和管理后台：XHIM Server
Demo 和业务页面二次开发：使用 Demo 进行二次开发
版本升级：升级、灰度和回滚

只有负责移植 SDK 或自定义服务端适配器的开发者，才需要继续阅读内核适配器接入；普通 App 二次开发无需阅读该页。

产品介绍、版本方案与商业信息请查看 XHIM 产品页。普通 App 开发者只需阅读当前平台的接入页和业务功能 API。

晞晗IM（XHIM）客户端 SDK 接入总览 ​

先选你的阅读路径 ​

1. 选择你的平台 ​

2. 客户端开始前领取四项信息 ​

3. 按统一步骤跑通 ​

4. 正式业务登录也只增加一个回调 ​

5. 客户端与服务端的职责边界 ​

6. 两个客户端互发 ​

7. 客户端发布前检查 ​

8. 继续开发 ​

晞晗IM（XHIM）客户端 SDK 接入总览

先选你的阅读路径

1. 选择你的平台

2. 客户端开始前领取四项信息

3. 按统一步骤跑通

4. 正式业务登录也只增加一个回调

5. 客户端与服务端的职责边界

6. 两个客户端互发

7. 客户端发布前检查

8. 继续开发