iOS 快速接入 | 泡泡 IM 开发文档

iOS SDK 提供现成的消息列表和通讯录页面，可以放进你应用的底部标签栏。进入聊天、好友资料和群管理等后续页面由 SDK 负责，你可以继续使用现有的账号系统和页面结构。
按下面步骤完成配置、放入页面并登录，就能使用 SDK 自带的聊天功能。 需要从自己的业务按钮打开聊天、展示未读角标等，再看进阶控制。
先完成认证与登录，并用后端示例准备好你自己的 POST /api/im-auth。本文的“宿主”就是你自己的网站或 App；Token 是当前用户进入聊天的临时凭证，authProvider 是你提供的“获取凭证”函数。示例中的 https://im.example.com 是 Popo IM 服务地址，请换成实际部署地址。
后端同事负责准备取凭证接口；客户端同事按下面步骤接入。/api/im-auth 是示例接口名，需要由你的后端实现，不能直接当成 Popo IM 自带接口。
在 Xcode 选择 File → Add Package Dependencies → Add Local，选中宿主内包含 Package.swift 的 sdk/ 目录，将 PopoIMKit 产品加入应用 Target。保留源码中的 Sources/PopoIMKit/Resources，其中包含 SDK 资源和隐私清单。
SwiftPM 会根据包清单下载配套媒体依赖。宿主只导入一个模块：
初始化就是告诉 SDK“连接哪个服务、到哪里获取用户凭证”，每次启动只配置一次；此时还不会登录。下面的 authProvider 在需要时请求你的后端，返回当前用户的资料、Token 和到期时间。
在应用启动且用户同意隐私政策后执行一次初始化。PopoIM UI 与会话入口在主 Actor 上调用；Provider 通过宿主后端异步获取当前账号凭证。
HostAuthClient 和 fetchImAuth() 需要由宿主实现，不是 SDK 自带类型或方法。它携带宿主登录凭证请求 /api/im-auth，校验 HTTP 状态与业务 code，将响应的 data 转为 PopoAuthInfo：
Provider 为 @Sendable () async throws -> PopoAuthInfo，宿主网络实现应满足 Swift 的并发要求；失败直接抛错。webSocketURL 可省略，默认使用服务地址的 /ws。初始化不请求网络，不能用反复初始化的方式切换账号或 Token。
下面创建两个底部标签：消息列表和通讯录。Controller 是 iOS 的页面对象，外层的导航控制器负责页面进入和返回；聊天内部页面由 SDK 打开：
两个根页可以独立嵌入。宿主的“我的”、登录、资料编辑和推送落地保留在自身导航中；SDK 处理聊天、好友和群等内部页面。
用户切换账号时，先让取凭证函数使用新账号的登录凭证，再调用 try await PopoIM.login()。用户退出宿主时调用 PopoIM.logout(clearLocalData: true)，同时移除该账号的 SDK 本地数据。
login() 会调用取凭证函数，再加载当前账号的聊天数据，完成后才表示登录成功。把上面的代码放在 @MainActor 的异步函数中，用 do/catch 捕获失败，通过产品的通用 Toast 展示错误并允许重试。网络失败时保留已有可读内容。
启用相应媒体能力时，在宿主 Info.plist 中配置用途说明：
SDK 在用户发起录音、拍摄、保存或通话时才申请所需权限。系统 PHPicker 选图不要求照片库读取权限。拒绝权限应保留可返回的页面与重新尝试入口，避免在进入首页时统一申请权限。
深浅色跟随宿主窗口的 UIKit trait；宿主通过 overrideUserInterfaceStyle 管理外观。普通推送、通知授权和桌面角标由宿主负责。若接入海外系统通话，还涉及公开的 PushKit / CallKit 接线入口，应结合宿主的签名、后台能力与服务端配置单独验收。
在真机用两个账号互发文字消息，验证从消息和通讯录进入聊天、返回上一页、后台恢复和账号切换。媒体另验证权限拒绝、选择取消、竖屏视频及保存；通话需要两台设备检查前后台与音频路由。
聊天已经能正常使用，就可以在这里结束。只有需要把聊天与自己的业务功能联动时，再查看 iOS 进阶控制：按场景找到方法，了解用途后再看参数，不必从头读完整页。