发版说明
本文提供 RTM v2 SDK 的发版说明。
2.2.0 版
该版本于 2024 年 8 月 29 日发布。
该版本在 RTMConfig 中删除了 token 参数，并在 login 方法中新增了 token 参数作为替代，你需要在升级后修改你的实现代码：
// 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);
}
// 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 回调，以便更好地管理连接状态。详见连接管理。
该版本改进了 Presence 功能的 REMOTE_STATE_CHANGED 事件的触发逻辑，即当用户一次设置或修改多个 key-value 时，频道内其他用户只会接收到一次事件通知。
该版本在如下回调中新增 timestamp 参数，报告触发事件通知的时间戳：
messagepresencetopicstoragelock
该版本优化了以下 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。
- 在之前版本中，不支持连续多次调用该方法，也不支持在该方法的
该版本将 RTMConfig 中 presenceTimeout 参数的取值范围由 [10,300] 修改为 [5,300]。
该版本还进行了如下优化：
- 优化了底层算法能力，提升了数据同步速度。
- 支持本地用户在发送消息时，可以收到自己发送的消息的事件通知，方便在调试阶段验证消息的收发。
- 在所有方法的 Response 对象中删除了无效的
timeToken参数。
2.1.10 版
该版本于 2024 年 6 月 11 日发布。
该版本优化了 login 调用失败的错误码提示。例如，开启了 Token 鉴权但使用 App ID 进行初始化，登录时会报错 RTM_ERROR_INVALID_TOKEN (-10005)。
该版本修复了如下问题：
- 频繁设置和获取锁的场景下，偶现
lock事件通知不准确。 - 断线重连后，调用
subscribe方法偶现 Presence 服务初始化失败。 - 使用 Vite 框架开发的 App，偶现收不到消息。
- 加入频道后断线重连，无法收到
lock和storage事件通知。 - 更新 User Metadata 时，偶现重复收到
UPDATE类型的storage事件通知。 - 删除锁时，偶现重复收到
REMOVED类型的lock事件通知。
2.1.9 版
该版本于 2024 年 3 月 8 日发布。
该版本修复了 messageEvent 回调的 messageType 参数类型。
2.1.8 版
该版本于 2024 年 2 月 29 日发布。
该版本优化了端侧加密的逻辑，当填入的 salt 长度不足 32 字节时，SDK 会自动加 0 补齐长度。
该版本修复了如下问题：
- 调用
renewToken刷新 Token，因部分服务未生效而导致非预期的连接断开。 - 掉线时长超过
presenceTimeout的设置值时，status事件通知报告的reason值有误。 - 弱网条件下，偶现无法恢复订阅 Lock 和 Storage 服务。
- 特定场景下，调用
acquireLock方法无法返回调用结果。 - 本地用户离开自己加入的最后一个 Topic 时，偶现远端用户收到
REMOTE_JOIN和REMOTE_LEAVE两个 Topic 事件。
2.1.7 版
该版本于 2024 年 1 月 9 日发布。
该版本进行了如下改进：
- 优化了在断线重连时对过期用户状态数据的处理逻辑。
- 提升了弱网条件下 Stream Channel 中消息传输的可靠性。
该版本修复了如下问题：
- 调用
whoNow方法并设置includedUserId = true、includedState = false时，返回值中缺少nextPage参数。 - 在随机订阅 Topic 的情况下，用户在
message事件通知中的收到的publisher和实际消息发送者不一致。 - 重复订阅同一频道后，取消订阅或离开该频道失败。
2.1.6 版
该版本于 2023 年 12 月 4 日发布。
该版本修复了如下问题：
- 加入频道时设置
withPresence为false，调用whoNow方法无法获取下一页的结果。 - 使用默认参数加入频道时，用户临时状态混乱。
2.1.5 版
该版本于 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 中传入中文等特殊字符时，消息发送到远端会被截断。
2.1.4 版
该版本于 2023 年 8 月 31 日发布。
该版本改变了事件监听程序的书写方式。升级至该版本后，你需要参考以下示例修改你的实现代码：
- v2.1.4 之前的方式：
rtmClient.addEventListener({
message: msgEvent => {
// message 事件通知的处理逻辑
},
presence: presenceEvent => {
// presence 事件通知的处理逻辑
},
// 添加其他事件通知
});
- v2.1.4 的方式：
rtmClient.addEventListener("message", msgEvent => {
// message 事件通知的处理逻辑
});
rtmClient.addEventListener("presence", presenceEvent => {
// presence 事件通知的处理逻辑
});
// 添加其他事件通知
该版本缩短了 logout 方法的响应时间。
该版本修复了如下问题：
- 日志中丢失了 SDK 版本信息。
- 调用
getState方法获取的GetStateResponse中userId字段为空字符串。 - 调用
removeState方法后，在执行删除操作之前就返回了RemoveStateResponse。
2.1.3 版
该版本于 2023 年 7 月 13 日发布。
修复了 Cloud Proxy 无法登录的问题。
2.1.2 版
该版本于 2023 年 6 月 30 日发布。
修复了 AreaCode 默认设置导致的 US/ROW 区域服务不可用的问题。
2.1.0-beta 版
该版本于 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）是初始化生产 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 服务。
频道是 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，并停止接收频道中的消息和事件通知。
其中：
subscribe、unsubscribe、join、leave方法都会触发presence事件通知。频道中的其他用户会收到对应的Join、Leave事件通知。- 调用
subscribe和join操作订阅或加入频道的时候，可以选择是否配置withMessage、withPresence、withMetadata、withLock等参数以开启对应事件通知的监听功能。如果开启，你同时也需要注册对应事件监听，才能顺利收到对应事件通知。
RTM 的基础是发送消息的能力，你可以随时随地向频道中发送消息，消息会在 100 毫秒内传递到任何地方。RTM 支持 String 类型和 Binary 类型的消息负载。
publish 向指定的 Message Channel 中发送消息。调用 publish 会触发 message 事件通知，如果想要收到频道中的消息，你需要在 subscribe 的时候，设置 withMessage = true，注册并实现 message 事件。
Topic 是 Stream Channel 中的数据流管理机制。你可以在 Stream Channel 中利用此特性进行数据流的订阅、分发、事件通知等，灵活使用 Topic 能力，能大大降低业务复杂度，提升开发效率。Topic 的主要功能如下：
joinTopic：注册成为此 Topic 的消息发布者（publisher）。注册后，该用户会具备发送消息的能力。publishTopicMessage：向 Stream Channel 中的 Topic 发送消息。leaveTopic： 取消注册为该 Topic 的消息发布者。subscribeTopic：订阅该频道中 Topic 的一名或多名消息发布者。unsubscribeTopic：取消订阅该 Topic 或取消订阅该 Topic 中指定的一名或多名消息发布者。
注册（joinTopic）或取消注册（leaveTopic）消息发布者操作，会触发 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 能力将大大简化开发者业务中关于在线用户上下线、状态变更等状态的同步逻辑实现，充分利用此特性将使得你的业务实现更稳定、实时、可靠。
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 的设置、删除和更新都会触发 storage 事件通知，合理使用此特性可以极大的优化业务逻辑，获得优异的用户体验。当前 storage 事件通知中携带的是当前 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 的设置、删除和更新都会触发 storage 事件通知，所有订阅此 User Metadata 的其他用户将会收到事件通知，合理使用此特性可以极大的优化业务逻辑，获得优异的用户体验。当前 storage 事件通知中携带的是所订阅 User Metadata 的全量信息，我们将在后续的版本中优化，提供性能更优的增量更新能力。
CAS 控制
Channel Metadata 和 User Metadata 都引进了版本控制逻辑 CAS（Compare And Set），该方法提供两种独立的版本控制字段，你可以根据实际业务场景设置任意一种或多种：
- 通过
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 会返回错误码。
临界资源一次只能供一个进程使用，如果不同的进程之间共享了某个临界资源，则各进程需要采取互斥的方式来防止彼此干扰。RTM 提供一整套 Lock 的方案，通过控制分布式系统的不同进程，你可以解决用户在访问共享资源时的竞争问题。Lock 为你提供了以下能力：
setLock：为指定频道设置锁。acquireLock：获取指定频道中指定的锁。releaseLock： 释放指定频道中指定的锁。revokeLock： 撤销指定频道中某个用户对此锁的占用权限以释放此锁。getLock： 获取指定频道中所有锁的详情。removeLock：删除指定频道中指定的锁。
频道中锁的设置、获取、释放、撤销和删除操作都会上报对应的 lock 事件通知。你可以充分利用此特性优化业务的实现逻辑。