Web / H5 进阶控制 | 泡泡 IM 开发文档

本页按需查阅，首次接入不需要把这些方法全部实现。 按快速接入完成配置、页面和登录后，SDK 已经处理常用的聊天界面、消息收发、好友与群管理、同步等流程。只有想从商品页直接打开聊天、把未读数放到自己的导航栏、同步头像昵称，或接入本页列出的平台能力时，才需要额外调用相应方法。
这里的方法参数使用 JavaScript 的驼峰写法，例如 userId、expireAt；HTTP 返回的 user_id、expire_at 需要在你自己的取凭证代码中转换。
Promise 表示需要等待的异步操作，通常用 await 等待，再用 try/catch 处理失败。Promise<void> 表示成功后没有额外数据；void 表示调用本身不返回数据，完成情况以方法说明为准。
“方法”是 SDK 提供给你调用的操作；“参数”是调用时要填写的信息；“返回值”是操作交回的结果。“回调”或“监听”表示操作完成或数据变化时，SDK 调用你提供的函数通知你。只订阅需要的数据，在所属页面结束时解除监听。
下面是常见的业务联动及接入方式，选需要的使用即可。打开聊天与监听未读前应已完成快速接入并登录；导入和浮层示例则替代快速接入中的对应步骤。例子里的用户和群 ID 要换成真实、当前账号有权访问的目标。JavaScript 中的 await 放在 async 函数内执行。
例如在客户资料页放一个“发消息”按钮，点击后执行：
id 使用你系统里的用户 ID 或公开群 ID，不填昵称，也不填内部 conversation_id。同一时刻打开一个目标即可；用 try/catch 处理失败，通过产品的通用 Toast 展示错误。
renderUnread 是你自己的角标展示函数。conversation 是消息未读总数，contact 是待处理申请数；每次收到新值就替换显示，不要累加。数值 100 显示为 99+。监听会立即给出当前值。
保存返回的 stopUnread，在所属组件卸载时调用：
如使用现有前端构建工具，可在宿主 package.json 引用本地模块，执行安装后导入：
导入后使用 createIM(...)，后续配置和快速接入中的 IMKit.createIM(...) 相同。SDK 自带运行时，界面与弹层放在同一 Shadow Root 中；宿主样式不会直接作用于 SDK 内部。
页面内嵌适合固定的聊天区域；如果希望点击“联系客服”或“消息”后再展开，可在创建实例后采用下面的挂载方式，替代快速接入中的内嵌挂载。
同一实例只挂载一次。show()、hide() 控制可见性；浮层中的“收起”保留连接和当前页面。移动端浮层自动铺满视口。需要把顶部头像或退出入口接到宿主时，在 mount 配置 onProfile、onLogout 回调。
创建一个独立 SDK 实例，尚未挂载界面或登录。
返回： IMClient 实例。配置不合法时抛出错误。每个工作台创建一次，后续复用该实例。
把 SDK 界面放进网页容器，或作为浮层显示；不会重新创建账号。
返回： void。同一实例只能挂载一次，重复挂载或容器无效会抛出错误。
无参数。调用 authProvider 获取当前宿主用户的 IM 凭证，完成认证与首次同步。
返回： Promise<void>。完成后 state.session 为 ready。网络失败时 Promise 仍会拒绝；如果已有可读缓存，SDK 可以保留离线阅读界面。切换账号时，先更新 Provider 的身份来源，再调用此方法。
让用户启动应用时先看到上次保存在本机的聊天内容，减少等待。只能恢复你已确认身份的当前账号，之后仍需正常登录。
返回： boolean，true 表示已恢复可用缓存，false 表示没有可恢复缓存。不会请求 Token 或访问网络，之后仍调用 login 完成正式登录。
无参数。退出当前 SDK 账号，并清理当前账号缓存。
返回： void。宿主自己的登录状态由宿主同时清理。
你的后端保存头像、昵称后，用它立即更新 SDK 内的个人资料展示。
返回： void。只更新 SDK 展示，不向服务端写资料。切换账号要调用 login，不能用此方法替换身份。
无参数。重新读取当前账号数据，用于宿主主动触发刷新。
返回： Promise<void>。未登录或刷新失败时拒绝。
用户点击你产品里的“发消息”或“联系客服”时，用它直接进入某个人或群的聊天页。
返回： Promise<void>，正常完成表示已打开相应会话；不代表对方已读。需要先登录。
让聊天界面与产品选择的浅色或深色外观一致。
把 SDK 的消息和申请未读数显示到你自己的导航栏或角标中。
返回： () => void，调用这个函数即可解除本次订阅。count.conversation 是消息未读数，count.contact 是申请未读数；均为 0–100，100 可显示为 99+。这些是当前总数，应替换角标，不能累加。
让你自己的界面跟随 SDK 的登录、连接等状态更新，例如显示连接情况。
返回： () => void，解除本次订阅。适用于 Vue、React 或普通页面，不需要读取 SDK 内部响应式对象。
返回： void。不会重新登录或创建实例。
无参数。隐藏已挂载界面，保留连接和当前页面。正在使用的通话界面不能通过此方法隐藏，应使用通话窗口的最小化入口。
无参数。移除工作台、结束订阅并释放实例资源，保留可恢复缓存。
返回： void。之后需要重新 createIM；如果用户是退出账号，应先调用 logout 清理当前账号数据。
从你自己的业务按钮发起一对一语音或视频呼叫，成功发起后仍需等待对方接听。
返回： Promise<boolean>，true 表示本次发起操作成功，false 表示未能完成。当前错误说明可读取 calls.state.error。成功不代表对方已经接听。