iOS 从零接入晞晗IM

完成本页后，你可以在空白 iOS App 中安装 SDK、连接账号、监听变化并向另一个账号 发送第一条文字消息。默认示例使用 Completion 回调，不要求在页面中写 try/catch。

1. 准备接入信息

向服务端负责人领取 Server URL、App ID、当前用户 ID 和一个对端测试用户 ID。 正式环境还需要应用自己的后台提供短期 XHIM 凭证。

2. 安装 SDK

最低支持 iOS 15。已有 CocoaPods 工程可以使用：

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

platform :ios, '15.0'

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

pod install
open YourApp.xcworkspace

Swift Package 项目在 Xcode 中选择 File → Add Package Dependencies...，添加 团队提供的 XHIMSwift 包，并给 App Target 勾选 XHIM。需要现成页面时再勾选 XHIMSwiftUI。两种安装方式不要在同一 Target 中混用。

完整的 CocoaPods 排错见 iOS CocoaPods 接入。

3. 连接当前账号

把 Client 放在账号级 Session 中，页面只读取它：

import XHIM

private var xhimClient: XHIMClient?
private var connectRequest: XHIMRequest?

connectRequest = XHIMClient.connect(
    server: "https://im-test.example.com",
    userID: currentUserID,
    onConnecting: {
        print("正在连接")
    },
    onConnectSuccess: { [weak self] client in
        self?.xhimClient = client
        self?.installXHIMListener(client)
    },
    onConnectFailure: { error in
        print(error.stableCode, error.message)
    }
)

Development Server 已开启测试登录时，上述代码即可使用。正式环境只增加业务凭证 提供器，页面仍然使用同一个 Client：

XHIMClient.connect(
    server: "https://im.example.com",
    userID: account.userID,
    authentication: .business(account.fetchXHIMCredential),
    onConnecting: {},
    onConnectSuccess: { client in
        account.xhimClient = client
    },
    onConnectFailure: { error in
        account.show(error.message)
    }
)

不要把固定凭证写进源码、Info.plist 或 UserDefaults。

4. 监听数据变化

private var eventToken: XHIMEventListenerToken?

private func installXHIMListener(_ client: XHIMClient) {
    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()
        default:
            break
        }
    }
}

事件表示“数据发生变化”。收到事件后重新查询当前会话或消息，不要在页面中另建 一套消息状态。

5. 发送第一条消息

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

让 Bob 使用同一个 Server 和 App ID 登录。Bob 收到事件后重新查询该会话，即可 看到消息。

6. 登出与换号

client.logout(
    onSuccess: { [weak self] in
        self?.eventToken = nil
        client.shutdown(onSuccess: {}, onFailure: { _ in })
    },
    onFailure: { error in
        print(error.message)
    }
)

普通聊天页面关闭时不要登出账号。切换账号后，用新的用户 ID 创建新 Client， 不要复用旧账号数据库。

7. 运行 UIKit Demo

cd platforms/ios/Examples/XHIMUIKitDemo
pod install
open XHIMUIKitDemo.xcworkspace

Demo 展示账号登录、会话列表、聊天页、通讯录、群组、媒体和常用页面结构，可直接 作为 UIKit 二次开发参考。详细说明见 XHIMUIKitDemo。

8. 下一步

• API 参数、返回值、错误和更多 Completion 示例： iOS 回调式 API；
• 会话、消息、好友和群组方法：SDK API Reference；
• 修改 Demo 页面、Store 或自定义消息： 客户端二次开发指南。

Swift Concurrency 重载仍可用于已经采用 async/await 的 Repository，但它属于可选 高级写法，不是本页默认接入方式。

9. 常见问题

No such module 'XHIM'

CocoaPods 工程只打开 .xcworkspace；Swift Package 工程确认 App Target 已勾选 XHIM。不要同时安装两份 SDK。

模拟器可以连接，真机不能连接

确认真机可以访问 Server URL，正式环境使用可信 HTTPS/WSS 证书。

能发送但对方页面不刷新

确认账号 Session 保留了 eventToken，并在消息事件后重新查询消息列表。