外观
SDK 参数与返回对象
SDK 方法调用与 HTTP 请求是两层接口。宿主一般调用 SDK；SDK 负责网络请求、消息缓存和界面。本页解释宿主接入时使用的对象，具体方法见各平台参考。
用户资料
| 含义 | Web / uni-app | Android | iOS / HarmonyOS |
|---|---|---|---|
| 外部用户 ID | userId | userId | userID |
| 账号 | username | username | username |
| 昵称 | nickname | nickname | nickname |
| 头像地址 | avatar | avatar | avatar |
| 个性签名 | signature | signature | signature |
| IP 属地 | uni-app: ipRegion | 不在 PopoUser 构造参数中 | ipRegion |
用户 ID 是宿主系统提供的稳定 ID，不能用昵称代替。昵称用于展示，头像使用 URL。没有头像时原生平台与 uni-app 可传空字符串。可选账号、签名和属地按各平台构造函数省略或传空值；Web 的可选字段省略即可。
| 资料项 | 值类型 | 提交要求 |
|---|---|---|
| 外部用户 ID | 文本 | 必填，1–64 字符，保持稳定，不含控制字符和首尾空白。 |
| 昵称 | 文本 | 必填，1–80 字符，用于显示。 |
| 头像 | URL 文本 | Android、iOS、HarmonyOS、uni-app 用户对象需要此字段，无头像时为空字符串；Web 可省略。 |
| 账号 | 文本或空值 | 可选，用于按账号查找用户，不是昵称。 |
| 个性签名 | 文本或空值 | 可选，没有签名时按平台使用空值或省略。 |
| IP 属地 | 文本或空值 | 仅提供此字段的平台可使用，不参与身份判断。 |
认证结果
各平台的 IMAuth 或 PopoAuthInfo 都包含三项：
| 字段 | 类型 | 说明 |
|---|---|---|
| user | 当前平台的用户对象 | 与 Token 对应的用户资料。 |
| token | string / String | 宿主后端向 PopoIM 获取的 IM Token。 |
| expireAt | number / Long / Int64 | 过期时间，Unix 秒时间戳，不是毫秒。 |
authProvider 由宿主实现：先依据宿主自己的登录态向宿主后端取票，再返回此对象。不要把 sdkSecret 放到客户端，也不要在客户端自行生成 Token。
会话目标
| 字段 | 含义 |
|---|---|
| type | friend 单聊或 group 群聊；Android/HarmonyOS 使用对应枚举。 |
| id / targetId / targetID | 单聊填写对方外部用户 ID；群聊填写公开 group_id。不是 conversation_id。 |
| messageId / messageID | 需要定位消息时传正十进制消息 ID。uni-app 放在目标对象里，Android/iOS 使用方法重载；其他入口打开最新消息。 |
Android 使用 PopoConversationTarget.friend(userId) 或 .group(groupId)；iOS 和 HarmonyOS 也提供同名创建方法。它们返回对应平台的会话目标对象，参数无效时按平台抛出错误。
未读数量
| 字段 | 类型 | 说明 |
|---|---|---|
| conversation | integer | 当前未读消息数。 |
| contact | integer | 当前未读申请数。 |
均为当前总数，范围 0–100，100 可展示为 99+。收到回调后替换宿主角标，不要累加。
完成回调与错误
Android PopoCallback 的 onComplete(error)、iOS PopoCompletion 的 error，为空表示成功；有值表示失败。方法本身通常返回 void/Void，结果通过回调送达。Android 和 iOS 的宿主完成回调在主线程处理。
HarmonyOS 与 uni-app 主要使用 Promise。Promise<void> 完成时没有业务数据，失败进入 catch；Promise<boolean> 则用布尔值表示该方法说明的结果。
| 错误字段 | 说明 |
|---|---|
| code | SDK 的错误枚举或稳定分类，适合程序判断。 |
| category | 配置、状态、认证、网络、协议、业务或取消等大类。 |
| message | 供开发排查或界面提示的说明。 |
| serverCode | 对应服务器业务错误码；本地错误可能没有有效服务器错误码。 |
Web 的错误规则见 Web 方法参考。错误不等于全部需要重新登录：网络失败保留可读界面，认证失效才重新通过宿主取票。
缓存大小
原生 SDK 的 cacheSize 返回可清理的媒体缓存字节数；clearCache 返回清理后剩余的字节数。清理不会删除聊天记录、草稿或待发送内容。显示给用户时再换算为 MiB。