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

适用版本：0.1 Commercial Beta
本页面向 iOS、macOS、Android、Windows、HarmonyOS、Flutter、Electron 和 Web 客户端开发者。每个平台的安装入口彼此独立。

如果你是普通客户端开发者，只做四件事：

text

添加平台 SDK
  → 填写 Server URL
  → 传入当前 User ID
  → 使用消息 API 或 UI Kit

你不需要部署数据库、运行服务端命令、编译 C++ Core、手工维护 WebSocket，也不需要向 XHIM 提供自己的 App 签名证书。

1. 选择你的平台

平台	从空白工程开始	可选 UI
iOS	iOS QuickStart / CocoaPods	`XHIMSwiftUI`
macOS	macOS QuickStart	`XHIMSwiftUI`
Android	Android QuickStart	`xhim-ui-compose`
Windows	Windows QuickStart	`XHIM.UI.Wpf`
HarmonyOS	HarmonyOS QuickStart	ArkUI 组件
Flutter	Flutter QuickStart	Flutter UI Kit 适配中
Electron	Electron QuickStart	Renderer 自定义 UI
Web	Web QuickStart	React/Vue/Svelte/原生 DOM 自定义 UI

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

购买方技术负责人和交付人员应先看商业交付与客户接入指南。

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

向服务端负责人领取：

text

Server URL       例如 https://im-test.customer.com
App ID           单租户可省略，SDK 使用 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)
    }
)

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

统一流程是：

text

connect → 等待 ready → 查询会话/消息 → sendText → 收到事件后重新查询

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 模式。业务鉴权回调是购买方正式开放公网用户时再完成的服务端对接，不影响 SDK 购买和前期接入。

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

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

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

6. 推荐的 App 结构

text

App Account Session
└── XHIMService                 每个登录账号一个 Client
    ├── ConversationRepository 会话查询
    ├── MessageRepository      消息和媒体
    ├── ConversationViewModel
    └── ChatViewModel
        └── XHIM UI Kit        可选

页面、Cell、Composable、Window 和 ArkUI Component 不创建 Client。UI Kit 可以替换，Headless SDK 继续负责连接、同步、收发和本地数据。

7. UI、媒体和二次开发

每个平台都拆成：

text

Headless SDK
  登录、会话、消息、媒体、同步、已读、Presence、Typing 和事件

UI Kit（可选）
  会话列表、聊天页、消息气泡、附件入口、主题和 Renderer

客户可以自定义导航、颜色、字体、消息 Cell、页面路由和消息 Renderer，不需要修改 Core。图片、视频、拍照、相册和文件选择使用平台系统 Picker；上传、下载、分片、缓存和重试由 SDK 负责。

业务消息使用 contentType + contentVersion + payload + fallbackText 扩展。旧版本遇到未知类型时显示 fallbackText，不会破坏消息时间线。

8. 两个客户端互发

两台设备使用同一个 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 的客户发行包。

9. 客户端发布前检查

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

这些是购买方自己的 App 上线检查，不是购买 XHIM SDK 之前必须准备的条件。

10. 深度定制入口

完整公开 API、事件、模型和错误：SDK API Reference
服务端部署和管理后台：XHIM Server
商业交付边界：商业交付与客户接入指南
SDK 平台 Facade 维护：平台 Facade 维护指南
C++ 内核和 Product Adapter：内核与产品 Adapter 接入指南
版本升级：升级、灰度和回滚

普通 App 开发者不需要阅读 C++、C ABI、SQLCipher 或服务端部署文档。

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

1. 选择你的平台 ​

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

3. 五分钟跑通 ​

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

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

6. 推荐的 App 结构 ​

7. UI、媒体和二次开发 ​

8. 两个客户端互发 ​

9. 客户端发布前检查 ​

10. 深度定制入口 ​

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

1. 选择你的平台

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

3. 五分钟跑通

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

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

6. 推荐的 App 结构

7. UI、媒体和二次开发

8. 两个客户端互发

9. 客户端发布前检查

10. 深度定制入口