iOS 方法参考

先按 iOS 接入加入本地 Swift Package。除 clientRequestHeaders() 外，PopoIM 的宿主操作在 MainActor 调用。用户、认证、目标、未读与错误字段见 SDK 对象说明。

下文优先展示 async 方法。同名 completion 版本也可使用：结果通过 completion(error: PopoError?) 返回，nil 表示成功。

创建配置：PopoConfig(...)

参数	类型	必填	说明
serverURL	String	是	部署根地址，例如 https://example.com。
webSocketURL	String?	否	WS/WSS 地址；默认从部署地址派生 /ws。
authProvider	@Sendable () async throws -> PopoAuthInfo	是	异步向宿主后端取票；失败时 throw，成功返回用户、Token 和秒级 expireAt。

返回： PopoConfig。这里创建配置，初始化时才检查并使用。

初始化：PopoIM.initialize(config)

参数 config: PopoConfig。

返回： Void；配置无效等情况 throw PopoError。每个进程初始化一次，之后调用 login。

登录：PopoIM.login()

无参数，调用 authProvider 完成认证和首次同步。

返回： async throws Void；正常完成没有额外数据，失败通过 throw 交付。回调版本为 login(completion:)。

恢复缓存：PopoIM.restoreCachedSession(user:)

参数 user: PopoUser 为宿主确认的当前本机用户。

返回： async throws Void。恢复当前账号的可读缓存，不请求 Token 或网络；之后仍调用 login。回调版本增加 completion。

退出：PopoIM.logout(clearLocalData:)

参数 clearLocalData: Bool 表示是否同时清理当前账号本地数据。也可调用无参数 logout()，保留可恢复缓存。

返回： Void。用户退出宿主账号时通常传 true，并同时清理宿主登录态。

更新资料：PopoIM.updateCurrentUser(user)

参数 user: PopoUser 为当前账号的新资料，不能用它切换身份。

返回： async throws Void；回调版本增加 completion。宿主统一管理资料时先在后端保存并同步，再更新 SDK。

打开会话：PopoIM.openConversation(...)

参数	类型	必填	说明
target	PopoConversationTarget	是	使用 try .friend(userID) 或 try .group(groupID) 创建。
at messageID	String	否	带此参数的重载用于定位历史消息；填写正十进制消息 ID。
from navigationController	UINavigationController	是	承载聊天页面的宿主导航控制器。

返回： async throws Void。正常完成表示聊天页已经打开，不代表对方已读。completion 版本使用相同参数并增加完成回调。

添加未读监听：PopoIM.addUnreadListener(listener)

参数 listener: (PopoUnreadCount) -> Void 接收 conversation 和 contact 两个当前未读总数。

返回： PopoUnreadObserver。保留此对象，稍后用于取消监听。

取消未读监听：PopoIM.removeUnreadListener(observer)

参数为添加时返回的 PopoUnreadObserver。

返回： Void。页面或宿主模块销毁时取消。

查询缓存：PopoIM.cacheSize()

无参数。

返回： async Int64，媒体缓存字节数。回调版本通过 completion(bytes: Int64) 返回。

清理缓存：PopoIM.clearCache()

无参数。

返回： async Int64，清理后剩余的媒体缓存字节数。回调版本通过 completion(bytes: Int64) 返回。

处理来电通知：PopoIM.handleCallNotification(callID:)

参数 callID: String 为推送中的通话 ID。

返回： async throws Void；completion 版本增加完成回调。先由 SDK 向服务器确认当前通话状态，避免把延迟推送当作仍然有效的来电。

设置 VoIP token：PopoIM.setVoIPPushToken(...)

参数	类型	说明
token	Data?	PushKit 返回的 VoIP token；失效时传 nil。
environment	PopoPushEnvironment	.development 或 .production。
bundleID	String	当前应用 Bundle ID。

返回： throws Void。参数或配置错误时抛出错误。宿主仍需按 Apple 的 PushKit 与 CallKit 流程接线。

上报系统来电：PopoIM.reportIncomingCall(...)

参数	类型	说明
callID	String	通话 ID。
callerID	String	来电用户的身份标识。
callerName	String	系统来电界面显示的姓名。
hasVideo	Bool	是否视频通话。
completion	PopoCompletion	系统来电上报完成结果；nil 表示成功。

返回： Void，结果在 completion 中交付。

结束系统来电：PopoIM.endReportedCall(callID:)

参数 callID: String 为之前上报的通话 ID。

返回： Void。关闭对应的系统来电展示；通话业务状态仍由 SDK 通话流程维护。

请求诊断头：PopoIM.clientRequestHeaders()

无参数。

返回： [String: String]，客户端版本与设备诊断请求头，不包含认证 Token。

创建根页面

PopoConversationController() 与 PopoContactController() 均无参数，分别返回会话与通讯录 UIViewController。宿主将它们放入自己的导航和 Tab 结构中，后续复用页面实例。

创建好友二维码：PopoUIKit.createFriendQRCode(...)

参数 username: String 为完整账号，size: CGFloat 为二维码图像尺寸。

返回： throws UIImage。不是根据昵称查找好友。

创建分享文本：PopoShareItem.text(value)

参数 value: String 为要分享的文本。

返回： throws PopoShareItem，kind 为 text、text 为输入内容。内容无效时抛出错误。

创建分享文件：PopoShareItem.file(...)

参数	类型	必填	说明
kind	PopoShareItem.Kind	是	.image、.video 或 .file。
url	URL	是	可读取的本地文件 URL。
fileName	String	是	展示文件名。
mimeType	String	是	文件实际 MIME 类型。
thumbnailURL	URL?	否	本地封面文件 URL，默认 nil。

返回： throws PopoShareItem，包含 kind、fileURL、fileName、mimeType、thumbnailURL；文件类型的 text 为 nil。

创建分享页面：PopoUIKit.makeShareViewController(...)

参数 items: [PopoShareItem] 为待分享内容；completion: PopoShareCompletion 接收 PopoError?，nil 表示成功。

返回： throws UIViewController，宿主负责展示此分享页面。分享流程结果通过 completion 返回。