macOS 从零接入晞晗IM

完成本页后，你可以在 macOS App 中连接账号、监听数据变化并发送第一条文字消息。 默认示例使用 Completion 回调，不要求在 Window 或 ViewModel 中写 try/catch。

1. 准备接入信息

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

2. 新建工程并添加 SDK

1. Xcode 选择 File → New → Project... → macOS → App；
2. Minimum Deployment 设为 macOS 12 或更高；
3. App Sandbox 勾选 Outgoing Connections (Client)；
4. File → Add Package Dependencies... → Add Local...；
5. 选择团队提供的 XHIMSwift，给 App Target 勾选 XHIM；
6. 需要现成页面时再勾选 XHIMSwiftUI。

发行包必须包含 macOS slice。不要把 iOS 静态库手工复制进 macOS 工程。

3. 连接当前账号

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

正式环境增加业务凭证提供器：

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

多窗口共享同一个账号 Client。Window 关闭重开时不要重复连接。

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

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

收到消息事件后重新查询当前会话，不要在 Window 中维护另一份消息状态。

5. 登出和退出

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

普通 Window 关闭不等于账号退出。只有真正登出或换号时才执行上述代码。

6. 可选 UI

需要现成 SwiftUI 页面时，引入 XHIMSwiftUI。完全自定义 AppKit/SwiftUI 时只保留 XHIM，用现有 MVVM、MVP 或 Repository 结构承载查询结果。

7. 下一步

• API 参数、返回值与 Completion 示例： macOS 回调式 API；
• 会话、消息、好友和群组方法：SDK API Reference；
• 页面与 Store 二次开发：客户端二次开发指南。

Swift Concurrency 重载仍然保留，但只是已经使用 async/await 的 Repository 的可选 写法，不是本页默认调用方式。

8. 常见问题

运行时提示缺少 macOS slice

当前包不是 macOS 发行包。请更换完整 XHIMSwift 制品，不要复制 iOS Library。

Sandbox App 无法连接

确认 Outgoing Connections (Client) 已启用，设备可以访问 Server URL。

多窗口收到重复事件

账号层只保留一个 Client 和一个长期事件监听；各 Window 只订阅自己的 Store。