生命周期与连接 API

1. 一键连接

lifecycle.connect

这是普通 App 推荐入口。SDK 自动发现公开服务配置、创建账号隔离存储、启动 Core、登录并安装续凭回调。

参数	必填	说明
`server` / `serverURL`	是	XHIM Server 的 HTTPS 基地址；开发环境可显式允许 HTTP
`userID`	是	当前 App 已登录业务用户 ID
`appID`	否	省略时采用 Server 公布的默认 App ID
`authentication`	否	Development、固定 Access Token 或业务凭证回调
`storageRoot`	否	SDK 账号隔离存储根目录；通常使用平台默认值

返回已登录的 XHIMClient。连接发现阶段错误使用 XHIMConnectionError； Core 运行阶段错误使用平台对应的 XHIMNativeError / XHIMException。

swift

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

平台符号：iOS/macOS/Android/HarmonyOS XHIMClient.connect，Windows XHIMClient.ConnectAsync。

iOS 与 macOS 回调式 API 的参数、回调线程和错误字段分别见 iOS 回调式 API和 macOS 回调式 API。原有 async throws 重载完整保留，供采用 Swift Concurrency 的账号 Repository 使用。

2. 手动创建与底层生命周期

手动模式主要供 SDK 容器、特殊存储目录和高级运行策略使用。普通页面不要走这条路径。

api-id	方法	输入	返回 / 状态
`lifecycle.create`	创建 Client	`XHIMClientConfiguration`	Client，状态 `created`
`lifecycle.start`	启动 Core	无	`Void`，状态 `started`
`lifecycle.login`	首次登录	`accountHint`, `accessToken`	`Void`，最终进入 `ready`
`lifecycle.update_credential`	更新过期凭证	`accessToken`	`Void`，恢复连接和同步
`lifecycle.logout`	退出当前账号	无	清理账号会话；Client 可再次登录
`lifecycle.state`	读取当前状态	无	`XHIMClientState`
`lifecycle.notify_network_available`	通知网络恢复	无	触发有界重连，不代表已 ready
`lifecycle.diagnostics`	读取安全诊断快照	无	`XHIMDiagnostics`，不含账号和凭证
`lifecycle.device_session_policy`	读取多端登录策略	无	`XHIMDeviceSessionPolicy`
`lifecycle.compatibility`	读取协议能力协商	无	`XHIMCompatibilitySnapshot`
`lifecycle.shutdown`	不可逆关闭	无	等待请求和事件通道收尾

合法主路径：

text

created → started → authenticating → connecting → synchronizing → ready
                                     credentialRequired ──update──┘
ready → loggingOut → started
任意可运行状态 → closed
不可恢复故障 → fatal

logout 与 shutdown 不同：退出后可在同一 Client 重新登录，关闭后必须新建 Client。一个 Client 只绑定一个账号；切换账号时先退出，并让 SDK 使用不同账号存储目录。

3. 鉴权模式

模式	用途	生产可用
Development	私有测试环境按 User ID 获取测试凭证	否
Access Token	已有短生命周期凭证的受控工具	仅特殊集成
Business Provider	使用 App 现有登录态向业务后端换取 XHIM 凭证	是

业务 Provider 只返回字符串凭证。SDK 在首次登录和 credentialRequired 时调用它，并合并并发刷新；View、ViewModel、Activity、 Window 或 ArkUI 页面不保存 Token。

4. 配置模型

XHIMClientConfiguration：

字段	说明
`appID`	租户 / App 标识
`storageURL` / `storagePath`	当前账号独享的加密数据库位置
`eventQueueCapacity`	有界事件队列容量，默认 1024
`runtimePolicy`	请求超时、同步页大小和有界重连退避
`deployment`	已验证的 Bootstrap URL、Endpoint Key ID 和 Ed25519 公钥

使用 connect 时，deployment 由 Server 公开发现结果生成，接入方不需要手写 Endpoint 公钥。

5. 资源释放

iOS：await client.shutdown()；
macOS：await client.shutdown()；
Android：client.shutdown()；
Windows：await client.DisposeAsync() 或 ShutdownAsync()；
HarmonyOS：await client.shutdown()，随后可调用 destroy() 立即释放壳对象。

析构函数和 GC 只作为泄漏兜底。账号容器应显式关闭 Client，并在关闭完成后再释放页面和仓库订阅。

生命周期与连接 API ​

1. 一键连接 ​

2. 手动创建与底层生命周期 ​

3. 鉴权模式 ​