语聊房场景 RTM 最佳实践
场景介绍
语聊房中,房主创建房间、管理公告和麦位,听众进入房间收听音频,也可以申请上麦、聊天或发送互动。所有成员需要看到一致的麦位归属,并能区分主动闭麦、被房主静音和麦克风异常。
本文按一轮完整的使用流程介绍实现方式:
- 用户取得身份和访问凭证,建立 RTM 会话。
- 房主创建房间,听众加入同一房间;各端同步公告、麦位和在线成员,并加入 RTC 收听音频。
- 听众申请上麦,房主审批并更新麦位;听众确认自己获得麦位后发布音频。
- 在麦成员开闭麦,房主执行麦控,各端同步成员状态。
- 成员发送公屏消息、礼物或爱心,接收端校验后展示。
- 用户下麦、离房或切换房间;再次进入时恢复当前状态。
麦位归属与音频发布结果分别维护。 成员在麦位上但没有声音,可能是主动闭麦、强制静音、采集失败或发布失败,不能仅凭 RTC 音频流判断其是否已下麦。
职责分工
| 能力 | 负责 | 不负责 |
|---|---|---|
| RTC | 麦克风采集、音频发布与订阅、实时音频传输 | 麦位归属、房间公告、互动消息、成员业务状态 |
| RTM | 房间状态、成员在线状态、麦位协同、文本互动、业务事件 | 音频数据传输 |
核心规则
集成 RTM 时,遵循以下五条核心规则:
- 一个用户身份只创建一个 RTM client,生命周期跟随 App 会话或语聊模块;进出房间不重复创建、不重复登录。
- 一个语聊房对应一个 RTM Channel,以稳定、唯一的
roomId作为 Channel Name;进房即订阅,离房即退订。 - 按数据特性选能力:需要被后来者恢复的房间状态放 Channel Storage,随成员在线而存在的临时状态放 Presence State,只处理一次的动作用 Message。
- 订阅成功 ≠ 房间状态就绪,链路恢复 ≠ 业务可恢复,两组状态分别建模。
- 所有业务消息带统一信封,消费前校验版本、房间、目标、有效期和消息 ID。
一次完整的上麦按以下顺序执行,麦位归属由 RTM 确认,RTC 发布结果不反向改变麦位:
RTM 确认麦位归属 → RTC 发布音频 → 发布失败时保留麦位 → 区分采集故障与发布故障
只有确认本地采集异常时,才通过 Presence 同步 microphoneError;采集正常但发布失败应单独提示,避免将网络发布故障显示为麦克风故障。
1. 为什么语聊房需要 RTM
RTM 在语聊房中主要解决三类业务问题:
- 表达业务状态。 RTC 音频流本身无法区分不在麦位、主动闭麦、采集异常或发布失败,麦位和成员状态需要独立同步。
- 恢复当前房间。 新加入或重连的用户需要直接获取完整麦位表、公告和在线成员,不能依赖过去的动作消息。
- 协同互动动作。 申请上麦、邀请上麦、公屏聊天、礼物和点赞通过实时消息完成。
这些需求对应以下能力:
| RTM 能力 | 在语聊房中的用途 |
|---|---|
| Message | 上麦协同、公屏消息、礼物、点赞等业务动作 |
| Presence | 在线成员列表及其临时状态(闭麦、麦克风异常) |
| Channel Storage | 麦位表、公告等房间权威状态,供新成员和重连成员直接读取 |
| Lock | 多个角色可修改麦位时的写入互斥 |
2. 设计原则
本节内容与平台无关。
Demo 的浏览器房间目录、昵称和准入逻辑用于演示,不构成服务端鉴权。生产环境应由业务服务端维护用户身份、房间目录、成员准入和权限,并提供 Token 服务。部署步骤见 部署 Token 服务器。
2.1 RTM client 与会话同生命周期
一个 RTM 用户身份只维护一个 client。client 可在 App 初始化时创建,是否立即登录取决于语聊在 App 中的定位:
- 语聊是核心功能:App 取得用户身份后即登录,App 退出或用户身份失效时登出;
- 语聊是附加功能:进入语聊模块时登录,退出整个模块时登出,避免闲置连接占用资源。
无论采用哪种生命周期,都要遵守:
- 所有事件监听在
login()之前注册,且只注册一次。否则可能收不到首次连接状态或登录期间到达的事件。 - 进出房间只对应
subscribe/unsubscribe。切房是先退订旧频道、再订阅新频道,不重建 client、不重复登录。 - 网络重连期间继续使用当前 client,等待 SDK 自动重连,并继续处理恢复期间到达的状态事件,不手动重登、不盲目重订阅。
- App 层持有 SDK 原始事件,按当前房间分发。切房时更换房间事件处理器,避免旧房间迟到的事件更新新房间页面。
2.2 一个房间对应一个 Channel
以业务 roomId 作为 RTM Channel Name,roomId 在当前 App ID 下唯一且稳定:
| 语聊房 | RTM Channel Name |
|---|---|
| 房间 A | voice-room-a8f31c |
| 房间 B | voice-room-c27d90 |
同一房间的房主与听众订阅同一 Channel,不同房间订阅不同 Channel。不要让多个房间共用一个 Channel 再靠消息字段区分:各房间会互相收到 Presence、Storage 和 Message,既浪费消息量,也容易误处理他房数据。
语聊房需要同时接收消息、Presence 和 Metadata,订阅时开启对应选项;只有单一角色写麦位时无需开启 Lock。
切房原则:先完整离开旧房间(停止新写入 → 等待关键写入结束 → 退出 RTC → 退订频道 → 清理本地状态与事件处理器),再进入新房间。用户连续切房时,客户端必须能识别并忽略旧房间迟到的异步结果,对迟到成功且已无人持有的旧频道订阅补做退订。实现方式见 3.4 切换与离开房间。
语聊房使用 Presence 和 Storage 前,需要在声网控制台开启对应功能;多个角色通过 Lock 协同管理麦位时,还需开启 Lock。控制台操作见 开通 RTM 服务。
2.3 按数据特性选择 Storage、Presence、Message
根据数据的有效期和接收范围选择能力:
| RTM 能力 | 适合的数据 | 语聊房示例 | 新成员是否需要获得 |
|---|---|---|---|
| Channel Storage | 房间当前的权威状态 | 公告、完整麦位表 | 是 |
| Presence State | 与在线成员绑定的临时状态 | 自主闭麦、麦克风异常 | 是,仅在成员在频道期间有效 |
USER Message | 只发给一个人的瞬时动作 | 申请上麦、邀请上麦、拒绝邀请 | 否 |
MESSAGE Message | 发给房间所有人的瞬时动作 | 公屏消息、礼物、点赞 | 否 |
Channel Storage:保存当前结果
后加入或重连的成员仍需读取的数据写入 Channel Storage。麦位表不能靠"某人刚刚上麦"的消息累加得出,因为晚加入者收不到之前的消息。
- 麦位由房主单点写入,避免多端并发修改;若有多个角色可管理麦位,配合 RTM Lock 使用。
- Storage 的
SNAPSHOT和UPDATE事件都携带完整的频道 Metadata。收到storage事件后,直接以最新快照替换本地房间状态;需要提示"某用户上麦"时,比较前后快照中对应麦位的userId是否从null变为具体用户即可。
Presence State:保存在线临时状态
Presence State 保存用户自己在频道期间有效的状态。每次只写入发生变化的字段;成员下麦后删除只在麦位上有意义的字段。收到 Presence SNAPSHOT 时全量替换在线成员列表,收到加入、离开或状态变化事件时增量更新。
用户离开频道后,其 Presence State 会同时从 RTM 服务端删除,因此不要用 Presence State 保存长期用户资料;长期资料使用 User Storage。
Message:传递瞬时动作
Message 用于发生后只处理一次的动作。只发给一个参与者的动作使用 USER Channel;房间内所有成员都要接收的互动使用当前房间的 MESSAGE Channel。
publish()的成功语义取决于 Channel Type:
- 使用
USERChannel 发送点对点消息时,publish()成功表示目标用户已经收到消息,但不代表目标用户已经完成对应的业务处理。- 使用
MESSAGEChannel 发送频道消息时,publish()成功表示消息已经发送到 RTM 服务端。服务端随后向频道内其他成员推送消息;其他成员能否收到,取决于其与 RTM 服务端的连接状态和网络质量。
因此,申请上麦等点对点动作不能以发送成功视为流程完成:审批后的麦位归属必须写入 Channel Storage,各端最终以 Storage 中的完整麦位表为准。
2.4 区分"频道已订阅"与"房间状态已就绪"
subscribe() 完成只表示 SDK 的订阅调用已结束,不表示首个 Presence 或 Storage 快照已到达。客户端需要分别维护两个状态:
- 频道已订阅:
subscribe()成功,可以结束"正在加入"提示、开始 RTC 入房; - 房间状态已就绪:当前房间的完整 Storage 快照已到达,依赖麦位或公告的操作才可开放。
不要把等待首个快照合并进订阅调用的结果中。
2.5 重连:链路恢复与业务恢复分开判断
网络中断后,把房间界面置为"恢复中"并暂停依赖实时连接的写入。连接恢复后不重建 client、不重复 login()、不盲目重复 subscribe(),继续处理 SDK 到达的状态事件:有事件就刷新对应状态,不把等待一条新的 Storage 或 Presence 事件作为恢复的必经条件。
| 信号 | 业务处理 |
|---|---|
当前 MESSAGE 服务的 linkState 恢复为已连接 | 恢复连接相关能力;检查当前房间是否仍有效,以及本地是否已有初始化完成的房间状态 |
| 收到当前房间完整 Storage 状态 | 用较新版本更新麦位和公告 |
| 收到 Presence 快照或成员变化事件 | 按事件语义刷新成员及其临时状态 |
Storage 版本未变化时,SDK 可能不再次通知;没有新事件不等于必须继续等待。已有有效状态可以继续使用。首次入房仍按 2.4 区分"频道已订阅"与"房间状态已就绪" 等待初始化;如果本地状态已丢失、订阅恢复失败,或业务操作要求主动确认最新状态,则发起查询、处理失败并设置超时,不能无限等待事件,也不能把“没有事件”解释成服务端状态一定未变。
2.6 消息协议必须可校验
RTM Message 支持文本和二进制两种格式。无论使用哪种,业务层都应定义统一的消息信封,标识协议版本、房间、目标用户、有效期和消息 ID。本文示例使用 JSON 文本便于跨端调试;使用 Protobuf 等二进制协议时应包含含义相同的字段。
收到消息后按以下顺序校验,任一项不通过即丢弃:
- 内容为合法格式,字段和类型完整;
schemaVersion为当前客户端支持的版本;- 信封中的
roomId属于当前房间;对于MESSAGE频道消息,还必须校验 SDK 事件的channelName与当前房间的 Channel Name 一致; - 对于
USER点对点消息,校验targetUserId是当前用户,并校验发送者的业务身份和权限;此时 SDK 事件的channelName是目标用户 UID,不能拿它与roomId比较; - 当前时间早于
expiresAt; messageId未处理过。
通过 TTL 丢弃已失效的上麦邀请或申请;用有容量上限的集合保存近期已处理的 messageId,避免重复执行,也避免长期运行后内存持续增长。
3. 实现指南
基础接入见 实现收发消息,凭证准备见 部署 Token 服务器 和 客户端鉴权。
文首在线体验和 Demo 源码均为 Web 版本。以下代码基于 RTM Java SDK 2.x,展示本平台的关键调用片段。事件名、参数结构和 Token 更新方式以实际接入的 SDK 版本为准。
3.1 创建 client 并注册事件
Java SDK 在创建 client 时通过 RtmConfig 传入事件监听,监听在 login() 之前即已生效:
RtmEventListener eventListener = new RtmEventListener() {
@Override
public void onLinkStateEvent(LinkStateEvent event) { onLinkState(event); }
@Override
public void onMessageEvent(MessageEvent event) { onMessage(event); }
@Override
public void onPresenceEvent(PresenceEvent event) { onPresence(event); }
@Override
public void onStorageEvent(StorageEvent event) { onStorage(event); }
@Override
public void onTokenPrivilegeWillExpire(String channelName) { onTokenWillExpire(channelName); }
};
// 全部事件随 client 一起注册,且只注册一次
RtmConfig config = new RtmConfig.Builder(appId, userId)
.eventListener(eventListener)
.build();
RtmClient client = RtmClient.create(config); // 失败时抛出 Exception
3.2 登录
按 2.1 RTM client 与会话同生命周期 确定的生命周期调用 login()。同一会话内只登录一次;登录结果返回前不要重复调用,登录失败后允许重试。
client.login(token, new ResultCallback<Void>() {
@Override
public void onSuccess(Void responseInfo) { /* 已登录 */ }
@Override
public void onFailure(ErrorInfo errorInfo) { /* 清除登录中标记,允许重试 */ }
});
3.3 进入房间
HashMap<String, String> states = new HashMap<>();
states.put("muted", "false");
states.put("microphoneError", "false");
client.getPresence().setState(roomId, RtmChannelType.MESSAGE, states, setStateCallback);
SubscribeOptions options = new SubscribeOptions();
options.setWithMessage(true);
options.setWithPresence(true);
options.setWithMetadata(true);
options.setWithLock(false); // 多角色管理麦位时改为 true 并配合 Lock 使用
client.subscribe(roomId, options, subscribeCallback);
在权威房间状态到达前(见 2.4 区分"频道已订阅"与"房间状态已就绪"),禁用依赖麦位或公告的操作。
3.4 切换与离开房间
离开房间:停止新的状态写入 → 等待已发起的关键写入结束 → 退出 RTC → unsubscribe(roomId) → 清理本地房间状态与事件处理器。用户仍在会话或语聊模块内时保留已登录的 client。
切换房间即"离开旧房间 → 进入新房间"。为每次入房生成递增的 generation,每个异步回调返回后先检查该次入房是否仍然有效,再更新 UI:
generation 由房间会话对象统一管理,每次新的入房意图或离房时递增;一次入房的多个异步步骤捕获同一个值,不能各自递增。连续 A→B→A 时,旧 A 的回调虽然过期,新一代却可能正在使用同一个频道。SDK 的退订按频道名生效,不区分业务 generation,因此不能仅凭 generation 不匹配就退订。
建议按频道串行执行订阅和退订,并在同一个业务线程维护当前需要持有的频道集合。下面的 isChannelStillDesired(roomId) 表示由会话管理器查询该集合;过期结果只在该频道已无人需要时补退订。检查和发起退订之间不能插入新的入房请求,退订完成后再启动同频道的新订阅;退订失败应记录并重试清理。
final int generation = ++this.generation;
client.subscribe(roomId, options, new ResultCallback<Void>() {
@Override
public void onSuccess(Void responseInfo) {
if (generation != RoomSession.this.generation) {
// 过期结果不更新 UI;仍被新一代需要的频道不能退订
if (!isChannelStillDesired(roomId)) {
client.unsubscribe(roomId, ignoreResultCallback);
}
return;
}
onRoomSubscribed(roomId);
}
@Override
public void onFailure(ErrorInfo errorInfo) {
if (generation != RoomSession.this.generation) return;
onRoomSubscribeFailed(roomId, errorInfo);
}
});
SDK 回调可能不在主线程触发,更新 UI 前请切换到主线程。
3.5 写入房间状态
麦位表写入 Channel Storage,二选一:整表作为一个 key(写入简单,整表竞争),或每个麦位一个 key(按麦位竞争,便于配合 Lock)。
{
"seats": [
{ "seatId": "seat-1", "userId": "user-a" },
{ "seatId": "seat-2", "userId": null }
]
}
{ "seat-1": { "userId": "user-a" }, "seat-2": { "userId": null } }
成员临时状态写入 Presence State,只更新变化的字段:
HashMap<String, String> changed = new HashMap<>();
changed.put("muted", "true");
client.getPresence().setState(roomId, RtmChannelType.MESSAGE, changed, setStateCallback);
3.6 发送与消费消息
统一信封示例:
public final class VoiceRoomEnvelope {
public int schemaVersion = 1;
public String messageId;
public String type;
public String roomId;
public String targetUserId; // 点对点消息必填
public long sentAt;
public long expiresAt;
public JSONObject payload;
}
onMessage 中按 2.6 消息协议必须可校验 的六步校验后再交给业务处理。
3.7 退出
语聊是核心功能时,仅在 App 销毁、用户退出账号或 RTM 身份变化时调用 logout() 并 release();语聊是附加功能时,退出整个语聊模块时执行。单纯离开一个房间不要 logout()。
client.logout(logoutCallback);
// release() 需要在非回调线程中调用
client.release();
3.8 封装建议
将 SDK client 封装在应用级 RTM 会话对象中,房间业务只调用 enterRoom()、leaveRoom()、requestSeat()、updateSeats()、sendChatMessage() 等业务方法,不直接传入消息类型、Metadata key 或 Channel Type,避免同一条协议规则散落在多个 UI 组件中。
Web Demo 使用 AppRtmSession 管理会话,HostRoomRtm / AudienceRoomRtm 封装角色操作,SingleRoomClient 消费房间状态并协调 RTC。这些都是 Web Demo 类,不是 SDK 接口;本平台可参考其职责划分封装业务。参考 会话封装 和 房间业务实现。
4. 常见错误
每次进房都创建并登录一个 RTM client
重复注册监听、重复维护连接状态,快速切房时留下旧实例。一个会话只登录一个 client,房间逻辑只负责订阅与退订。
多个房间共用一个 Channel,再靠消息字段过滤
各房间互相收到彼此的 Presence、Storage 和 Message,浪费消息量且容易误处理。每个语聊房使用独立 Channel。
用 Message 保存最终房间状态
后加入的成员收不到之前的 Message。公告、麦位表等当前状态必须写入 Channel Storage,Message 只传递动作。
用 Storage 保存高频临时状态
自主闭麦、麦克风异常只在成员在线期间有效,应写入 Presence State。写进 Storage 会增加无意义的状态合并和并发写入。
把 subscribe() 完成当作房间状态已就绪
订阅成功与首个快照到达是两个阶段。收到 Storage 快照前,依赖麦位或公告的按钮保持不可用。
链路恢复后立即开放全部操作
连接恢复后,结合当前房间是否有效、是否已初始化以及操作的状态要求恢复能力;有新事件就刷新,没有新事件不强制等待。需要确认最新状态时主动查询,并处理失败和超时。
收到消息后直接执行
未经校验的消息可能已过期、属于其他房间或被重复投递。版本、房间、目标、TTL 和 messageId 全部通过后才交给业务处理。
5. 上线检查清单
- 一个 App 会话或语聊模块会话中,同一 RTM 身份只创建一个 client
- 所有 SDK 事件都在
login()前注册,且只注册一次 - 每个语聊房都有唯一、稳定的 Channel Name
- 进房使用
subscribe(roomId),离房使用unsubscribe(roomId) - 离开或切换房间不触发
logout() - 核心功能在 App 退出或用户身份结束时
logout();附加功能在退出语聊模块时logout() - Channel Storage 只保存需要被恢复的房间当前状态
- Presence State 只保存在线成员的临时状态
- 单人动作使用
USERMessage,房间广播使用MESSAGEMessage - 最终麦位状态以 Storage 为准,不从 Message 历史推导
- "频道已订阅"与"房间状态已就绪"分别建模
- 重连后按事件刷新状态,不强制等待新事件;不重建 client、不盲目重复订阅
- 消息包含版本、唯一 ID、房间、时间和过期时间,并在消费前校验
- 快速切房时统一管理 generation,并在补退订前检查频道是否仍被新会话需要
- RTC 失败不会自动回滚已确认的 RTM 房间状态