uni-app 快速接入 | 泡泡 IM 开发文档

uni-app SDK 提供现成的消息列表、通讯录和聊天页面，支持 Vue 2、Vue 3 的 Android App 和 iOS App。你保留自己的账号系统和底部导航，SDK 负责聊天内部流程。
按下面步骤完成配置、放入页面并登录，就能使用 SDK 自带的聊天功能。 需要从自己的业务按钮打开聊天、展示未读角标等，再看进阶控制。
先完成认证与登录，并用后端示例准备好你自己的 POST /api/im-auth。本文的“宿主”就是你自己的网站或 App；Token 是当前用户进入聊天的临时凭证，authProvider 是你提供的“获取凭证”函数。示例中的 https://im.example.com 是 Popo IM 服务地址，请换成实际部署地址。
后端同事负责准备取凭证接口；客户端同事按下面步骤接入。/api/im-auth 是示例接口名，需要由你的后端实现，不能直接当成 Popo IM 自带接口。
使用 HBuilderX 4.51 或更新版本，面向 Android App 与 iOS App；文件选择原生模块要求 iOS 15+。Vue 2、Vue 3 使用同一公开入口。H5、小程序、nvue 和 HarmonyOS 不应直接视为与两个 App 平台具有相同的支持范围；网站优先接入独立 Web SDK。
将完整模块加入宿主，保留 utssdk、共享媒体模块、页面和资源：
将模块 pages_init.json 中的页面配置完整合并到宿主 pages.json，保留每页的 style；HBuilderX 导入时如果已完成合并，不要重复注册。不要只注册两个根页而遗漏聊天、媒体或举报等内部页面。
原生文件选择器在 utssdk 中。首次安装或原生模块更新后应重新构建 App 或自定义基座，单独更新 WGT 无法新增原生代码。
初始化就是告诉 SDK“连接哪个服务、到哪里获取用户凭证”，每次启动只配置一次；此时还不会登录。下面的 authProvider 在需要时请求你的后端，返回当前用户的资料、Token 和到期时间。
hostRequest 需先校验 HTTP 状态及 code/msg/data 返回格式，再返回 data；/api/im-auth 由宿主实现，见认证与登录。取凭证函数不持有 SDKSecret，也不传宿主 Cookie 给 SDK。webSocketUrl 可省略，默认派生同域 /ws。
宿主可将以下页面设为两个 Tab 根页，顺序和位置自行决定：
从宿主导航切换这两个根页可使用 uni.switchTab；聊天及其他内部页面交给 SDK。宿主不要自行拼接聊天 URL 或使用 uni.reLaunch 处理 SDK 退出。
用户切换账号时，先让取凭证函数使用新账号的登录凭证，再调用 await PopoIM.login()。用户退出宿主时调用 PopoIM.logout(true)，同时移除该账号的 SDK 本地数据。
login() 会调用取凭证函数，再加载当前账号的聊天数据，完成后才表示登录成功。放在 async 函数中，用 try/catch 捕获失败，通过产品的通用 Toast 提示重试。SDK 在整个 App 中共享，离开某个页面时不用退出账号。
App 回到前台时需要恢复连接，进入后台时需要调整连接状态。将真实 App 生命周期转发一次，放在宿主 App.vue，不要在每个聊天页重复调用：
网络监听从已断网恢复为联网时再调用 PopoIM.onNetworkAvailable()；初次收到“在线”回调不应伪造一次恢复事件。SDK 管理重连与消息补齐，宿主无需增加轮询。
在宿主 manifest.json 根据需要配置 Barcode、Camera、Invocation、Record、VideoPlayer 模块。语音消息在 App 原生侧使用 M4A/AAC，需声明 Android 麦克风权限与 iOS NSMicrophoneUsageDescription；拍摄、保存等能力另外按平台配置用途说明。
深浅色由宿主解析后调用 setUiTheme。App 的首帧背景与底部手势区也由宿主管理：APP-PLUS 下的全局 page 背景需允许 SDK 原生画布显示，避免全局浅色背景覆盖夜间页面。保留模块页面自带的样式和安全区配置，不逐页覆盖颜色。
一对一通话属于可选扩展：SDK 管理呼叫、接听、挂断等通话状态，你的 App 还需要接入配套原生媒体模块、设备权限、视频视图和通话展示页。准备好后再通过通话展示能力设置告诉 SDK 当前支持语音还是视频；仅调用这个方法不会自动接好媒体模块，也不能代替服务端能力开关。普通文字、语音消息和视频消息不要求你实现通话页。
本模块没有 U-Push、UniPush 或离线系统消息通知接入入口，不应直接照搬其他平台的推送注册方式。
在 Android 和 iOS 的实际 App 包中检查两个根页、聊天返回、未读更新、后台恢复、账号切换及深浅色切换。媒体需要验证录音上传播放、系统文件选择、选择取消和竖屏视频；H5 预览与资源编译通过不能替代 App 真机验收。
聊天已经能正常使用，就可以在这里结束。只有需要把聊天与自己的业务功能联动时，再查看 uni-app 进阶控制：按场景找到方法，了解用途后再看参数，不必从头读完整页。