# 语聊房场景 (/zh-CN/realtime-media/rtm/best-practice/voice-room)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在线体验本场景} href="https://rtm-demo.shengwang.cn/social/voice-room?utm_source=docs&utm_medium=scenario_doc" external />
查看 Demo 源码} href="https://github.com/AgoraIO-Community/RTM-Demo/tree/master/src/scenes/voice-room" external />
<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" />
## 场景介绍 [#场景介绍]
语聊房中,房主创建房间、管理公告和麦位,听众进入房间收听音频,也可以申请上麦、聊天或发送互动。所有成员需要看到一致的麦位归属,并能区分主动闭麦、被房主静音和麦克风异常。
本文按一轮完整的使用流程介绍实现方式:
1. 用户取得身份和访问凭证,建立 RTM 会话。
2. 房主创建房间,听众加入同一房间;各端同步公告、麦位和在线成员,并加入 RTC 收听音频。
3. 听众申请上麦,房主审批并更新麦位;听众确认自己获得麦位后发布音频。
4. 在麦成员开闭麦,房主执行麦控,各端同步成员状态。
5. 成员发送公屏消息、礼物或爱心,接收端校验后展示。
6. 用户下麦、离房或切换房间;再次进入时恢复当前状态。
**麦位归属与音频发布结果分别维护。** 成员在麦位上但没有声音,可能是主动闭麦、强制静音、采集失败或发布失败,不能仅凭 RTC 音频流判断其是否已下麦。
### 职责分工 [#职责分工]
| 能力 | 负责 | 不负责 |
| ---- | ---------------------------------------------------- | ------------------------------------------ |
| RTC | 麦克风采集、音频发布与订阅、实时音频传输 | 麦位归属、房间公告、互动消息、成员业务状态 |
| RTM | 房间状态、成员在线状态、麦位协同、文本互动、业务事件 | 音频数据传输 |
### 核心规则 [#核心规则]
集成 RTM 时,遵循以下五条核心规则:
1. **一个用户身份只创建一个 RTM client**,生命周期跟随 App 会话或语聊模块;进出房间不重复创建、不重复登录。
2. **一个语聊房对应一个 RTM Channel**,以稳定、唯一的 `roomId` 作为 Channel Name;进房即订阅,离房即退订。
3. **按数据特性选能力**:需要被后来者恢复的房间状态放 Channel Storage,随成员在线而存在的临时状态放 Presence State,只处理一次的动作用 Message。
4. **订阅成功 ≠ 房间状态就绪,链路恢复 ≠ 业务可恢复**,两组状态分别建模。
5. **所有业务消息带统一信封**,消费前校验版本、房间、目标、有效期和消息 ID。
一次完整的上麦按以下顺序执行,麦位归属由 RTM 确认,RTC 发布结果不反向改变麦位:
```text
RTM 确认麦位归属 → RTC 发布音频 → 发布失败时保留麦位 → 区分采集故障与发布故障
```
只有确认本地采集异常时,才通过 Presence 同步 `microphoneError`;采集正常但发布失败应单独提示,避免将网络发布故障显示为麦克风故障。
## 1. 为什么语聊房需要 RTM [#1-为什么语聊房需要-rtm]
RTM 在语聊房中主要解决三类业务问题:
- **表达业务状态。** RTC 音频流本身无法区分不在麦位、主动闭麦、采集异常或发布失败,麦位和成员状态需要独立同步。
- **恢复当前房间。** 新加入或重连的用户需要直接获取完整麦位表、公告和在线成员,不能依赖过去的动作消息。
- **协同互动动作。** 申请上麦、邀请上麦、公屏聊天、礼物和点赞通过实时消息完成。
这些需求对应以下能力:
| RTM 能力 | 在语聊房中的用途 |
| --------------- | ------------------------------------------------------ |
| Message | 上麦协同、公屏消息、礼物、点赞等业务动作 |
| Presence | 在线成员列表及其临时状态(闭麦、麦克风异常) |
| Channel Storage | 麦位表、公告等房间权威状态,供新成员和重连成员直接读取 |
| Lock | 多个角色可修改麦位时的写入互斥 |
## 2. 设计原则 [#2-设计原则]
本节内容与平台无关。
:::note[Demo 与生产接入]
Demo 的浏览器房间目录、昵称和准入逻辑用于演示,不构成服务端鉴权。生产环境应由业务服务端维护用户身份、房间目录、成员准入和权限,并提供 Token 服务。部署步骤见 [部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。
:::
### 2.1 RTM client 与会话同生命周期 [#21-rtm-client-与会话同生命周期]
一个 RTM 用户身份只维护一个 client。client 可在 App 初始化时创建,**是否立即登录取决于语聊在 App 中的定位**:
- 语聊是核心功能:App 取得用户身份后即登录,App 退出或用户身份失效时登出;
- 语聊是附加功能:进入语聊模块时登录,退出整个模块时登出,避免闲置连接占用资源。

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

无论采用哪种生命周期,都要遵守:
- **所有事件监听在 `login()` 之前注册,且只注册一次**。否则可能收不到首次连接状态或登录期间到达的事件。
- **进出房间只对应 `subscribe` / `unsubscribe`**。切房是先退订旧频道、再订阅新频道,不重建 client、不重复登录。
- **网络重连期间继续使用当前 client**,等待 SDK 自动重连,并继续处理恢复期间到达的状态事件,不手动重登、不盲目重订阅。
- **App 层持有 SDK 原始事件,按当前房间分发**。切房时更换房间事件处理器,避免旧房间迟到的事件更新新房间页面。
### 2.2 一个房间对应一个 Channel [#22-一个房间对应一个-channel-1]
以业务 `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 切换与离开房间](#34-切换与离开房间)。
语聊房使用 Presence 和 Storage 前,需要在声网控制台开启对应功能;多个角色通过 Lock 协同管理麦位时,还需开启 Lock。控制台操作见 [开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service#3-开通-rtm-服务)。
### 2.3 按数据特性选择 Storage、Presence、Message [#23-按数据特性选择-storagepresencemessage-1]
根据数据的**有效期**和**接收范围**选择能力:
| RTM 能力 | 适合的数据 | 语聊房示例 | 新成员是否需要获得 |
| ----------------- | ------------------------ | ---------------------------- | -------------------------- |
| Channel Storage | 房间当前的权威状态 | 公告、完整麦位表 | 是 |
| Presence State | 与在线成员绑定的临时状态 | 自主闭麦、麦克风异常 | 是,仅在成员在频道期间有效 |
| `USER` Message | 只发给一个人的瞬时动作 | 申请上麦、邀请上麦、拒绝邀请 | 否 |
| `MESSAGE` Message | 发给房间所有人的瞬时动作 | 公屏消息、礼物、点赞 | 否 |
**Channel Storage:保存当前结果**
后加入或重连的成员仍需读取的数据写入 Channel Storage。麦位表不能靠"某人刚刚上麦"的消息累加得出,因为晚加入者收不到之前的消息。
- 麦位由房主单点写入,避免多端并发修改;若有多个角色可管理麦位,配合 [RTM Lock](/zh-CN/api-reference/rtm/ios/lock) 使用。
- Storage 的 `SNAPSHOT` 和 `UPDATE` 事件都携带完整的频道 Metadata。收到 `storage` 事件后,直接以最新快照替换本地房间状态;需要提示"某用户上麦"时,比较前后快照中对应麦位的 `userId` 是否从 `null` 变为具体用户即可。
**Presence State:保存在线临时状态**
Presence State 保存用户自己在频道期间有效的状态。每次只写入发生变化的字段;成员下麦后删除只在麦位上有意义的字段。收到 Presence `SNAPSHOT` 时全量替换在线成员列表,收到加入、离开或状态变化事件时增量更新。
用户离开频道后,其 Presence State 会同时从 RTM 服务端删除,因此不要用 Presence State 保存长期用户资料;长期资料使用 [User Storage](/zh-CN/api-reference/rtm/ios/storage#setusermetadata)。
**Message:传递瞬时动作**
Message 用于发生后只处理一次的动作。只发给一个参与者的动作使用 `USER` Channel;房间内所有成员都要接收的互动使用当前房间的 `MESSAGE` Channel。
`publish()` 的成功语义取决于 Channel Type:
- 使用 `USER` Channel 发送点对点消息时,`publish()` 成功表示目标用户已经收到消息,但不代表目标用户已经完成对应的业务处理。
- 使用 `MESSAGE` Channel 发送频道消息时,`publish()` 成功表示消息已经发送到 RTM 服务端。服务端随后向频道内其他成员推送消息;其他成员能否收到,取决于其与 RTM 服务端的连接状态和网络质量。
因此,**申请上麦等点对点动作不能以发送成功视为流程完成**:审批后的麦位归属必须写入 Channel Storage,各端最终以 Storage 中的完整麦位表为准。
### 2.4 区分"频道已订阅"与"房间状态已就绪" [#24-区分频道已订阅与房间状态已就绪-1]
`subscribe()` 完成只表示 SDK 的订阅调用已结束,不表示首个 Presence 或 Storage 快照已到达。客户端需要分别维护两个状态:
- **频道已订阅**:`subscribe()` 成功,可以结束"正在加入"提示、开始 RTC 入房;
- **房间状态已就绪**:当前房间的完整 Storage 快照已到达,依赖麦位或公告的操作才可开放。
不要把等待首个快照合并进订阅调用的结果中。
### 2.5 重连:链路恢复与业务恢复分开判断 [#25-重连链路恢复与业务恢复分开判断-1]
网络中断后,把房间界面置为"恢复中"并暂停依赖实时连接的写入。连接恢复后不重建 client、不重复 `login()`、不盲目重复 `subscribe()`,继续处理 SDK 到达的状态事件:**有事件就刷新对应状态,不把等待一条新的 Storage 或 Presence 事件作为恢复的必经条件**。
| 信号 | 业务处理 |
| ---- | -------- |
| 当前 MESSAGE 服务的 `linkState` 恢复为已连接 | 恢复连接相关能力;检查当前房间是否仍有效,以及本地是否已有初始化完成的房间状态 |
| 收到当前房间完整 Storage 状态 | 用较新版本更新麦位和公告 |
| 收到 Presence 快照或成员变化事件 | 按事件语义刷新成员及其临时状态 |
Storage 版本未变化时,SDK 可能不再次通知;没有新事件不等于必须继续等待。已有有效状态可以继续使用。首次入房仍按 [2.4 区分"频道已订阅"与"房间状态已就绪"](#24-区分频道已订阅与房间状态已就绪) 等待初始化;如果本地状态已丢失、订阅恢复失败,或业务操作要求主动确认最新状态,则发起查询、处理失败并设置超时,不能无限等待事件,也不能把“没有事件”解释成服务端状态一定未变。
### 2.6 消息协议必须可校验 [#26-消息协议必须可校验-1]
RTM Message 支持文本和二进制两种格式。无论使用哪种,业务层都应定义统一的消息信封,标识协议版本、房间、目标用户、有效期和消息 ID。本文示例使用 JSON 文本便于跨端调试;使用 Protobuf 等二进制协议时应包含含义相同的字段。
收到消息后按以下顺序校验,任一项不通过即丢弃:
1. 内容为合法格式,字段和类型完整;
2. `schemaVersion` 为当前客户端支持的版本;
3. 信封中的 `roomId` 属于当前房间;对于 `MESSAGE` 频道消息,还必须校验 SDK 事件的 `channelName` 与当前房间的 Channel Name 一致;
4. 对于 `USER` 点对点消息,校验 `targetUserId` 是当前用户,并校验发送者的业务身份和权限;此时 SDK 事件的 `channelName` 是目标用户 UID,不能拿它与 `roomId` 比较;
5. 当前时间早于 `expiresAt`;
6. `messageId` 未处理过。
通过 TTL 丢弃已失效的上麦邀请或申请;用有容量上限的集合保存近期已处理的 `messageId`,避免重复执行,也避免长期运行后内存持续增长。
## 3. 实现指南 [#3-实现指南-1]
基础接入见 [实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start/ios),凭证准备见 [部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation) 和 [客户端鉴权](/zh-CN/realtime-media/rtm/build/authentication-and-connection/user-authentication/ios)。
文首在线体验和 Demo 源码均为 Web 版本。以下代码基于 RTM Objective-C SDK 2.x,展示本平台的关键调用片段。事件名、参数结构和 Token 更新方式以实际接入的 SDK 版本为准。
### 3.1 创建 client 并注册事件 [#31-创建-client-并注册事件-1]
Objective-C SDK 在创建 client 时传入 `AgoraRtmClientDelegate`,监听在 `loginByToken` 之前即已生效:
```objc
@interface VoiceRoomRtmListener : NSObject
@end
@implementation VoiceRoomRtmListener
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveLinkStateEvent:(AgoraRtmLinkStateEvent *)event {}
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveMessageEvent:(AgoraRtmMessageEvent *)event {}
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceivePresenceEvent:(AgoraRtmPresenceEvent *)event {}
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveStorageEvent:(AgoraRtmStorageEvent *)event {}
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit tokenPrivilegeWillExpire:(NSString *)channel {}
@end
// 全部事件随 client 一起注册,且只注册一次
AgoraRtmClientConfig *config = [[AgoraRtmClientConfig alloc] initWithAppId:appId userId:userId];
NSError *initError = nil;
self.listener = [[VoiceRoomRtmListener alloc] init];
self.rtm = [[AgoraRtmClientKit alloc] initWithConfig:config delegate:self.listener error:&initError];
```
### 3.2 登录 [#32-登录-1]
按 [2.1 RTM client 与会话同生命周期](#21-rtm-client-与会话同生命周期) 确定的生命周期调用 `loginByToken`。同一会话内只登录一次;登录结果返回前不要重复调用,登录失败后允许重试。
```objc
[self.rtm loginByToken:token completion:^(AgoraRtmCommonResponse *response, AgoraRtmErrorInfo *errorInfo) {
if (errorInfo == nil) {
// 已登录
} else {
// 清除登录中标记,允许重试
}
}];
```
### 3.3 进入房间 [#33-进入房间-1]
```objc
NSDictionary *states = @{ @"muted": @"false", @"microphoneError": @"false" };
[[self.rtm getPresence] setState:roomId
channelType:AgoraRtmChannelTypeMessage
items:states
completion:setStateCompletion];
AgoraRtmSubscribeOptions *options = [[AgoraRtmSubscribeOptions alloc] init];
// 多角色管理麦位时再加上 AgoraRtmSubscribeChannelFeatureLock,并配合 Lock 使用
options.features = AgoraRtmSubscribeChannelFeatureMessage |
AgoraRtmSubscribeChannelFeaturePresence |
AgoraRtmSubscribeChannelFeatureMetadata;
[self.rtm subscribeWithChannel:roomId option:options completion:subscribeCompletion];
```
在权威房间状态到达前(见 [2.4 区分"频道已订阅"与"房间状态已就绪"](#24-区分频道已订阅与房间状态已就绪)),禁用依赖麦位或公告的操作。
### 3.4 切换与离开房间 [#34-切换与离开房间-1]
离开房间:停止新的状态写入 → 等待已发起的关键写入结束 → 退出 RTC → `unsubscribeWithChannel:` → 清理本地房间状态与事件处理器。用户仍在会话或语聊模块内时保留已登录的 client。
切换房间即"离开旧房间 → 进入新房间"。为每次入房生成递增的 `generation`,每个异步回调返回后先检查该次入房是否仍然有效,再更新 UI:
:::note[集成约束]
`generation` 由房间会话对象统一管理,每次新的入房意图或离房时递增;一次入房的多个异步步骤捕获同一个值,不能各自递增。连续 A→B→A 时,旧 A 的回调虽然过期,新一代却可能正在使用同一个频道。SDK 的退订按频道名生效,不区分业务 generation,因此不能仅凭 generation 不匹配就退订。
:::
建议按频道串行执行订阅和退订,并在同一个业务线程维护当前需要持有的频道集合。下面的 `isChannelStillDesired(roomId)` 表示由会话管理器查询该集合;过期结果只在该频道已无人需要时补退订。检查和发起退订之间不能插入新的入房请求,退订完成后再启动同频道的新订阅;退订失败应记录并重试清理。
```objc
NSInteger generation = ++self.generation;
__weak typeof(self) weakSelf = self;
[self.rtm subscribeWithChannel:roomId option:options completion:^(AgoraRtmCommonResponse *response, AgoraRtmErrorInfo *errorInfo) {
__strong typeof(weakSelf) strongSelf = weakSelf;
if (strongSelf == nil) return;
if (generation != strongSelf.generation) {
// 订阅期间用户已切房:成功的订阅需要补退订,忽略本次结果
if (errorInfo == nil && ![strongSelf isChannelStillDesired:roomId]) {
[strongSelf.rtm unsubscribeWithChannel:roomId completion:nil];
}
return;
}
// 处理本次订阅结果
}];
```
### 3.5 写入房间状态 [#35-写入房间状态-1]
麦位表写入 Channel Storage,二选一:整表作为一个 key(写入简单,整表竞争),或每个麦位一个 key(按麦位竞争,便于配合 Lock)。
```json
{
"seats": [
{ "seatId": "seat-1", "userId": "user-a" },
{ "seatId": "seat-2", "userId": null }
]
}
```
```json
{ "seat-1": { "userId": "user-a" }, "seat-2": { "userId": null } }
```
成员临时状态写入 Presence State,只更新变化的字段:
```objc
[[self.rtm getPresence] setState:roomId
channelType:AgoraRtmChannelTypeMessage
items:@{ @"muted": @"true" }
completion:setStateCompletion];
```
### 3.6 发送与消费消息 [#36-发送与消费消息-1]
统一信封示例:
```objc
@interface VoiceRoomEnvelope : NSObject
@property (nonatomic, assign) NSInteger schemaVersion; // 固定为 1
@property (nonatomic, copy) NSString *messageId;
@property (nonatomic, copy) NSString *type;
@property (nonatomic, copy) NSString *roomId;
@property (nonatomic, copy, nullable) NSString *targetUserId; // 点对点消息必填
@property (nonatomic, assign) int64_t sentAt;
@property (nonatomic, assign) int64_t expiresAt;
@property (nonatomic, copy) NSDictionary *payload;
@end
```
`didReceiveMessageEvent` 中按 [2.6 消息协议必须可校验](#26-消息协议必须可校验) 的六步校验后再交给业务处理。
### 3.7 退出 [#37-退出-1]
语聊是核心功能时,仅在 App 销毁、用户退出账号或 RTM 身份变化时调用 `logout:` 并 `destroy`;语聊是附加功能时,退出整个语聊模块时执行。**单纯离开一个房间不要 `logout:`。**
```objc
[self.rtm logout:^(AgoraRtmCommonResponse *response, AgoraRtmErrorInfo *errorInfo) {
// 登出结果
}];
// destroy 需要在非回调线程中调用
[self.rtm destroy];
self.rtm = nil;
```
### 3.8 封装建议 [#38-封装建议-1]
将 SDK client 封装在应用级 RTM 会话对象中,房间业务只调用 `enterRoom`、`leaveRoom`、`requestSeat`、`updateSeats`、`sendChatMessage` 等业务方法,不直接传入消息类型、Metadata key 或 Channel Type,避免同一条协议规则散落在多个 UI 组件中。
Web Demo 使用 `AppRtmSession` 管理会话,`HostRoomRtm` / `AudienceRoomRtm` 封装角色操作,`SingleRoomClient` 消费房间状态并协调 RTC。这些都是 Web Demo 类,不是 SDK 接口;本平台可参考其职责划分封装业务。参考 [会话封装](https://github.com/AgoraIO-Community/RTM-Demo/blob/a79b0bd17aa503214aac7b33e5426dd13b19356a/src/scenes/voice-room/app-rtm.ts) 和 [房间业务实现](https://github.com/AgoraIO-Community/RTM-Demo/blob/a79b0bd17aa503214aac7b33e5426dd13b19356a/src/scenes/voice-room/event-driven-single-room-client.ts)。
## 4. 常见错误 [#4-常见错误-1]
**每次进房都创建并登录一个 RTM client**
重复注册监听、重复维护连接状态,快速切房时留下旧实例。一个会话只登录一个 client,房间逻辑只负责订阅与退订。
**多个房间共用一个 Channel,再靠消息字段过滤**
各房间互相收到彼此的 Presence、Storage 和 Message,浪费消息量且容易误处理。每个语聊房使用独立 Channel。
**用 Message 保存最终房间状态**
后加入的成员收不到之前的 Message。公告、麦位表等当前状态必须写入 Channel Storage,Message 只传递动作。
**用 Storage 保存高频临时状态**
自主闭麦、麦克风异常只在成员在线期间有效,应写入 Presence State。写进 Storage 会增加无意义的状态合并和并发写入。
**把 `subscribe()` 完成当作房间状态已就绪**
订阅成功与首个快照到达是两个阶段。收到 Storage 快照前,依赖麦位或公告的按钮保持不可用。
**链路恢复后立即开放全部操作**
连接恢复后,结合当前房间是否有效、是否已初始化以及操作的状态要求恢复能力;有新事件就刷新,没有新事件不强制等待。需要确认最新状态时主动查询,并处理失败和超时。
**收到消息后直接执行**
未经校验的消息可能已过期、属于其他房间或被重复投递。版本、房间、目标、TTL 和 `messageId` 全部通过后才交给业务处理。
## 5. 上线检查清单 [#5-上线检查清单-1]
- 一个 App 会话或语聊模块会话中,同一 RTM 身份只创建一个 client
- 所有 SDK 事件都在 `login()` 前注册,且只注册一次
- 每个语聊房都有唯一、稳定的 Channel Name
- 进房使用 `subscribe(roomId)`,离房使用 `unsubscribe(roomId)`
- 离开或切换房间不触发 `logout()`
- 核心功能在 App 退出或用户身份结束时 `logout()`;附加功能在退出语聊模块时 `logout()`
- Channel Storage 只保存需要被恢复的房间当前状态
- Presence State 只保存在线成员的临时状态
- 单人动作使用 `USER` Message,房间广播使用 `MESSAGE` Message
- 最终麦位状态以 Storage 为准,不从 Message 历史推导
- "频道已订阅"与"房间状态已就绪"分别建模
- 重连后按事件刷新状态,不强制等待新事件;不重建 client、不盲目重复订阅
- 消息包含版本、唯一 ID、房间、时间和过期时间,并在消费前校验
- 快速切房时统一管理 generation,并在补退订前检查频道是否仍被新会话需要
- RTC 失败不会自动回滚已确认的 RTM 房间状态
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" />
## 场景介绍 [#场景介绍-2]
语聊房中,房主创建房间、管理公告和麦位,听众进入房间收听音频,也可以申请上麦、聊天或发送互动。所有成员需要看到一致的麦位归属,并能区分主动闭麦、被房主静音和麦克风异常。
本文按一轮完整的使用流程介绍实现方式:
1. 用户取得身份和访问凭证,建立 RTM 会话。
2. 房主创建房间,听众加入同一房间;各端同步公告、麦位和在线成员,并加入 RTC 收听音频。
3. 听众申请上麦,房主审批并更新麦位;听众确认自己获得麦位后发布音频。
4. 在麦成员开闭麦,房主执行麦控,各端同步成员状态。
5. 成员发送公屏消息、礼物或爱心,接收端校验后展示。
6. 用户下麦、离房或切换房间;再次进入时恢复当前状态。
**麦位归属与音频发布结果分别维护。** 成员在麦位上但没有声音,可能是主动闭麦、强制静音、采集失败或发布失败,不能仅凭 RTC 音频流判断其是否已下麦。
### 职责分工 [#职责分工-2]
| 能力 | 负责 | 不负责 |
| ---- | ---------------------------------------------------- | ------------------------------------------ |
| RTC | 麦克风采集、音频发布与订阅、实时音频传输 | 麦位归属、房间公告、互动消息、成员业务状态 |
| RTM | 房间状态、成员在线状态、麦位协同、文本互动、业务事件 | 音频数据传输 |
### 核心规则 [#核心规则-2]
集成 RTM 时,遵循以下五条核心规则:
1. **一个用户身份只创建一个 RTM client**,生命周期跟随 App 会话或语聊模块;进出房间不重复创建、不重复登录。
2. **一个语聊房对应一个 RTM Channel**,以稳定、唯一的 `roomId` 作为 Channel Name;进房即订阅,离房即退订。
3. **按数据特性选能力**:需要被后来者恢复的房间状态放 Channel Storage,随成员在线而存在的临时状态放 Presence State,只处理一次的动作用 Message。
4. **订阅成功 ≠ 房间状态就绪,链路恢复 ≠ 业务可恢复**,两组状态分别建模。
5. **所有业务消息带统一信封**,消费前校验版本、房间、目标、有效期和消息 ID。
一次完整的上麦按以下顺序执行,麦位归属由 RTM 确认,RTC 发布结果不反向改变麦位:
```text
RTM 确认麦位归属 → RTC 发布音频 → 发布失败时保留麦位 → 区分采集故障与发布故障
```
只有确认本地采集异常时,才通过 Presence 同步 `microphoneError`;采集正常但发布失败应单独提示,避免将网络发布故障显示为麦克风故障。
## 1. 为什么语聊房需要 RTM [#1-为什么语聊房需要-rtm-2]
RTM 在语聊房中主要解决三类业务问题:
- **表达业务状态。** RTC 音频流本身无法区分不在麦位、主动闭麦、采集异常或发布失败,麦位和成员状态需要独立同步。
- **恢复当前房间。** 新加入或重连的用户需要直接获取完整麦位表、公告和在线成员,不能依赖过去的动作消息。
- **协同互动动作。** 申请上麦、邀请上麦、公屏聊天、礼物和点赞通过实时消息完成。
这些需求对应以下能力:
| RTM 能力 | 在语聊房中的用途 |
| --------------- | ------------------------------------------------------ |
| Message | 上麦协同、公屏消息、礼物、点赞等业务动作 |
| Presence | 在线成员列表及其临时状态(闭麦、麦克风异常) |
| Channel Storage | 麦位表、公告等房间权威状态,供新成员和重连成员直接读取 |
| Lock | 多个角色可修改麦位时的写入互斥 |
## 2. 设计原则 [#2-设计原则-2]
本节内容与平台无关。
:::note[Demo 与生产接入]
Demo 的浏览器房间目录、昵称和准入逻辑用于演示,不构成服务端鉴权。生产环境应由业务服务端维护用户身份、房间目录、成员准入和权限,并提供 Token 服务。部署步骤见 [部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。
:::
### 2.1 RTM client 与会话同生命周期 [#21-rtm-client-与会话同生命周期-2]
一个 RTM 用户身份只维护一个 client。client 可在 App 初始化时创建,**是否立即登录取决于语聊在 App 中的定位**:
- 语聊是核心功能:App 取得用户身份后即登录,App 退出或用户身份失效时登出;
- 语聊是附加功能:进入语聊模块时登录,退出整个模块时登出,避免闲置连接占用资源。

无论采用哪种生命周期,都要遵守:
- **所有事件监听在 `login()` 之前注册,且只注册一次**。否则可能收不到首次连接状态或登录期间到达的事件。
- **进出房间只对应 `subscribe` / `unsubscribe`**。切房是先退订旧频道、再订阅新频道,不重建 client、不重复登录。
- **网络重连期间继续使用当前 client**,等待 SDK 自动重连和随后的全量事件,不手动重登、不盲目重订阅。
- **App 层持有 SDK 原始事件,按当前房间分发**。切房时更换房间事件处理器,避免旧房间迟到的事件更新新房间页面。
### 2.2 一个房间对应一个 Channel [#22-一个房间对应一个-channel-2]
以业务 `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。先在声网控制台的 **实时消息 RTM > 功能配置** 中确认已开启 Presence 和 Storage,再在订阅时设置 `withMessage`、`withPresence` 和 `withMetadata`。如果多个角色需要通过 Lock 协同写入,还需在控制台开启 Lock,并设置 `withLock`;只有单一角色写麦位时无需开启。控制台操作见 [开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service#3-开通-rtm-服务)。
**切房原则**:先完整离开旧房间(停止新写入 → 等待关键写入结束 → 退出 RTC → 退订频道 → 清理本地状态与事件处理器),再进入新房间。用户连续切房时,客户端必须能识别并忽略旧房间迟到的异步结果,并对迟到成功的旧频道订阅补做一次退订。实现方式见 [3.4 切换与离开房间](#34-切换与离开房间)。
### 2.3 按数据特性选择 Storage、Presence、Message [#23-按数据特性选择-storagepresencemessage-2]
根据数据的**有效期**和**接收范围**选择能力:
| RTM 能力 | 适合的数据 | 语聊房示例 | 新成员是否需要获得 |
| ----------------- | ------------------------ | ---------------------------- | -------------------------- |
| Channel Storage | 房间当前的权威状态 | 公告、完整麦位表 | 是 |
| Presence State | 与在线成员绑定的临时状态 | 自主闭麦、麦克风异常 | 是,仅在成员在频道期间有效 |
| `USER` Message | 只发给一个人的瞬时动作 | 申请上麦、邀请上麦、拒绝邀请 | 否 |
| `MESSAGE` Message | 发给房间所有人的瞬时动作 | 公屏消息、礼物、点赞 | 否 |
**Channel Storage:保存当前结果**
后加入或重连的成员仍需读取的数据写入 Channel Storage。麦位表不能靠"某人刚刚上麦"的消息累加得出,因为晚加入者收不到之前的消息。
- 麦位由房主单点写入,避免多端并发修改;若有多个角色可管理麦位,配合 [RTM Lock](/zh-CN/api-reference/rtm/web/lock) 使用。
- Storage 的 `SNAPSHOT` 和 `UPDATE` 事件都携带完整的频道 Metadata。收到 `storage` 事件后,直接以最新快照替换本地房间状态;需要提示"某用户上麦"时,比较前后快照中对应麦位的 `userId` 是否从 `null` 变为具体用户即可。
**Presence State:保存在线临时状态**
Presence State 保存用户自己在频道期间有效的状态。每次只写入发生变化的字段;成员下麦后删除只在麦位上有意义的字段。收到 Presence `SNAPSHOT` 时全量替换在线成员列表,收到加入、离开或状态变化事件时增量更新。
用户离开频道后,其 Presence State 会同时从 RTM 服务端删除,因此不要用 Presence State 保存长期用户资料;长期资料使用 [User Storage](/zh-CN/api-reference/rtm/web/storage#setusermetadata)。
**Message:传递瞬时动作**
Message 用于发生后只处理一次的动作。只发给一个参与者的动作使用 `USER` Channel;房间内所有成员都要接收的互动使用当前房间的 `MESSAGE` Channel。
`publish()` 的成功语义取决于 Channel Type:
- 使用 `USER` Channel 发送点对点消息时,`publish()` 成功表示目标用户已经收到消息,但不代表目标用户已经完成对应的业务处理。
- 使用 `MESSAGE` Channel 发送频道消息时,`publish()` 成功表示消息已经发送到 RTM 服务端。服务端随后向频道内其他成员推送消息;其他成员能否收到,取决于其与 RTM 服务端的连接状态和网络质量。
因此,**申请上麦等点对点动作不能以发送成功视为流程完成**:审批后的麦位归属必须写入 Channel Storage,各端最终以 Storage 中的完整麦位表为准。
### 2.4 区分"频道已订阅"与"房间状态已就绪" [#24-区分频道已订阅与房间状态已就绪-2]
`subscribe()` 完成只表示 SDK 的订阅调用已结束,不表示首个 Presence 或 Storage 快照已到达。客户端需要分别维护两个状态:
- **频道已订阅**:`subscribe()` 成功,可以结束"正在加入"提示、开始 RTC 入房;
- **房间状态已就绪**:当前房间的完整 Storage 快照已到达,依赖麦位或公告的操作才可开放。
不要把等待首个快照合并进订阅的 Promise 中。
### 2.5 重连:链路恢复与业务恢复分开判断 [#25-重连链路恢复与业务恢复分开判断-2]
网络中断后,把房间界面置为"恢复中"并禁用依赖实时状态的操作。连接恢复后不重建 client、不重复 `login()`、不主动重复 `subscribe()`,继续处理 SDK 随后下发的全量事件,并分三步判断恢复程度:
| 信号 | 含义 | 可恢复的操作 |
| ----------------------------- | ------------------------ | ---------------------- |
| `linkState` 恢复为已连接 | RTM 链路已恢复 | 无(继续等待状态事件) |
| 收到当前房间完整 Storage 状态 | 麦位、公告已刷新 | 依赖麦位与公告的操作 |
| 收到 Presence 快照 | 在线成员及临时状态已刷新 | 依赖成员列表的操作 |
`linkState` 恢复后不要立即开放全部操作。
### 2.6 消息协议必须可校验 [#26-消息协议必须可校验-2]
RTM Message 支持文本和二进制两种格式。无论使用哪种,业务层都应定义统一的消息信封,标识协议版本、房间、目标用户、有效期和消息 ID。本文示例使用 JSON 文本便于跨端调试;使用 Protobuf 等二进制协议时应包含含义相同的字段。
收到消息后按以下顺序校验,任一项不通过即丢弃:
1. 内容为合法格式,字段和类型完整;
2. `schemaVersion` 为当前客户端支持的版本;
3. 信封中的 `roomId` 属于当前房间;对于 `MESSAGE` 事件,`channelName` 应为该房间 ID;对于 `USER` 事件,`channelName` 应为本端 RTM 用户 ID;
4. 点对点消息的 `targetUserId` 是当前用户;
5. 当前时间早于 `expiresAt`;
6. `messageId` 未处理过。
通过 TTL 丢弃已失效的上麦邀请或申请;用有容量上限的集合保存近期已处理的 `messageId`,避免重复执行,也避免长期运行后内存持续增长。
## 3. 实现指南 [#3-实现指南-2]
以下代码基于 RTM Web SDK 2.3.0,展示关键调用片段。开始前可参考 [实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start/web) 完成基础接入,并按 [部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation) 准备凭证服务。事件名、参数结构和 Token 更新方式以实际接入的 SDK 版本为准。
### 3.1 创建 client 并注册事件 [#31-创建-client-并注册事件-2]
`appId`、`userId` 由业务提供;下列 `onLinkState`、`onMessage` 等为 App 自己实现的事件处理函数。
```ts
import AgoraRTM from "agora-rtm";
const client = new AgoraRTM.RTM(appId, userId);
// 全部事件在 login() 之前注册,且只注册一次
client.addEventListener("linkState", onLinkState);
client.addEventListener("message", onMessage);
client.addEventListener("presence", onPresence);
client.addEventListener("storage", onStorage);
client.addEventListener("token", onToken);
```
### 3.2 登录 [#32-登录-2]
按 [2.1 RTM client 与会话同生命周期](#21-rtm-client-与会话同生命周期) 确定的生命周期调用 `login()`。同一会话内只登录一次;若有并发调用,复用同一个登录 Promise,登录失败后清除以便重试。
```ts
await client.login({ token });
```
### 3.3 进入房间 [#33-进入房间-2]
```ts
await client.subscribe(roomId, {
withMessage: true,
withPresence: true,
withMetadata: true,
withLock: false, // 多角色管理麦位时改为 true 并配合 Lock 使用
});
```
在权威房间状态到达前(见 [2.4 区分频道已订阅与房间状态已就绪](#24-区分频道已订阅与房间状态已就绪)),禁用依赖麦位或公告的操作。
### 3.4 切换与离开房间 [#34-切换与离开房间-2]
离开房间:停止新的状态写入 → 等待已发起的关键写入结束 → 退出 RTC → `unsubscribe(roomId)` → 清理本地房间状态与事件处理器。用户仍在会话或语聊模块内时保留已登录的 client。
切换房间即"离开旧房间 → 进入新房间"。为每次入房生成递增的 `generation`(或使用 `AbortController`),每个异步步骤返回后先检查该次入房是否仍然有效,再更新 UI:
```ts
const generation = ++this.generation;
await client.subscribe(roomId, options);
if (generation !== this.generation) {
// 切房流程串行编排:旧订阅清理完毕后再启动新订阅。
// 订阅期间用户已切房:补退订,忽略本次结果
await client.unsubscribe(roomId).catch(() => undefined);
return;
}
```
### 3.5 写入房间状态 [#35-写入房间状态-2]
麦位表写入 Channel Storage,可选择整表作为一个 key(写入简单,整表竞争),或每个麦位一个 key(按麦位竞争,便于配合 Lock)。以下 JSON 仅展示业务数据组织方式;当前 Demo 使用 `seats` key 保存完整麦位对象,客户端按约定结构消费。
```json
{
"seats": [
{ "seatId": "seat-1", "userId": "user-a" },
{ "seatId": "seat-2", "userId": null }
]
}
```
```json
{ "seat-1": { "userId": "user-a" }, "seat-2": { "userId": null } }
```
成员上麦后的临时状态写入 Presence State,只更新变化的字段:
```ts
await client.presence.setState(roomId, "MESSAGE", { muted: "true" });
```
听众下麦后,使用 `presence.removeState(roomId, "MESSAGE", { states: ["muted", "microphoneError"] })` 清理仅在麦位上有效的字段。
### 3.6 发送与消费消息 [#36-发送与消费消息-2]
统一信封示例:
```ts
interface VoiceRoomEnvelope> {
schemaVersion: 1;
messageId: string;
type: string;
roomId: string;
targetUserId?: string;
sentAt: number;
expiresAt: number;
payload: T;
}
```
`onMessage` 中按 [2.6 消息协议必须可校验](#26-消息协议必须可校验) 的六步校验后再交给业务处理。
### 3.7 退出 [#37-退出-2]
语聊是核心功能时,仅在 App 销毁、用户退出账号或 RTM 身份变化时移除监听并调用 `logout()`;语聊是附加功能时,退出整个语聊模块时执行。**单纯离开一个房间不要 `logout()`。**
### 3.8 封装建议 [#38-封装建议-2]
将 SDK client 封装在应用级 RTM 会话对象中,房间业务通过进入房间、申请上麦、更新麦位和发送消息等方法调用它,避免协议规则散落在多个 UI 组件中。
当前 Demo 使用 `AppRtmSession` 管理会话,`HostRoomRtm` / `AudienceRoomRtm` 封装角色操作,`SingleRoomClient` 消费房间状态并协调 RTC。这些都是 Demo 类,不是 SDK 接口。参考 [会话封装](https://github.com/AgoraIO-Community/RTM-Demo/blob/a79b0bd17aa503214aac7b33e5426dd13b19356a/src/scenes/voice-room/app-rtm.ts) 和 [房间业务实现](https://github.com/AgoraIO-Community/RTM-Demo/blob/a79b0bd17aa503214aac7b33e5426dd13b19356a/src/scenes/voice-room/event-driven-single-room-client.ts)。
## 4. 常见错误 [#4-常见错误-2]
**每次进房都创建并登录一个 RTM client**
重复注册监听、重复维护连接状态,快速切房时留下旧实例。一个会话只登录一个 client,房间逻辑只负责订阅与退订。
**多个房间共用一个 Channel,再靠消息字段过滤**
各房间互相收到彼此的 Presence、Storage 和 Message,浪费消息量且容易误处理。每个语聊房使用独立 Channel。
**用 Message 保存最终房间状态**
后加入的成员收不到之前的 Message。公告、麦位表等当前状态必须写入 Channel Storage,Message 只传递动作。
**用 Storage 保存高频临时状态**
自主闭麦、麦克风异常只在成员在线期间有效,应写入 Presence State。写进 Storage 会增加无意义的状态合并和并发写入。
**把 `subscribe()` 完成当作房间状态已就绪**
订阅成功与首个快照到达是两个阶段。收到 Storage 快照前,依赖麦位或公告的按钮保持不可用。
**链路恢复后立即开放全部操作**
连接恢复不代表麦位、公告和成员状态已更新。等待当前房间的完整状态事件到达后再恢复相关操作。
**收到消息后直接执行**
未经校验的消息可能已过期、属于其他房间或被重复投递。版本、房间、目标、TTL 和 `messageId` 全部通过后才交给业务处理。
## 5. 上线检查清单 [#5-上线检查清单-2]
- 一个 App 会话或语聊模块会话中,同一 RTM 身份只创建一个 client
- 所有 SDK 事件都在 `login()` 前注册,且只注册一次
- 每个语聊房都有唯一、稳定的 Channel Name
- 进房使用 `subscribe(roomId)`,离房使用 `unsubscribe(roomId)`
- 离开或切换房间不触发 `logout()`
- 核心功能在 App 退出或用户身份结束时 `logout()`;附加功能在退出语聊模块时 `logout()`
- Channel Storage 只保存需要被恢复的房间当前状态
- Presence State 只保存在线成员的临时状态
- 单人动作使用 `USER` Message,房间广播使用 `MESSAGE` Message
- 最终麦位状态以 Storage 为准,不从 Message 历史推导
- "频道已订阅"与"房间状态已就绪"分别建模
- 重连后等待全量状态事件,不重建 client、不盲目重复订阅
- 消息包含版本、唯一 ID、房间、时间和过期时间,并在消费前校验
- 快速切房时使用 generation 或取消标记忽略迟到结果
- RTC 失败不会自动回滚已确认的 RTM 房间状态,仅采集异常同步麦克风错误
- 目录、准入、权限和 Token 已接入业务服务
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="harmonyos" />
## 场景介绍 [#场景介绍-3]
语聊房中,房主创建房间、管理公告和麦位,听众进入房间收听音频,也可以申请上麦、聊天或发送互动。所有成员需要看到一致的麦位归属,并能区分主动闭麦、被房主静音和麦克风异常。
本文按一轮完整的使用流程介绍实现方式:
1. 用户取得身份和访问凭证,建立 RTM 会话。
2. 房主创建房间,听众加入同一房间;各端同步公告、麦位和在线成员,并加入 RTC 收听音频。
3. 听众申请上麦,房主审批并更新麦位;听众确认自己获得麦位后发布音频。
4. 在麦成员开闭麦,房主执行麦控,各端同步成员状态。
5. 成员发送公屏消息、礼物或爱心,接收端校验后展示。
6. 用户下麦、离房或切换房间;再次进入时恢复当前状态。
**麦位归属与音频发布结果分别维护。** 成员在麦位上但没有声音,可能是主动闭麦、强制静音、采集失败或发布失败,不能仅凭 RTC 音频流判断其是否已下麦。
### 职责分工 [#职责分工-3]
| 能力 | 负责 | 不负责 |
| ---- | ---------------------------------------------------- | ------------------------------------------ |
| RTC | 麦克风采集、音频发布与订阅、实时音频传输 | 麦位归属、房间公告、互动消息、成员业务状态 |
| RTM | 房间状态、成员在线状态、麦位协同、文本互动、业务事件 | 音频数据传输 |
### 核心规则 [#核心规则-3]
集成 RTM 时,遵循以下五条核心规则:
1. **一个用户身份只创建一个 RTM client**,生命周期跟随 App 会话或语聊模块;进出房间不重复创建、不重复登录。
2. **一个语聊房对应一个 RTM Channel**,以稳定、唯一的 `roomId` 作为 Channel Name;进房即订阅,离房即退订。
3. **按数据特性选能力**:需要被后来者恢复的房间状态放 Channel Storage,随成员在线而存在的临时状态放 Presence State,只处理一次的动作用 Message。
4. **订阅成功 ≠ 房间状态就绪,链路恢复 ≠ 业务可恢复**,两组状态分别建模。
5. **所有业务消息带统一信封**,消费前校验版本、房间、目标、有效期和消息 ID。
一次完整的上麦按以下顺序执行,麦位归属由 RTM 确认,RTC 发布结果不反向改变麦位:
```text
RTM 确认麦位归属 → RTC 发布音频 → 发布失败时保留麦位 → 区分采集故障与发布故障
```
只有确认本地采集异常时,才通过 Presence 同步 `microphoneError`;采集正常但发布失败应单独提示,避免将网络发布故障显示为麦克风故障。
## 1. 为什么语聊房需要 RTM [#1-为什么语聊房需要-rtm-3]
RTM 在语聊房中主要解决三类业务问题:
- **表达业务状态。** RTC 音频流本身无法区分不在麦位、主动闭麦、采集异常或发布失败,麦位和成员状态需要独立同步。
- **恢复当前房间。** 新加入或重连的用户需要直接获取完整麦位表、公告和在线成员,不能依赖过去的动作消息。
- **协同互动动作。** 申请上麦、邀请上麦、公屏聊天、礼物和点赞通过实时消息完成。
这些需求对应以下能力:
| RTM 能力 | 在语聊房中的用途 |
| --------------- | ------------------------------------------------------ |
| Message | 上麦协同、公屏消息、礼物、点赞等业务动作 |
| Presence | 在线成员列表及其临时状态(闭麦、麦克风异常) |
| Channel Storage | 麦位表、公告等房间权威状态,供新成员和重连成员直接读取 |
| Lock | 多个角色可修改麦位时的写入互斥 |
## 2. 设计原则 [#2-设计原则-3]
本节内容与平台无关。
:::note[Demo 与生产接入]
Demo 的浏览器房间目录、昵称和准入逻辑用于演示,不构成服务端鉴权。生产环境应由业务服务端维护用户身份、房间目录、成员准入和权限,并提供 Token 服务。部署步骤见 [部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。
:::
### 2.1 RTM client 与会话同生命周期 [#21-rtm-client-与会话同生命周期-3]
一个 RTM 用户身份只维护一个 client。client 可在 App 初始化时创建,**是否立即登录取决于语聊在 App 中的定位**:
- 语聊是核心功能:App 取得用户身份后即登录,App 退出或用户身份失效时登出;
- 语聊是附加功能:进入语聊模块时登录,退出整个模块时登出,避免闲置连接占用资源。

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

无论采用哪种生命周期,都要遵守:
- **所有事件监听在 `login()` 之前注册,且只注册一次**。否则可能收不到首次连接状态或登录期间到达的事件。
- **进出房间只对应 `subscribe` / `unsubscribe`**。切房是先退订旧频道、再订阅新频道,不重建 client、不重复登录。
- **网络重连期间继续使用当前 client**,等待 SDK 自动重连,并继续处理恢复期间到达的状态事件,不手动重登、不盲目重订阅。
- **App 层持有 SDK 原始事件,按当前房间分发**。切房时更换房间事件处理器,避免旧房间迟到的事件更新新房间页面。
### 2.2 一个房间对应一个 Channel [#22-一个房间对应一个-channel-4]
以业务 `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 切换与离开房间](#34-切换与离开房间)。
语聊房使用 Presence 和 Storage 前,需要在声网控制台开启对应功能;多个角色通过 Lock 协同管理麦位时,还需开启 Lock。控制台操作见 [开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service#3-开通-rtm-服务)。
### 2.3 按数据特性选择 Storage、Presence、Message [#23-按数据特性选择-storagepresencemessage-4]
根据数据的**有效期**和**接收范围**选择能力:
| RTM 能力 | 适合的数据 | 语聊房示例 | 新成员是否需要获得 |
| ----------------- | ------------------------ | ---------------------------- | -------------------------- |
| Channel Storage | 房间当前的权威状态 | 公告、完整麦位表 | 是 |
| Presence State | 与在线成员绑定的临时状态 | 自主闭麦、麦克风异常 | 是,仅在成员在频道期间有效 |
| `USER` Message | 只发给一个人的瞬时动作 | 申请上麦、邀请上麦、拒绝邀请 | 否 |
| `MESSAGE` Message | 发给房间所有人的瞬时动作 | 公屏消息、礼物、点赞 | 否 |
**Channel Storage:保存当前结果**
后加入或重连的成员仍需读取的数据写入 Channel Storage。麦位表不能靠"某人刚刚上麦"的消息累加得出,因为晚加入者收不到之前的消息。
- 麦位由房主单点写入,避免多端并发修改;若有多个角色可管理麦位,配合 [RTM Lock](/zh-CN/api-reference/rtm/cpp/lock) 使用。
- Storage 的 `SNAPSHOT` 和 `UPDATE` 事件都携带完整的频道 Metadata。收到 `storage` 事件后,直接以最新快照替换本地房间状态;需要提示"某用户上麦"时,比较前后快照中对应麦位的 `userId` 是否从 `null` 变为具体用户即可。
**Presence State:保存在线临时状态**
Presence State 保存用户自己在频道期间有效的状态。每次只写入发生变化的字段;成员下麦后删除只在麦位上有意义的字段。收到 Presence `SNAPSHOT` 时全量替换在线成员列表,收到加入、离开或状态变化事件时增量更新。
用户离开频道后,其 Presence State 会同时从 RTM 服务端删除,因此不要用 Presence State 保存长期用户资料;长期资料使用 [User Storage](/zh-CN/api-reference/rtm/cpp/storage#setusermetadata)。
**Message:传递瞬时动作**
Message 用于发生后只处理一次的动作。只发给一个参与者的动作使用 `USER` Channel;房间内所有成员都要接收的互动使用当前房间的 `MESSAGE` Channel。
`publish()` 的成功语义取决于 Channel Type:
- 使用 `USER` Channel 发送点对点消息时,`publish()` 成功表示目标用户已经收到消息,但不代表目标用户已经完成对应的业务处理。
- 使用 `MESSAGE` Channel 发送频道消息时,`publish()` 成功表示消息已经发送到 RTM 服务端。服务端随后向频道内其他成员推送消息;其他成员能否收到,取决于其与 RTM 服务端的连接状态和网络质量。
因此,**申请上麦等点对点动作不能以发送成功视为流程完成**:审批后的麦位归属必须写入 Channel Storage,各端最终以 Storage 中的完整麦位表为准。
### 2.4 区分"频道已订阅"与"房间状态已就绪" [#24-区分频道已订阅与房间状态已就绪-4]
`subscribe()` 完成只表示 SDK 的订阅调用已结束,不表示首个 Presence 或 Storage 快照已到达。客户端需要分别维护两个状态:
- **频道已订阅**:`subscribe()` 成功,可以结束"正在加入"提示、开始 RTC 入房;
- **房间状态已就绪**:当前房间的完整 Storage 快照已到达,依赖麦位或公告的操作才可开放。
不要把等待首个快照合并进订阅调用的结果中。
### 2.5 重连:链路恢复与业务恢复分开判断 [#25-重连链路恢复与业务恢复分开判断-4]
网络中断后,把房间界面置为"恢复中"并暂停依赖实时连接的写入。连接恢复后不重建 client、不重复 `login()`、不盲目重复 `subscribe()`,继续处理 SDK 到达的状态事件:**有事件就刷新对应状态,不把等待一条新的 Storage 或 Presence 事件作为恢复的必经条件**。
| 信号 | 业务处理 |
| ---- | -------- |
| 当前 MESSAGE 服务的 `linkState` 恢复为已连接 | 恢复连接相关能力;检查当前房间是否仍有效,以及本地是否已有初始化完成的房间状态 |
| 收到当前房间完整 Storage 状态 | 用较新版本更新麦位和公告 |
| 收到 Presence 快照或成员变化事件 | 按事件语义刷新成员及其临时状态 |
Storage 版本未变化时,SDK 可能不再次通知;没有新事件不等于必须继续等待。已有有效状态可以继续使用。首次入房仍按 [2.4 区分"频道已订阅"与"房间状态已就绪"](#24-区分频道已订阅与房间状态已就绪) 等待初始化;如果本地状态已丢失、订阅恢复失败,或业务操作要求主动确认最新状态,则发起查询、处理失败并设置超时,不能无限等待事件,也不能把“没有事件”解释成服务端状态一定未变。
### 2.6 消息协议必须可校验 [#26-消息协议必须可校验-4]
RTM Message 支持文本和二进制两种格式。无论使用哪种,业务层都应定义统一的消息信封,标识协议版本、房间、目标用户、有效期和消息 ID。本文示例使用 JSON 文本便于跨端调试;使用 Protobuf 等二进制协议时应包含含义相同的字段。
收到消息后按以下顺序校验,任一项不通过即丢弃:
1. 内容为合法格式,字段和类型完整;
2. `schemaVersion` 为当前客户端支持的版本;
3. 信封中的 `roomId` 属于当前房间;对于 `MESSAGE` 频道消息,还必须校验 SDK 事件的 `channelName` 与当前房间的 Channel Name 一致;
4. 对于 `USER` 点对点消息,校验 `targetUserId` 是当前用户,并校验发送者的业务身份和权限;此时 SDK 事件的 `channelName` 是目标用户 UID,不能拿它与 `roomId` 比较;
5. 当前时间早于 `expiresAt`;
6. `messageId` 未处理过。
通过 TTL 丢弃已失效的上麦邀请或申请;用有容量上限的集合保存近期已处理的 `messageId`,避免重复执行,也避免长期运行后内存持续增长。
## 3. 实现指南 [#3-实现指南-4]
基础接入见 [实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start/cpp),凭证准备见 [部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation) 和 [客户端鉴权](/zh-CN/realtime-media/rtm/build/authentication-and-connection/user-authentication/cpp)。
文首在线体验和 Demo 源码均为 Web 版本。以下代码基于 RTM C++ SDK 2.x,展示本平台的关键调用片段。事件名、参数结构和 Token 更新方式以实际接入的 SDK 版本为准。
C++ SDK 的异步业务方法返回类型为 `void`,通过 `requestId` 输出参数提供请求编号;调用结果通过 `IRtmEventHandler` 中对应的 `onXxxResult` 回调返回。因此本节代码分为"发起调用"和"处理回调"两部分,App 需要用 `requestId` 关联两者。
### 3.1 创建 client 并注册事件 [#31-创建-client-并注册事件-4]
C++ SDK 在创建 client 时通过 `RtmConfig::eventHandler` 传入事件监听,监听在 `login()` 之前即已生效:
```cpp
class VoiceRoomRtmHandler : public IRtmEventHandler {
public:
// 事件通知
void onLinkStateEvent(const LinkStateEvent& event) override { /* ... */ }
void onMessageEvent(const MessageEvent& event) override { /* ... */ }
void onPresenceEvent(const PresenceEvent& event) override { /* ... */ }
void onStorageEvent(const StorageEvent& event) override { /* ... */ }
void onTokenPrivilegeWillExpire(const char* channelName) override { /* ... */ }
// 调用结果
void onLoginResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) override;
void onSubscribeResult(const uint64_t requestId, const char* channelName, RTM_ERROR_CODE errorCode) override;
void onPresenceSetStateResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) override { /* ... */ }
};
// 全部事件随 client 一起注册,且只注册一次
RtmConfig config;
config.appId = appId.c_str();
config.userId = userId.c_str();
config.eventHandler = handler_.get(); // handler_ 的生命周期需长于 client
int errorCode = 0;
IRtmClient* client = createAgoraRtmClient(config, errorCode);
if (client == nullptr || errorCode != 0) {
// 创建失败
}
```
SDK 回调在 SDK 线程中触发。不要在回调中执行耗时操作或调用 `release()`,需要更新 UI 时请切换到 App 的业务线程。
### 3.2 登录 [#32-登录-4]
按 [2.1 RTM client 与会话同生命周期](#21-rtm-client-与会话同生命周期) 确定的生命周期调用 `login()`。同一会话内只登录一次;在收到 `onLoginResult` 之前不要重复调用,登录失败后允许重试。
```cpp
uint64_t requestId = 0;
client->login(token.c_str(), requestId);
loginRequestId_ = requestId;
// 回调
void VoiceRoomRtmHandler::onLoginResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) {
if (errorCode != RTM_ERROR_OK) {
// 清除登录中标记,允许重试
}
}
```
### 3.3 进入房间 [#33-进入房间-4]
```cpp
StateItem items[2];
items[0].key = "muted"; items[0].value = "false";
items[1].key = "microphoneError"; items[1].value = "false";
uint64_t setStateRequestId = 0;
client->getPresence()->setState(roomId.c_str(), RTM_CHANNEL_TYPE_MESSAGE, items, 2, setStateRequestId);
SubscribeOptions options;
options.withMessage = true;
options.withPresence = true;
options.withMetadata = true;
options.withLock = false; // 多角色管理麦位时改为 true 并配合 Lock 使用
uint64_t subscribeRequestId = 0;
client->subscribe(roomId.c_str(), options, subscribeRequestId);
```
在权威房间状态到达前(见 [2.4 区分"频道已订阅"与"房间状态已就绪"](#24-区分频道已订阅与房间状态已就绪)),禁用依赖麦位或公告的操作。
### 3.4 切换与离开房间 [#34-切换与离开房间-4]
离开房间:停止新的状态写入 → 等待已发起的关键写入结束 → 退出 RTC → `unsubscribe(roomId)` → 清理本地房间状态与事件处理器。用户仍在会话或语聊模块内时保留已登录的 client。
切换房间即"离开旧房间 → 进入新房间"。为每次入房生成递增的 `generation`,并用 `requestId` 记录发起订阅时的 `generation`。收到回调后先检查该次入房是否仍然有效,再更新 UI:
:::note[集成约束]
`generation` 由房间会话对象统一管理,每次新的入房意图或离房时递增;一次入房的多个异步步骤捕获同一个值,不能各自递增。连续 A→B→A 时,旧 A 的回调虽然过期,新一代却可能正在使用同一个频道。SDK 的退订按频道名生效,不区分业务 generation,因此不能仅凭 generation 不匹配就退订。
:::
建议按频道串行执行订阅和退订,并在同一个业务线程维护当前需要持有的频道集合。下面的 `isChannelStillDesired(roomId)` 表示由会话管理器查询该集合;过期结果只在该频道已无人需要时补退订。检查和发起退订之间不能插入新的入房请求,退订完成后再启动同频道的新订阅;退订失败应记录并重试清理。
```cpp
// 发起订阅
uint64_t requestId = 0;
const uint64_t generation = ++generation_;
client->subscribe(roomId.c_str(), options, requestId);
pendingSubscribes_[requestId] = generation;
// 回调(在 SDK 线程中触发,读写共享状态时注意加锁)
void VoiceRoomRtmHandler::onSubscribeResult(const uint64_t requestId, const char* channelName, RTM_ERROR_CODE errorCode) {
const uint64_t generation = takePendingSubscribe(requestId);
if (generation != currentGeneration()) {
// 订阅期间用户已切房:成功的订阅需要补退订,忽略本次结果
if (errorCode == RTM_ERROR_OK && !isChannelStillDesired(channelName)) {
uint64_t unsubscribeRequestId = 0;
client_->unsubscribe(channelName, unsubscribeRequestId);
}
return;
}
// 处理本次订阅结果
}
```
### 3.5 写入房间状态 [#35-写入房间状态-4]
麦位表写入 Channel Storage,二选一:整表作为一个 key(写入简单,整表竞争),或每个麦位一个 key(按麦位竞争,便于配合 Lock)。
```json
{
"seats": [
{ "seatId": "seat-1", "userId": "user-a" },
{ "seatId": "seat-2", "userId": null }
]
}
```
```json
{ "seat-1": { "userId": "user-a" }, "seat-2": { "userId": null } }
```
成员临时状态写入 Presence State,只更新变化的字段:
```cpp
StateItem changed;
changed.key = "muted";
changed.value = "true";
uint64_t requestId = 0;
client->getPresence()->setState(roomId.c_str(), RTM_CHANNEL_TYPE_MESSAGE, &changed, 1, requestId);
```
### 3.6 发送与消费消息 [#36-发送与消费消息-4]
统一信封示例:
```cpp
struct VoiceRoomEnvelope {
int schemaVersion = 1;
std::string messageId;
std::string type;
std::string roomId;
std::string targetUserId; // 点对点消息必填
int64_t sentAt = 0;
int64_t expiresAt = 0;
std::string payload; // JSON 文本
};
```
`onMessageEvent` 中按 [2.6 消息协议必须可校验](#26-消息协议必须可校验) 的六步校验后再交给业务处理。`MessageEvent` 中的字符串指针只在回调期间有效,需要异步处理时先复制数据。
### 3.7 退出 [#37-退出-4]
语聊是核心功能时,仅在 App 销毁、用户退出账号或 RTM 身份变化时调用 `logout()` 并 `release()`;语聊是附加功能时,退出整个语聊模块时执行。**单纯离开一个房间不要 `logout()`。**
```cpp
uint64_t requestId = 0;
client->logout(requestId);
// release() 需要在非回调线程中调用
client->release();
client = nullptr;
```
### 3.8 封装建议 [#38-封装建议-4]
将 SDK client 封装在应用级 RTM 会话对象中,房间业务只调用 `enterRoom()`、`leaveRoom()`、`requestSeat()`、`updateSeats()`、`sendChatMessage()` 等业务方法,不直接传入消息类型、Metadata key 或 Channel Type,避免同一条协议规则散落在多个 UI 组件中。
Web Demo 使用 `AppRtmSession` 管理会话,`HostRoomRtm` / `AudienceRoomRtm` 封装角色操作,`SingleRoomClient` 消费房间状态并协调 RTC。这些都是 Web Demo 类,不是 SDK 接口;本平台可参考其职责划分封装业务。参考 [会话封装](https://github.com/AgoraIO-Community/RTM-Demo/blob/a79b0bd17aa503214aac7b33e5426dd13b19356a/src/scenes/voice-room/app-rtm.ts) 和 [房间业务实现](https://github.com/AgoraIO-Community/RTM-Demo/blob/a79b0bd17aa503214aac7b33e5426dd13b19356a/src/scenes/voice-room/event-driven-single-room-client.ts)。
## 4. 常见错误 [#4-常见错误-4]
**每次进房都创建并登录一个 RTM client**
重复注册监听、重复维护连接状态,快速切房时留下旧实例。一个会话只登录一个 client,房间逻辑只负责订阅与退订。
**多个房间共用一个 Channel,再靠消息字段过滤**
各房间互相收到彼此的 Presence、Storage 和 Message,浪费消息量且容易误处理。每个语聊房使用独立 Channel。
**用 Message 保存最终房间状态**
后加入的成员收不到之前的 Message。公告、麦位表等当前状态必须写入 Channel Storage,Message 只传递动作。
**用 Storage 保存高频临时状态**
自主闭麦、麦克风异常只在成员在线期间有效,应写入 Presence State。写进 Storage 会增加无意义的状态合并和并发写入。
**把 `subscribe()` 完成当作房间状态已就绪**
订阅成功与首个快照到达是两个阶段。收到 Storage 快照前,依赖麦位或公告的按钮保持不可用。
**链路恢复后立即开放全部操作**
连接恢复后,结合当前房间是否有效、是否已初始化以及操作的状态要求恢复能力;有新事件就刷新,没有新事件不强制等待。需要确认最新状态时主动查询,并处理失败和超时。
**收到消息后直接执行**
未经校验的消息可能已过期、属于其他房间或被重复投递。版本、房间、目标、TTL 和 `messageId` 全部通过后才交给业务处理。
## 5. 上线检查清单 [#5-上线检查清单-4]
- 一个 App 会话或语聊模块会话中,同一 RTM 身份只创建一个 client
- 所有 SDK 事件都在 `login()` 前注册,且只注册一次
- 每个语聊房都有唯一、稳定的 Channel Name
- 进房使用 `subscribe(roomId)`,离房使用 `unsubscribe(roomId)`
- 离开或切换房间不触发 `logout()`
- 核心功能在 App 退出或用户身份结束时 `logout()`;附加功能在退出语聊模块时 `logout()`
- Channel Storage 只保存需要被恢复的房间当前状态
- Presence State 只保存在线成员的临时状态
- 单人动作使用 `USER` Message,房间广播使用 `MESSAGE` Message
- 最终麦位状态以 Storage 为准,不从 Message 历史推导
- "频道已订阅"与"房间状态已就绪"分别建模
- 重连后按事件刷新状态,不强制等待新事件;不重建 client、不盲目重复订阅
- 消息包含版本、唯一 ID、房间、时间和过期时间,并在消费前校验
- 快速切房时统一管理 generation,并在补退订前检查频道是否仍被新会话需要
- RTC 失败不会自动回滚已确认的 RTM 房间状态
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="swift" />
## 场景介绍 [#场景介绍-5]
语聊房中,房主创建房间、管理公告和麦位,听众进入房间收听音频,也可以申请上麦、聊天或发送互动。所有成员需要看到一致的麦位归属,并能区分主动闭麦、被房主静音和麦克风异常。
本文按一轮完整的使用流程介绍实现方式:
1. 用户取得身份和访问凭证,建立 RTM 会话。
2. 房主创建房间,听众加入同一房间;各端同步公告、麦位和在线成员,并加入 RTC 收听音频。
3. 听众申请上麦,房主审批并更新麦位;听众确认自己获得麦位后发布音频。
4. 在麦成员开闭麦,房主执行麦控,各端同步成员状态。
5. 成员发送公屏消息、礼物或爱心,接收端校验后展示。
6. 用户下麦、离房或切换房间;再次进入时恢复当前状态。
**麦位归属与音频发布结果分别维护。** 成员在麦位上但没有声音,可能是主动闭麦、强制静音、采集失败或发布失败,不能仅凭 RTC 音频流判断其是否已下麦。
### 职责分工 [#职责分工-5]
| 能力 | 负责 | 不负责 |
| ---- | ---------------------------------------------------- | ------------------------------------------ |
| RTC | 麦克风采集、音频发布与订阅、实时音频传输 | 麦位归属、房间公告、互动消息、成员业务状态 |
| RTM | 房间状态、成员在线状态、麦位协同、文本互动、业务事件 | 音频数据传输 |
### 核心规则 [#核心规则-5]
集成 RTM 时,遵循以下五条核心规则:
1. **一个用户身份只创建一个 RTM client**,生命周期跟随 App 会话或语聊模块;进出房间不重复创建、不重复登录。
2. **一个语聊房对应一个 RTM Channel**,以稳定、唯一的 `roomId` 作为 Channel Name;进房即订阅,离房即退订。
3. **按数据特性选能力**:需要被后来者恢复的房间状态放 Channel Storage,随成员在线而存在的临时状态放 Presence State,只处理一次的动作用 Message。
4. **订阅成功 ≠ 房间状态就绪,链路恢复 ≠ 业务可恢复**,两组状态分别建模。
5. **所有业务消息带统一信封**,消费前校验版本、房间、目标、有效期和消息 ID。
一次完整的上麦按以下顺序执行,麦位归属由 RTM 确认,RTC 发布结果不反向改变麦位:
```text
RTM 确认麦位归属 → RTC 发布音频 → 发布失败时保留麦位 → 区分采集故障与发布故障
```
只有确认本地采集异常时,才通过 Presence 同步 `microphoneError`;采集正常但发布失败应单独提示,避免将网络发布故障显示为麦克风故障。
## 1. 为什么语聊房需要 RTM [#1-为什么语聊房需要-rtm-5]
RTM 在语聊房中主要解决三类业务问题:
- **表达业务状态。** RTC 音频流本身无法区分不在麦位、主动闭麦、采集异常或发布失败,麦位和成员状态需要独立同步。
- **恢复当前房间。** 新加入或重连的用户需要直接获取完整麦位表、公告和在线成员,不能依赖过去的动作消息。
- **协同互动动作。** 申请上麦、邀请上麦、公屏聊天、礼物和点赞通过实时消息完成。
这些需求对应以下能力:
| RTM 能力 | 在语聊房中的用途 |
| --------------- | ------------------------------------------------------ |
| Message | 上麦协同、公屏消息、礼物、点赞等业务动作 |
| Presence | 在线成员列表及其临时状态(闭麦、麦克风异常) |
| Channel Storage | 麦位表、公告等房间权威状态,供新成员和重连成员直接读取 |
| Lock | 多个角色可修改麦位时的写入互斥 |
## 2. 设计原则 [#2-设计原则-5]
本节内容与平台无关。
:::note[Demo 与生产接入]
Demo 的浏览器房间目录、昵称和准入逻辑用于演示,不构成服务端鉴权。生产环境应由业务服务端维护用户身份、房间目录、成员准入和权限,并提供 Token 服务。部署步骤见 [部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。
:::
### 2.1 RTM client 与会话同生命周期 [#21-rtm-client-与会话同生命周期-5]
一个 RTM 用户身份只维护一个 client。client 可在 App 初始化时创建,**是否立即登录取决于语聊在 App 中的定位**:
- 语聊是核心功能:App 取得用户身份后即登录,App 退出或用户身份失效时登出;
- 语聊是附加功能:进入语聊模块时登录,退出整个模块时登出,避免闲置连接占用资源。

无论采用哪种生命周期,都要遵守:
- **所有事件监听在 `login()` 之前注册,且只注册一次**。否则可能收不到首次连接状态或登录期间到达的事件。
- **进出房间只对应 `subscribe` / `unsubscribe`**。切房是先退订旧频道、再订阅新频道,不重建 client、不重复登录。
- **网络重连期间继续使用当前 client**,等待 SDK 自动重连,并继续处理恢复期间到达的状态事件,不手动重登、不盲目重订阅。
- **App 层持有 SDK 原始事件,按当前房间分发**。切房时更换房间事件处理器,避免旧房间迟到的事件更新新房间页面。
### 2.2 一个房间对应一个 Channel [#22-一个房间对应一个-channel-5]
以业务 `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 切换与离开房间](#34-切换与离开房间)。
语聊房使用 Presence 和 Storage 前,需要在声网控制台开启对应功能;多个角色通过 Lock 协同管理麦位时,还需开启 Lock。控制台操作见 [开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service#3-开通-rtm-服务)。
### 2.3 按数据特性选择 Storage、Presence、Message [#23-按数据特性选择-storagepresencemessage-5]
根据数据的**有效期**和**接收范围**选择能力:
| RTM 能力 | 适合的数据 | 语聊房示例 | 新成员是否需要获得 |
| ----------------- | ------------------------ | ---------------------------- | -------------------------- |
| Channel Storage | 房间当前的权威状态 | 公告、完整麦位表 | 是 |
| Presence State | 与在线成员绑定的临时状态 | 自主闭麦、麦克风异常 | 是,仅在成员在频道期间有效 |
| `USER` Message | 只发给一个人的瞬时动作 | 申请上麦、邀请上麦、拒绝邀请 | 否 |
| `MESSAGE` Message | 发给房间所有人的瞬时动作 | 公屏消息、礼物、点赞 | 否 |
**Channel Storage:保存当前结果**
后加入或重连的成员仍需读取的数据写入 Channel Storage。麦位表不能靠"某人刚刚上麦"的消息累加得出,因为晚加入者收不到之前的消息。
- 麦位由房主单点写入,避免多端并发修改;若有多个角色可管理麦位,配合 [RTM Lock](/zh-CN/api-reference/rtm/swift/lock) 使用。
- Storage 的 `SNAPSHOT` 和 `UPDATE` 事件都携带完整的频道 Metadata。收到 `storage` 事件后,直接以最新快照替换本地房间状态;需要提示"某用户上麦"时,比较前后快照中对应麦位的 `userId` 是否从 `null` 变为具体用户即可。
**Presence State:保存在线临时状态**
Presence State 保存用户自己在频道期间有效的状态。每次只写入发生变化的字段;成员下麦后删除只在麦位上有意义的字段。收到 Presence `SNAPSHOT` 时全量替换在线成员列表,收到加入、离开或状态变化事件时增量更新。
用户离开频道后,其 Presence State 会同时从 RTM 服务端删除,因此不要用 Presence State 保存长期用户资料;长期资料使用 [User Storage](/zh-CN/api-reference/rtm/swift/storage#setusermetadata)。
**Message:传递瞬时动作**
Message 用于发生后只处理一次的动作。只发给一个参与者的动作使用 `USER` Channel;房间内所有成员都要接收的互动使用当前房间的 `MESSAGE` Channel。
`publish()` 的成功语义取决于 Channel Type:
- 使用 `USER` Channel 发送点对点消息时,`publish()` 成功表示目标用户已经收到消息,但不代表目标用户已经完成对应的业务处理。
- 使用 `MESSAGE` Channel 发送频道消息时,`publish()` 成功表示消息已经发送到 RTM 服务端。服务端随后向频道内其他成员推送消息;其他成员能否收到,取决于其与 RTM 服务端的连接状态和网络质量。
因此,**申请上麦等点对点动作不能以发送成功视为流程完成**:审批后的麦位归属必须写入 Channel Storage,各端最终以 Storage 中的完整麦位表为准。
### 2.4 区分"频道已订阅"与"房间状态已就绪" [#24-区分频道已订阅与房间状态已就绪-5]
`subscribe()` 完成只表示 SDK 的订阅调用已结束,不表示首个 Presence 或 Storage 快照已到达。客户端需要分别维护两个状态:
- **频道已订阅**:`subscribe()` 成功,可以结束"正在加入"提示、开始 RTC 入房;
- **房间状态已就绪**:当前房间的完整 Storage 快照已到达,依赖麦位或公告的操作才可开放。
不要把等待首个快照合并进订阅调用的结果中。
### 2.5 重连:链路恢复与业务恢复分开判断 [#25-重连链路恢复与业务恢复分开判断-5]
网络中断后,把房间界面置为"恢复中"并暂停依赖实时连接的写入。连接恢复后不重建 client、不重复 `login()`、不盲目重复 `subscribe()`,继续处理 SDK 到达的状态事件:**有事件就刷新对应状态,不把等待一条新的 Storage 或 Presence 事件作为恢复的必经条件**。
| 信号 | 业务处理 |
| ---- | -------- |
| 当前 MESSAGE 服务的 `linkState` 恢复为已连接 | 恢复连接相关能力;检查当前房间是否仍有效,以及本地是否已有初始化完成的房间状态 |
| 收到当前房间完整 Storage 状态 | 用较新版本更新麦位和公告 |
| 收到 Presence 快照或成员变化事件 | 按事件语义刷新成员及其临时状态 |
Storage 版本未变化时,SDK 可能不再次通知;没有新事件不等于必须继续等待。已有有效状态可以继续使用。首次入房仍按 [2.4 区分"频道已订阅"与"房间状态已就绪"](#24-区分频道已订阅与房间状态已就绪) 等待初始化;如果本地状态已丢失、订阅恢复失败,或业务操作要求主动确认最新状态,则发起查询、处理失败并设置超时,不能无限等待事件,也不能把“没有事件”解释成服务端状态一定未变。
### 2.6 消息协议必须可校验 [#26-消息协议必须可校验-5]
RTM Message 支持文本和二进制两种格式。无论使用哪种,业务层都应定义统一的消息信封,标识协议版本、房间、目标用户、有效期和消息 ID。本文示例使用 JSON 文本便于跨端调试;使用 Protobuf 等二进制协议时应包含含义相同的字段。
收到消息后按以下顺序校验,任一项不通过即丢弃:
1. 内容为合法格式,字段和类型完整;
2. `schemaVersion` 为当前客户端支持的版本;
3. 信封中的 `roomId` 属于当前房间;对于 `MESSAGE` 频道消息,还必须校验 SDK 事件的 `channelName` 与当前房间的 Channel Name 一致;
4. 对于 `USER` 点对点消息,校验 `targetUserId` 是当前用户,并校验发送者的业务身份和权限;此时 SDK 事件的 `channelName` 是目标用户 UID,不能拿它与 `roomId` 比较;
5. 当前时间早于 `expiresAt`;
6. `messageId` 未处理过。
通过 TTL 丢弃已失效的上麦邀请或申请;用有容量上限的集合保存近期已处理的 `messageId`,避免重复执行,也避免长期运行后内存持续增长。
## 3. 实现指南 [#3-实现指南-5]
基础接入见 [实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start/swift),凭证准备见 [部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation) 和 [客户端鉴权](/zh-CN/realtime-media/rtm/build/authentication-and-connection/user-authentication/swift)。
文首在线体验和 Demo 源码均为 Web 版本。以下代码基于 RTM Swift SDK 2.x,展示本平台的关键调用片段。事件名、参数结构和 Token 更新方式以实际接入的 SDK 版本为准。
### 3.1 创建 client 并注册事件 [#31-创建-client-并注册事件-5]
Swift SDK 在创建 client 时传入 `AgoraRtmClientDelegate`,监听在 `login` 之前即已生效:
```swift
final class VoiceRoomRtmSession: NSObject, AgoraRtmClientDelegate {
private var rtm: AgoraRtmClientKit?
func setUp(appId: String, userId: String) throws {
let config = AgoraRtmClientConfig(appId: appId, userId: userId)
// 全部事件随 client 一起注册,且只注册一次
rtm = try AgoraRtmClientKit(config, delegate: self)
}
func rtmKit(_ rtmKit: AgoraRtmClientKit, didReceiveLinkStateEvent event: AgoraRtmLinkStateEvent) {}
func rtmKit(_ rtmKit: AgoraRtmClientKit, didReceiveMessageEvent event: AgoraRtmMessageEvent) {}
func rtmKit(_ rtmKit: AgoraRtmClientKit, didReceivePresenceEvent event: AgoraRtmPresenceEvent) {}
func rtmKit(_ rtmKit: AgoraRtmClientKit, didReceiveStorageEvent event: AgoraRtmStorageEvent) {}
func rtmKit(_ rtmKit: AgoraRtmClientKit, tokenPrivilegeWillExpire channel: String?) {}
}
```
### 3.2 登录 [#32-登录-5]
按 [2.1 RTM client 与会话同生命周期](#21-rtm-client-与会话同生命周期) 确定的生命周期调用 `login`。同一会话内只登录一次;登录结果返回前不要重复调用,登录失败后允许重试。
```swift
rtm?.login(token) { response, error in
if let error = error {
// 清除登录中标记,允许重试
print("login failed: \(error.reason)")
} else {
// 已登录
}
}
```
### 3.3 进入房间 [#33-进入房间-5]
```swift
guard let rtm = rtm else { return }
_ = await rtm.getPresence()?.setState(
channelName: roomId,
channelType: .message,
items: ["muted": "false", "microphoneError": "false"]
)
let options = AgoraRtmSubscribeOptions()
// 多角色管理麦位时再加上 .lock,并配合 Lock 使用
options.features = [.message, .presence, .metadata]
let (_, error) = await rtm.subscribe(channelName: roomId, option: options)
guard error == nil else {
// 将订阅失败交给房间会话处理,停止本次入房
return
}
```
在权威房间状态到达前(见 [2.4 区分"频道已订阅"与"房间状态已就绪"](#24-区分频道已订阅与房间状态已就绪)),禁用依赖麦位或公告的操作。
### 3.4 切换与离开房间 [#34-切换与离开房间-5]
离开房间:停止新的状态写入 → 等待已发起的关键写入结束 → 退出 RTC → `unsubscribe(roomId)` → 清理本地房间状态与事件处理器。用户仍在会话或语聊模块内时保留已登录的 client。
切换房间即"离开旧房间 → 进入新房间"。为每次入房生成递增的 `generation`(或使用 `Task` 取消),每个异步步骤返回后先检查该次入房是否仍然有效,再更新 UI:
:::note[集成约束]
`generation` 由房间会话对象统一管理,每次新的入房意图或离房时递增;一次入房的多个异步步骤捕获同一个值,不能各自递增。连续 A→B→A 时,旧 A 的回调虽然过期,新一代却可能正在使用同一个频道。SDK 的退订按频道名生效,不区分业务 generation,因此不能仅凭 generation 不匹配就退订。
:::
建议按频道串行执行订阅和退订,并在同一个业务线程维护当前需要持有的频道集合。下面的 `isChannelStillDesired(roomId)` 表示由会话管理器查询该集合;过期结果只在该频道已无人需要时补退订。检查和发起退订之间不能插入新的入房请求,退订完成后再启动同频道的新订阅;退订失败应记录并重试清理。
```swift
generation += 1
let current = generation
let (_, error) = await rtm.subscribe(channelName: roomId, option: options)
if current != generation {
// 订阅期间用户已切房:补退订,忽略本次结果
if error == nil && !isChannelStillDesired(roomId) {
_ = await rtm.unsubscribe(roomId)
}
return
}
```
### 3.5 写入房间状态 [#35-写入房间状态-5]
麦位表写入 Channel Storage,二选一:整表作为一个 key(写入简单,整表竞争),或每个麦位一个 key(按麦位竞争,便于配合 Lock)。
```json
{
"seats": [
{ "seatId": "seat-1", "userId": "user-a" },
{ "seatId": "seat-2", "userId": null }
]
}
```
```json
{ "seat-1": { "userId": "user-a" }, "seat-2": { "userId": null } }
```
成员临时状态写入 Presence State,只更新变化的字段:
```swift
_ = await rtm.getPresence()?.setState(channelName: roomId, channelType: .message, items: ["muted": "true"])
```
### 3.6 发送与消费消息 [#36-发送与消费消息-5]
统一信封示例:
```swift
struct VoiceRoomEnvelope: Codable {
var schemaVersion = 1
let messageId: String
let type: String
let roomId: String
var targetUserId: String? // 点对点消息必填
let sentAt: Int64
let expiresAt: Int64
let payload: Payload
}
```
`didReceiveMessageEvent` 中按 [2.6 消息协议必须可校验](#26-消息协议必须可校验) 的六步校验后再交给业务处理。
### 3.7 退出 [#37-退出-5]
语聊是核心功能时,仅在 App 销毁、用户退出账号或 RTM 身份变化时调用 `logout()` 并 `destroy()`;语聊是附加功能时,退出整个语聊模块时执行。**单纯离开一个房间不要 `logout()`。**
```swift
rtm?.logout()
// destroy() 需要在非回调线程中调用
rtm?.destroy()
rtm = nil
```
### 3.8 封装建议 [#38-封装建议-5]
将 SDK client 封装在应用级 RTM 会话对象中,房间业务只调用 `enterRoom()`、`leaveRoom()`、`requestSeat()`、`updateSeats()`、`sendChatMessage()` 等业务方法,不直接传入消息类型、Metadata key 或 Channel Type,避免同一条协议规则散落在多个 UI 组件中。
Web Demo 使用 `AppRtmSession` 管理会话,`HostRoomRtm` / `AudienceRoomRtm` 封装角色操作,`SingleRoomClient` 消费房间状态并协调 RTC。这些都是 Web Demo 类,不是 SDK 接口;本平台可参考其职责划分封装业务。参考 [会话封装](https://github.com/AgoraIO-Community/RTM-Demo/blob/a79b0bd17aa503214aac7b33e5426dd13b19356a/src/scenes/voice-room/app-rtm.ts) 和 [房间业务实现](https://github.com/AgoraIO-Community/RTM-Demo/blob/a79b0bd17aa503214aac7b33e5426dd13b19356a/src/scenes/voice-room/event-driven-single-room-client.ts)。
## 4. 常见错误 [#4-常见错误-5]
**每次进房都创建并登录一个 RTM client**
重复注册监听、重复维护连接状态,快速切房时留下旧实例。一个会话只登录一个 client,房间逻辑只负责订阅与退订。
**多个房间共用一个 Channel,再靠消息字段过滤**
各房间互相收到彼此的 Presence、Storage 和 Message,浪费消息量且容易误处理。每个语聊房使用独立 Channel。
**用 Message 保存最终房间状态**
后加入的成员收不到之前的 Message。公告、麦位表等当前状态必须写入 Channel Storage,Message 只传递动作。
**用 Storage 保存高频临时状态**
自主闭麦、麦克风异常只在成员在线期间有效,应写入 Presence State。写进 Storage 会增加无意义的状态合并和并发写入。
**把 `subscribe()` 完成当作房间状态已就绪**
订阅成功与首个快照到达是两个阶段。收到 Storage 快照前,依赖麦位或公告的按钮保持不可用。
**链路恢复后立即开放全部操作**
连接恢复后,结合当前房间是否有效、是否已初始化以及操作的状态要求恢复能力;有新事件就刷新,没有新事件不强制等待。需要确认最新状态时主动查询,并处理失败和超时。
**收到消息后直接执行**
未经校验的消息可能已过期、属于其他房间或被重复投递。版本、房间、目标、TTL 和 `messageId` 全部通过后才交给业务处理。
## 5. 上线检查清单 [#5-上线检查清单-5]
- 一个 App 会话或语聊模块会话中,同一 RTM 身份只创建一个 client
- 所有 SDK 事件都在 `login()` 前注册,且只注册一次
- 每个语聊房都有唯一、稳定的 Channel Name
- 进房使用 `subscribe(roomId)`,离房使用 `unsubscribe(roomId)`
- 离开或切换房间不触发 `logout()`
- 核心功能在 App 退出或用户身份结束时 `logout()`;附加功能在退出语聊模块时 `logout()`
- Channel Storage 只保存需要被恢复的房间当前状态
- Presence State 只保存在线成员的临时状态
- 单人动作使用 `USER` Message,房间广播使用 `MESSAGE` Message
- 最终麦位状态以 Storage 为准,不从 Message 历史推导
- "频道已订阅"与"房间状态已就绪"分别建模
- 重连后按事件刷新状态,不强制等待新事件;不重建 client、不盲目重复订阅
- 消息包含版本、唯一 ID、房间、时间和过期时间,并在消费前校验
- 快速切房时统一管理 generation,并在补退订前检查频道是否仍被新会话需要
- RTC 失败不会自动回滚已确认的 RTM 房间状态
<_PlatformProcessedMarker close="true" />