HarmonyOS 进阶控制 | 泡泡 IM 开发文档

本页按需查阅，首次接入不需要把这些方法全部实现。 按快速接入完成配置、页面和登录后，SDK 已经处理常用的聊天界面、消息收发、好友与群管理、同步等流程。只有想从商品页直接打开聊天、把未读数放到自己的导航栏、同步头像昵称，或接入本页列出的平台能力时，才需要额外调用相应方法。
用户、认证、会话目标、未读和错误见 SDK 对象说明。Promise 方法失败时进入 catch；Promise<void> 正常完成没有额外数据。
“方法”是 SDK 提供给你调用的操作；“参数”是调用时要填写的信息；“返回值”是操作交回的结果。“回调”或“监听”表示操作完成或数据变化时，SDK 调用你提供的函数通知你。只订阅需要的数据，在所属页面结束时解除监听。
下面是两种常见的业务联动，选需要的使用即可。调用前应已完成快速接入并登录；例子里的用户和群 ID 要换成真实、当前账号有权访问的目标。ArkTS 中的 await 放在 async 函数内执行。
例如在客户资料页点击“发消息”时，在异步函数中执行：
会话根页尚未显示时，初始化中的 onConversationRequested 回调需要同步选中承载它的标签。方法成功表示目标已交给根页导航，页面动画由 ArkUI 完成。用 try/catch 处理失败并通过产品的通用 Toast 展示错误。
这里的 AppStorage 键名由你的应用定义，导航栏读取这些值显示角标。conversation 是消息未读总数，contact 是待处理申请数；每次替换当前值，不要累加，数值 100 显示为 99+。
保存返回的 observer，在所属页面结束时移除：
把服务地址与取凭证函数组合成配置，供初始化时使用。
返回： PopoConfig 配置对象。
在应用启动时登记 SDK 配置。它为后续登录做准备，不会替用户登录你的产品。
参数 context: common.Context 为宿主上下文，config: PopoConfig 为配置。
返回： void。配置错误会抛出 PopoError；初始化后再登录。
在你的用户登录成功后获取 IM 凭证并加载聊天数据，让该账号可以开始聊天。主动调用可切换账号，调用前先更新取凭证函数的身份来源；自动续期只保持原账号，不用于切换身份。
返回： Promise<void>，在认证和首次同步完成后正常完成。
初始化后，宿主从自己的后端刷新到新的实时地址时调用此方法；普通同域部署无需主动调用。
参数 value?: string 为完整的 ws:// 或 wss:// 地址，不包含账号密码、查询参数或片段。省略时恢复为部署地址对应的 /ws。正式部署使用 wss://。
返回： void。地址变化时使用当前账号凭证重新连接，保留会话和缓存；地址相同不重连，未登录时只更新配置。无效地址抛出 PopoError，并保留原地址。
让用户启动应用时先看到上次保存在本机的聊天内容，减少等待。只能恢复你已确认身份的当前账号，之后仍需正常登录。
参数 user: PopoUser 为宿主确认的本机用户。
返回： Promise<boolean>，true 表示恢复到可用缓存，false 表示没有可恢复缓存。此操作不请求网络，之后仍调用 login。
你的后端保存头像、昵称等资料后，用它让 SDK 使用当前账号的最新资料。
参数 user: PopoUser 为当前用户的新资料，不用于切换身份。
返回： Promise<void>。资料由宿主管理时，先保存并同步后端资料，再更新 SDK。
用户退出你的产品时同时结束 SDK 登录，避免继续接收旧账号数据。
返回： void，退出当前 SDK 会话。宿主同时完成自己的账号退出。
告诉 SDK 应用现在是否可见，让它按应用状态管理连接。
参数 active: boolean，前台为 true，后台为 false。
返回： void。跟随 Ability 生命周期调用，不需要重新初始化 SDK。
为你产品的“存储空间”页面读取当前媒体缓存大小。
返回： Promise<number>，媒体缓存字节数。
为你产品的“清理缓存”按钮清除可重新下载的媒体文件，保留聊天记录、草稿和待发送内容。
返回： Promise<number>，清理后剩余字节数。不会删除聊天记录、草稿或待发送内容。
把 SDK 的消息和申请未读数显示到你自己的导航栏或角标中。
参数 listener: (count: PopoUnreadCount) => void 接收 conversation、contact 两个未读总数。
返回： PopoUnreadObserver，保留对象用于取消监听。
所属页面结束时停止接收未读变化，避免页面已关闭仍被通知。
参数为添加时返回的 PopoUnreadObserver。
用户点击可信的系统消息通知后，将其中的会话 ID 交给 SDK，打开对应聊天。
参数 conversationID: string 为通知中的会话 ID。