外观
SDK 总览
Popo IM SDK 将会话、通讯录、好友与群聊、消息和实时连接接入现有应用。宿主保留自己的登录、账号资料和主导航；SDK 提供完整聊天界面，负责消息同步与内部页面流转。
选择平台
| 平台 | UI 接入方式 | 环境基线 |
|---|---|---|
| Web / H5 | 完整工作台，嵌入容器或浮层 | 现代浏览器；构建需要 Node.js 22.12+ |
| Android | 会话、通讯录两个 AndroidX Fragment | Android 5.0 / API 21+；源码工程 compileSdk 35、JDK 17 |
| iOS | 会话、通讯录两个 UIKit Controller | iOS 15+；Swift 5，SwiftPM 工具版本 5.9+ |
| HarmonyOS | 会话、通讯录两个 ArkUI 页面 | HarmonyOS NEXT 5.0 / API 12+；手机 |
| uni-app | 会话、通讯录两个页面，可作为 Tab 根页 | HBuilderX 4.51+；Vue 2 / Vue 3；Android App、iOS App |
各端均提供单聊、群聊、文字、图片、语音、视频、文件、名片、搜索和二维码等界面。入口是否显示、媒体大小及通话权限由服务端配置决定；群通话不在当前支持范围。uni-app 的原生通话还需要宿主接入媒体插件与展示页，详见该平台说明。
一次接入的顺序
- 部署 Popo IM 服务，确认 HTTPS 与 WebSocket 可用。
- 阅读认证与 Token，让宿主后端为当前登录用户取得 IM 凭证。
- 加入对应平台模块，初始化一次并配置
authProvider。 - 挂载 SDK 界面，调用
login()，等待首次同步完成。 - 使用两个账号验证收发、未读、退出和切换账号。
初始化只配置 SDK，不代表用户已经登录。各平台的 login() 均在取得凭证并从服务器完成首次同步后才报告成功；可选的 restoreCachedSession 用于提前展示当前账号缓存，也不等于登录成功。
宿主与 SDK 的分工
| 宿主负责 | SDK 负责 |
|---|---|
| 登录、注册、修改密码与宿主登录态 | IM Bearer Token 的使用与续期 |
| 向宿主后端请求 IM 凭证 | /app/sdk/* 业务请求与 WebSocket |
| 账号资料的保存与更新、个人中心 | 会话、通讯录、好友、群与聊天内部页面 |
| 根标签、应用导航、系统权限及推送接入 | 消息同步、历史分页、已读与 SDK 未读计数 |
| 将 SDK 未读与其他业务未读汇总展示 | 账号隔离的本地数据与媒体缓存 |
宿主通过公开入口打开会话，不需要读取 SDK 内部状态或自行拼接聊天页路径。发送消息、修改关系、建群等常规操作由 SDK 界面完成；公开宿主 API 不等于内部所有实现类。
统一的身份约定
- 用户 ID 是宿主稳定、大小写敏感的字符串，例如
chenyue；不能使用每次登录都会变化的会话标识。 - 打开单聊传宿主用户 ID；打开群聊传公开群 ID。它们均不是内部
conversation_id。 - Provider 返回当前用户资料、
token和 Unix 秒级expireAt，用户 ID 与到期时间必须与 Token 一致。 - SDK 未读分为
conversation（未设免打扰的消息）与contact（待处理申请）。原生及 uni-app 的数值100表示界面展示99+。 - HTTP JSON 使用
user_id、expire_at等字段；宿主 SDK 模型采用所在语言的命名方式，只在认证适配处转换。
接入验收
发布前至少完成一次完整流程：陈悦登录后与林舟互发消息，进入聊天清除未读；切到后台再返回，确认新消息补齐；断网时保留可读内容，联网后恢复；退出后不再接收旧账号数据，切换账号后只显示新身份内容。
图片、语音、视频和通话还需在目标浏览器或真机验证权限拒绝、取消操作与重新进入。编译通过不能替代这些交互验证。
方法与参数
接入步骤用于先把 SDK 跑起来；下面的参考逐个解释宿主可以调用的方法，以及输入参数、返回值和完成回调。