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

Android SDK 提供现成的消息列表和通讯录页面，放进你应用的主导航即可使用。聊天、搜索、好友资料、群管理和媒体页面由 SDK 负责，Java 和 Kotlin 项目都可以接入。
按下面步骤完成配置、放入页面并登录，就能使用 SDK 自带的聊天功能。 需要从自己的业务按钮打开聊天、展示未读角标等，再看进阶控制。
先完成认证与登录，并用后端示例准备好你自己的 POST /api/im-auth。本文的“宿主”就是你自己的网站或 App；Token 是当前用户进入聊天的临时凭证，authProvider 是你提供的“获取凭证”函数。示例中的 https://im.example.com 是 Popo IM 服务地址，请换成实际部署地址。
后端同事负责准备取凭证接口；客户端同事按下面步骤接入。/api/im-auth 是示例接口名，需要由你的后端实现，不能直接当成 Popo IM 自带接口。
源码模块使用 compileSdk 35；这与最低运行系统 API 21 是不同概念。宿主可继续使用自身的 targetSdk，并按目标 Android 版本完成权限和安全区适配。
保留 宿主内的 sdk/core 和 sdk/uikit，在宿主的 settings.gradle.kts 中声明：
UIKit 已依赖 Core，无需再重复添加。宿主需提供 google() 与 mavenCentral() 仓库、Android library 插件，以及 android.useAndroidX=true；具体版本以 SDK 工程配置为准。媒体和扫码等第三方依赖由模块的 Gradle 文件管理。
初始化就是告诉 SDK“连接哪个服务、到哪里获取用户凭证”，每次启动只配置一次；此时还不会登录。下面的 authProvider 在需要时请求你的后端，返回当前用户的资料、Token 和到期时间。
在宿主 Application 的启动流程中初始化，避免系统直接重建 SDK 聊天页时找不到配置。初始化放在用户同意应用隐私政策之后，每个进程执行一次。
hostAuth.fetchImAuth 需要在宿主网络层实现，不是 SDK 自带方法：携带宿主登录凭证请求 /api/im-auth，校验 HTTP 状态和业务 code，再将 data 映射为下面的 PopoAuthInfo：
PopoAuthProvider 使用回调，不能写成返回字符串或 suspend () -> String。网络失败调用 onError；成功只调用一次 onSuccess。webSocketUrl 可以省略，默认由服务地址派生 /ws。
SDK 提供两个现成的 Fragment（可以放进 Activity 的页面区域）：消息列表和通讯录。把它们放入你应用对应的两个标签页，不需要自己编写聊天页：
message_container、contact_container 是宿主自己的容器。首次创建时添加 Fragment，系统恢复后使用原实例；不要在每次标签切换时重新创建。宿主切换可见根页，SDK 处理根页以内的页面栈。
为从 SDK 内部流程返回后选中消息标签，宿主实现 PopoConversationNavigationHost.showConversationListOnReturn()，并在主 Activity 创建时注册：
此处 this 为已实现该接口的宿主 Activity。接口只要求宿主展示自己的消息标签，不传递 SDK 内部路由。
用户切换账号时，先让取凭证函数使用新账号的登录凭证，再调用同一个 PopoIM.login。用户退出宿主时调用 PopoIM.logout(true)，同时清理当前账号的 SDK 本地数据。
login() 会调用上面配置的取凭证函数，再加载聊天数据。回调就是操作结束后 SDK 通知你的函数；error == null 表示成功，其他情况通过产品的通用 Toast 展示错误。回调在主线程，可直接更新界面。showError 是你产品中调用 Toast 的方法，需要自行提供。
SDK 模块 Manifest 会参与合并，发布前检查最终 Manifest 的网络、相机、麦克风等声明和宿主权限文案。相册及文件优先使用系统选择器，不应为 SDK 补一组无关的广泛存储权限。
SDK 自动观察 Application 的前后台变化，宿主无需自行重建长连接。两个根 Fragment 跟随宿主 Activity 方向；内部页面继承下层宿主 Activity 的方向策略。主题使用 Android 的 values / values-night 资源与宿主模式。
普通通知授权、推送平台与桌面角标由宿主负责。SDK 回调给出当前未读总数，宿主替换相应角标后再与其他业务未读汇总，不能每次回调累加。需要展示清理缓存入口时，再查阅进阶控制。
用两个账号互发文字消息，验证消息和通讯录切换、聊天返回、切换账号和进程被回收后的页面恢复。另在目标 Android 版本真机检查手势区、软键盘、录音权限及竖屏视频；深浅色模式都应操作一遍。
聊天已经能正常使用，就可以在这里结束。只有需要把聊天与自己的业务功能联动时，再查看 Android 进阶控制：按场景找到方法，了解用途后再看参数，不必从头读完整页。