# 发版说明 (/zh-CN/realtime-media/rtm/reference/release-notes/unity) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文提供 RTM v2 SDK 的发版说明。 ## 2.1.9 版 [#219-版-3] 该版本于 2024 年 1 月 25 日发布。 ### 升级必看 [#升级必看-19] 该版本对如下内容进行了优化,请在升级到该版本后更新 App 代码。 #### 消息发送选项 [#消息发送选项] 该版本对 `PublishAsync` 和 `PublishTopicMessageAsync` 方法中的 `options` 参数进行如下优化: - 在 `PublishAsync` 方法的 `PublishOptions` 中删除了 `sendTs` 参数,并新增了 `channelType` 参数。详见 [`PublishOptions`](/zh-CN/api-reference/rtm/unity/message#options)。 - 将 `publishTopicMessage` 方法中的 `options` 参数类型由 `PublishOptions` 修改为 `TopicMessageOptions`。详见 [`TopicMessageOptions`](/zh-CN/api-reference/rtm/unity/topic#options)。 #### 连接状态回调更名 [#连接状态回调更名] 该版本将 `onConnectionStateChange` 回调名称修改为 `onConnectionStateChanged`。 ### 改进 [#改进-38] #### 错误码 [#错误码] 该版本新增了 `INVALID_CHANNEL_TYPE`、`INVALID_ENCRYPTION_PARAMETER` 和 `OPERATION_RATE_EXCEED_LIMITATION` 错误码。错误码描述及解决方法见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 #### 在线状态模块 [#在线状态模块] 该版本优化了在断线重连时对过期用户状态数据的处理逻辑,并提升了在 `JoinChannelOptions` 中设置 Presence 事件通知的性能。 #### 其他 [#其他-2] 该版本优化了内存表现并修复了潜在的内存泄漏问题。 ### 问题修复 [#问题修复-42] 该版本修复了如下问题: - 调用 `WhoNowAsync` 方法返回分页结果时偶现崩溃。 - 特定场景下,偶现 Presence 数据丢包。 - 特定场景下,方法调用后未触发异步回调。 - 使用端侧加密时,参数无效导致的崩溃。 - 当网络状态发生变化时,偶现无法登录或登出 RTM 系统。 - 网络断开后,因数据未清理导致偶现用户无法收到 `SNAPSHOT` 事件通知。 - 用户加入频道后,把 App 切到后台再切换回前台时,偶现 SDK 多次触发 `REMOTE_JOIN` 事件通知。 ## 2.1.4 版 [#214-版-3] 该版本于 2023 年 8 月 22 日发布。 ### 新特性 [#新特性-16] #### 自定义消息负载 [#自定义消息负载] 为满足用户在各类业务中对消息负载类型的不同需求,该版本提供一套收发自定义消息负载的方案: - 发送自定义消息负载:调用 `PublishAsync` 或 `PublishTopicMessageAsync` 方法并在 `customType` 参数中填写自定义消息负载类型。 - 接收自定义消息负载:通过 `OnMessageEvent` 回调的 `customType` 参数获取自定义消息负载的类型,然后根据实际业务需求进行消息反序列化等操作。 #### RtmResult`` 解构能力 [#rtmresultt-解构能力] 为方便用户在调用 API 时使用返回值,提升业务代码可读性,该版本在 API 返回值(`RtmResult`)中提供解构能力。你可以通过如下方式获取 API 调用的返回值: ```csharp 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)); } ``` ### 改进 [#改进-39] #### 错误信息扩充 [#错误信息扩充] 为提升用户排查错误的效率,该版本在 API 返回值中扩充了 `Status` 结构体的 `Reason` 字段内容,删除了 `Response` 结构体内的 `ErrorCode` 字段。你只需通过 `Status` 结构体即可获取错误码和错误描述。 #### API 简化 [#api-简化] 为提升易用性,该版本对 API 进行了简化: - 枚举和结构体命名优化:简化了所有枚举值和部分结构体的名称,例如,将 `RTM_CHANNEL_TYPE_MESSAGE` 简化为 `MESSAGE`。 - 数据类型优化: - `IntervalInfo` 结构体中 `joinUserList` 参数的类型由 `UserList` 改为 `string[]`。 - `MessageEvent` 结构体中 `message` 参数的类型由 `object` 改为 `IRtmMessage`。 - 在 `LogoutAsync` 中新增 `RtmResult` 类型的返回值。 - 删除冗余字段: - 在 `PublishOptions` 中删除了 `messageType` 字段。 - 在 `GetLocksResult`、`WhoNowResult` 等 `Result` 结构体中删除 `Count` 字段。 - 在 `TopicOptions` 结构体中删除 `userCount` 字段。 - 在 `IntervalInfo` 结构体中删除 `userStateCount` 字段。 - 在 `SnapshotInfo` 结构体中删除 `userCount` 字段。 - 在 `LockEvent` 结构体中删除 `count` 字段。 - 在 `PresenceEvent` 结构体中删除 `stateItemCount` 字段。 - 在 `TopicEvent` 结构体中删除 `topicInfoCount` 字段,并将 `userId` 参数名修改为 `publisher`。 详见 [API 参考](/zh-CN/api-reference/rtm/unity/configuration)。 ## 2.1.0-beta 版 [#210-beta-版-1] 该版本于 2023 年 4 月 27 日发布。这是 RTM v2 Unity SDK 的第一个版本。 本次发布意味着声网实时通讯(RTM)产品步入 v2 时代,我们在功能覆盖、性能提升、体验优化上都将为用户带来革新。 - 功能覆盖:该版本通过引入频道(Channel)、消息(Message)、Topic、Presence、Storage 和 Lock 等功能模块,能覆盖更多业务场景,你可以把更多的精力集中在自己的业务创新上。 - 性能提升:我们在新版本中重构了后台架构,通过优化网络连接进一步提升性能,提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力,让你无需为业务质量担忧。 - 体验优化:我们重新设计并简化了 API 接口,支持业界最流行的 Async/Await 编程模式;优化了包括用户指南、API 参考在内的所有文档,提供了更全面的示例程序,支持开发者低成本学习使用 SDK,快速完成集成,提高开发效率。 ### 新特性 [#新特性-17] 该版本提供的核心功能模块如下。 :::info[信息] RTM 2.1.0-beta 目前处于 Public Beta 阶段,某些功能细节可能会在随后的版本中发生改变,以提升用户体验。 ::: #### 初始配置(Setup) [#初始配置setup-4] 初始配置(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) [#频道channel-4] 频道是 RTM 实时网络中一种数据传输的管理机制,任何订阅或加入频道的用户都可以在 100 毫秒内接收到频道中传输的消息和事件,RTM 允许客户端订阅数百甚至数千个频道。大多数 RTM API 都将以频道为基础进行发送、接收、加密等行为。 基于声网的能力,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) [#消息message-4] RTM 的基础是发送消息的能力,你可以随时随地向频道中发送消息,消息会在 100 毫秒内传递到任何地方。RTM 支持 String 类型和 Binary 类型的消息负载。 `PublishAsync` 向指定的 Message Channel 中发送消息。调用 `PublishAsync` 会触发 `OnMessageEvent` 事件通知,如果想要收到频道中的消息,你需要在 `SubscribeAsync` 的时候,设置 `withMessage = true`,注册并实现 `OnMessageEvent` 事件。 #### Topic [#topic-4] Topic 是 Stream Channel 中的数据流管理机制。你可以在 Stream Channel 中利用此特性进行数据流的订阅、分发、事件通知等,灵活使用 Topic 能力,能大大降低业务复杂度,提升开发效率。Topic 的主要功能如下: - `JoinTopicAsync`:注册成为此 Topic 的消息发布者(publisher)。注册后,该用户会具备发送消息的能力。 - `PublishTopicMessageAsync`:向 Stream Channel 中的 Topic 发送消息。 - `LeaveTopicAsync`: 取消注册为该 Topic 的消息发布者。 - `SubscribeTopicAsync`:订阅该频道中 Topic 的一名或多名消息发布者。 - `UnsubscribeTopicAsync`:取消订阅该 Topic 或取消订阅该 Topic 中指定的一名或多名消息发布者。 注册(`JoinTopicAsync`)或取消注册(`LeaveTopicAsync`)消息发布者操作,会触发 `OnTopicEvent` 事件通知,频道中的其他用户将会收到此事件通知。 :::info[信息] Topic 特性只在 Stream Channel 中有效,Message Channel 中不存在此特性。 ::: #### 在线状态 [#在线状态-4] Presence 提供监控用户在线状态及临时状态变化的能力。通过 Presence 功能,你可以实时获取以下信息: - 用户加入或离开频道的实时状态 - 订阅或加入同一频道的所有用户的实时状态 - 一个用户订阅或加入的所有频道的实时信息 - 自定义临时用户状态及其变更信息 在 Message Channel 和 Stream Channel 中均可使用以下 Presence 功能: - `WhoNowAsync`:实时获取指定频道的在线用户数量、在线用户列表、在线用户的临时状态等信息。 - `WhereNowAsync`:实时获取指定用户所在频道的列表。 - `SetStateAsync`:设置用户在指定频道的临时状态。 - `GetStateAsync`:获取用户在指定频道的临时状态。 - `RemoveStateAsync`:删除用户在特定频道的临时状态。 Presence 在提供上述功能的同时,也提供了 `OnPresenceEvent` 事件通知能力。频道中用户的加入、离开、掉线、用户状态设置、用户状态删除等事件都会以实时通知(Announce Mode)或定时通知(Interval Mode)的方式通知到频道中的其他用户。Presence 能力将大大简化开发者业务中关于在线用户上下线、状态变更等状态的同步逻辑实现,充分利用此特性将使得你的业务实现更稳定、实时、可靠。 #### 存储 [#存储-4] RTM 的 Storage 功能提供了一套动态数据库机制,可以让开发者动态设置、存储、更新、删除 Channel Metadata 和 User Metadata 等数据,并监听由 Channel Metadata 或 User Metadata 变更而产生的事件通知。 ##### Channel Metadata [#channel-metadata-4] - `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 的全量信息,我们将在后续版本中优化,提供性能更优的增量更新能力。 Channel Metadata 同时也引入了 Lock 的控制能力,当调用 API 设置、删除、更新 Channel Metadata 时,如果参数中的 `lockName` 被设置,则开启 Lock 的校验,此时只有拥有此锁的用户才被允许成功调用对应的方法。 ##### User Metadata [#user-metadata-4] - `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 控制 [#cas-控制-4] 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` 为 Int64 正整数时,本次调用开启 CAS 验证。如果 Metadata 或 Metadata Item 已存在,则 SDK 会在版本号验证成功后更新对应的值;如果 Metadata 或 Metadata Item 不存在,则 SDK 会返回错误码。 #### 锁 [#锁-4] 临界资源一次只能供一个进程使用,如果不同的进程之间共享了某个临界资源,则各进程需要采取互斥的方式来防止彼此干扰。RTM 提供一整套 Lock 的方案,通过控制分布式系统的不同进程,你可以解决用户在访问共享资源时的竞争问题。Lock 为你提供了以下能力: - `SetLockAsync`:为指定频道设置锁。 - `AcquireLockAsync`:获取指定频道中指定的锁。 - `ReleaseLockAsync`: 释放指定频道中指定的锁。 - `RevokeLockAsync`: 撤销指定频道中某个用户对此锁的占用权限以释放此锁。 - `GetLocksAsync`: 获取指定频道中所有锁的详情。 - `RemoveLockAsync`:删除指定频道中指定的锁。 频道中锁的设置、获取、释放、撤销和删除操作都会上报对应的 `OnLockEvent` 事件通知。你可以充分利用此特性优化业务的实现逻辑。