从零到第一条消息

这是一条只面向客户端开发者的最短路径。你不需要在客户端工程里安装 Docker，也不需要理解 XHIM 服务端内部组件；只需要从服务端团队领取公开连接信息和用户登录凭证。

先运行 Demo

SDK 包附带可运行 Demo。建议先用两个测试账号确认服务器、网络和消息通道正常，再把相同配置写入自己的 App。

这篇文档怎么读

第一次接入只完成下面四个里程碑，不必先翻完整 API 表：

安装当前平台固定版本 SDK；
在账号级登录管理代码中连接，并在成功回调中立即监听事件；
Alice 给 Bob 发送第一条文本消息；
Bob 重查消息、标记已读，Alice 看见会话状态更新。

跑通后再按需求进入客户端接入总览或客户端二次开发。API Reference 是查询手册，不是第一次接入的阅读起点。

1. 选择平台

你正在开发	从这里开始
iPhone / iPad App	iOS 接入
macOS App	macOS 接入
Android App	Android Java 接入
Windows App	Windows 接入
HarmonyOS App	HarmonyOS 接入
浏览器网站	Web 接入
Electron 桌面应用	Electron 接入
Flutter App	Flutter 接入
React Native App	React Native 接入
Unity 游戏	Unity 接入
uni-app	uni-app 接入
微信或其他小程序	小程序接入

2. 从服务端团队领取连接信息

客户端只需要保存以下公开配置，不应该获得数据库密码、对象存储密钥或服务端签名私钥。

text

Server 地址:    https://im.example.com
测试用户:       alice / bob
App ID:         单租户通常省略，多租户时由服务端提供
生产鉴权:       由应用自己的业务账号层提供

XHIM 会从 Server 自动发现 WebSocket、对象存储、协议能力和公开签名配置。客户端不需要分别拼接多个内部服务地址。

如果你同时负责服务端部署，请先看服务端部署与管理后台；完成部署后，按照客户端联调交接清单把上述信息交给 App 团队。

3. 安装 SDK

以 iOS CocoaPods 为例，Podfile 只保留 SDK 依赖：

ruby

source 'git@git.xihansoftware.com:laowang/xhim-specs.git'
source 'https://cdn.cocoapods.org/'

target 'YourApp' do
  use_frameworks! :linkage => :static
  pod 'XHIM', '= <团队锁定的版本>'
  pod 'XHIMSwiftUI', '= <同一版本>'
end

bash

pod install --repo-update
open YourApp.xcworkspace

其他平台从对应主接入页安装固定版本包，不要混用不同版本的 SDK 与 UI 包。

4. 配置并登录

Development Server 开启测试直登后，只填写 Server 地址和用户 ID：

swift

import XHIM

private var client: XHIMClient?
private var connectRequest: XHIMRequest?

connectRequest = XHIMClient.connect(
    server: "https://im-test.example.com",
    userID: "alice",
    onConnecting: {
        print("XHIM 正在连接")
    },
    onConnectSuccess: { [weak self] client in
        self?.client = client
        print("XHIM 连接成功")
    },
    onConnectFailure: { error in
        print("连接失败:", error.code, error.message)
    }
)

这段代码会完成客户端初始化、登录、实时连接和首次同步。正式环境只需把 App 自己的账号鉴权函数通过 authentication: .business(...) 传入，普通页面不处理 Token。

不要在 App 中写死服务端密钥

开发环境可以使用服务端发放的测试凭证。正式环境必须由你的业务登录接口按当前用户签发或换取凭证；客户端只负责提交和自动续凭。

5. 订阅事件

连接成功后先安装账号级监听，再查询首屏。监听 token 必须由账号容器强引用：

swift

private var eventToken: XHIMEventListenerToken?

eventToken = client.addEventListener { [weak self] event in
    switch event {
    case .messageUpserted(let change),
         .messageStateChanged(let change):
        self?.reloadMessages(conversationID: change.conversationID)
    case .conversationChanged:
        self?.reloadConversations()
    case .conversationReadChanged:
        self?.reloadUnreadCount()
    case .stateChanged(let state):
        self?.updateConnectionState(state)
    default:
        break
    }
}

所有事件、线程要求和刷新边界见事件与回调。

6. 发送第一条消息

swift

client.directConversation(
    with: "bob",
    onSuccess: { conversation in
        client.sendText(
            conversationID: conversation.conversationID,
            text: "你好，XHIM",
            onSuccess: { _ in
                print("消息已进入发送队列")
            },
            onFailure: { error in
                print("发送失败:", error.stableCode, error.message)
            }
        )
    },
    onFailure: { error in
        print("创建单聊失败:", error.message)
    }
)

然后用 Bob 登录第二台设备确认：

Alice 发送后得到本地消息 ID 和发送状态；
Bob 收到 messageUpserted 事件并重新查询会话消息；
Bob 打开会话并上报已读；
Alice 收到 conversationReadChanged 或会话更新事件。

更完整的消息、会话、已读、草稿和搜索 API 本段是 iOS 示例，完整原型见iOS 回调式 API；macOS 开发者使用独立的macOS 回调式 API。通用语义见消息与会话。

7. 接入基础 UI

UI Kit 是可选的现成界面：

快速上线时，直接使用聊天列表、聊天页、输入区和媒体 Picker；
已有自己的界面时，直接使用公开 SDK 方法并替换组件外观；
完全自研 UI 时，只依赖公开 SDK 和事件流。

完整的可替换边界见二次开发扩展点。

8. 上线前检查

使用正式 HTTPS / WSS 域名，不绕过证书校验；
App 中没有数据库密码、对象存储 Secret 或服务端私钥；
登录凭证可自动续期，退出登录会清理当前账号会话；
网络断开、切网、弱网、后台恢复和请求取消已验证；
图片、视频、文件的上传、缓存、审核失败与重试路径已验证；
两个真实账号在两部真机上完成消息、已读、离线推送和多端登录测试。

平台级完整步骤和故障排查，请先进入平台支持矩阵，再选择当前目标端的独立接入指南。

从零到第一条消息 ​

这篇文档怎么读 ​

1. 选择平台 ​

2. 从服务端团队领取连接信息 ​

3. 安装 SDK ​

4. 配置并登录 ​

5. 订阅事件 ​

6. 发送第一条消息 ​

7. 接入基础 UI ​

8. 上线前检查 ​

从零到第一条消息

这篇文档怎么读

1. 选择平台

2. 从服务端团队领取连接信息

3. 安装 SDK

4. 配置并登录

5. 订阅事件

6. 发送第一条消息

7. 接入基础 UI

8. 上线前检查