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

HarmonyOS SDK 提供现成的消息列表和通讯录页面，放进你的鸿蒙应用即可使用。你负责主导航、账号登录和应用前后台通知，SDK 负责聊天、好友资料、群管理等内部流程。
按下面步骤完成配置、放入页面并登录，就能使用 SDK 自带的聊天功能。 需要从自己的业务按钮打开聊天、展示未读角标等，再看进阶控制。
先完成认证与登录，并用后端示例准备好你自己的 POST /api/im-auth。本文的“宿主”就是你自己的网站或 App；Token 是当前用户进入聊天的临时凭证，authProvider 是你提供的“获取凭证”函数。示例中的 https://im.example.com 是 Popo IM 服务地址，请换成实际部署地址。
后端同事负责准备取凭证接口；客户端同事按下面步骤接入。/api/im-auth 是示例接口名，需要由你的后端实现，不能直接当成 Popo IM 自带接口。
最低 HarmonyOS NEXT 5.0.0 / API 12，当前面向手机。源码工程使用 DevEco Studio 5.0.0 Release 对应工具链，已验证构建号 5.0.3.910；选择工具链时应保持工程的 API 12 与 runtimeOS: HarmonyOS 配置一致。
配套宿主内的 sdk/ 是 SDK 工程，里面的 sdk/ 是模块目录。在 DevEco Studio 打开宿主内的 sdk/，同步 OHPM 依赖后以 release 模式构建 sdk 模块。
以下路径统一相对于宿主根目录：Release HAR 为 sdk/sdk/build/default/outputs/default/sdk.har，公开入口为 sdk/sdk/Index.ets。配套媒体依赖由模块清单管理。
配套宿主将 SDK 放在工程内的 sdk/，在宿主 entry/oh-package.json5 添加本地引用，然后执行 OHPM 同步：
修改 SDK 后重新构建 HAR，再同步宿主依赖；避免宿主继续编译旧产物。
初始化就是告诉 SDK“连接哪个服务、到哪里获取用户凭证”，每次启动只配置一次；此时还不会登录。下面的 authProvider 在需要时请求你的后端，返回当前用户的资料、Token 和到期时间。
公开模块为 @popoim/sdk，使用 ArkTS 和 ArkUI。用户同意隐私政策后，在应用启动流程中初始化一次：
hostAuth.fetchImAuth 需要由宿主实现，不是 SDK 自带方法。它携带宿主登录凭证请求 /api/im-auth，校验 HTTP 状态和业务 code，再将响应 data 转成下面的 PopoAuthInfo。expireAt 使用 Unix 秒：
webSocketURL 可省略，默认从服务地址派生 /ws。最后一个回调 onConversationRequested 只负责同步激活宿主容器，不需要传递 SDK 内部页面路径；宿主使用自己的标签顺序即可。
将两个根页放入宿主对应标签内容区，在 ArkUI build() 中使用：
这里的 messagesNested、contactsNested 和 selectedTab 是宿主状态。宿主依据当前可见标签的嵌套状态隐藏或恢复自己的 TabBar，不能让隐藏根页的回调覆盖可见页状态。通讯录根页保留在内存但不可见时，传 active: false。
启用 SDK 通话时，另外在应用根 Stack 的主内容上方放置一个 PopoCallPage()：
HostMainPage 是宿主自己的主页面。会话与通讯录仍为两个导航入口，通话页只负责根层展示。
用户切换账号时，先让取凭证函数使用新账号的登录凭证，再调用 await PopoIM.login()。用户退出宿主时同时调用 PopoIM.logout()。
login() 会调用取凭证函数，再加载当前账号的聊天数据，完成后才表示登录成功。放在 async 函数中，用 try/catch 捕获失败，通过产品的通用 Toast 提示重试。网络暂时失败时保留已有内容，恢复联网或回到前台时 SDK 会重试。
应用回到前台时需要恢复连接，进入后台时需要调整连接状态。在宿主 Ability 中转发一次，不要在每个聊天页面重复调用。
宿主 Ability 在前后台切换时转发：
最终 HAP 要合并网络权限，并为 ohos.permission.MICROPHONE、ohos.permission.CAMERA 提供真实的用户授权理由；相册与文件使用系统 Picker，无需广泛存储权限。相机、扫码和媒体交互依赖当前可见页面的 Ability 上下文，SDK 根页会进行绑定。
普通推送服务、通知授权和应用图标上的未读数字由你的应用负责。需要点击通知后打开聊天时，查看通知处理方法。来电通过 SDK 的实时连接处理，无需另加轮询。
用真机上的两个账号互发文字消息，验证消息与通讯录切换、进入聊天时底部标签栏隐藏、后台恢复和账号切换。扫码需分别检查相机授权、相册识别与取消；通话另外检查相机、麦克风拒绝后的返回与重试。
聊天已经能正常使用，就可以在这里结束。只有需要把聊天与自己的业务功能联动时，再查看 HarmonyOS 进阶控制：按场景找到方法，了解用途后再看参数，不必从头读完整页。