从零到第一条消息

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

先运行 Demo

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

1. 选择平台

平台	推荐发行形式	从这里开始
iOS	CocoaPods / XCFramework	iOS CocoaPods 接入
macOS	Swift Package / XCFramework	macOS 接入
Android	Maven / AAR	Android 接入
Windows	NuGet	Windows 接入
HarmonyOS	OHPM / HAR	HarmonyOS 接入
Flutter	pub + 原生二进制依赖	Flutter 接入
Electron	npm + 预编译 Node-API	Electron 接入

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', '= 0.1.0-dev.1'
  pod 'XHIMSwiftUI', '= 0.1.0-dev.1'
end

bash

pod install --repo-update
open YourApp.xcworkspace

其他平台分别通过 Maven、NuGet 或 OHPM 获取正式签名制品，应用工程不需要复制 C++ 内核源码。

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)
    }
)

这段代码自动完成配置发现、账号隔离数据库、Core 启动、登录、WebSocket 连接和首次同步。正式环境只需把 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 是可选层。它依赖公开 SDK API，不要求你的业务继承内部页面：

快速上线时，直接使用聊天列表、聊天页、输入区和媒体 Picker；
已有设计系统时，保留 Repository / ViewModel，替换组件外观；
完全自研 UI 时，只依赖 Core 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. 上线前检查