发版说明 | 声网文档中心

已知问题和局限性

自 2.2.0 起，RTM SDK 和 RTC SDK（4.3.0 及以上版本）都包含 libaosl.so 库。如果你同时使用了 RTM 和 RTC SDK，为避免冲突，需进行如下操作：

如果你通过 CDN 手动集成 SDK，请手动删除更低版本的 libaosl.so 库；
如果你使用依赖管理工具（如 Maven 或 CocoaPods）集成 SDK，请确保在项目中引入更高版本的 libaosl.so 库。

具体的集成指南可以参考如何处理同时集成 RTM SDK 和 RTC SDK 遇到的问题？

2.3.0 RTM SDK libaosl.so 库版本为 1.3.5。
2.2.8 RTM SDK libaosl.so 库版本为 1.3.0。
2.2.7 RTM SDK libaosl.so 库版本为 1.3.0。
2.2.3、2.2.4、2.2.5、2.2.6 RTM SDK libaosl.so 库版本为 1.2.13。
2.2.2 RTM SDK libaosl.so 库版本为 1.0.11。
2.2.1 RTM SDK libaosl.so 库版本为 1.0.11。
2.2.0 RTM SDK libaosl.so 库版本为 1.0.0.17。

该版本于 2026 年 7 月 28 日发布。

升级必看

移除旧连接状态回调

该版本移除 onConnectionStateChanged 回调。监听连接状态变化时，请改用 onLinkStateEvent。

改进

Presence 服务支持控制台开关

声网控制台支持开启或关闭 Presence 服务，该开关默认开启。只有在控制台中开启 Presence 服务后，Presence 相关配置项和 API 调用才会生效。

新增错误码

该版本新增以下错误码：

PRESENCE_INACTIVE (-13014)：Presence 服务未开启或当前不可用。
PRESENCE_PENDING_REQUEST_CANCELLED (-13015)：Presence 待处理请求已取消。
PRESENCE_PENDING_REQUEST_EXCEED_LIMITATION (-13016)：Presence 待处理请求数量超过限制。
CHANNEL_SUBSCRIBE_CANCELED (-11040)：频道订阅尚未完成时被取消。

其它改进

优化控制台创建项目时的体验流程，取消在创建通用项目时配置服务区域，改为在功能配置中开启。
优化登录后的 Presence 查询可用性。调用 login 成功后，如果 Presence 服务仍在准备，SDK 会暂时等待并在服务可用后自动执行 whoNow、whereNow 和远端用户 getState 查询。应用无需增加固定延迟或通过临时订阅判断服务是否就绪，现有异步结果处理方式保持不变。
优化大规模频道中的 Presence 成员同步。当频道在线人数超过 512 人时，SDK 会自动采用大频道优化策略，以最多 512 名成员为持续同步的明细范围，并通过 PresenceEvent.IntervalInfo.totalOccupancy 提供频道总在线人数。应用仍可通过 whoNow 分页查询完整在线成员，并可按需查询远端用户状态；无需新增模式切换代码。
加快订阅频道的速度。
登录服务后如果发生异常断开，异常断开期间发起的订阅请求会在连接恢复后重新发送。

问题修复

修复了未登录情况下切到后台，可能导致连接状态通知不正确的问题。
修复了网络切换场景下重新连接服务耗时较长的问题。

变更后（v2.2.7 及之后）	变更前（v2.2.6 及之前）
groovy `dependencies { // ... implementation 'cn.shengwang.rtm:android-java:x.y.z' }`	groovy `dependencies { // ... implementation 'io.agora:agora-rtm:x.y.z' }`

该版本于 2024 年 11 月 6 日发布。

升级必看

SNAPSHOT 状态触发时机变更

该版本修订了 Presence 事件中 SNAPSHOT 事件的触发时机。现在，只要用户在频道内，就可能会再次收到 SNAPSHOT 事件；收到后，用户可以更新自己的全量信息，来避免因异常导致的状态不同步问题。

锁过期时间计算规则变更

该版本修改了锁（Lock）过期时间的计算规则。该版本起，锁的过期时间将从服务端判定用户离线开始计算。

新特性

支持历史消息

该版本在 PublishOptions 中新增了 storeInHistory 属性，支持在频道中发送消息的同时，将消息存储到云端，后续用户可以通过历史消息接口获取。

信息

该功能目前处于 Public Beta 阶段。如需使用，需要前往控制台开启。

SDK 连接状态变化原因

该版本在 SDK 连接状态 LinkStateEvent 中添加 RtmLinkStateChangeReason 枚举类，报告连接状态变更的原因。

支持 16 KB 内存页大小

自 Android 15 起，系统新增了对 16 KB 内存页大小的支持，详见支持 16 KB 的页面大小。为了保证 App 的稳定性和性能表现，自该版本起，SDK 支持 16 KB 内存页大小，确保可以在使用 4 KB 和 16 KB 内存页大小的设备上无缝运行，提升兼容性并避免崩溃。

改进

该版本提升了基础消息服务在服务异常时的业务表现，避免因部分服务出现异常，导致的消息服务不可用的问题。

问题修复

该版本修复了如下问题：

某些场景下，Token 类型不正确导致异常错误。
某些场景下，用户可能多次收到相同离线用户的离线通知。
相同用户 ID 在不同端登录后，可能出现连接状态异常。
频繁设置 Presence 状态时，可能导致数据异常。
未开通指定服务时，加入频道时未返回错误。
某些场景下，异常属性值可能导致崩溃问题。

该版本于 2024 年 4 月 23 日发布。

升级必看

该版本对以下功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码：

删除了 createMetadata 方法。参考如下示例代码修改你的实现代码：

Java

// v2.2.0 之前
Metadata metadata = rtmClient.getStorage().createMetadata();

Java

// v2.2.0
Metadata metadata = new Metadata();

取消了 StateItem 类，并将如下参数由 ArrayList<StateItem> 类型变为 HashMap<String, String> 类型，参考对应 API 文档修改你的实现代码。
- setState 中的 items 参数。
- PresenceEvent 中的 stateItems 参数。
- UserState 中的 states 参数。
在 RtmConnectionChangeReason 中新增了 CERTIFICATION_VERIFY_FAILURE(22) 枚举，并将 STREAM_CHANNEL_NOT_AVAILABLE 和 INCONSISTENT_APPID 枚举对应的值修改为 23 和 24。

新特性

新增私有化部署能力

该版本在 RtmConfig 中新增 privateConfig 参数，用于实现私有化部署功能。详见私有化配置。

新增心跳时间配置

该版本在 RtmConfig 中新增 heartbeatInterval 参数，用于配置 SDK 向 RTM 服务器发送心跳包的时间间隔。详见 Heartbeat Interval 与 Presence Timeout。

新增双环境配置

该版本在 RtmConfig 中新增 protocolType 参数，用于自定义网络传输协议，以便于更好地适配你的网络环境。详见连接协议配置。

新增用户频道类型

该版本在 RtmChannelType 中新增 USER 类型，用于向指定用户发送消息。该功能可以替代 v1 的点对点消息功能。详见在 User Channel 中发送消息。

新增静默模式配置

该版本在 SubscribeOptions 和 JoinChannelOptions 中新增 beQuiet 属性。该属性设置为 true 时表示静默订阅或加入频道，频道中其他用户无法感知该用户的出席状态。

改进

改进连接状态管理逻辑

该版本新增 onLinkStateEvent 回调，用于替代废弃的 onConnectionStateChanged 回调，以便更好地管理连接状态。详见连接管理。

改进 REMOTE_STATE_CHANGED 事件通知逻辑

该版本改进了 Presence 功能的 REMOTE_STATE_CHANGED 事件的触发逻辑，即当用户一次设置或修改多个 key-value 时，频道内其他用户只会接收到一次事件通知。

支持事件通知触发时间戳

该版本在如下数据结构中新增 timestamp 参数，报告触发事件通知的时间戳：

优化 API 行为

该版本优化了以下 API 的行为：

login：
- 在之前版本中，不支持连续多次调用该方法；也不支持在该方法的 token 参数中传入空字符串。
- 自 2.2.0 版本起，支持连续多次调用该方法，中间无需额外调用 logout 方法。此外，当 token 参数为空字符串时，SDK 会默认使用你初始化时传入的 App ID 替代 Token。
subscribe：
- 在之前版本中，不支持连续多次调用该方法。
- 自 2.2.0 版本起，支持连续多次调用该方法。
join：
- 在之前版本中，不支持连续多次调用该方法，也不支持在该方法的 token 参数中传入空字符串。
- 自 2.2.0 版本起，支持连续多次调用该方法。此外，当 token 参数为空字符串时，SDK 会默认使用你初始化时传入的 App ID 替代 Token。

修改 presenceTimeout 取值范围

该版本将 RtmConfig 中 presenceTimeout 参数的取值范围由 [10,300] 修改为 [5,300]。

该版本于 2023 年 9 月 19 日发布。

升级必看

该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。

多访问区域设置

为支持同时设置多个访问区域，该版本将 areaCode 参数类型由 RtmAreaCode 修改为 EnumSet<RtmAreaCode>。你需要参考以下示例代码修改你的实现方式：

Java

// v2.1.6 之前的方式
RtmConfig config = new RtmConfig();
config.code = RtmConstants.RtmAreaCode.GLOB;

Java

// v2.1.6 的方式
RtmConfig config = new RtmConfig.Builder(myAppId, mUserId)
    .eventListener(eventListener)
    .areaCode(EnumSet.of(RtmConstants.RtmAreaCode.AS, RtmConstants.RtmAreaCode.CN))
    .build();

RtmConfig 构造函数优化

该版本将 RtmConfig 的构造函数修改为 Builder 模式。修改示例如下：

Java

// v2.1.6 之前的方式
RtmConfig config = new RtmConfig();
config.appId = myAppId;
config.userId = mUserId;
config.eventListener = eventListener;
config.logConfig = logConfig;

Java

// v2.1.6 的方式
RtmConfig config = new RtmConfig.Builder(myAppId, mUserId)
    .eventListener(eventListener)
    .logConfig(logConfig)
    .build();

回调名变更

该版本将 onConnectionStateChange 回调名称修改为 onConnectionStateChanged。

新特性

多种事件监听方式

该版本新增 addEventListener 和 removeEventListener 方法。除了在初始化时添加或删除事件监听外，你还可以调用新增方法在 App 生命周期的任意时间添加、删除一个或多个事件监听对象。

此外，为优化设置事件监听的体验，该版本不再需要强制实现 RtmEventListener 的所有事件，只需实现你关注的事件。示例代码如下：

Java

RtmEventListener eventListener = new RtmEventListener() {
    @Override
    public void onMessageEvent(MessageEvent event) {
        String text = "Message received from " + event.publisher + " Message: " + event.message.getData() + "\n";
        writeToMessageHistory(text);
    }

    @Override
    public void onPresenceEvent(PresenceEvent event) {
        String text = "receive presence event, user: " + event.publisher + " event: " + event.type + "\n";
        writeToMessageHistory(text);
    }

    @Override
    public void onConnectionStateChanged(String mChannelName, RtmConstants.RtmConnectionState state, RtmConstants.RtmConnectionChangeReason reason) {
        String text = "Connection state changed to " + state + ", Reason: " + reason + "\n";
        writeToMessageHistory(text);
    }
};

新结构体构造函数

该版本为如下结构体新增构造函数：

你可以继续使用之前的实现方式，也可以参考以下示例代码改用新的实现方式：

Java

// v2.1.6 之前的方式
SubscribeOptions options = new SubscribeOptions();
options.withMessage = true;
options.withMetadata = false;
options.withPresence = true;
options.withLock = false;

Java

// v2.1.6 的方式，任选一种方式即可
// 方式一：传参方式
SubscribeOptions options = new SubscribeOptions(true, true, false, false);
// 方式二：SET 方式
SubscribeOptions options = new SubscribeOptions();
options.setWithMessage(true);
options.setWithMetadata(false);
options.setWithPresence(true);
options.setWithLock(false);

改进

该版本提升了在 JoinChannelOptions 中设置 Presence 事件通知的性能。

问题修复

该版本修复了如下问题：

当网络状态发生变化时，偶现无法登出 RTM 系统。
登出 RTM 系统后，当网络状态发生变化时，偶现无法登录 RTM 系统。
网络断开后，因数据未清理导致偶现用户无法收到 SNAPSHOT 事件通知。
用户加入频道后，把 App 切到后台再切换回前台时，偶现 SDK 多次触发 REMOTE_JOIN 事件通知。

该版本于 2023 年 8 月 16 日发布。这是 RTM v2 Java SDK 的第一个版本。

本次发布意味着声网实时通讯（RTM）产品步入 v2 时代，我们在功能覆盖、性能提升、体验优化上都将为用户带来革新。

功能覆盖：该版本通过引入频道（Channel）、消息（Message）、Topic、Presence、Storage 和 Lock 等功能模块，能覆盖更多业务场景，你可以把更多的精力集中在自己的业务创新上。
性能提升：我们在新版本中重构了后台架构，通过优化网络连接进一步提升性能，提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力，让你无需为业务质量担忧。
体验优化：我们重新设计并简化了 API 接口；优化了包括用户指南、API 参考在内的所有文档，提供了更全面的示例程序，支持开发者低成本学习使用 SDK，快速完成集成，提高开发效率。

新特性

该版本提供的核心功能模块如下。

信息

RTM 2.1.4 目前处于 Public Beta 阶段，某些功能细节可能会在随后的版本中发生改变，以提升用户体验。

初始配置（Setup）

初始配置（Setup）是初始化生产 RTM Client 时预先定义或配置一些关键参数，影响其后续的行为。同时它还提供了登录、登出等功能。核心能力如下：

create：创建一个 RTM Client 实例，并进行如下初始配置：
- appId：设置 App ID。相同 App ID 的 App 间可以通信，不同 App ID 的 App 相互隔离。
- userId：设置用户 ID，用以区分用户或设备。
- areaCode：设置区域代码，用于 Geo-fencing 功能。
- presenceTimeout：设置 Presence 服务的超时时间。
- useStringUserId：设置用户 ID 的数据类型，可以是 String 类型，也可以是 Uint 类型。
- eventListener：设置事件监听函数。
- logConfig：配置本地日志大小、位置、输出信息等级等参数。
- proxyConfig：配置 Proxy 服务参数。
- encryptionConfig：配置端侧加密参数。
事件监听：实现 onMessageEvent、onPresenceEvent、onTopicEvent、onStorageEvent、onLockEvent、onConnectionStateChange、onTokenPrivilegeWillExpire 等事件通知的业务逻辑。
login：登录 RTM 服务。
logout：登出 RTM 服务。
release：销毁 RTM Client 实例，释放资源。

频道（Channel）

频道是 RTM 实时网络中一种数据传输的管理机制，任何订阅或加入频道的用户都可以在 100 毫秒内接收到频道中传输的消息和事件，RTM 允许客户端订阅数百甚至数千个频道。大多数 RTM API 都将以频道为基础进行发送、接收、加密等行为。

基于声网的能力，RTM 的频道分成两种类型：Message Channel 和 Stream Channel。两种类型频道的核心能力如下：

Message Channel：
- subscribe：订阅指定 Message Channel 并开始接收频道中的消息和事件通知。
- unsubscribe：取消订阅指定 Message Channel 并停止接收频道中的消息和事件通知。
Stream Channel：
- createStreamChannel：创建 Stream Channel 实例，随后可以调用其中的方法。
- join：加入 Stream Channel，并开始接收频道中的消息和事件通知。
- leave：离开 Stream Channel，并停止接收频道中的消息和事件通知。
- release：销毁 Stream Channel 实例以释放资源。

其中：

subscribe、unsubscribe、join、leave 方法都会触发 onPresenceEvent 事件通知。频道中的其他用户会收到对应的 Join、Leave 事件通知。
调用 subscribe 和 join 操作订阅或加入频道的时候，可以选择是否配置 withMessage、withPresence、withMetadata、withLock 等参数以开启对应事件通知的监听功能。如果开启，你同时也需要注册对应事件监听，才能顺利收到对应事件通知。

消息（Message）

RTM 的基础是发送消息的能力，你可以随时随地向频道中发送消息，消息会在 100 毫秒内传递到任何地方。RTM 支持 String 类型和 Byte 类型的消息负载。

publish 向指定的 Message Channel 中发送消息。调用 publish 会触发 onMessageEvent 事件通知，如果想要收到频道中的消息，你需要在 subscribe 的时候，设置 withMessage = true，注册并实现 onMessageEvent 事件。

Topic

Topic 是 Stream Channel 中的数据流管理机制。你可以在 Stream Channel 中利用此特性进行数据流的订阅、分发、事件通知等，灵活使用 Topic 能力，能大大降低业务复杂度，提升开发效率。Topic 的主要功能如下：

joinTopic：注册成为此 Topic 的消息发布者（publisher）。注册后，该用户会具备发送消息的能力。
publishTopicMessage：向 Stream Channel 中的 Topic 发送消息。
leaveTopic：取消注册为该 Topic 的消息发布者。
subscribeTopic：订阅该频道中 Topic 的一名或多名消息发布者。
unsubscribeTopic：取消订阅该 Topic 或取消订阅该 Topic 中指定的一名或多名消息发布者。

信息

Topic 特性只在 Stream Channel 中有效，Message Channel 中不存在此特性。

在线状态

Presence 提供监控用户在线状态及临时状态变化的能力。通过 Presence 功能，你可以实时获取以下信息：

用户加入或离开频道的实时状态
订阅或加入同一频道的所有用户的实时状态
一个用户订阅或加入的所有频道的实时信息
自定义临时用户状态及其变更信息

在 Message Channel 和 Stream Channel 中均可使用以下 Presence 功能：

whoNow：实时获取指定频道的在线用户数量、在线用户列表、在线用户的临时状态等信息。
whereNow：实时获取指定用户所在频道的列表。
setState：设置用户在指定频道的临时状态。
getState：获取用户在指定频道的临时状态。
removeState：删除用户在特定频道的临时状态。

Presence 在提供上述功能的同时，也提供了 onPresenceEvent 事件通知能力。频道中用户的加入、离开、掉线、用户状态设置、用户状态删除等事件都会以实时通知（Announce Mode）或定时通知（Interval Mode）的方式通知到频道中的其他用户。Presence 能力将大大简化开发者业务中关于在线用户上下线、状态变更等状态的同步逻辑实现，充分利用此特性将使得你的业务实现更稳定、实时、可靠。

存储

RTM 的 Storage 功能提供了一套动态数据库机制，可以让开发者动态设置、存储、更新、删除 Channel Metadata 和 User Metadata 等数据，并监听由 Channel Metadata 或 User Metadata 变更而产生的事件通知。

Channel Metadata

setChannelMetadata：为指定频道设置 Channel Metadata 或 Channel Metadata Item。
getChannelMetadata：获取指定频道的 Channel Metadata 和 Channel Metadata Item。
removeChannelMetadata：删除指定频道的 Channel Metadata 或 Channel Metadata Item。
updateChannelMetadata：更新指定频道已有 Channel Metadata 或 Channel Metadata Item。

Channel Metadata 的设置、删除和更新都会触发 onStorageEvent 事件通知，合理使用此特性可以极大的优化业务逻辑，获得优异的用户体验。当前 onStorageEvent 事件通知中携带的是当前 Channel Metadata 的全量信息，我们将在后续版本中优化，提供性能更优的增量更新能力。

Channel Metadata 同时也引入了 Lock 的控制能力，当调用 API 设置、删除、更新 Channel Metadata 时，如果参数中的 lockName 被设置，则开启 Lock 的校验，此时只有拥有此锁的用户才被允许成功调用对应的方法。

User Metadata

setUserMetadata：设置指定用户的 User Metadata 或 User Metadata Item。
getUserMetadata：获取指定用户的 User Metadata 和 User Metadata Item。
removeUserMetadata：删除指定用户的 User Metadata 或 User Metadata Item。
updateUserMetadata：更新指定用户已存在的 User Metadata 或 User Metadata Item。
subscribeUserMetadata：订阅指定用户的 User Metadata 或 User Metadata Item 变更事件通知。
unsubscribeUserMetadata：取消订阅指定用户的 User Metadata 或 User Metadata Item 事件通知。

User Metadata 的设置、删除和更新都会触发 onStorageEvent 事件通知，所有订阅此 User Metadata 的其他用户将会收到事件通知，合理使用此特性可以极大的优化业务逻辑，获得优异的用户体验。当前 onStorageEvent 事件通知中携带的是所订阅 User Metadata 的全量信息，我们将在后续的版本中优化，提供性能更优的增量更新能力。

CAS 控制

Channel Metadata 和 User Metadata 都引进了版本控制逻辑 CAS（Compare And Set），该方法提供两种独立的版本控制字段，你可以根据实际业务场景设置任意一种或多种：

通过 Metadata 中的 setMajorRevision 方法设置 majorRevision 属性开启整组 Channel Metadata 的版本号校验。
通过 MetadataItem 中的 revision 属性开启某个 Metadata Item 的版本号校验。

设置、删除、更新 Channel Metadata 或 User Metadata 时，配合 revision 参数可以控制本次调用是否开启 Revision 校验，逻辑如下：

majorRevision 或 revision 为 -1 时，本次调用不开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则该 Metadata 或 Metadata Item 会被最新值覆盖；如果 Metadata 或 Metadata Item 不存在，则会创建对应的 Metadata 或 Metadata Item。
majorRevision 或 revision 为 Uint64 正整数时，本次调用开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则 SDK 会在版本号验证成功后更新对应的值；如果 Metadata 或 Metadata Item 不存在，则 SDK 会返回错误码。

锁

临界资源一次只能供一个进程使用，如果不同的进程之间共享了某个临界资源，则各进程需要采取互斥的方式来防止彼此干扰。RTM 提供一整套 Lock 的方案，通过控制分布式系统的不同进程，你可以解决用户在访问共享资源时的竞争问题。Lock 为你提供了以下能力：

setLock：为指定频道设置锁。
acquireLock：获取指定频道中指定的锁。
releaseLock：释放指定频道中指定的锁。
revokeLock：撤销指定频道中某个用户对此锁的占用权限以释放此锁。
getLocks：获取指定频道中所有锁的详情。
removeLock：删除指定频道中指定的锁。

频道中锁的设置、获取、释放、撤销和删除操作都会上报对应的 onLockEvent 事件通知。你可以充分利用此特性优化业务的实现逻辑。

本文提供 RTM v2 SDK 的发版说明。

已知问题和局限性

自 2.2.0 起，RTM SDK 和 RTC SDK（4.3.0 及以上版本）都包含 aosl.xframework 库。如果你同时使用了 RTM 和 RTC SDK，为避免冲突，需进行如下操作：

如果你通过 CDN 手动集成 SDK，请手动删除更低版本的 aosl.xframework 库；
如果你使用依赖管理工具（如 Maven 或 CocoaPods）集成 SDK，请确保在项目中引入更高版本的 aosl.xframework 库。

具体的集成指南可以参考如何处理同时集成 RTM SDK 和 RTC SDK 遇到的问题？

2.3.0 RTM SDK aosl.xframework 库版本为 1.3.5。
2.2.8 RTM SDK aosl.xframework 库版本为 1.3.0。
2.2.7 RTM SDK aosl.xframework 库版本为 1.3.0。
2.2.3、2.2.4、2.2.5、2.2.6 RTM SDK aosl.xframework 库版本为 1.2.13。
2.2.2 RTM SDK aosl.xframework 库版本为 1.0.11。
2.2.1 RTM SDK aosl.xframework 库版本为 1.0.11。
2.2.0 RTM SDK aosl.xframework 库版本为 1.0.0.17。

该版本于 2026 年 7 月 28 日发布。

升级必看

移除旧连接状态回调

该版本移除旧连接状态回调。监听连接状态变化时，请改用 didReceiveLinkStateEvent。

改进

Presence 服务支持控制台开关

声网控制台支持开启或关闭 Presence 服务，该开关默认开启。只有在控制台中开启 Presence 服务后，Presence 相关配置项和 API 调用才会生效。

新增错误码

该版本新增以下错误码：

AgoraRtmErrorPresenceInactive (-13014)：Presence 服务未开启或当前不可用。
AgoraRtmErrorPresencePendingRequestCancelled (-13015)：Presence 待处理请求已取消。
AgoraRtmErrorPresencePendingRequestExceedLimitation (-13016)：Presence 待处理请求数量超过限制。
AgoraRtmErrorChannelSubscribeCanceled (-11040)：频道订阅尚未完成时被取消。

其它改进

优化控制台创建项目时的体验流程，取消在创建通用项目时配置服务区域，改为在功能配置中开启。
优化登录后的 Presence 查询可用性。调用 login 成功后，如果 Presence 服务仍在准备，SDK 会暂时等待并在服务可用后自动执行 whoNow、whereNow 和远端用户 getState 查询。应用无需增加固定延迟或通过临时订阅判断服务是否就绪，现有异步结果处理方式保持不变。
优化大规模频道中的 Presence 成员同步。当频道在线人数超过 512 人时，SDK 会自动采用大频道优化策略，以最多 512 名成员为持续同步的明细范围，并通过 AgoraRtmPresenceEvent.interval.totalOccupancy 提供频道总在线人数。应用仍可通过 whoNow 分页查询完整在线成员，并可按需查询远端用户状态；无需新增模式切换代码。
加快订阅频道的速度。
登录服务后如果发生异常断开，异常断开期间发起的订阅请求会在连接恢复后重新发送。
优化了部分配置参数的使用方式。

问题修复

修复了未登录情况下切到后台，可能导致连接状态通知不正确的问题。
修复了网络切换场景下重新连接服务耗时较长的问题。

变更后（v2.2.7 及之后）	变更前（v2.2.6 及之前）
Ruby `platform :ios, '11.0' target 'Your App' do # ... pod 'ShengwangRtm', 'x.y.z' end`	Ruby `platform :ios, '11.0' target 'Your App' do # ... pod 'AgoraRtm', 'x.y.z' end`

该版本于 2024 年 4 月 23 日发布。

升级必看

API 变更

该版本的 API 变更如下：

删除了 createMetadata 方法。参考如下示例代码修改你的实现代码：

Objective-C

// v2.2.0 之前
AgoraRtmMetadata* metadata = [[rtm getStorage] createMetadata];

Objective-C

// v2.2.0
AgoraRtmMetadata* metadata = [[AgoraRtmMetadata alloc] init];

取消了 AgoraRtmStateItem 类，并将如下参数由 NSArray<AgoraRtmStateItem *> 类型变为 NSDictionary 类型，参考对应 API 文档修改你的实现代码。
- setState 中的 items 参数。
- PresenceEvent 中的 states 参数。
- UserState 中的 states 参数。

新特性

新增支持 macOS 和 VisionOS 平台

该版本新增支持 macOS 和 VisionOS 平台，支持的最小版本和目标架构见平台支持。同时，该版本也将包名由 AgoraRtm_iOS 变更为 AgoraRtm。升级至该版本后，在使用 CocoaPods 集成方式时，你需要将 Podfile 文件修改为以下内容：

Ruby

platform :ios, '11.0'
target 'Your App' do
pod 'AgoraRtm', '2.2.0'
end

新增私有化部署能力

该版本在 AgoraRtmClientConfig 中新增 privateConfig 参数，用于实现私有化部署功能。详见私有化配置。

新增心跳时间配置

该版本在 AgoraRtmClientConfig 中新增 heartbeatInterval 参数，用于配置 SDK 向 RTM 服务器发送心跳包的时间间隔。详见 Heartbeat Interval 与 Presence Timeout。

新增双环境配置

该版本在 AgoraRtmClientConfig 中新增 protocolType 参数，用于自定义网络传输协议，以便于更好地适配你的网络环境。详见连接协议配置。

新增用户频道类型

该版本在 AgoraRtmChannelType 中新增 AgoraRtmChannelTypeUser 类型，用于向指定用户发送消息。该功能可以替代 v1 的点对点消息功能。详见在 User Channel 中发送消息。

新增静默模式配置

该版本在 AgoraRtmSubscribeChannelFeature 中新增 AgoraRtmSubscribeChannelFeatureBeQuiet 枚举，在 AgoraRtmJoinChannelFeature 中新增 AgoraRtmJoinChannelFeatureBeQuiet 枚举，用于设置静默订阅或加入频道。设置成功后，频道中其他用户无法感知该用户的出席状态。

改进

改进连接状态管理逻辑

该版本新增 didReceiveLinkStateEvent 回调，用于替代废弃的 connectionChangedToState 回调，以便更好地管理连接状态。详见连接管理。

改进 AgoraRtmPresenceEventTypeRemoteStateChanged 事件通知逻辑

该版本改进了 Presence 功能的 AgoraRtmPresenceEventTypeRemoteStateChanged 事件的触发逻辑，即当用户一次设置或修改多个 key-value 时，频道内其他用户只会接收到一次事件通知。

支持事件通知触发时间戳

该版本在如下数据结构中新增 timestamp 参数，报告触发事件通知的时间戳：

优化 API 行为

该版本优化了以下 API 的行为：

loginByToken：
- 在之前版本中，不支持连续多次调用该方法；也不支持在该方法的 token 参数中传入空字符串。
- 自 2.2.0 版本起，支持连续多次调用该方法，中间无需额外调用 logout 方法。此外，当 token 参数为空字符串时，SDK 会默认使用你初始化时传入的 App ID 替代 Token。
subscribeWithChannel：
- 在之前版本中，不支持连续多次调用该方法。
- 自 2.2.0 版本起，支持连续多次调用该方法。
joinWithOption：
- 在之前版本中，不支持连续多次调用该方法，也不支持在该方法的 token 参数中传入空字符串。
- 自 2.2.0 版本起，支持连续多次调用该方法。此外，当 token 参数为空字符串时，SDK 会默认使用你初始化时传入的 App ID 替代 Token。

修改 presenceTimeout 取值范围

该版本将 AgoraRtmClientConfig 中 presenceTimeout 参数的取值范围由 [10,300] 修改为 [5,300]。

该版本于 2023 年 9 月 19 日发布。

升级必看

该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。

初始化参数

为提醒用户在初始化时设置必填参数，该版本新增如下方法：

在 AgoraRtmMetadata 中新增 init 方法，禁止用户不填参数就初始化。
在 AgoraRtmProxyConfig 中新增 init 和 initWithServer 方法，要求用户在初始化时填写 server、port 和 proxyType 参数。
在 AgoraRtmClientConfig 中新增 init 和 initWithAppId 方法，要求用户在初始化时填写 appId 和 userId 参数。

频道选项

该版本对 AgoraRtmJoinChannelOption 和 AgoraRtmSubscribeOptions 类进行了如下修改：

在 AgoraRtmJoinChannelOption 中删除了 withMetadata、withPresence 和 withLock 参数，并新增 features 参数替代。根据需要，你可以在 features 参数中设置一种或多种事件通知。
在 AgoraRtmSubscribeOptions 中删除了 withMessage、withMetadata、withPresence 和 withLock 参数，并新增 features 参数替代。根据需要，你可以在 features 参数中设置一种或多种事件通知。

此外，该版本提升了在 AgoraRtmJoinChannelOption 中设置 Presence 事件通知的性能。

命名变更

该版本修改了如下回调的名称：

v2.1.6 之前	v2.1.6
`onMessageEvent`	`didReceiveMessageEvent`
`onPresenceEvent`	`didReceivePresenceEvent`
`onLockEvent`	`didReceiveLockEvent`
`onStorageEvent`	`didReceiveStorageEvent`
`onTopicEvent`	`didReceiveTopicEvent`
`onTokenPrivilegeWillExpire`	`tokenPrivilegeWillExpire`
`connectionStateChanged`	`connectionChangedToState`

此外，该版本还将 removeState 方法的 items 参数更名为 keys，将 areaCode 参数类型由 unsigned int 修改为 AgoraRtmAreaCode。

新特性

多种事件监听方式

该版本新增 addDelegate 和 removeDelegate 方法。除了在初始化时添加或删除事件监听外，你还可以调用新增方法在 App 生命周期的任意时间添加、删除一个或多个事件监听对象。

改进

消息发送

该版本新增 publish 和 publishTopicMessage 方法的同名方法，并修改了原方法中 message 参数的类型。详情如下：

Objective-C

// v2.1.6 之前
// message 参数类型为 NSObject，支持传入字符串和二进制消息
- (void) publish: (NSString* _Nonnull)channelName
         message: (NSObject* _Nonnull)message
      withOption: (AgoraRtmPublishOptions* _Nullable)publishOption
      completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

- (void) publishTopicMessage: (NSObject * _Nonnull) message
                     inTopic: (NSString * _Nonnull) topic
                  withOption:(AgoraRtmPublishOptions * _Nullable) options
                  completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

Objective-C

// v2.1.6
// message 参数分为 NSString 和 NSData 类型
// NSString 类型仅支持传入字符串数据
// NSData 类型仅支持传入二进制数据

// publish[1/2]
- (void) publish:(NSString* _Nonnull)channelName
         message:(NSString* _Nonnull)message
          option:(AgoraRtmPublishOptions* _Nullable)publishOption
      completion:(AgoraRtmOperationBlock _Nullable)completionBlock

// publish[2/2]
- (void) publish:(NSString* _Nonnull)channelName
            data:(NSData* _Nonnull)data
          option:(AgoraRtmPublishOptions* _Nullable)publishOption
      completion:(AgoraRtmOperationBlock _Nullable)completionBlock

// publishTopicMessage[1/2]
- (void) publishTopicMessage:(NSString * _Nonnull)topic
                     message:(NSString * _Nonnull)message
                      option:(AgoraRtmPublishOptions * _Nullable)options
                  completion:(AgoraRtmOperationBlock _Nullable)completionBlock

// publishTopicMessage[2/2]
- (void) publishTopicMessage:(NSString * _Nonnull)topic
                        data:(NSData * _Nonnull)data
                      option:(AgoraRtmPublishOptions * _Nullable)options
                  completion:(AgoraRtmOperationBlock _Nullable)completionBlock

消息接收

该方法在 AgoraRtmMessage 类中删除了 getData 方法、getType 方法和 AgoraRtmMessageType 类，新增了 rawData 和 stringData 属性，分别用于接收二进制消息和字符串消息。

响应和错误信息优化

该版本优化了各方法中 completion 回调函数返回的信息：

如果方法调用成功，则会在 response 参数中返回对应数据，在 errorInfo 参数中返回 nil。
如果方法调用失败，则会在 response 参数中返回 nil，在 errorInfo 参数中返回错误信息。

此外，该版本在 initWithConfig 和 createStreamChannel 方法中新增 error 参数，用于输出方法调用失败的错误描述，方便排查问题。

问题修复

该版本修复了如下问题：

当网络状态发生变化时，偶现无法登出 RTM 系统。
登出 RTM 系统后，当网络状态发生变化时，偶现无法登录 RTM 系统。
网络断开后，因数据未清理导致偶现用户无法收到 Snapshot 事件通知。
用户加入频道后，把 App 切到后台再切换回前台时，偶现 SDK 多次触发 REMOTE_JOIN 事件通知。

该版本于 2023 年 8 月 16 日发布。这是 RTM v2 Objective-C SDK 的第一个版本。

本次发布意味着声网实时通讯（RTM）产品步入 v2 时代，我们在功能覆盖、性能提升、体验优化上都将为用户带来革新。

功能覆盖：该版本通过引入频道（Channel）、消息（Message）、Topic、Presence、Storage 和 Lock 等功能模块，能覆盖更多业务场景，你可以把更多的精力集中在自己的业务创新上。
性能提升：我们在新版本中重构了后台架构，通过优化网络连接进一步提升性能，提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力，让你无需为业务质量担忧。
体验优化：我们重新设计并简化了 API 接口；优化了包括用户指南、API 参考在内的所有文档，提供了更全面的示例程序，支持开发者低成本学习使用 SDK，快速完成集成，提高开发效率。

新特性

该版本提供的核心功能模块如下。

信息

RTM 2.1.4 目前处于 Public Beta 阶段，某些功能细节可能会在随后的版本中发生改变，以提升用户体验。

初始配置（Setup）

初始配置（Setup）是初始化生产 RTM Client 时预先定义或配置一些关键参数，影响其后续的行为。同时它还提供了登录、登出等功能。核心能力如下：

initWithConfig：创建一个 RTM Client 实例，并进行如下初始配置：
- appId：设置 App ID。相同 App ID 的 App 间可以通信，不同 App ID 的 App 相互隔离。
- userId：设置用户 ID，用以区分用户或设备。
- areaCode：设置区域代码，用于 Geo-fencing 功能。
- presenceTimeout：设置 Presence 服务的超时时间。
- useStringUserId：设置用户 ID 的数据类型，可以是 String 类型，也可以是 Uint 类型。
- logConfig：配置本地日志大小、位置、输出信息等级等参数。
- proxyConfig：配置 Proxy 服务参数。
- encryptionConfig：配置端侧加密参数。
事件监听：实现 onMessageEvent、onPresenceEvent、onTopicEvent、onStorageEvent、onLockEvent、connectionStateChanged、onTokenPrivilegeWillExpire 等事件通知的业务逻辑。
loginByToken：登录 RTM 服务。
logout：登出 RTM 服务。
destroy：销毁 RTM Client 实例，释放资源。

频道（Channel）

基于声网的能力，RTM 的频道分成两种类型：Message Channel 和 Stream Channel。两种类型频道的核心能力如下：

Message Channel：
- subscribeWithChannel：订阅指定 Message Channel 并开始接收频道中的消息和事件通知。
- unsubscribeWithChannel：取消订阅指定 Message Channel 并停止接收频道中的消息和事件通知。
Stream Channel：
- createStreamChannel：创建 Stream Channel 实例，随后可以调用其中的方法。
- joinWithOption：加入 Stream Channel，并开始接收频道中的消息和事件通知。
- leave：离开 Stream Channel，并停止接收频道中的消息和事件通知。
- destroy：销毁 Stream Channel 实例以释放资源。

其中：

subscribeWithChannel、unsubscribeWithChannel、joinWithOption、leave 方法都会触发 onPresenceEvent 事件通知。频道中的其他用户会收到对应的 Join、Leave 事件通知。
调用 subscribeWithChannel 和 joinWithOption 操作订阅或加入频道的时候，可以选择是否配置 withMessage、withPresence、withMetadata、withLock 等参数以开启对应事件通知的监听功能。如果开启，你同时也需要注册对应事件监听，才能顺利收到对应事件通知。

消息（Message）

RTM 的基础是发送消息的能力，你可以随时随地向频道中发送消息，消息会在 100 毫秒内传递到任何地方。RTM 支持 String 类型和 Byte 类型的消息负载。

publish 向指定的 Message Channel 中发送消息。调用 publish 会触发 onMessageEvent 事件通知，如果想要收到频道中的消息，你需要在 subscribeWithChannel 的时候，设置 withMessage = true，注册并实现 onMessageEvent 事件。

Topic

joinTopic：注册成为此 Topic 的消息发布者（publisher）。注册后，该用户会具备发送消息的能力。
publishTopicMessage：向 Stream Channel 中的 Topic 发送消息。
leaveTopic：取消注册为该 Topic 的消息发布者。
subscribeTopic：订阅该频道中 Topic 的一名或多名消息发布者。
unsubscribeTopic：取消订阅该 Topic 或取消订阅该 Topic 中指定的一名或多名消息发布者。

信息

Topic 特性只在 Stream Channel 中有效，Message Channel 中不存在此特性。

在线状态

Presence 提供监控用户在线状态及临时状态变化的能力。通过 Presence 功能，你可以实时获取以下信息：

用户加入或离开频道的实时状态
订阅或加入同一频道的所有用户的实时状态
一个用户订阅或加入的所有频道的实时信息
自定义临时用户状态及其变更信息

在 Message Channel 和 Stream Channel 中均可使用以下 Presence 功能：

whoNow：实时获取指定频道的在线用户数量、在线用户列表、在线用户的临时状态等信息。
whereNow：实时获取指定用户所在频道的列表。
setState：设置用户在指定频道的临时状态。
getState：获取用户在指定频道的临时状态。
removeState：删除用户在特定频道的临时状态。

存储

Channel Metadata

setChannelMetadata：为指定频道设置 Channel Metadata 或 Channel Metadata Item。
getChannelMetadata：获取指定频道的 Channel Metadata 和 Channel Metadata Item。
removeChannelMetadata：删除指定频道的 Channel Metadata 或 Channel Metadata Item。
updateChannelMetadata：更新指定频道已有 Channel Metadata 或 Channel Metadata Item。

Channel Metadata 同时也引入了 Lock 的控制能力，当调用 API 设置、删除、更新 Channel Metadata 时，如果参数中的 lock 被设置，则开启 Lock 的校验，此时只有拥有此锁的用户才被允许成功调用对应的方法。

User Metadata

setUserMetadata：设置指定用户的 User Metadata 或 User Metadata Item。
getUserMetadata：获取指定用户的 User Metadata 和 User Metadata Item。
removeUserMetadata：删除指定用户的 User Metadata 或 User Metadata Item。
updateUserMetadata：更新指定用户已存在的 User Metadata 或 User Metadata Item。
subscribeUserMetadata：订阅指定用户的 User Metadata 或 User Metadata Item 变更事件通知。
unsubscribeUserMetadata：取消订阅指定用户的 User Metadata 或 User Metadata Item 事件通知。

CAS 控制

通过 AgoraRtmMetadata 中的 setMajorRevision 方法设置 majorRevision 属性开启整组 Channel Metadata 的版本号校验。
通过 AgoraRtmMetadataItem 中的 revision 属性开启某个 Metadata Item 的版本号校验。

设置、删除、更新 Channel Metadata 或 User Metadata 时，配合 revision 参数可以控制本次调用是否开启 Revision 校验，逻辑如下：

majorRevision 或 revision 为 -1 时，本次调用不开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则该 Metadata 或 Metadata Item 会被最新值覆盖；如果 Metadata 或 Metadata Item 不存在，则会创建对应的 Metadata 或 Metadata Item。
majorRevision 或 revision 为 Uint64 正整数时，本次调用开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则 SDK 会在版本号验证成功后更新对应的值；如果 Metadata 或 Metadata Item 不存在，则 SDK 会返回错误码。

锁

setLock：为指定频道设置锁。
acquireLock：获取指定频道中指定的锁。
releaseLock：释放指定频道中指定的锁。
revokeLock：撤销指定频道中某个用户对此锁的占用权限以释放此锁。
getLocks：获取指定频道中所有锁的详情。
removeLock：删除指定频道中指定的锁。

频道中锁的设置、获取、释放、撤销和删除操作都会上报对应的 onLockEvent 事件通知。你可以充分利用此特性优化业务的实现逻辑。

本文提供 RTM v2 SDK 的发版说明。

该版本于 2026 年 8 月 18 日发布。

升级必看

移除旧连接状态事件

该版本移除 status 和 connectionStateChange 事件通知。监听连接状态变化时，请改用 linkState 事件。

Cloud Proxy 需显式开启

该版本不再自动回退到 Cloud Proxy。需要使用 Cloud Proxy 时，需在初始化 RTM 实例时显式设置 rtmConfig.cloudProxy = true。建议根据业务需要向终端用户提供 Cloud Proxy 开关。

限制重复创建实例

同一 appId 和 userId 已被活跃 RTM 实例占用时，再次创建实例会返回 RTM_ERROR_DUPLICATE_USER_ID (-10027)。确保同一 appId 和 userId 只创建一个 RTM 实例，优先复用已有实例，避免多实例问题。

信息

如遇 RTM_ERROR_DUPLICATE_USER_ID（-10027）错误，可参考 WebRTM Integration Demo，确保同一 appId 和 userId 只创建一个 RTM 实例，优先复用已有实例。

新特性

新增微信小程序 SDK

该版本新增微信小程序 SDK，提供小程序所需的基础 RTM 能力。微信小程序 SDK 暂不支持 Stream Channel、Cloud Proxy、私有化部署和 Geofencing。

改进

Presence 服务支持控制台开关

Console控制台支持对Presence服务做开关控制，该开关默认开启。只有在控制台中开启Presence服务后，Presence的相关配置项和API调用才会生效。

其它改进

优化了 Web 弱网重连和退避策略，提高连接恢复的可靠性。
增加 login 全链路上报，并支持通过云端配置开启日志上传，提升问题排查效率。
Geofencing 场景新增多个可用接入节点，提高服务可用性。
优化了登录后的 Presence 查询可用性。调用 login 成功后，如果 Presence 服务仍在准备，SDK 会暂时等待并在服务可用后自动执行 whoNow、whereNow 和远端用户 getState 查询。应用无需增加固定延迟或通过临时订阅判断服务是否就绪，现有异步结果处理方式保持不变。
优化了大规模频道中的 Presence 成员同步。当频道在线人数超过 512 人时，SDK 会自动采用大频道优化策略，以最多 512 名成员为持续同步的明细范围，并通过 PresenceEvent.IntervalInfo.totalOccupancy 提供频道总在线人数。应用仍可通过 whoNow 分页查询完整在线成员，并可按需查询远端用户状态；无需新增模式切换代码。
登录服务后如果发生异常断开，异常断开期间发起的订阅请求会在连接恢复后重新发送。

问题修复

修复了设置或订阅 Metadata 后立即调用 get，偶现返回 -12001 的问题。
修复了使用过期 Token 登录时，linkState 原因错误显示为 rejected 的问题。修复后会正确报告 Token 过期，并在 linkState 中体现 LOGIN_NOT_AUTHORIZED。
修复了使用非法 Token 登录时，偶现返回 -10016 或 The appid is not consistent. 的问题。
修复了用户 logout 后，短时间内仍能通过 whoNow 查询到该用户的问题。
修复了加入 Stream Channel Topic 后空闲约一分钟，再发送 Topic 消息可能返回 -11024 的问题。

该版本于 2024 年 8 月 29 日发布。

升级必看

该版本在 RTMConfig 中删除了 token 参数，并在 login 方法中新增了 token 参数作为替代，你需要在升级后修改你的实现代码：

JavaScript

// v2.2.0 之前的方式
const { RTM, EncryptionMode } = AgoraRTM;
const rtmConfig = {
    token : "yourToken",
    encryptionMode : EncryptionMode.AES_256_GCM,
    salt : yourSalt,
    cipherKey : "yourCipherKey",
    presenceTimeout : 300,
    logUpload : true,
    logLevel : "debug",
    cloudProxy : false,
    useStringUserId : false
    privateConfig: {
        serviceType: ["MESSAGE", "STREAM"]
    },
    heartbeatInterval: 5
};
const rtm = new RTM("yourAppId", "yourUserId", rtmConfig);

try{
    const result = await rtm.login();
    console.log(result);
} catch (status){
    console.log(status);
}

JavaScript

// v2.2.0 及之后的方式
const { RTM, EncryptionMode } = AgoraRTM;
const rtmConfig = {
    encryptionMode : EncryptionMode.AES_256_GCM,
    salt : yourSalt,
    cipherKey : "yourCipherKey",
    presenceTimeout : 300,
    logUpload : true,
    logLevel : "debug",
    cloudProxy : false,
    useStringUserId : false
    privateConfig: {
        serviceType: ["MESSAGE", "STREAM"]
    },
    heartbeatInterval: 5
};
const rtm = new RTM("yourAppId", "yourUserId", rtmConfig);

try {
    const result = await rtm.login({ token: "your_token" });
} catch (status) {
    const { operation, reason, errorCode } = status;
    console.log(`${operation} failed, the error code is ${errorCode}, because of: ${reason}.`);
}

新特性

新增私有化部署能力

该版本在 RTMConfig 中新增 privateConfig 参数，用于实现私有化部署功能。详见私有化配置。

新增心跳时间配置

该版本在 RTMConfig 中新增 heartbeatInterval 参数，用于配置 SDK 向 RTM 服务器发送心跳包的时间间隔。详见 Heartbeat Interval 与 Presence Timeout。

新增用户频道类型

该版本在 channelType 中新增 USER 类型，用于向指定用户发送消息。该功能可以替代 v1 的点对点消息功能。详见在 User Channel 中发送消息。

新增静默模式配置

该版本在 subscribe 和 join 方法的 options 对象中新增 beQuiet 属性。该属性设置为 true 时表示静默订阅或加入频道，频道中其他用户无法感知该用户的出席状态。

改进

改进连接状态管理逻辑

该版本新增 linkState 回调，用于替代废弃的 status 回调，以便更好地管理连接状态。详见连接管理。

改进 REMOTE_STATE_CHANGED 事件通知逻辑

该版本改进了 Presence 功能的 REMOTE_STATE_CHANGED 事件的触发逻辑，即当用户一次设置或修改多个 key-value 时，频道内其他用户只会接收到一次事件通知。

支持事件通知触发时间戳

该版本在如下回调中新增 timestamp 参数，报告触发事件通知的时间戳：

message
presence
topic
storage
lock

优化 API 行为

该版本优化了以下 API 的行为：

login：
- 在之前版本中，不支持连续多次调用该方法；也不支持在该方法的 token 参数中传入空字符串。
- 自 2.2.0 版本起，支持连续多次调用该方法，中间无需额外调用 logout 方法。此外，当 token 参数为空字符串时，SDK 会默认使用你初始化时传入的 App ID 替代 Token。
subscribe：
- 在之前版本中，不支持连续多次调用该方法。
- 自 2.2.0 版本起，支持连续多次调用该方法。
join：
- 在之前版本中，不支持连续多次调用该方法，也不支持在该方法的 token 参数中传入空字符串。
- 自 2.2.0 版本起，支持连续多次调用该方法。此外，当 token 参数为空字符串时，SDK 会默认使用你初始化时传入的 App ID 替代 Token。

修改 presenceTimeout 取值范围

该版本将 RTMConfig 中 presenceTimeout 参数的取值范围由 [10,300] 修改为 [5,300]。

其他

该版本还进行了如下优化：

优化了底层算法能力，提升了数据同步速度。
支持本地用户在发送消息时，可以收到自己发送的消息的事件通知，方便在调试阶段验证消息的收发。
在所有方法的 Response 对象中删除了无效的 timeToken 参数。

该版本于 2023 年 9 月 28 日发布。

升级必看

该版本对以下 API 进行了修改，你需要在升级后修改你的实现代码：

把 messageType 的参数类型由 string | binary 修改为 STRING | BINARY。
把 TokenPrivilegeWillExpire 回调改名为 tokenPrivilegeWillExpire。

新特性

删除事件监听

该版本新增 removeEventListener 方法，用于删除指定的事件监听。

定时通知模式

该版本支持定时通知模式。当频道中的在线人数超过 Announce Max 的值时，频道会进入定时通知模式。SDK 会以一定的时间间隔触发 presence 事件通知，并在 interval 属性中返回当前频道在上一个周期内用户加入、离开、超时、状态变更等事件通知的聚合增量信息。详见定时通知模式。

改进

在线状态服务

该版本优化了 Presence 服务未就绪时调用 Presence 模块 API 的行为。加入 Stream Channel 或订阅 Message Channel 后，如果 Presence 服务未就绪，SDK 会把你对 Presence 模块的调用操作存在本地，待 Presence 服务就绪后发送出去。

此外，该版本在 whoNow 方法的返回值中删除了超时用户的信息。

消息发布者订阅

该版本优化了输入无效用户 ID 时订阅消息发布者的行为。调用 subscribeTopic 方法时，如果发布者列表（users 属性）中包含无效的用户 ID，则 SDK 会忽略无效的用户 ID 并成功订阅有效的用户 ID。

自定义消息类型

该版本支持在调用 publish 或 publishTopicMessage 方法时把中文等特殊字符传入 customType 参数。

加密盐

该版本支持设置加密时不传入 salt 参数。

错误信息优化

为方便排查错误，该版本为每个错误码添加了错误描述，并在 Storage 和 Lock 模块的错误信息中补充了错误堆栈。同时，该版本删除了 RTM_ERROR_INVALID_ARGUMENT(-2) 和 RTM_ERROR_TOO_OFTEN(-12) 错误码，并新增了如下错误码：

RTM_ERROR_LOGIN_NOT_AUTHORIZED(-10015)
RTM_ERROR_INCONSISTENT_APPID(-10016)
RTM_ERROR_INVALID_CHANNEL_TYPE(-10019)
RTM_ERROR_INVALID_ENCRYPTION_PARAMETER(-10020)
RTM_ERROR_OPERATION_RATE_EXCEED_LIMITATION(-10021)

错误码描述及处理方法见错误排查。

问题修复

该版本修复了如下问题：

弱网场景下的异常。
在加入频道时设置 withPresence : false 后，getState 方法返回的 userId 属性为空。
在断网重连期间，调用任意 API 都会失败并返回 RTM_ERROR_NOT_LOGIN(-10002) 错误码。
当客户端设备进入休眠状态后被唤醒时，调用 Presence 模块的任意 API 会失败。
在资源未加载的情况下，调用 login 方法失败。
在 Presence 模块的 API 中传入中文等特殊字符时，消息发送到远端会被截断。

该版本于 2023 年 6 月 15 日发布。这是 RTM v2 JavaScript SDK 的第一个版本。

本次发布意味着声网实时通讯（RTM）产品步入 v2 时代，我们在功能覆盖、性能提升、体验优化上都将为用户带来革新。

功能覆盖：该版本通过引入频道（Channel）、消息（Message）、Topic、Presence、Storage 和 Lock 等功能模块，能覆盖更多业务场景，你可以把更多的精力集中在自己的业务创新上。
性能提升：我们在新版本中重构了后台架构，通过优化网络连接进一步提升性能，提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力，让你无需为业务质量担忧。
体验优化：我们重新设计并简化了 API 接口，支持业界最流行的 Async/Await 编程模式；优化了包括用户指南、API 参考在内的所有文档，提供了更全面的示例程序，支持开发者低成本学习使用 SDK，快速完成集成，提高开发效率。

新特性

该版本提供的核心功能模块如下。

信息

RTM 2.1.0-beta 目前处于 Public Beta 阶段，某些功能细节可能会在随后的版本中发生改变，以提升用户体验。

初始配置（Setup）

初始配置（Setup）是初始化 RTM Client 时预先定义或配置的一些关键参数，影响其后续行为。同时，它还提供了登录、登出等功能。核心能力如下：

new RTM()：创建一个 RTM Client 实例，并进行如下初始配置：
- appId：设置 App ID。相同 App ID 的 App 间可以通信，不同 App ID 的 App 相互隔离。
- userId：设置用户 ID，用以区分用户或设备。
- rtmConfig：
  - token: 设置用于用户鉴权的 Token。
  - encryptionMode: 设置端侧加密模式。
  - cipherKey: 设置端侧加密密钥。
  - salt：设置端侧加密盐。
  - logUpload: 配置是否开启日志上传。
  - logLevel: 配置日志消息过滤等级。
  - cloudProxy: 配置是否开启云代理。
  - useStringUserId: 设置是否使用字符串类型的用户 ID。
事件监听：实现 message、presence、topic、storage、lock、status、tokenPrivilegeWillExpire 等事件通知的业务逻辑。
login：登录 RTM 服务。
logout：登出 RTM 服务。

频道（Channel）

基于声网的能力，RTM 的频道分成两种类型：Message Channel 和 Stream Channel。两种类型频道的核心能力如下：

Message Channel：
- subscribe：订阅指定 Message Channel 并开始接收频道中的消息和事件通知。
- unsubscribe：取消订阅指定 Message Channel 并停止接收频道中的消息和事件通知。
Stream Channel：
- createStreamChannel：创建 Stream Channel 实例，随后可以调用其中的方法。
- join：加入 Stream Channel，并开始接收频道中的消息和事件通知。
- leave：离开 Stream Channel，并停止接收频道中的消息和事件通知。

其中：

subscribe、unsubscribe、join、leave 方法都会触发 presence 事件通知。频道中的其他用户会收到对应的 Join、Leave 事件通知。
调用 subscribe 和 join 操作订阅或加入频道的时候，可以选择是否配置 withMessage、withPresence、withMetadata、withLock 等参数以开启对应事件通知的监听功能。如果开启，你同时也需要注册对应事件监听，才能顺利收到对应事件通知。

消息（Message）

RTM 的基础是发送消息的能力，你可以随时随地向频道中发送消息，消息会在 100 毫秒内传递到任何地方。RTM 支持 String 类型和 Binary 类型的消息负载。

publish 向指定的 Message Channel 中发送消息。调用 publish 会触发 message 事件通知，如果想要收到频道中的消息，你需要在 subscribe 的时候，设置 withMessage = true，注册并实现 message 事件。

Topic

joinTopic：注册成为此 Topic 的消息发布者（publisher）。注册后，该用户会具备发送消息的能力。
publishTopicMessage：向 Stream Channel 中的 Topic 发送消息。
leaveTopic：取消注册为该 Topic 的消息发布者。
subscribeTopic：订阅该频道中 Topic 的一名或多名消息发布者。
unsubscribeTopic：取消订阅该 Topic 或取消订阅该 Topic 中指定的一名或多名消息发布者。

信息

Topic 特性只在 Stream Channel 中有效，Message Channel 中不存在此特性。

在线状态

Presence 提供监控用户在线状态及临时状态变化的能力。通过 Presence 功能，你可以实时获取以下信息：

获取频道内在线用户列表。
获取在线用户所在频道列表。
动态监控用户加入或离开频道。
动态监控在线用户临时状态变更。

在 Message Channel 和 Stream Channel 中均可使用以下 Presence 功能：

whoNow：实时获取指定频道的在线用户数量、在线用户列表、在线用户的临时状态等信息。
whereNow：实时获取指定用户所在频道的列表。
setState：设置用户在指定频道的临时状态。
getState：获取用户在指定频道的临时状态。
removeState：删除用户在特定频道的临时状态。

Presence 在提供上述功能的同时，也提供了 presence 事件通知能力。频道中用户的加入、离开、掉线、用户状态设置、用户状态删除等事件都会以实时通知（Announce Mode）或定时通知（Interval Mode）的方式通知到频道中的其他用户。Presence 能力将大大简化开发者业务中关于在线用户上下线、状态变更等状态的同步逻辑实现，充分利用此特性将使得你的业务实现更稳定、实时、可靠。

存储

Channel Metadata

setChannelMetadata：为指定频道设置 Channel Metadata 或 Channel Metadata Item。
getChannelMetadata：获取指定频道的 Channel Metadata 和 Channel Metadata Item。
removeChannelMetadata：删除指定频道的 Channel Metadata 或 Channel Metadata Item。
updateChannelMetadata：更新指定频道已有 Channel Metadata 或 Channel Metadata Item。

Channel Metadata 的设置、删除和更新都会触发 storage 事件通知，合理使用此特性可以极大的优化业务逻辑，获得优异的用户体验。当前 storage 事件通知中携带的是当前 Channel Metadata 的全量信息，我们将在后续版本中优化，提供性能更优的增量更新能力。

User Metadata

setUserMetadata：设置指定用户的 User Metadata 或 User Metadata Item。
getUserMetadata：获取指定用户的 User Metadata 和 User Metadata Item。
removeUserMetadata：删除指定用户的 User Metadata 或 User Metadata Item。
updateUserMetadata：更新指定用户已存在的 User Metadata 或 User Metadata Item。
subscribeUserMetadata：订阅指定用户的 User Metadata 或 User Metadata Item 变更事件通知。
unsubscribeUserMetadata：取消订阅指定用户的 User Metadata 或 User Metadata Item 事件通知。

User Metadata 的设置、删除和更新都会触发 storage 事件通知，所有订阅此 User Metadata 的其他用户将会收到事件通知，合理使用此特性可以极大的优化业务逻辑，获得优异的用户体验。当前 storage 事件通知中携带的是所订阅 User Metadata 的全量信息，我们将在后续的版本中优化，提供性能更优的增量更新能力。

CAS 控制

通过 RtmMetadata 中的 majorRevision 参数开启整组 Metadata 的版本号校验。
通过 RtmMetadata 中 MetadataItem[] 类的 revision 参数开启每个 Metadata Item 数组的版本号校验。

设置、删除、更新 Channel Metadata 或 User Metadata 时，配合 revision 参数可以控制本次调用是否开启 Revision 校验，逻辑如下：

majorRevision 或 revision 为 -1 时，本次调用不开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则该 Metadata 或 Metadata Item 会被最新值覆盖；如果 Metadata 或 Metadata Item 不存在，则会创建对应的 Metadata 或 Metadata Item。
majorRevision 或 revision 为 Uint64 正整数时，本次调用开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则 SDK 会在版本号验证成功后更新对应的值；如果 Metadata 或 Metadata Item 不存在，则 SDK 会返回错误码。

锁

setLock：为指定频道设置锁。
acquireLock：获取指定频道中指定的锁。
releaseLock：释放指定频道中指定的锁。
revokeLock：撤销指定频道中某个用户对此锁的占用权限以释放此锁。
getLock：获取指定频道中所有锁的详情。
removeLock：删除指定频道中指定的锁。

频道中锁的设置、获取、释放、撤销和删除操作都会上报对应的 lock 事件通知。你可以充分利用此特性优化业务的实现逻辑。

本文提供 RTM v2 SDK 的发版说明。

已知问题和局限性

自 2.2.0 起，RTM SDK 和 RTC SDK（4.3.0 及以上版本）都包含 libaosl.so 库。如果你同时使用了 RTM 和 RTC SDK，为避免冲突，需进行如下操作：

如果你通过 CDN 手动集成 SDK，请手动删除更低版本的 libaosl.so 库；
如果你使用依赖管理工具（如 Maven 或 CocoaPods）集成 SDK，请确保在项目中引入更高版本的 libaosl.so 库。

具体的集成指南可以参考如何处理同时集成 RTM SDK 和 RTC SDK 遇到的问题？

2.3.0 RTM SDK libaosl.so 库版本为 1.3.5。
2.2.8 RTM SDK libaosl.so 库版本为 1.3.0。

该版本于 2026 年 7 月 28 日发布。

改进

Presence 服务支持控制台开关

声网控制台支持开启或关闭 Presence 服务，该开关默认开启。只有在控制台中开启 Presence 服务后，Presence 相关配置项和 API 调用才会生效。

新增错误码

该版本新增以下错误码：

PRESENCE_INACTIVE (-13014)：Presence 服务未开启或当前不可用。
PRESENCE_PENDING_REQUEST_CANCELLED (-13015)：Presence 待处理请求已取消。
PRESENCE_PENDING_REQUEST_EXCEED_LIMITATION (-13016)：Presence 待处理请求数量超过限制。
CHANNEL_SUBSCRIBE_CANCELED (-11040)：频道订阅尚未完成时被取消。

其它改进

优化控制台创建项目时的体验流程，取消在创建通用项目时配置服务区域，改为在功能配置中开启。
优化登录后的 Presence 查询可用性。调用 login 成功后，如果 Presence 服务仍在准备，SDK 会暂时等待并在服务可用后自动执行 whoNow、whereNow 和远端用户 getState 查询。应用无需增加固定延迟或通过临时订阅判断服务是否就绪，现有异步结果处理方式保持不变。
优化大规模频道中的 Presence 成员同步。当频道在线人数超过 512 人时，SDK 会自动采用大频道优化策略，以最多 512 名成员为持续同步的明细范围，并通过 PresenceEvent.interval.totalOccupancy 提供频道总在线人数。应用仍可通过 whoNow 分页查询完整在线成员，并可按需查询远端用户状态；无需新增模式切换代码。
加快订阅频道的速度。
登录服务后如果发生异常断开，异常断开期间发起的订阅请求会在连接恢复后重新发送。

问题修复

修复了未登录情况下切到后台，可能导致连接状态通知不正确的问题。
修复了网络切换场景下重新连接服务耗时较长的问题。

该版本于 2026 年 2 月 12 日发布。这是 RTM v2 HarmonyOS SDK 的 Beta 版本。

本次发布意味着声网实时通讯（RTM）产品正式支持 HarmonyOS 平台，我们在功能覆盖、性能提升、体验优化上都将为用户带来革新。

功能覆盖：该版本通过引入频道（Channel）、消息（Message）、Topic、Presence、Storage 和 Lock 等功能模块，能覆盖更多业务场景，你可以把更多的精力集中在自己的业务创新上。
性能提升：我们在新版本中重构了后台架构，通过优化网络连接进一步提升性能，提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力，让你无需为业务质量担忧。
体验优化：我们重新设计并简化了 API 接口，支持 Promise/Async-Await 异步编程模式；优化了包括用户指南、API 参考在内的所有文档，提供了更全面的示例程序，支持开发者低成本学习使用 SDK，快速完成集成，提高开发效率。

新特性

该版本提供的核心功能模块如下。

初始配置（Setup）

初始配置（Setup）是初始化生产 RTM Client 时预先定义或配置一些关键参数，影响其后续的行为。同时它还提供了登录、登出等功能。核心能力如下：

new RtmClient(...)：创建一个 RTM Client 实例，并进行如下初始配置：
- appId：设置 App ID。相同 App ID 的 App 间可以通信，不同 App ID 的 App 相互隔离。
- userId：设置用户 ID，用以区分用户或设备。
- areaCode：设置区域代码，用于 Geo-fencing 功能。
- protocolType：设置消息传输协议类型。
- presenceTimeout：设置 Presence 服务的超时时间。
- heartbeatInterval：设置 SDK 心跳间隔时间。
- useStringUserId：设置用户 ID 的数据类型，可以是 String 类型，也可以是 number 类型。
- logConfig：配置本地日志大小、位置、输出信息等级等参数。
- proxyConfig：配置 Proxy 服务参数。
- encryptionConfig：配置端侧加密参数。
- privateConfig：配置私有化部署参数。
- reconnectTimeout：配置连接超时时间，超时后将返回连接失败。
事件监听：实现 message、presence、topic、storage、lock、linkState、token 等事件通知的业务逻辑。
login()：登录 RTM 服务。
logout()：登出 RTM 服务。
release()：销毁 RTM Client 实例，释放资源。

频道（Channel）

基于声网的能力，RTM 的频道分成三种类型：Message Channel、User Channel 和 Stream Channel。三种类型频道的核心能力如下：

Message Channel：
- subscribe()：订阅指定 Message Channel 并开始接收频道中的消息和事件通知。
- unsubscribe()：取消订阅指定 Message Channel 并停止接收频道中的消息和事件通知。
User Channel：用户无需订阅频道操作，可以直接指定用户 ID 发送消息，接收消息也只需监听 message 事件。
Stream Channel：
- createStreamChannel()：创建 Stream Channel 实例，随后可以调用其中的方法。
- join()：加入 Stream Channel，并开始接收频道中的消息和事件通知。
- leave()：离开 Stream Channel，并停止接收频道中的消息和事件通知。
- release()：销毁 Stream Channel 实例以释放资源。

其中：

subscribe()、unsubscribe()、join()、leave() 方法都会触发 presence 事件通知。频道中的其他用户会收到对应的 Join、Leave 事件通知。
调用 subscribe() 和 join() 操作订阅或加入频道的时候，可以选择是否配置 withMessage、withPresence、withMetadata、withLock 等参数以开启对应事件通知的监听功能。如果开启，你同时也需要注册对应事件监听，才能顺利收到对应事件通知。

消息（Message）

RTM 的基础是发送消息的能力，你可以随时随地向频道中发送消息，消息会在 100 毫秒内传递到任何地方。RTM 支持 String 类型和 Binary 类型的消息负载。

publish() 向指定的 Message Channel 或 User Channel 中发送消息。调用 publish() 会触发 message 事件通知，如果想要收到频道中的消息，你需要在 subscribe() 的时候，设置 withMessage = true，注册并实现 message 事件。

Topic

joinTopic()：注册成为此 Topic 的消息发布者（publisher）。注册后，该用户会具备发送消息的能力。
publishTopicMessage()：向 Stream Channel 中的 Topic 发送消息。
leaveTopic()：取消注册为该 Topic 的消息发布者。
subscribeTopic()：订阅该频道中 Topic 的一名或多名消息发布者。
unsubscribeTopic()：取消订阅该 Topic 或取消订阅该 Topic 中指定的一名或多名消息发布者。

信息

Topic 特性只在 Stream Channel 中有效，Message Channel 或 User Channel 中不存在此特性。

在线状态

Presence 提供监控用户在线状态及临时状态变化的能力。通过 Presence 功能，你可以实时获取以下信息：

用户加入或离开频道的实时状态
订阅或加入同一频道的所有用户的实时状态
一个用户订阅或加入的所有频道的实时信息
自定义临时用户状态及其变更信息

在所有频道类型中均可使用以下 Presence 功能：

whoNow()：实时获取指定频道的在线用户数量、在线用户列表、在线用户的临时状态等信息。
whereNow()：实时获取指定用户所在频道的列表。
setState()：设置用户在指定频道的临时状态。
getState()：获取用户在指定频道的临时状态。
removeState()：删除用户在特定频道的临时状态。

存储

Channel Metadata

setChannelMetadata()：为指定频道设置 Channel Metadata 或 Channel Metadata Item。
getChannelMetadata()：获取指定频道的 Channel Metadata 和 Channel Metadata Item。
removeChannelMetadata()：删除指定频道的 Channel Metadata 或 Channel Metadata Item。
updateChannelMetadata()：更新指定频道已有 Channel Metadata 或 Channel Metadata Item。

User Metadata

setUserMetadata()：设置指定用户的 User Metadata 或 User Metadata Item。
getUserMetadata()：获取指定用户的 User Metadata 和 User Metadata Item。
removeUserMetadata()：删除指定用户的 User Metadata 或 User Metadata Item。
updateUserMetadata()：更新指定用户已存在的 User Metadata 或 User Metadata Item。
subscribeUserMetadata()：订阅指定用户的 User Metadata 或 User Metadata Item 变更事件通知。
unsubscribeUserMetadata()：取消订阅指定用户的 User Metadata 或 User Metadata Item 事件通知。

CAS 控制

通过 majorRevision 参数开启整组 Metadata 的版本号校验。
通过 MetadataItem 类的 revision 参数开启每个 Metadata Item 数组的版本号校验。

设置、删除、更新 Channel Metadata 或 User Metadata 时，配合 revision 参数可以控制本次调用是否开启 Revision 校验，逻辑如下：

majorRevision 或 revision 为 -1 时，本次调用不开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则该 Metadata 或 Metadata Item 会被最新值覆盖；如果 Metadata 或 Metadata Item 不存在，则会创建对应的 Metadata 或 Metadata Item。
majorRevision 或 revision 为正整数时，本次调用开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则 SDK 会在版本号验证成功后更新对应的值；如果 Metadata 或 Metadata Item 不存在，则 SDK 会返回错误码。

锁

setLock()：为指定频道设置锁。
acquireLock()：获取指定频道中指定的锁。
releaseLock()：释放指定频道中指定的锁。
revokeLock()：撤销指定频道中某个用户对此锁的占用权限以释放此锁。
getLock()：获取指定频道中所有锁的详情。
removeLock()：删除指定频道中指定的锁。

频道中锁的设置、获取、释放、撤销和删除操作都会上报对应的 lock 事件通知。你可以充分利用此特性优化业务的实现逻辑。

本文提供 RTM v2 SDK 的发版说明。

该版本于 2024 年 1 月 25 日发布。

升级必看

该版本对如下内容进行了优化，请在升级到该版本后更新 App 代码。

消息发送选项

该版本对 PublishAsync 和 PublishTopicMessageAsync 方法中的 options 参数进行如下优化：

在 PublishAsync 方法的 PublishOptions 中删除了 sendTs 参数，并新增了 channelType 参数。详见 PublishOptions。
将 publishTopicMessage 方法中的 options 参数类型由 PublishOptions 修改为 TopicMessageOptions。详见 TopicMessageOptions。

连接状态回调更名

该版本将 onConnectionStateChange 回调名称修改为 onConnectionStateChanged。

改进

错误码

该版本新增了 INVALID_CHANNEL_TYPE、INVALID_ENCRYPTION_PARAMETER 和 OPERATION_RATE_EXCEED_LIMITATION 错误码。错误码描述及解决方法见错误排查。

在线状态模块

该版本优化了在断线重连时对过期用户状态数据的处理逻辑，并提升了在 JoinChannelOptions 中设置 Presence 事件通知的性能。

其他

该版本优化了内存表现并修复了潜在的内存泄漏问题。

问题修复

该版本修复了如下问题：

调用 WhoNowAsync 方法返回分页结果时偶现崩溃。
特定场景下，偶现 Presence 数据丢包。
特定场景下，方法调用后未触发异步回调。
使用端侧加密时，参数无效导致的崩溃。
当网络状态发生变化时，偶现无法登录或登出 RTM 系统。
网络断开后，因数据未清理导致偶现用户无法收到 SNAPSHOT 事件通知。
用户加入频道后，把 App 切到后台再切换回前台时，偶现 SDK 多次触发 REMOTE_JOIN 事件通知。

该版本于 2023 年 8 月 22 日发布。

新特性

自定义消息负载

为满足用户在各类业务中对消息负载类型的不同需求，该版本提供一套收发自定义消息负载的方案：

发送自定义消息负载：调用 PublishAsync 或 PublishTopicMessageAsync 方法并在 customType 参数中填写自定义消息负载类型。
接收自定义消息负载：通过 OnMessageEvent 回调的 customType 参数获取自定义消息负载的类型，然后根据实际业务需求进行消息反序列化等操作。

RtmResult`<T>` 解构能力

为方便用户在调用 API 时使用返回值，提升业务代码可读性，该版本在 API 返回值（RtmResult<T>）中提供解构能力。你可以通过如下方式获取 API 调用的返回值：

var (status, response) = await streamChannel.SubscribeTopicAsync(subtopic, topicOptions);
if (status.Error){
    Debug.Log(string.Format("{0} is failed, The error code is {1}, because of: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("User:{0} Join Topic:{1} success! at Channel:{2}", response.UserId, response.Topic, response.ChannelName));
}

改进

错误信息扩充

为提升用户排查错误的效率，该版本在 API 返回值中扩充了 Status 结构体的 Reason 字段内容，删除了 Response 结构体内的 ErrorCode 字段。你只需通过 Status 结构体即可获取错误码和错误描述。

API 简化

为提升易用性，该版本对 API 进行了简化：

枚举和结构体命名优化：简化了所有枚举值和部分结构体的名称，例如，将 RTM_CHANNEL_TYPE_MESSAGE 简化为 MESSAGE。
数据类型优化：
- IntervalInfo 结构体中 joinUserList 参数的类型由 UserList 改为 string[]。
- MessageEvent 结构体中 message 参数的类型由 object 改为 IRtmMessage。
- 在 LogoutAsync 中新增 RtmResult<LogoutResult> 类型的返回值。
删除冗余字段：
- 在 PublishOptions 中删除了 messageType 字段。
- 在 GetLocksResult、WhoNowResult 等 Result 结构体中删除 Count 字段。
- 在 TopicOptions 结构体中删除 userCount 字段。
- 在 IntervalInfo 结构体中删除 userStateCount 字段。
- 在 SnapshotInfo 结构体中删除 userCount 字段。
- 在 LockEvent 结构体中删除 count 字段。
- 在 PresenceEvent 结构体中删除 stateItemCount 字段。
- 在 TopicEvent 结构体中删除 topicInfoCount 字段，并将 userId 参数名修改为 publisher。

详见 API 参考。

该版本于 2023 年 4 月 27 日发布。这是 RTM v2 Unity SDK 的第一个版本。

本次发布意味着声网实时通讯（RTM）产品步入 v2 时代，我们在功能覆盖、性能提升、体验优化上都将为用户带来革新。

功能覆盖：该版本通过引入频道（Channel）、消息（Message）、Topic、Presence、Storage 和 Lock 等功能模块，能覆盖更多业务场景，你可以把更多的精力集中在自己的业务创新上。
性能提升：我们在新版本中重构了后台架构，通过优化网络连接进一步提升性能，提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力，让你无需为业务质量担忧。
体验优化：我们重新设计并简化了 API 接口，支持业界最流行的 Async/Await 编程模式；优化了包括用户指南、API 参考在内的所有文档，提供了更全面的示例程序，支持开发者低成本学习使用 SDK，快速完成集成，提高开发效率。

新特性

该版本提供的核心功能模块如下。

信息

RTM 2.1.0-beta 目前处于 Public Beta 阶段，某些功能细节可能会在随后的版本中发生改变，以提升用户体验。

初始配置（Setup）

初始配置（Setup）是初始化 RTM Client 时预先定义或配置的一些关键参数，影响其后续行为。同时，它还提供了登录、登出等功能。核心能力如下：

CreateAgoraRtmClient：创建一个 RTM Client 实例，并进行如下初始配置：
- appId：设置 App ID。相同 App ID 的 App 间可以通信，不同 App ID 的 App 相互隔离。
- userId：设置用户 ID，用以区分用户或设备。
- areaCode：设置区域代码，用于 Geo-fencing 功能。
- presenceTimeout：设置 Presence 服务的超时时间。
- useStringUserId：设置用户 ID 的数据类型，可以是 String 类型，也可以是 Uint 类型。
- logConfig：配置本地日志大小、位置、输出信息等级等参数。
- proxyConfig：配置 Proxy 服务参数。
- encryptionConfig：配置端侧加密参数。
事件监听：实现 OnMessageEvent、OnPresenceEvent、OnTopicEvent、OnStorageEvent、OnLockEvent、OnConnectionStateChanged、OnTokenPrivilegeWillExpire 等事件通知的业务逻辑。
LoginAsync：登录 RTM 服务。
LogoutAsync：登出 RTM 服务。
Dispose：销毁 RTM Client 实例，释放资源。

频道（Channel）

基于声网的能力，RTM 的频道分成两种类型：Message Channel 和 Stream Channel。两种类型频道的核心能力如下：

Message Channel：
- SubscribeAsync：订阅指定 Message Channel 并开始接收频道中的消息和事件通知。
- UnsubscribeAsync：取消订阅指定 Message Channel 并停止接收频道中的消息和事件通知。
Stream Channel：
- CreateStreamChannel：创建 Stream Channel 实例，随后可以调用其中的方法。
- JoinAsync：加入 Stream Channel，并开始接收频道中的消息和事件通知。
- LeaveAsync：离开 Stream Channel，并停止接收频道中的消息和事件通知。
- Dispose：销毁 Stream Channel 实例以释放资源。

其中：

SubscribeAsync、UnsubscribeAsync、JoinAsync、LeaveAsync 方法都会触发 OnPresenceEvent 事件通知。频道中的其他用户会收到对应的 Join、Leave 事件通知。
调用 SubscribeAsync 和 JoinAsync 操作订阅或加入频道的时候，可以选择是否配置 withMessage、withPresence、withMetadata、withLock 等参数以开启对应事件通知的监听功能。如果开启，你同时也需要注册对应事件监听，才能顺利收到对应事件通知。

消息（Message）

RTM 的基础是发送消息的能力，你可以随时随地向频道中发送消息，消息会在 100 毫秒内传递到任何地方。RTM 支持 String 类型和 Binary 类型的消息负载。

PublishAsync 向指定的 Message Channel 中发送消息。调用 PublishAsync 会触发 OnMessageEvent 事件通知，如果想要收到频道中的消息，你需要在 SubscribeAsync 的时候，设置 withMessage = true，注册并实现 OnMessageEvent 事件。

Topic

JoinTopicAsync：注册成为此 Topic 的消息发布者（publisher）。注册后，该用户会具备发送消息的能力。
PublishTopicMessageAsync：向 Stream Channel 中的 Topic 发送消息。
LeaveTopicAsync：取消注册为该 Topic 的消息发布者。
SubscribeTopicAsync：订阅该频道中 Topic 的一名或多名消息发布者。
UnsubscribeTopicAsync：取消订阅该 Topic 或取消订阅该 Topic 中指定的一名或多名消息发布者。

信息

Topic 特性只在 Stream Channel 中有效，Message Channel 中不存在此特性。

在线状态

Presence 提供监控用户在线状态及临时状态变化的能力。通过 Presence 功能，你可以实时获取以下信息：

用户加入或离开频道的实时状态
订阅或加入同一频道的所有用户的实时状态
一个用户订阅或加入的所有频道的实时信息
自定义临时用户状态及其变更信息

在 Message Channel 和 Stream Channel 中均可使用以下 Presence 功能：

WhoNowAsync：实时获取指定频道的在线用户数量、在线用户列表、在线用户的临时状态等信息。
WhereNowAsync：实时获取指定用户所在频道的列表。
SetStateAsync：设置用户在指定频道的临时状态。
GetStateAsync：获取用户在指定频道的临时状态。
RemoveStateAsync：删除用户在特定频道的临时状态。

Presence 在提供上述功能的同时，也提供了 OnPresenceEvent 事件通知能力。频道中用户的加入、离开、掉线、用户状态设置、用户状态删除等事件都会以实时通知（Announce Mode）或定时通知（Interval Mode）的方式通知到频道中的其他用户。Presence 能力将大大简化开发者业务中关于在线用户上下线、状态变更等状态的同步逻辑实现，充分利用此特性将使得你的业务实现更稳定、实时、可靠。

存储

Channel Metadata

SetChannelMetadataAsync：为指定频道设置 Channel Metadata 或 Channel Metadata Item。
GetChannelMetadataAsync：获取指定频道的 Channel Metadata 和 Channel Metadata Item。
RemoveChannelMetadataAsync：删除指定频道的 Channel Metadata 或 Channel Metadata Item。
UpdateChannelMetadataAsync：更新指定频道已有 Channel Metadata 或 Channel Metadata Item。

Channel Metadata 的设置、删除和更新都会触发 OnStorageEvent 事件通知，合理使用此特性可以极大的优化业务逻辑，获得优异的用户体验。当前 OnStorageEvent 事件通知中携带的是当前 Channel Metadata 的全量信息，我们将在后续版本中优化，提供性能更优的增量更新能力。

User Metadata

SetUserMetadataAsync：设置指定用户的 User Metadata 或 User Metadata Item。
GetUserMetadataAsync：获取指定用户的 User Metadata 和 User Metadata Item。
RemoveUserMetadataAsync：删除指定用户的 User Metadata 或 User Metadata Item。
UpdateUserMetadataAsync：更新指定用户已存在的 User Metadata 或 User Metadata Item。
SubscribeUserMetadataAsync：订阅指定用户的 User Metadata 或 User Metadata Item 变更事件通知。
UnsubscribeUserMetadataAsync：取消订阅指定用户的 User Metadata 或 User Metadata Item 事件通知。

User Metadata 的设置、删除和更新都会触发 OnStorageEvent 事件通知，所有订阅此 User Metadata 的其他用户将会收到事件通知，合理使用此特性可以极大的优化业务逻辑，获得优异的用户体验。当前 OnStorageEvent 事件通知中携带的是所订阅 User Metadata 的全量信息，我们将在后续的版本中优化，提供性能更优的增量更新能力。

CAS 控制

通过 RtmMetadata 中的 majorRevision 参数开启整组 Metadata 的版本号校验。
通过 RtmMetadata 中 MetadataItem 类的 revision 参数开启每个 Metadata Item 数组的版本号校验。

设置、删除、更新 Channel Metadata 或 User Metadata 时，配合 revision 参数可以控制本次调用是否开启 Revision 校验，逻辑如下：

majorRevision 或 revision 为 -1 时，本次调用不开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则该 Metadata 或 Metadata Item 会被最新值覆盖；如果 Metadata 或 Metadata Item 不存在，则会创建对应的 Metadata 或 Metadata Item。
majorRevision 或 revision 为 Int64 正整数时，本次调用开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则 SDK 会在版本号验证成功后更新对应的值；如果 Metadata 或 Metadata Item 不存在，则 SDK 会返回错误码。

锁

SetLockAsync：为指定频道设置锁。
AcquireLockAsync：获取指定频道中指定的锁。
ReleaseLockAsync：释放指定频道中指定的锁。
RevokeLockAsync：撤销指定频道中某个用户对此锁的占用权限以释放此锁。
GetLocksAsync：获取指定频道中所有锁的详情。
RemoveLockAsync：删除指定频道中指定的锁。

频道中锁的设置、获取、释放、撤销和删除操作都会上报对应的 OnLockEvent 事件通知。你可以充分利用此特性优化业务的实现逻辑。

本文提供 RTM v2 SDK 的发版说明。

已知问题和局限性

自 2.2.0 起，RTM SDK 和 RTC SDK（4.3.0 及以上版本）都包含动态库文件。如果你同时使用了 RTM 和 RTC SDK，为避免冲突，请手动删除更低版本的动态库文件。

2.3.0 RTM SDK 动态库版本为 1.3.5。
2.2.8 RTM SDK 动态库版本为 1.3.0。
2.2.7 RTM SDK 动态库版本为 1.3.0。
2.2.3、2.2.4、2.2.5、2.2.6 RTM SDK 动态库版本为 1.2.13。
2.2.2 RTM SDK 动态库版本为 1.0.11。
2.2.1 RTM SDK 动态库版本为 1.0.11。
2.2.0 RTM SDK 动态库版本为 1.0.0.17。

该版本于 2026 年 7 月 28 日发布。

升级必看

移除旧连接状态回调

该版本移除 onConnectionStateChanged 回调。监听连接状态变化时，请改用 onLinkStateEvent。

改进

Presence 服务支持控制台开关

声网控制台支持开启或关闭 Presence 服务，该开关默认开启。只有在控制台中开启 Presence 服务后，Presence 相关配置项和 API 调用才会生效。

新增错误码

该版本新增以下错误码：

RTM_ERROR_PRESENCE_INACTIVE (-13014)：Presence 服务未开启或当前不可用。
RTM_ERROR_PRESENCE_PENDING_REQUEST_CANCELLED (-13015)：Presence 待处理请求已取消。
RTM_ERROR_PRESENCE_PENDING_REQUEST_EXCEED_LIMITATION (-13016)：Presence 待处理请求数量超过限制。
RTM_ERROR_CHANNEL_SUBSCRIBE_CANCELED (-11040)：频道订阅尚未完成时被取消。

其它改进

优化控制台创建项目时的体验流程，取消在创建通用项目时配置服务区域，改为在功能配置中开启。
优化登录后的 Presence 查询可用性。调用 login 成功后，如果 Presence 服务仍在准备，SDK 会暂时等待并在服务可用后自动执行 whoNow、whereNow 和远端用户 getState 查询。应用无需增加固定延迟或通过临时订阅判断服务是否就绪，现有异步结果处理方式保持不变。
优化大规模频道中的 Presence 成员同步。当频道在线人数超过 512 人时，SDK 会自动采用大频道优化策略，以最多 512 名成员为持续同步的明细范围，并通过 PresenceEvent.interval.totalOccupancy 提供频道总在线人数。应用仍可通过 whoNow 分页查询完整在线成员，并可按需查询远端用户状态；无需新增模式切换代码。
加快订阅频道的速度。
登录服务后如果发生异常断开，异常断开期间发起的订阅请求会在连接恢复后重新发送。

问题修复

修复了未登录情况下切到后台，可能导致连接状态通知不正确的问题。
修复了网络切换场景下重新连接服务耗时较长的问题。

该版本于 2024 年 7 月 26 日发布。

升级必看

该版本对以下功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。

初始化

该版本删除了 initialize 方法，并在 createAgoraRtmClient 方法中新增初始化参数作为替代。参考如下示例代码修改你的实现代码：

C++

// v2.2.1 之前
// 创建 RTM 实例
IRtmClient* rtmClient = createAgoraRtmClient();

RtmConfig config;
config.appId = "your_appid";
config.userId = "your_name";
config.eventHandler = new RtmEventHandler();
// 初始化 RTM 实例
int ret = rtmClient->initialize(config);
if (ret != RTM_ERROR_OK) {
    // 处理初始化报错
}

C++

// v2.2.1
RtmConfig config;
config.appId = "your_appid"
config.userId = "your_name";
config.eventHandler = new RtmEventHandler();

int errorCode = 0;
// 创建并初始化 RTM 实例
rtmClient = createAgoraRtmClient(config, errorCode);
if (!rtmClient || errorCode != 0) {
    std::cout << RED <<"error creating rtm service!" << std::endl;
    exit(0);
}

API 返回值

该版本将除 createAgoraRtmClient、createStreamChannel 和 release 以外方法的返回值从 int 类型修改为 void 类型，并补齐以下异步回调：

创建 Metadata

该版本删除了 createMetadata 方法。参考如下示例代码修改你的实现代码：

C++

// v2.2.1 之前
IMetadata* metadata = rtmClient->getStorage()->createMetadata();

C++

// v2.2.1
Metadata data;

枚举值变更

该版本在 RTM_CONNECTION_CHANGE_REASON 中新增了 RTM_CONNECTION_CHANGED_CERTIFICATION_VERIFY_FAILURE(22) 枚举，并将 RTM_CONNECTION_CHANGED_STREAM_CHANNEL_NOT_AVAILABLE 和 RTM_CONNECTION_CHANGED_INCONSISTENT_APPID 枚举对应的值修改为 23 和 24。

新特性

新增私有化部署能力

该版本在 RtmConfig 中新增 privateConfig 参数，用于实现私有化部署功能。详见私有化配置。

新增心跳时间配置

该版本在 RtmConfig 中新增 heartbeatInterval 参数，用于配置 SDK 向 RTM 服务器发送心跳包的时间间隔。详见 Heartbeat Interval 与 Presence Timeout。

新增双环境配置

该版本在 RtmConfig 中新增 protocolType 参数，用于自定义网络传输协议，以便于更好地适配你的网络环境。详见连接协议配置。

新增用户频道类型

该版本在 RTM_CHANNEL_TYPE 中新增 RTM_CHANNEL_TYPE_USER 类型，用于向指定用户发送消息。该功能可以替代 v1 的点对点消息功能。详见在 User Channel 中发送消息。

新增静默模式配置

改进

改进连接状态管理逻辑

该版本新增 onLinkStateEvent 回调，用于替代废弃的 onConnectionStateChanged 回调，以便更好地管理连接状态。详见连接管理。

改进 RTM_PRESENCE_EVENT_TYPE_REMOTE_STATE_CHANGED 事件通知逻辑

该版本改进了 Presence 功能的 RTM_PRESENCE_EVENT_TYPE_REMOTE_STATE_CHANGED 事件的触发逻辑，即当用户一次设置或修改多个 key-value 时，频道内其他用户只会接收到一次事件通知。

支持事件通知触发时间戳

该版本在如下数据结构中新增 timestamp 参数，报告触发事件通知的时间戳：

优化 API 行为

该版本优化了以下 API 的行为：

login：
- 在之前版本中，不支持连续多次调用该方法；也不支持在该方法的 token 参数中传入空字符串。
- 自 2.2.1 版本起，支持连续多次调用该方法，中间无需额外调用 logout 方法。此外，当 token 参数为空字符串时，SDK 会默认使用你初始化时传入的 App ID 替代 Token。
subscribe：
- 在之前版本中，不支持连续多次调用该方法。
- 自 2.2.1 版本起，支持连续多次调用该方法。
join：
- 在之前版本中，不支持连续多次调用该方法，也不支持在该方法的 token 参数中传入空字符串。
- 自 2.2.1 版本起，支持连续多次调用该方法。此外，当 token 参数为空字符串时，SDK 会默认使用你初始化时传入的 App ID 替代 Token。

修改 presenceTimeout 取值范围

该版本将 RtmConfig 中 presenceTimeout 参数的取值范围由 [10,300] 修改为 [5,300]。

其他

该版本还进行了如下改进。

优化了底层算法能力，提升了数据同步速度。
在以下方法中新增 requestId 参数：
在 createStreamChannel 方法中新增 errorCode 参数。

问题修复

该版本修复了本地用户未调用 leave 方法直接调用 logout 方法时，偶现远端用户收不到 RTM_PRESENCE_EVENT_TYPE_REMOTE_LEAVE_CHANNEL 事件通知的问题。

该版本于 2023 年 12 月 4 日发布。这是 RTM v2 C++ SDK 的第一个版本。

本次发布意味着声网实时通讯（RTM）产品步入 v2 时代，我们在功能覆盖、性能提升、体验优化上都将为用户带来革新。

功能覆盖：该版本通过引入频道（Channel）、消息（Message）、Topic、Presence、Storage 和 Lock 等功能模块，能覆盖更多业务场景，你可以把更多的精力集中在自己的业务创新上。
性能提升：我们在新版本中重构了后台架构，通过优化网络连接进一步提升性能，提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力，让你无需为业务质量担忧。
体验优化：我们重新设计并简化了 API 接口；优化了包括用户指南、API 参考在内的所有文档，提供了更全面的示例程序，支持开发者低成本学习使用 SDK，快速完成集成，提高开发效率。

新特性

该版本提供的核心功能模块如下。

初始配置（Setup）

初始配置（Setup）是初始化生产 RTM Client 时预先定义或配置一些关键参数，影响其后续的行为。同时它还提供了登录、登出等功能。核心能力如下：

createAgoraRtmClient：创建一个 RTM Client 实例。
initialize：进行如下初始配置：
- appId：设置 App ID。相同 App ID 的 App 间可以通信，不同 App ID 的 App 相互隔离。
- userId：设置用户 ID，用以区分用户或设备。
- areaCode：设置区域代码，用于 Geo-fencing 功能。
- presenceTimeout：设置 Presence 服务的超时时间。
- context：
  - 对于 Android 操作系统，设置安卓活动上下文。
  - 对于 Windows 操作系统，设置视窗句柄。如设值，则表示支持设备热插拔。
- useStringUserId：设置用户 ID 的数据类型，可以是 String 类型，也可以是 Uint 类型。
- eventHandler：设置事件监听函数。
- logConfig：配置本地日志大小、位置、输出信息等级等参数。
- proxyConfig：配置 Proxy 服务参数。
- encryptionConfig：配置端侧加密参数。
事件监听：实现 onMessageEvent、onPresenceEvent、onTopicEvent、onStorageEvent、onLockEvent、onConnectionStateChange、onTokenPrivilegeWillExpire 等事件通知的业务逻辑。
login：登录 RTM 服务。
logout：登出 RTM 服务。
release：销毁 RTM Client 实例，释放资源。

频道（Channel）

基于声网的能力，RTM 的频道分成两种类型：Message Channel 和 Stream Channel。两种类型频道的核心能力如下：

Message Channel：
- subscribe：订阅指定 Message Channel 并开始接收频道中的消息和事件通知。
- unsubscribe：取消订阅指定 Message Channel 并停止接收频道中的消息和事件通知。
Stream Channel：
- createStreamChannel：创建 Stream Channel 实例，随后可以调用其中的方法。
- join：加入 Stream Channel，并开始接收频道中的消息和事件通知。
- leave：离开 Stream Channel，并停止接收频道中的消息和事件通知。
- release：销毁 Stream Channel 实例以释放资源。

其中：

subscribe、unsubscribe、join、leave 方法都会触发 onPresenceEvent 事件通知。频道中的其他用户会收到对应的 RTM_PRESENCE_EVENT_TYPE_REMOTE_JOIN_CHANNEL、RTM_PRESENCE_EVENT_TYPE_REMOTE_LEAVE_CHANNEL 事件通知。
调用 subscribe 和 join 操作订阅或加入频道的时候，可以选择是否配置 withMessage、withPresence、withMetadata、withLock 等参数以开启对应事件通知的监听功能。如果开启，你同时也需要注册对应事件监听，才能顺利收到对应事件通知。

消息（Message）

RTM 的基础是发送消息的能力，你可以随时随地向频道中发送消息，消息会在 100 毫秒内传递到任何地方。RTM 支持 String 类型和 Byte 类型的消息负载。

Topic

joinTopic：注册成为此 Topic 的消息发布者（publisher）。注册后，该用户会具备发送消息的能力。
publishTopicMessage：向 Stream Channel 中的 Topic 发送消息。
leaveTopic：取消注册为该 Topic 的消息发布者。
subscribeTopic：订阅该频道中 Topic 的一名或多名消息发布者。
unsubscribeTopic：取消订阅该 Topic 或取消订阅该 Topic 中指定的一名或多名消息发布者。

信息

Topic 特性只在 Stream Channel 中有效，Message Channel 中不存在此特性。

在线状态

Presence 提供监控用户在线状态及临时状态变化的能力。通过 Presence 功能，你可以实时获取以下信息：

用户加入或离开频道的实时状态
订阅或加入同一频道的所有用户的实时状态
一个用户订阅或加入的所有频道的实时信息
自定义临时用户状态及其变更信息

在 Message Channel 和 Stream Channel 中均可使用以下 Presence 功能：

whoNow：实时获取指定频道的在线用户数量、在线用户列表、在线用户的临时状态等信息。
whereNow：实时获取指定用户所在频道的列表。
setState：设置用户在指定频道的临时状态。
getState：获取用户在指定频道的临时状态。
removeState：删除用户在特定频道的临时状态。

存储

RTM 的 Storage 功能提供了一套动态数据库机制，可以让开发者动态设置、存储、更新、删除 Channel Metadata 和 User Metadata 等数据，并监听由 Channel Metadata 或 User Metadata 变更而产生的事件通知。调用 createMetadata 创建 Metadata 后，你可以根据实际需求对 Channel Metadata 和 User Metadata 进行操作。

Channel Metadata

setChannelMetadata：为指定频道设置 Channel Metadata 或 Channel Metadata Item。
getChannelMetadata：获取指定频道的 Channel Metadata 和 Channel Metadata Item。
removeChannelMetadata：删除指定频道的 Channel Metadata 或 Channel Metadata Item。
updateChannelMetadata：更新指定频道已有 Channel Metadata 或 Channel Metadata Item。

User Metadata

setUserMetadata：设置指定用户的 User Metadata 或 User Metadata Item。
getUserMetadata：获取指定用户的 User Metadata 和 User Metadata Item。
removeUserMetadata：删除指定用户的 User Metadata 或 User Metadata Item。
updateUserMetadata：更新指定用户已存在的 User Metadata 或 User Metadata Item。
subscribeUserMetadata：订阅指定用户的 User Metadata 或 User Metadata Item 变更事件通知。
unsubscribeUserMetadata：取消订阅指定用户的 User Metadata 或 User Metadata Item 事件通知。

CAS 控制

通过 Metadata 中的 setMajorRevision 方法设置 revision 属性开启整组 Channel Metadata 的版本号校验。
通过 MetadataItem 中的 revision 属性开启某个 Metadata Item 的版本号校验。

设置、删除、更新 Channel Metadata 或 User Metadata 时，配合 revision 参数可以控制本次调用是否开启 Revision 校验，逻辑如下：

revision 为 -1 时，本次调用不开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则该 Metadata 或 Metadata Item 会被最新值覆盖；如果 Metadata 或 Metadata Item 不存在，则会创建对应的 Metadata 或 Metadata Item。
revision 为 Uint64 正整数时，本次调用开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则 SDK 会在版本号验证成功后更新对应的值；如果 Metadata 或 Metadata Item 不存在，则 SDK 会返回错误码。

锁

setLock：为指定频道设置锁。
acquireLock：获取指定频道中指定的锁。
releaseLock：释放指定频道中指定的锁。
revokeLock：撤销指定频道中某个用户对此锁的占用权限以释放此锁。
getLocks：获取指定频道中所有锁的详情。
removeLock：删除指定频道中指定的锁。

频道中锁的设置、获取、释放、撤销和删除操作都会上报对应的 onLockEvent 事件通知。你可以充分利用此特性优化业务的实现逻辑。

本文提供 RTM v2 SDK 的发版说明。

已知问题和局限性

自 2.2.0 起，RTM SDK 和 RTC SDK（4.3.0 及以上版本）都包含 aosl.xframework 库。如果你同时使用了 RTM 和 RTC SDK，为避免冲突，需进行如下操作：

如果你通过 CDN 手动集成 SDK，请手动删除更低版本的 aosl.xframework 库；
如果你使用依赖管理工具（如 Maven 或 CocoaPods）集成 SDK，请确保在项目中引入更高版本的 aosl.xframework 库。

具体的集成指南可以参考如何处理同时集成 RTM SDK 和 RTC SDK 遇到的问题？

2.3.0 RTM SDK aosl.xframework 库版本为 1.3.5。
2.2.8 RTM SDK aosl.xframework 库版本为 1.3.0。
2.2.7 RTM SDK aosl.xframework 库版本为 1.3.0。
2.2.3、2.2.4、2.2.5、2.2.6 RTM SDK aosl.xframework 库版本为 1.2.13。
2.2.2 RTM SDK aosl.xframework 库版本为 1.0.11。

该版本于 2026 年 7 月 28 日发布。

升级必看

移除旧连接状态回调

该版本移除旧连接状态回调。监听连接状态变化时，请改用 didReceiveLinkStateEvent。

Presence 服务支持控制台开关

声网控制台支持开启或关闭 Presence 服务，该开关默认开启。只有在控制台中开启 Presence 服务后，Presence 相关配置项和 API 调用才会生效。

新增错误码

该版本新增以下错误码：

presenceInactive (-13014)：Presence 服务未开启或当前不可用。
presencePendingRequestCancelled (-13015)：Presence 待处理请求已取消。
presencePendingRequestExceedLimitation (-13016)：Presence 待处理请求数量超过限制。
channelSubscribeCanceled (-11040)：频道订阅尚未完成时被取消。

其它改进

优化控制台创建项目时的体验流程，取消在创建通用项目时配置服务区域，改为在功能配置中开启。
优化登录后的 Presence 查询可用性。调用 login 成功后，如果 Presence 服务仍在准备，SDK 会暂时等待并在服务可用后自动执行 whoNow、whereNow 和远端用户 getState 查询。应用无需增加固定延迟或通过临时订阅判断服务是否就绪，现有异步结果处理方式保持不变。
优化大规模频道中的 Presence 成员同步。当频道在线人数超过 512 人时，SDK 会自动采用大频道优化策略，以最多 512 名成员为持续同步的明细范围，并通过 AgoraRtmPresenceEvent.interval.totalOccupancy 提供频道总在线人数。应用仍可通过 whoNow 分页查询完整在线成员，并可按需查询远端用户状态；无需新增模式切换代码。
加快订阅频道的速度。
登录服务后如果发生异常断开，异常断开期间发起的订阅请求会在连接恢复后重新发送。
优化了部分配置参数的使用方式。

问题修复

修复了未登录情况下切到后台，可能导致连接状态通知不正确的问题。
修复了网络切换场景下重新连接服务耗时较长的问题。

变更后（v2.2.7 及之后）	变更前（v2.2.6 及之前）
Ruby `platform :ios, '11.0' target 'Your App' do # ... pod 'ShengwangRtm', 'x.y.z' end`	Ruby `platform :ios, '11.0' target 'Your App' do # ... pod 'AgoraRtm', 'x.y.z' end`

该版本于 2024 年 11 月 6 日发布。这是 RTM v2 Swift SDK 的第一个版本。

本次发布意味着声网实时通讯（RTM）产品步入 v2 时代，我们在功能覆盖、性能提升、体验优化上都将为用户带来革新。

功能覆盖：该版本通过引入频道（Channel）、消息（Message）、Topic、Presence、Storage 和 Lock 等功能模块，能覆盖更多业务场景，你可以把更多的精力集中在自己的业务创新上。
性能提升：我们在新版本中重构了后台架构，通过优化网络连接进一步提升性能，提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力，让你无需为业务质量担忧。
体验优化：我们重新设计并简化了 API 接口；优化了包括用户指南、API 参考在内的所有文档，提供了更全面的示例程序，支持开发者低成本学习使用 SDK，快速完成集成，提高开发效率。

新特性

该版本提供的核心功能模块如下。

初始配置（Setup）

初始配置（Setup）是初始化 RTM Client 时预先定义或配置的一些关键参数，影响其后续行为。同时，它还提供了登录、登出等功能。核心能力如下：

createAgoraRtmClient：创建一个 RTM Client 实例，并进行如下初始配置：
- appId：设置 App ID。相同 App ID 的 App 间可以通信，不同 App ID 的 App 相互隔离。
- userId：设置用户 ID，用以区分用户或设备。
- areaCode：设置区域代码，用于 Geo-fencing 功能。
- presenceTimeout：设置 Presence 服务的超时时间。
- useStringUserId：设置用户 ID 的数据类型，可以是 String 类型，也可以是 Uint 类型。
- logConfig：配置本地日志大小、位置、输出信息等级等参数。
- proxyConfig：配置 Proxy 服务参数。
- encryptionConfig：配置端侧加密参数。
事件监听：实现 onMessageEvent、onPresenceEvent、onTopicEvent、onStorageEvent、onLockEvent、connectionStateChanged、onTokenPrivilegeWillExpire 等事件通知的业务逻辑。
login：登录 RTM 服务。
logout：登出 RTM 服务。
destroy：销毁 RTM Client 实例，释放资源。

频道（Channel）

基于声网的能力，RTM 的频道分成两种类型：Message Channel 和 Stream Channel。两种类型频道的核心能力如下：

Message Channel：
- subscribe：订阅指定 Message Channel 并开始接收频道中的消息和事件通知。
- unsubscribe：取消订阅指定 Message Channel 并停止接收频道中的消息和事件通知。
Stream Channel：
- createStreamChannel：创建 Stream Channel 实例，随后可以调用其中的方法。
- join：加入 Stream Channel，并开始接收频道中的消息和事件通知。
- leave：离开 Stream Channel，并停止接收频道中的消息和事件通知。
- destroy：销毁 Stream Channel 实例以释放资源。

其中：

subscribe、unsubscribe、join、leave 方法都会触发 onPresenceEvent 事件通知。频道中的其他用户会收到对应的 Join、Leave 事件通知。
调用 subscribe 和 join 操作订阅或加入频道的时候，可以选择是否配置 withMessage、withPresence、withMetadata、withLock 等参数以开启对应事件通知的监听功能。如果开启，你同时也需要注册对应事件监听，才能顺利收到对应事件通知。

消息（Message）

RTM 的基础是发送消息的能力，你可以随时随地向频道中发送消息，消息会在 100 毫秒内传递到任何地方。RTM 支持 String 类型和 Byte 类型的消息负载。

publish 向指定的 Message Channel 中发送消息，同时支持存储历史消息。调用 publish 会触发 onMessageEvent 事件通知，如果想要收到频道中的消息，你需要在 subscribe 的时候，设置 withMessage = true，注册并实现 onMessageEvent 事件。

Topic

joinTopic：注册成为此 Topic 的消息发布者（publisher）。注册后，该用户会具备发送消息的能力。
publishTopicMessage：向 Stream Channel 中的 Topic 发送消息。
leaveTopic：取消注册为该 Topic 的消息发布者。
subscribeTopic：订阅该频道中 Topic 的一名或多名消息发布者。
unsubscribeTopic：取消订阅该 Topic 或取消订阅该 Topic 中指定的一名或多名消息发布者。

信息

Topic 特性只在 Stream Channel 中有效，Message Channel 中不存在此特性。

在线状态

Presence 提供监控用户在线状态及临时状态变化的能力。通过 Presence 功能，你可以实时获取以下信息：

用户加入或离开频道的实时状态
订阅或加入同一频道的所有用户的实时状态
一个用户订阅或加入的所有频道的实时信息
自定义临时用户状态及其变更信息

在 Message Channel 和 Stream Channel 中均可使用以下 Presence 功能：

whoNow：实时获取指定频道的在线用户数量、在线用户列表、在线用户的临时状态等信息。
whereNow：实时获取指定用户所在频道的列表。
setState：设置用户在指定频道的临时状态。
getState：获取用户在指定频道的临时状态。
removeState：删除用户在特定频道的临时状态。

存储

Channel Metadata

setChannelMetadata：为指定频道设置 Channel Metadata 或 Channel Metadata Item。
getChannelMetadata：获取指定频道的 Channel Metadata 和 Channel Metadata Item。
removeChannelMetadata：删除指定频道的 Channel Metadata 或 Channel Metadata Item。
updateChannelMetadata：更新指定频道已有 Channel Metadata 或 Channel Metadata Item。

User Metadata

setUserMetadata：设置指定用户的 User Metadata 或 User Metadata Item。
getUserMetadata：获取指定用户的 User Metadata 和 User Metadata Item。
removeUserMetadata：删除指定用户的 User Metadata 或 User Metadata Item。
updateUserMetadata：更新指定用户已存在的 User Metadata 或 User Metadata Item。
subscribeUserMetadata：订阅指定用户的 User Metadata 或 User Metadata Item 变更事件通知。
unsubscribeUserMetadata：取消订阅指定用户的 User Metadata 或 User Metadata Item 事件通知。

CAS 控制

通过 AgoraRtmMetadata 中的 setMajorRevision 方法设置 majorRevision 属性开启整组 Channel Metadata 的版本号校验。
通过 AgoraRtmMetadataItem 中的 revision 属性开启某个 Metadata Item 的版本号校验。

设置、删除、更新 Channel Metadata 或 User Metadata 时，配合 revision 参数可以控制本次调用是否开启 Revision 校验，逻辑如下：

majorRevision 或 revision 为 -1 时，本次调用不开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则该 Metadata 或 Metadata Item 会被最新值覆盖；如果 Metadata 或 Metadata Item 不存在，则会创建对应的 Metadata 或 Metadata Item。
majorRevision 或 revision 为 Uint64 正整数时，本次调用开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在，则 SDK 会在版本号验证成功后更新对应的值；如果 Metadata 或 Metadata Item 不存在，则 SDK 会返回错误码。

锁

setLock：为指定频道设置锁。
acquireLock：获取指定频道中指定的锁。
releaseLock：释放指定频道中指定的锁。
revokeLock：撤销指定频道中某个用户对此锁的占用权限以释放此锁。
getLocks：获取指定频道中所有锁的详情。
removeLock：删除指定频道中指定的锁。

频道中锁的设置、获取、释放、撤销和删除操作都会上报对应的 onLockEvent 事件通知。你可以充分利用此特性优化业务的实现逻辑。

已知问题和局限性Copy Anchor Link

2.3.0 版

升级必看Copy Anchor Link

移除旧连接状态回调Copy Anchor Link

改进Copy Anchor Link

Presence 服务支持控制台开关Copy Anchor Link

新增错误码Copy Anchor Link

其它改进Copy Anchor Link

问题修复Copy Anchor Link

2.2.8 版

问题修复Copy Anchor Link

2.2.7 版

升级必看Copy Anchor Link

引用方式变更Copy Anchor Link

改进Copy Anchor Link

问题修复Copy Anchor Link

2.2.6 版

改进Copy Anchor Link

新增重连超时配置Copy Anchor Link

2.2.5 版

新特性Copy Anchor Link

支持 IoT 设备域名白名单Copy Anchor Link

问题修复Copy Anchor Link

2.2.4 版

2.2.3 版

改进Copy Anchor Link

新增连接状态改变原因Copy Anchor Link

新增更新 Token 超时错误码Copy Anchor Link

在线状态事件通知优化Copy Anchor Link

其它改进Copy Anchor Link

问题修复Copy Anchor Link

2.2.2 版

升级必看Copy Anchor Link

SNAPSHOT 状态触发时机变更Copy Anchor Link

锁过期时间计算规则变更Copy Anchor Link

新特性Copy Anchor Link

支持历史消息Copy Anchor Link

SDK 连接状态变化原因Copy Anchor Link

支持 16 KB 内存页大小Copy Anchor Link

改进Copy Anchor Link

问题修复Copy Anchor Link

2.2.1 版

改进Copy Anchor Link

问题修复Copy Anchor Link

2.2.0 版

升级必看Copy Anchor Link

新特性Copy Anchor Link

新增私有化部署能力Copy Anchor Link

新增心跳时间配置Copy Anchor Link

新增双环境配置Copy Anchor Link

新增用户频道类型Copy Anchor Link

新增静默模式配置Copy Anchor Link

改进Copy Anchor Link

改进连接状态管理逻辑Copy Anchor Link

改进 REMOTE_STATE_CHANGED 事件通知逻辑Copy Anchor Link

支持事件通知触发时间戳Copy Anchor Link

优化 API 行为Copy Anchor Link

修改 presenceTimeout 取值范围Copy Anchor Link

2.1.12 版

改进Copy Anchor Link

问题修复Copy Anchor Link

2.1.11 版

改进Copy Anchor Link

问题修复Copy Anchor Link

2.1.10 版

问题修复Copy Anchor Link

2.1.9 版

改进Copy Anchor Link

2.1.8 版

升级必看Copy Anchor Link

改进Copy Anchor Link

问题修复Copy Anchor Link

2.1.7 版

改进Copy Anchor Link

问题修复Copy Anchor Link

2.1.6 版

升级必看Copy Anchor Link

多访问区域设置Copy Anchor Link

RtmConfig 构造函数优化Copy Anchor Link

回调名变更Copy Anchor Link

已知问题和局限性

升级必看

移除旧连接状态回调

改进

Presence 服务支持控制台开关

新增错误码

其它改进

问题修复

问题修复

升级必看

引用方式变更

改进

问题修复

改进

新增重连超时配置

新特性

支持 IoT 设备域名白名单

问题修复

改进

新增连接状态改变原因

新增更新 Token 超时错误码

在线状态事件通知优化

其它改进

问题修复

升级必看

SNAPSHOT 状态触发时机变更

锁过期时间计算规则变更

新特性

支持历史消息

SDK 连接状态变化原因

支持 16 KB 内存页大小

改进

问题修复

改进

问题修复

升级必看

新特性

新增私有化部署能力

新增心跳时间配置

新增双环境配置

新增用户频道类型

新增静默模式配置

改进

改进连接状态管理逻辑

改进 REMOTE_STATE_CHANGED 事件通知逻辑

支持事件通知触发时间戳

优化 API 行为

修改 presenceTimeout 取值范围

改进

问题修复

改进

问题修复

问题修复

改进

升级必看

改进

问题修复

改进

问题修复

升级必看

多访问区域设置

RtmConfig 构造函数优化

回调名变更

新特性

多种事件监听方式

新结构体构造函数

改进

问题修复

新特性

初始配置（Setup）

频道（Channel）

消息（Message）

Topic

在线状态

存储

Channel Metadata

User Metadata

CAS 控制

锁