生命周期与连接 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。

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.sdk_metadata	读取本进程 SDK 构建元信息	无	XHIMSDKMetadata
lifecycle.app_runtime_state_get	读取本机 App 前后台事实	无	XHIMAppRuntimeState
lifecycle.app_runtime_state_set	报告本机 App 前后台事实	foreground / background	本地 revision 与可选远端确认快照
lifecycle.shutdown	不可逆关闭	无	等待请求和事件通道收尾

合法主路径：

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. SDK 构建元信息

XHIMSDKMetadata 只读包含 version、sourceCommit 和 abiVersion。原生端直接读取当前进程已加载的 XHIM Core，不请求 Server，因此不会把服务端版本冒充客户端 SDK 版本。不包含账号、 Token、Endpoint 或设备标识。

旧 Native 制品缺少任一元信息符号时，Facade 明确返回 unsupported / PlatformNotSupportedException，不伪造 0.0.0、 unknown 或 ABI 默认值。Web 不加载 C ABI：它返回 npm 制品的 package-build 元信息和协议指纹，abiVersion 为 null。这些值由 prebuild / prepack 从 package.json、协议指纹和源码提交生成；开发中的 脏工作区带 +dirty，发行打包直接拒绝脏工作区。

6. App Runtime State

App Runtime State 只表示当前设备上的宿主 App 是前台还是后台，和用户可见的 Presence 完全分离：切到后台不会把账号改成“离线”，Presence 也不能替代系统 生命周期报告。

• lifecycle.app_runtime_state_get 是同步、只读的本机状态读取；
• lifecycle.app_runtime_state_set 先在 Core 串行提交本地单调 revision，再向 Server 报告。即使网络失败，错误对象仍保留已经生效的本地快照；
• 后台状态会拒绝新的 isTyping=true，但停止输入的 false 仍允许发送；
• 回到前台会唤醒有界重连，并把多次触发合并为一次增量 Sync；
• 旧 Server 未声明 session.app_runtime_state 时返回明确 unsupported，不会把 它伪装成普通超时。

服务端只有在“同一设备会话的最新前台 CAS 状态”和“未过期的短时实时 Presence Lease”同时存在时才抑制 Push。App 被强杀、崩溃或网络断开后，Lease 到期即恢复 Push，不会因为长生命周期登录 Token 仍有效而长期漏通知。

宿主应从 Scene / Activity / Window / ArkUI / Electron 生命周期统一调用，不要 在每个页面手动上报。Web/Flutter/Electron 使用各自平台适配层，语义与原生端 一致。

7. 资源释放

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

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