Web / H5 方法参考

本页逐项说明宿主可以调用的方法。先按 Web / H5 接入创建工作台，再按需要调用。这里的方法参数使用 JavaScript 的驼峰写法，例如 userId、expireAt；HTTP 返回的 user_id、expire_at 需要在宿主取票代码中转换。

返回 Promise<void> 的方法需要 await：正常完成时没有额外数据，失败时进入 catch。返回 void 的方法同步执行，没有返回参数。

创建实例：createIM(options)

创建一个独立 SDK 实例，尚未挂载界面或登录。

参数	类型	必填	说明
options.serverUrl	string	是	部署根地址，例如 https://example.com，不包含 /app/sdk、查询参数或 URL 片段。也可用同源路径。
options.webSocketUrl	string	否	WS/WSS 地址；省略时从 serverUrl 派生 /ws。
options.authProvider	() => Promise<IMAuth>	是	访问宿主取票服务，返回本页下方说明的 IMAuth。首次登录或需要重新认证时会调用。
options.appVersion	string	否	宿主应用版本，便于诊断。
options.onAuthError	() => void	否	认证失效时通知宿主，可引导用户重新登录宿主。无参数，无返回值。

返回： IMClient 实例。配置不合法时抛出错误。每个工作台创建一次，后续复用该实例。

挂载界面：client.mount(options)

参数	类型	必填	说明
options.mode	'embedded' 或 'floating'	否	默认 embedded，显示在页面容器中；floating 为浮层。
options.container	HTMLElement	内嵌必填	已插入页面、具有明确高度的容器。浮层使用 document.body，不需要此参数。
options.onProfile	(container?: HTMLElement) => void	否	SDK 请求展示宿主资料页时调用；窄屏下可能给出承载资料页的容器。
options.onLogout	() => void 或 Promise<void>	否	用户从 SDK 选择退出时调用，由宿主完成自己的退出逻辑。

返回： void。同一实例只能挂载一次，重复挂载或容器无效会抛出错误。

登录：client.login()

无参数。调用 authProvider 获取当前宿主用户的 IM 凭证，完成认证与首次同步。

返回： Promise<void>。完成后 state.session 为 ready。网络失败时 Promise 仍会拒绝；如果已有可读缓存，SDK 可以保留离线阅读界面。切换账号时，先更新 Provider 的身份来源，再调用此方法。

恢复缓存：client.restoreCachedSession(user)

参数	类型	必填	说明
user	IMUser	是	宿主已确认的当前本机用户，字段见下方用户对象。

返回： boolean，true 表示已恢复可用缓存，false 表示没有可恢复缓存。不会请求 Token 或访问网络，之后仍调用 login 完成正式登录。

退出：client.logout()

无参数。退出当前 SDK 账号，并清理当前账号缓存。

返回： void。宿主自己的登录状态由宿主同时清理。

更新本地资料：client.refreshCurrentUser(user)

参数	类型	必填	说明
user	IMUser	是	已由宿主后端保存并同步的资料，userId 必须与当前 SDK 用户一致。

返回： void。只更新 SDK 展示，不向服务端写资料。切换账号要调用 login，不能用此方法替换身份。

刷新数据：client.refresh()

无参数。重新读取当前账号数据，用于宿主主动触发刷新。

返回： Promise<void>。未登录或刷新失败时拒绝。

打开会话：client.openConversation(target)

参数	类型	必填	说明
target.type	'friend' 或 'group'	是	friend 单聊；group 群聊。
target.id	string	是	对方外部 user_id 或公开 group_id；不是 conversation_id。用户 ID 最多 64 字符，群 ID 为 1–32 位字母、数字、点、下划线或连字符。

返回： Promise<void>，正常完成表示已打开相应会话；不代表对方已读。需要先登录。

await client.openConversation({ type: 'friend', id: 'linzhou' })

设置主题：client.setTheme(theme)

参数	类型	必填	说明
theme	'system'、'light' 或 'dark'	是	跟随系统、浅色或深色。

返回： void。其他取值会抛出错误。

订阅未读：client.onUnreadChange(listener)

参数	类型	必填	说明
listener	(count: UnreadCounts) => void	是	注册后立即收到当前计数，之后在计数变化时调用。

返回： () => void，调用这个函数即可解除本次订阅。count.conversation 是消息未读数，count.contact 是申请未读数；均为 0–100，100 可显示为 99+。这些是当前总数，应替换角标，不能累加。

const stop = client.onUnreadChange(count => {
  renderBadge(count.conversation, count.contact)
})
// 宿主组件卸载时
stop()

renderBadge 是宿主自己的角标函数。

订阅状态：client.onStateChange(listener)

参数	类型	必填	说明
listener	(state: IMClientState) => void	是	立即接收当前只读状态，之后状态变化时再次调用。字段见下方状态对象。

返回： () => void，解除本次订阅。适用于 Vue、React 或普通页面，不需要读取 SDK 内部响应式对象。

显示界面：client.show()

无参数。显示已挂载的 SDK 界面。

返回： void。不会重新登录或创建实例。

收起界面：client.hide()

无参数。隐藏已挂载界面，保留连接和当前页面。正在使用的通话界面不能通过此方法隐藏，应使用通话窗口的最小化入口。

返回： void。

销毁实例：client.destroy()

无参数。移除工作台、结束订阅并释放实例资源，保留可恢复缓存。

返回： void。之后需要重新 createIM；如果用户是退出账号，应先调用 logout 清理当前账号数据。

发起通话：client.calls.start(userId, media)

参数	类型	必填	说明
userId	string	是	被叫的外部 user_id。
media	'audio' 或 'video'	是	语音或视频通话。

返回： Promise<boolean>，true 表示本次发起操作成功，false 表示未能完成。当前错误说明可读取 calls.state.error。成功不代表对方已经接听。

接听通话：client.calls.accept()

无参数，接听当前来电。

返回： Promise<boolean>，true 表示本次接听操作完成，false 表示当前状态、设备权限或媒体条件不允许完成。后续状态仍以 calls.state 为准。

结束通话：client.calls.end()

无参数。SDK 根据当前身份和通话阶段选择拒绝、取消或挂断操作。

返回： Promise<boolean>，表示本次结束操作是否完成。

麦克风静音：client.calls.setMuted(value)

参数	类型	必填	说明
value	boolean	是	true 关闭本地麦克风，false 取消静音。

返回： Promise<boolean>，是否成功切换。当前值见 calls.state.muted。

摄像头开关：client.calls.setCameraMuted(value)

参数	类型	必填	说明
value	boolean	是	true 关闭本地摄像头，false 重新开启。

返回： Promise<boolean>，是否成功切换。当前值见 calls.state.cameraMuted。

切换摄像头：client.calls.switchCamera()

无参数，切换前后摄像头。

返回： Promise<boolean>，是否切换成功。当前是否前置见 calls.state.frontCamera，实际能力取决于设备。

恢复通话声音：client.calls.resumeAudio()

无参数。浏览器阻止自动播放时，在用户点击“恢复声音”后调用。

返回： Promise<boolean>，表示本次恢复是否成功。是否仍受限制见 calls.state.autoplayBlocked。

用户和认证对象

IMUser 字段：

字段	类型	必填	说明
userId	string	是	外部用户 ID，1–64 字符，无控制字符或首尾空白。
nickname	string	是	昵称，1–80 字符，无控制字符或首尾空白。
avatar	string	否	头像地址，最长 2048 字符。
username	string	否	账号，最长 64 字符。HTTP 值为 null 时可省略。
signature	string	否	个性签名，最长 255 字符。

authProvider 返回 IMAuth：

字段	类型	说明
user	IMUser	Token 对应用户的资料。
token	string	服务器签发的有效 IM Token，身份须与 user.userId 一致。
expireAt	number	Unix 秒时间戳，须与 Token 的 exp 一致，且尚未过期。

client.state 字段

状态只读，不要直接修改。

字段	类型	说明
session	'signed_out'、'offline'、'ready'	未登录、离线可读、已完成认证和同步。
connection	'online' 或 'offline'	当前网络连接状态。
loading	boolean	是否正在加载。
theme	'system'、'light' 或 'dark'	当前主题设置。
user	IMUser 或 null	当前用户；未登录时为 null。

client.calls.state 字段

字段	类型	说明
call	CallSnapshot 或 null	当前 SDK 通话状态；没有通话时为 null。字段含义见通话状态。SDK 的公开字段范围见表后说明。
isActing	boolean	是否正在提交接听、挂断等通话操作。
error	string	当前错误说明；没有错误时为空字符串。
preparing	boolean	是否正在为发起或接听准备媒体。
pending	object 或 null	媒体准备期间的目标；包含 userId 和 media，分别为对方外部 ID 与 audio/video。
mediaReady	boolean	媒体连接是否可用。
mediaPrepared	boolean	本地媒体是否已经准备好。
muted	boolean	本地麦克风是否静音。
cameraMuted	boolean	本地摄像头是否关闭。
frontCamera	boolean	是否正在使用前置摄像头。
remoteVideo	boolean	对方视频画面是否可用。
autoplayBlocked	boolean	浏览器是否阻止播放远端声音。

CallSnapshot 公开 call_id、kind、media、status、version、creator_id、participants、self、ring_deadline_at、lease_expires_at、answer_expires_at、connect_expires_at、started_at、ended_at、end_reason。参与人公开 user.user_id、user.nickname、user.avatar、role、status；self 公开 role、status、selected_device_id、lease_expires_at。它不暴露 TRTC 凭证。

浏览器外观同步：observeBrowserChrome()

从 SDK 模块直接导入此辅助函数，无参数。用于观察浏览器顶层页面的主题和边缘样式变化；常规 createIM 挂载已自动接入，不需要宿主重复调用。

返回： () => void，停止本次观察并在不再使用时恢复相关外观设置。

错误对象

参数错误可能为 TypeError，网络或业务失败可能为 ApiError。使用 try/catch 显示适当提示。

字段	类型	说明
message	string	错误说明。
code	number	ApiError 的业务错误码；普通 Error 不保证有此字段。
status	number	ApiError 保存的 HTTP 状态码；未取得响应时可能为 0。
recoverable	boolean	ApiError 是否标记为可通过恢复网络或重试恢复的读取错误。

销毁实例后不要继续调用需要活动实例的方法。需要重新使用时，重新创建并挂载。