# 发版说明 (/zh-CN/realtime-media/rtm/reference/release-notes/ios) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文提供 RTM v2 SDK 的发版说明。 ### 已知问题和局限性 [#已知问题和局限性-1] 自 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 遇到的问题?](/zh-CN/reference/faq/integration/rtm2_rtc_integration_issue) - 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。 ## 2.3.1 版 [#231-版-ios] 发布日期:2026 年 11 月 17 日。 ### 升级必看 [#rtm-ios-231-升级必看] #### SDK 引用方式变更 [#rtm-ios-231-SDK-引用方式变更] 自 v2.3.1 起,通过 CocoaPods 集成 RTM SDK 时,需要在 `Podfile` 中添加 `source 'https://download.shengwang.cn/cocoapods/'`,并保留项目已有的源。SDK 依赖包名仍为 `ShengWang-Rtm`,版本更新为 `2.3.1`。分别通过 `RtmKit` 和 `RtmBasic` 引入 RTM 主库和 aosl 基础库: ```ruby pod 'ShengWang-Rtm', '2.3.1', :subspecs => ['RtmKit'] pod 'ShengWang-Rtm', '2.3.1', :subspecs => ['RtmBasic'] ``` 具体配置见[实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start)。 ### 新特性 [#rtm-ios-231-新特性] #### 查询用户在线状态 [#rtm-ios-231-查询用户在线状态] 新增 [`getUserOnlineStatus`](/zh-CN/api-reference/rtm/ios/presence#getUserOnlineStatus),用于按单个精确 User ID 查询当前 App ID 下的用户是否存在有效的 RTM 登录连接。查询方和目标用户都无需加入或订阅频道。调用方须具有可用的 MESSAGE service 且 MESSAGE session 已连接;该查询不依赖 Presence 服务开关或 Sync Database 就绪。 成功结果包含 `userId` 和 `online`。目标离线或不存在时返回成功结果 `online=false`;调用失败通过对应平台的错误处理机制返回。结果是服务端响应时刻的状态快照,不提供在线状态变更订阅。具体流程见[查询用户在线状态](/zh-CN/realtime-media/rtm/build/state-and-attributes/presence-basic/ios#query-user-online-status-ios)。 ### 接口变更 [#rtm-ios-231-接口变更] - 新增 [`getUserOnlineStatus`](/zh-CN/api-reference/rtm/ios/presence#getUserOnlineStatus) 方法。 - 新增 [`AgoraRtmUserOnlineStatus`](/zh-CN/api-reference/rtm/ios/presence#AgoraRtmUserOnlineStatus) 结果类型。 - 新增 [`AgoraRtmGetUserOnlineStatusBlock`](/zh-CN/api-reference/rtm/ios/presence#AgoraRtmGetUserOnlineStatusBlock) completion 回调类型。 ### 问题修复 [#rtm-ios-231-问题修复] - 修复多链路交错断连,可能无法完全恢复服务的问题。 - 修复断网恢复后,对已有频道执行重订阅可能引发崩溃的问题。 ## 2.3.0 版 [#230-版-1] 该版本于 2026 年 7 月 28 日发布。 ### 升级必看 [#升级必看-6] #### 移除旧连接状态回调 [#移除旧连接状态回调-1] 该版本移除旧连接状态回调。监听连接状态变化时,请改用 `didReceiveLinkStateEvent`。 ### 改进 [#改进-13] #### Presence 服务支持控制台开关 [#presence-服务支持控制台开关-1] 声网控制台支持开启或关闭 Presence 服务,该开关默认开启。只有在控制台中开启 Presence 服务后,Presence 相关配置项和 API 调用才会生效。 #### 新增错误码 [#新增错误码-1] 该版本新增以下错误码: - `AgoraRtmErrorPresenceInactive` (-13014):Presence 服务未开启或当前不可用。 - `AgoraRtmErrorPresencePendingRequestCancelled` (-13015):Presence 待处理请求已取消。 - `AgoraRtmErrorPresencePendingRequestExceedLimitation` (-13016):Presence 待处理请求数量超过限制。 - `AgoraRtmErrorChannelSubscribeCanceled` (-11040):频道订阅尚未完成时被取消。 #### 其它改进 [#其它改进-2] - 优化控制台创建项目时的体验流程,取消在创建通用项目时配置服务区域,改为在功能配置中开启。 - 优化登录后的 Presence 查询可用性。调用 `login` 成功后,如果 Presence 服务仍在准备,SDK 会暂时等待并在服务可用后自动执行 `whoNow`、`whereNow` 和远端用户 `getState` 查询。应用无需增加固定延迟或通过临时订阅判断服务是否就绪,现有异步结果处理方式保持不变。 - 优化大规模频道中的 Presence 成员同步。当频道在线人数超过 512 人时,SDK 会自动采用大频道优化策略,以最多 512 名成员为持续同步的明细范围,并通过 `AgoraRtmPresenceEvent.interval.totalOccupancy` 提供频道总在线人数。应用仍可通过 `whoNow` 分页查询完整在线成员,并可按需查询远端用户状态;无需新增模式切换代码。 - 加快订阅频道的速度。 - 登录服务后如果发生异常断开,异常断开期间发起的订阅请求会在连接恢复后重新发送。 - 优化了部分配置参数的使用方式。 ### 问题修复 [#问题修复-13] - 修复了未登录情况下切到后台,可能导致连接状态通知不正确的问题。 - 修复了网络切换场景下重新连接服务耗时较长的问题。 ## 2.2.8 版 [#228-版-1] 该版本于 2026 年 2 月 12 日发布。 ### 问题修复 [#问题修复-14] - 修复部分场景下,App 从后台恢复并叠加网络切换时,可能导致服务连接状态异常的问题。 - 修复部分场景下,设置 [`Presence`](/zh-CN/api-reference/rtm/ios/presence) 的临时用户状态后,事件通知无法正常下发的问题。 ## 2.2.7 版 [#227-版-1] 该版本于 2025 年 12 月 12 日发布。 ### 升级必看 [#升级必看-7] #### SDK 引用方式变更 [#sdk-引用方式变更] 从 v2.2.7 起,如果你使用 CocoaPods 将 RTM SDK 导入到项目中,则 `Podfile` 文件中引入 SDK 的代码需要进行如下变更: | 变更后(v2.2.7 及之后) | 变更前(v2.2.6 及之前) | | --- | --- | | [release-notes-ios-html-0-1-0 details](#table-slot-release-notes-ios-html-0-1-0) | [release-notes-ios-html-0-1-1 details](#table-slot-release-notes-ios-html-0-1-1) | **release-notes-ios-html-0-1-0 details** ```ruby platform :ios, '11.0' target 'Your App' do # ... // highlight-start pod 'ShengwangRtm', 'x.y.z' // highlight-end end ``` **release-notes-ios-html-0-1-1 details** ```ruby platform :ios, '11.0' target 'Your App' do # ... // highlight-start pod 'AgoraRtm', 'x.y.z' // highlight-end end ``` 详细集成步骤可以参考[快速开始](/zh-CN/realtime-media/rtm/get-started/quick-start)。 在同时集成了 RTC SDK v4.3.0 及以上版本的场景中,RTM 轻量库的引入代码方式详见 [FAQ](/zh-CN/reference/faq/integration/rtm2_rtc_integration_issue)。 ### 改进 [#改进-14] - 该版本在 [`AgoraRtmClientConfig`](/zh-CN/api-reference/rtm/ios/configuration#agorartmclientconfig) 中新增 `callbackQueue` 参数,支持对回调所在的线程进行设置。 - 优化了登录操作 (`loginByToken`) 的响应机制。 ### 问题修复 [#问题修复-15] - 修复了某些极端情况下,调整设备时钟可能触发 SDK 进入重连状态的问题。 - 修复了在长时间和 RTM 服务断开的情况下,重新连接后,自身所在频道的 Presence 状态可能出现异常的问题。 ## 2.2.6 版 [#226-版-1] 该版本于 2025 年 10 月 31 日发布。 ### 改进 [#改进-15] #### 新增重连超时配置 [#新增重连超时配置-1] 该版本在 [`AgoraRtmClientConfig`](/zh-CN/api-reference/rtm/ios/configuration#rtmconfig) 中增加 `reconnectTimeout` 字段。你可以通过该字段配置 SDK 在登录或断线重连时,返回超时错误的时间,单位为秒。当登录或重连超过设置的时间,SDK 会通过回调报告当前的连接状态和原因。 ## 2.2.5 版 [#225-版-1] 该版本于 2025 年 7 月 1 日发布。 ### 新特性 [#新特性-5] #### 支持 IoT 设备域名白名单 [#支持-iot-设备域名白名单-1] 在 IoT 场景下,设备可能受限于互联网服务提供商 (ISP)。为解决这一限制,该版本在 [`AgoraRtmClientConfig`](/zh-CN/api-reference/rtm/ios/configuration#rtmconfig) 中增加 `ispPolicyEnabled` 字段。通过将该字段设为 `true`,SDK 会仅连接到已向运营商报备的域名或 IP 白名单中的服务器。 ### 问题修复 [#问题修复-16] - 某些场景下,Token 过期的通知可能被多次触发。 - 某些场景下,点对点消息已送达对端,但发送端却反馈超时。 - 某些场景下,iOS 系统在退出 App 时,可能引起 RTM SDK 崩溃的问题。 - 私有化场景下,频繁切换网络可能造成连接状态异常。 ## 2.2.4 版 [#224-版-1] 该版本于 2025 年 4 月 1 日发布。主要改动点如下: - 进一步优化了登录服务的时长。 - 修复了回调函数中,如果业务代码存在未捕获的异常,可能引起 SDK 崩溃的问题。 - 修复了订阅 Topic 时,可能返回未加入频道的问题。 ## 2.2.3 版 [#223-版-1] 该版本于 2025 年 3 月 21 日发布。 ### 升级必看 [#升级必看-8] 从该版本起,RTM SDK 支持通过 SPM (Swift Package Manager) 集成 SDK。你可以选择该方式进行集成,详见[安装 SDK](/zh-CN/realtime-media/rtm/build/rtm-initialization/application-setup#安装-sdk)。 ### 改进 [#改进-16] #### 新增连接状态改变原因 [#新增连接状态改变原因-1] 该版本在 AgoraRtmLinkStateChangeReason 中增加原因 AgoraRtmLinkStateChangeReasonLoginTooFrequent (37),表示当前登录操作过于频繁。 #### 新增更新 Token 超时错误码 [#新增更新-token-超时错误码-1] 为反馈更新 Token 操作的结果,该版本新增错误码 AgoraRtmErrorRenewTokenTimeout (10026)。 #### 在线状态事件通知优化 [#在线状态事件通知优化-1] 当频道数据无法正常同步时,SDK 会重新触发一次 AgoraRtmPresenceEventTypeSnapshot 事件。收到该事件后,用户可以更新自己 App 的本地缓存。 #### 其它改进 [#其它改进-3] - 加快了切后台或休眠后,RTM 服务恢复重连的速度。 - 优化了 SDK 在弱网情况下的表现。 - 优化了接入节点的选择,提升了服务的连接速度。 ### 问题修复 [#问题修复-17] - 重连时偶现订阅服务未恢复。 - 部分频道内用户查询结果时,可能包含异常离线用户的信息。 ## 2.2.2 版 [#222-版-1] 该版本于 2024 年 11 月 6 日发布。 ### 升级必看 [#升级必看-9] #### SNAPSHOT 状态触发时机变更 [#snapshot-状态触发时机变更-1] 该版本修订了 Presence 事件中 `SNAPSHOT` 事件的触发时机。现在,只要用户在频道内,就可能会再次收到 `SNAPSHOT` 事件;收到后,用户可以更新自己的全量信息,来避免因异常导致的状态不同步问题。 #### 锁过期时间计算规则变更 [#锁过期时间计算规则变更-1] 该版本修改了锁(Lock)过期时间的计算规则。该版本起,锁的过期时间将从服务端判定用户离线开始计算。 ### 新特性 [#新特性-6] #### 支持历史消息 [#支持历史消息-1] 该版本在 AgoraRtmPublishOptions 中新增了 `storeInHistory` 属性,支持在频道中发送消息的同时,将消息存储到云端,后续用户可以通过历史消息接口获取。 :::info[信息] 该功能目前处于 Public Beta 阶段。如需使用,需要前往[控制台](https://console.shengwang.cn/product/RTM2?tab=config)开启。 ::: #### SDK 连接状态变化原因 [#sdk-连接状态变化原因-1] 该版本在 SDK 连接状态 `LinkStateEvent` 中添加 AgoraRtmLinkStateChangeReason 枚举类,报告连接状态变更的原因。 ### 改进 [#改进-17] 该版本提升了基础消息服务在服务异常时的业务表现,避免因部分服务出现异常,导致的消息服务不可用的问题。 ### 问题修复 [#问题修复-18] 该版本修复了如下问题: - 某些场景下,Token 类型不正确导致异常错误。 - 某些场景下,用户可能多次收到相同离线用户的离线通知。 - 相同用户 ID 在不同端登录后,可能出现连接状态异常。 - 频繁设置 Presence 状态时,可能导致数据异常。 - 未开通指定服务时,加入频道时未返回错误。 - 某些场景下,异常属性值可能导致崩溃问题。 ## 2.2.1 版 [#221-版-1] 该版本于 2024 年 7 月 17 日发布。 ### 改进 [#改进-18] 该版本进行了如下改进: - 优化了底层算法能力,提升了数据同步速度。 - 在 AgoraRtmLinkStateEvent 中,将 Token 过期时返回的 `reason` 字段由 `TicketExpired` 改为 `TokenExpired`。 ### 问题修复 [#问题修复-19] 该版本修复了本地用户未调用 leave 方法直接调用 logout 方法时,偶现远端用户收不到 AgoraRtmPresenceEventTypeRemoteLeaveChannel 事件通知的问题。 ## 2.2.0 版 [#220-版-1] 该版本于 2024 年 4 月 23 日发布。 ### 升级必看 [#升级必看-10] #### API 变更 [#api-变更] 该版本的 API 变更如下: - 删除了 `createMetadata` 方法。参考如下示例代码修改你的实现代码: ```objc // v2.2.0 之前 AgoraRtmMetadata* metadata = [[rtm getStorage] createMetadata]; ``` ```objc // v2.2.0 AgoraRtmMetadata* metadata = [[AgoraRtmMetadata alloc] init]; ``` - 取消了 `AgoraRtmStateItem` 类,并将如下参数由 `NSArray` 类型变为 `NSDictionary` 类型,参考对应 API 文档修改你的实现代码。 - [`setState`](/zh-CN/api-reference/rtm/ios/presence#setstate) 中的 `items` 参数。 - [`PresenceEvent`](/zh-CN/api-reference/rtm/ios/configuration#agorartmpresenceevent) 中的 `states` 参数。 - [`UserState`](/zh-CN/api-reference/rtm/ios/presence#getstate) 中的 `states` 参数。 ### 新特性 [#新特性-7] #### 新增支持 macOS 和 VisionOS 平台 [#新增支持-macos-和-visionos-平台] 该版本新增支持 macOS 和 VisionOS 平台,支持的最小版本和目标架构见[平台支持](/zh-CN/realtime-media/rtm/reference/capabilities-and-compatibility/platform-support)。同时,该版本也将包名由 `AgoraRtm_iOS` 变更为 `AgoraRtm`。升级至该版本后,在使用 CocoaPods 集成方式时,你需要将 `Podfile` 文件修改为以下内容: ```ruby platform :ios, '11.0' target 'Your App' do pod 'AgoraRtm', '2.2.0' end ``` #### 新增私有化部署能力 [#新增私有化部署能力-1] 该版本在 [`AgoraRtmClientConfig`](/zh-CN/api-reference/rtm/ios/configuration#agorartmclientconfig) 中新增 `privateConfig` 参数,用于实现私有化部署功能。详见[私有化配置](/zh-CN/realtime-media/rtm/build/network-and-private-deployment/private-setup)。 #### 新增心跳时间配置 [#新增心跳时间配置-1] 该版本在 [`AgoraRtmClientConfig`](/zh-CN/api-reference/rtm/ios/configuration#agorartmclientconfig) 中新增 `heartbeatInterval` 参数,用于配置 SDK 向 RTM 服务器发送心跳包的时间间隔。详见 [Heartbeat Interval 与 Presence Timeout](/zh-CN/realtime-media/rtm/build/authentication-and-connection/link-basic#heartbeatinterval-and-presencetimeout)。 #### 新增双环境配置 [#新增双环境配置-1] 该版本在 [`AgoraRtmClientConfig`](/zh-CN/api-reference/rtm/ios/configuration#agorartmclientconfig) 中新增 `protocolType` 参数,用于自定义网络传输协议,以便于更好地适配你的网络环境。详见[连接协议配置](/zh-CN/realtime-media/rtm/build/network-and-private-deployment/network-configuration#protocol)。 #### 新增用户频道类型 [#新增用户频道类型-1] 该版本在 [`AgoraRtmChannelType`](/zh-CN/api-reference/rtm/ios/enumv#channeltype) 中新增 `AgoraRtmChannelTypeUser` 类型,用于向指定用户发送消息。该功能可以替代 v1 的点对点消息功能。详见[在 User Channel 中发送消息](/zh-CN/realtime-media/rtm/build/messaging/send-message#userchannel)。 #### 新增静默模式配置 [#新增静默模式配置-1] 该版本在 [`AgoraRtmSubscribeChannelFeature`](/zh-CN/api-reference/rtm/ios/enumv#subscribechannelfeature) 中新增 `AgoraRtmSubscribeChannelFeatureBeQuiet` 枚举,在 [`AgoraRtmJoinChannelFeature`](/zh-CN/api-reference/rtm/ios/enumv#joinchannelfeature) 中新增 `AgoraRtmJoinChannelFeatureBeQuiet` 枚举,用于设置静默订阅或加入频道。设置成功后,频道中其他用户无法感知该用户的出席状态。 ### 改进 [#改进-19] #### 改进连接状态管理逻辑 [#改进连接状态管理逻辑-1] 该版本新增 [`didReceiveLinkStateEvent`](/zh-CN/api-reference/rtm/ios/configuration#事件监听) 回调,用于替代废弃的 `connectionChangedToState` 回调,以便更好地管理连接状态。详见[连接管理](/zh-CN/realtime-media/rtm/build/authentication-and-connection/link-basic)。 #### 改进 AgoraRtmPresenceEventTypeRemoteStateChanged 事件通知逻辑 [#改进-agorartmpresenceeventtyperemotestatechanged-事件通知逻辑] 该版本改进了 Presence 功能的 `AgoraRtmPresenceEventTypeRemoteStateChanged` 事件的触发逻辑,即当用户一次设置或修改多个 key-value 时,频道内其他用户只会接收到一次事件通知。 #### 支持事件通知触发时间戳 [#支持事件通知触发时间戳-1] 该版本在如下数据结构中新增 `timestamp` 参数,报告触发事件通知的时间戳: - [`AgoraRtmMessageEvent`](/zh-CN/api-reference/rtm/ios/configuration#messageevent) - [`AgoraRtmPresenceEvent`](/zh-CN/api-reference/rtm/ios/configuration#presenceevent) - [`AgoraRtmTopicEvent`](/zh-CN/api-reference/rtm/ios/configuration#topicevent) - [`AgoraRtmStorageEvent`](/zh-CN/api-reference/rtm/ios/configuration#storageevent) - [`AgoraRtmLockEvent`](/zh-CN/api-reference/rtm/ios/configuration#lockevent) #### 优化 API 行为 [#优化-api-行为-1] 该版本优化了以下 API 的行为: - [`loginByToken`](/zh-CN/api-reference/rtm/ios/configuration#login): - 在之前版本中,不支持连续多次调用该方法;也不支持在该方法的 `token` 参数中传入空字符串。 - 自 2.2.0 版本起,支持连续多次调用该方法,中间无需额外调用 `logout` 方法。此外,当 `token` 参数为空字符串时,SDK 会默认使用你初始化时传入的 App ID 替代 Token。 - [`subscribeWithChannel`](/zh-CN/api-reference/rtm/ios/channel#subscribe): - 在之前版本中,不支持连续多次调用该方法。 - 自 2.2.0 版本起,支持连续多次调用该方法。 - [`joinWithOption`](/zh-CN/api-reference/rtm/ios/channel#join): - 在之前版本中,不支持连续多次调用该方法,也不支持在该方法的 `token` 参数中传入空字符串。 - 自 2.2.0 版本起,支持连续多次调用该方法。此外,当 `token` 参数为空字符串时,SDK 会默认使用你初始化时传入的 App ID 替代 Token。 #### 修改 presenceTimeout 取值范围 [#修改-presencetimeout-取值范围-1] 该版本将 [`AgoraRtmClientConfig`](/zh-CN/api-reference/rtm/ios/configuration#agorartmclientconfig) 中 `presenceTimeout` 参数的取值范围由 [10,300] 修改为 [5,300]。 ## 2.1.12 版 [#2112-版-1] 该版本于 2024 年 6 月 7 日发布。 ### 改进 [#改进-20] 该版本进行了如下改进: - 在因网络原因导致数据同步出错的情况下,该版本增加了用户退出机制,SDK 会自动登出 RTM 系统。 - 断网期间取消订阅,不再返回取消订阅失败的错误。 ### 问题修复 [#问题修复-20] 该版本修复了如下问题: - 弱网条件下,断线期间用户取消订阅 Message Channel 出错。 - 弱网条件下,登录成功后,偶现无法收到回调。 - 断线重连情况下,偶现丢失 `didReceiveStorageEvent` 事件通知。 - 断线重连情况下,偶现无法恢复 Stream Channel 中的订阅关系。 - 偶现收不到 Web 端的 Topic 消息。 ## 2.1.11 版 [#2111-版-1] 该版本于 2024 年 4 月 30 日发布。 ### 改进 [#改进-21] #### 新增隐私清单文件 [#新增隐私清单文件] 为满足 Apple 对于 App 发布的安全合规要求,SDK 自该版本起新增隐私清单文件 `PrivacyInfo.xcprivacy`,其中包含 SDK 中需要访问或使用用户数据的 API 调用说明和 SDK 采集的数据类型说明。 :::info[信息] 如果你需要将集成 v2.1.10 之前的 SDK 版本的 App 发布到苹果应用商店,则需要在 Xcode 工程中手动添加 `PrivacyInfo.xcprivacy` 文件。详见[如何在 App 中增加隐私清单?](/zh-CN/reference/faq/other/privacyinfortm) ::: #### 其他 [#其他] 该版本优化了使用 `AgoraRtmSubscribeChannelFeaturePresence` 订阅频道或使用 `AgoraRtmJoinChannelFeaturePresence` 加入频道时的响应机制。如果 5 秒内未收到 `AgoraRtmPresenceEventTypeSnapshot` 类型的 `didReceivePresenceEvent` 事件通知,则 SDK 会在 `completion` 参数中报告 `AgoraRtmErrorChannelPresenceNotReady` 错误码。 ### 问题修复 [#问题修复-21] 该版本修复了如下问题: - 特定场景下,登出 RTM 系统后再次登录,然后使用 `AgoraRtmSubscribeChannelFeaturePresence` 订阅频道或使用 `AgoraRtmJoinChannelFeaturePresence` 加入频道时,偶现订阅或加入频道失败。 - 由网络问题导致连接断开并恢复的情况下,本地用户主动调用 `leave` 离开频道,偶现远端用户收不到 `AgoraRtmPresenceEventTypeRemoteConnectionTimeout` 类型的 `didReceivePresenceEvent` 事件通知。 - 频繁调用 `subscribeWithChannel` 和 `unsubscribeWithChannel` 方法,偶现调用失败。 ## 2.1.10 版 [#2110-版-1] 该版本于 2024 年 2 月 26 日发布。 ### 问题修复 [#问题修复-22] 该版本修复了如下问题: - 频繁发送消息时,偶现消息发送超时。 - 调用 `renewToken` 刷新 Token,因部分服务未能生效而导致非预期的连接断开。 ## 2.1.9 版 [#219-版-1] 该版本于 2024 年 1 月 10 日发布。 ### 改进 [#改进-22] 该版本优化了在断线重连时对过期用户状态数据的处理逻辑。 ### 问题修复 [#问题修复-23] 该版本修复了初始化时的内存泄露问题。 ## 2.1.8 版 [#218-版-1] 该版本于 2023 年 12 月 4 日发布。 ### 升级必看 [#升级必看-11] 该版本对消息发送选项进行了如下优化,请在升级到该版本后更新 App 代码: - 在 `AgoraRtmPublishOptions` 中删除了 `sendTs` 参数,并新增了 `channelType` 参数。详见 [`AgoraRtmPublishOptions`](/zh-CN/api-reference/rtm/ios/message#options)。 - 将 `publishTopicMessage` 方法中的 `options` 参数类型由 `AgoraRtmPublishOptions` 修改为 `AgoraRtmTopicMessageOptions`。详见 [`AgoraRtmTopicMessageOptions`](/zh-CN/api-reference/rtm/ios/topic#options)。 ### 改进 [#改进-23] 该版本新增了 `AgoraRtmErrorInvalidChannelType`、`AgoraRtmErrorInvalidEncryptionParameter` 和 `AgoraRtmErrorOperationRateExceedLimitation` 错误码。错误码描述及解决方法见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 ### 问题修复 [#问题修复-24] 该版本修复了如下问题: - 初始化时 `encryptionKdfSalt` 参数长度不为 32 字节,未返回初始化失败。 - 调用 `whoNow` 方法返回分页结果时,偶现崩溃。 ## 2.1.7 版 [#217-版-1] 该版本于 2023 年 10 月 20 日发布。 ### 改进 [#改进-24] 该版本优化了内存表现并修复了潜在的内存泄漏问题。 ### 问题修复 [#问题修复-25] 该版本修复了如下问题: - 特定场景下,偶现 Presence 数据丢包。 - 特定场景下,方法调用后未触发异步回调。 - 使用端侧加密时,参数无效导致的崩溃。 - 特定场景下,直接销毁 RTM 实例导致的 ANR (Application Not Responding) 问题。 ## 2.1.6 版 [#216-版-1] 该版本于 2023 年 9 月 19 日发布。 ### 升级必看 [#升级必看-12] 该版本对部分功能的实现方式进行了优化,请在升级到该版本后更新 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`。 ### 新特性 [#新特性-8] #### 多种事件监听方式 [#多种事件监听方式-1] 该版本新增 `addDelegate` 和 `removeDelegate` 方法。除了在初始化时添加或删除事件监听外,你还可以调用新增方法在 App 生命周期的任意时间添加、删除一个或多个事件监听对象。 ### 改进 [#改进-25] #### 消息发送 [#消息发送] 该版本新增 `publish` 和 `publishTopicMessage` 方法的同名方法,并修改了原方法中 `message` 参数的类型。详情如下: ```objc // 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; ``` ```objc // 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` 参数,用于输出方法调用失败的错误描述,方便排查问题。 ### 问题修复 [#问题修复-26] 该版本修复了如下问题: - 当网络状态发生变化时,偶现无法登出 RTM 系统。 - 登出 RTM 系统后,当网络状态发生变化时,偶现无法登录 RTM 系统。 - 网络断开后,因数据未清理导致偶现用户无法收到 `Snapshot` 事件通知。 - 用户加入频道后,把 App 切到后台再切换回前台时,偶现 SDK 多次触发 `REMOTE_JOIN` 事件通知。 ## 2.1.4 版 [#214-版-1] 该版本于 2023 年 8 月 16 日发布。这是 RTM v2 Objective-C SDK 的第一个版本。 本次发布意味着声网实时通讯(RTM)产品步入 v2 时代,我们在功能覆盖、性能提升、体验优化上都将为用户带来革新。 - 功能覆盖:该版本通过引入频道(Channel)、消息(Message)、Topic、Presence、Storage 和 Lock 等功能模块,能覆盖更多业务场景,你可以把更多的精力集中在自己的业务创新上。 - 性能提升:我们在新版本中重构了后台架构,通过优化网络连接进一步提升性能,提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力,让你无需为业务质量担忧。 - 体验优化:我们重新设计并简化了 API 接口;优化了包括用户指南、API 参考在内的所有文档,提供了更全面的示例程序,支持开发者低成本学习使用 SDK,快速完成集成,提高开发效率。 ### 新特性 [#新特性-9] 该版本提供的核心功能模块如下。 :::info[信息] RTM 2.1.4 目前处于 Public Beta 阶段,某些功能细节可能会在随后的版本中发生改变,以提升用户体验。 ::: #### 初始配置(Setup) [#初始配置setup-1] 初始配置(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) [#频道channel-1] 频道是 RTM 实时网络中一种数据传输的管理机制,任何订阅或加入频道的用户都可以在 100 毫秒内接收到频道中传输的消息和事件,RTM 允许客户端订阅数百甚至数千个频道。大多数 RTM API 都将以频道为基础进行发送、接收、加密等行为。 基于声网的能力,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) [#消息message-1] RTM 的基础是发送消息的能力,你可以随时随地向频道中发送消息,消息会在 100 毫秒内传递到任何地方。RTM 支持 String 类型和 Byte 类型的消息负载。 `publish` 向指定的 Message Channel 中发送消息。调用 `publish` 会触发 `onMessageEvent` 事件通知,如果想要收到频道中的消息,你需要在 `subscribeWithChannel` 的时候,设置 `withMessage = true`,注册并实现 `onMessageEvent` 事件。 #### Topic [#topic-1] Topic 是 Stream Channel 中的数据流管理机制。你可以在 Stream Channel 中利用此特性进行数据流的订阅、分发、事件通知等,灵活使用 Topic 能力,能大大降低业务复杂度,提升开发效率。Topic 的主要功能如下: - `joinTopic`:注册成为此 Topic 的消息发布者(publisher)。注册后,该用户会具备发送消息的能力。 - `publishTopicMessage`:向 Stream Channel 中的 Topic 发送消息。 - `leaveTopic`: 取消注册为该 Topic 的消息发布者。 - `subscribeTopic`:订阅该频道中 Topic 的一名或多名消息发布者。 - `unsubscribeTopic`:取消订阅该 Topic 或取消订阅该 Topic 中指定的一名或多名消息发布者。 注册(`joinTopic`)或取消注册(`leaveTopic`)消息发布者操作,会触发 `onTopicEvent` 事件通知,频道中的其他用户将会收到此事件通知。 :::info[信息] Topic 特性只在 Stream Channel 中有效,Message Channel 中不存在此特性。 ::: #### 在线状态 [#在线状态-1] Presence 提供监控用户在线状态及临时状态变化的能力。通过 Presence 功能,你可以实时获取以下信息: - 用户加入或离开频道的实时状态 - 订阅或加入同一频道的所有用户的实时状态 - 一个用户订阅或加入的所有频道的实时信息 - 自定义临时用户状态及其变更信息 在 Message Channel 和 Stream Channel 中均可使用以下 Presence 功能: - `whoNow`:实时获取指定频道的在线用户数量、在线用户列表、在线用户的临时状态等信息。 - `whereNow`:实时获取指定用户所在频道的列表。 - `setState`:设置用户在指定频道的临时状态。 - `getState`:获取用户在指定频道的临时状态。 - `removeState`:删除用户在特定频道的临时状态。 Presence 在提供上述功能的同时,也提供了 `onPresenceEvent` 事件通知能力。频道中用户的加入、离开、掉线、用户状态设置、用户状态删除等事件都会以实时通知(Announce Mode)或定时通知(Interval Mode)的方式通知到频道中的其他用户。Presence 能力将大大简化开发者业务中关于在线用户上下线、状态变更等状态的同步逻辑实现,充分利用此特性将使得你的业务实现更稳定、实时、可靠。 #### 存储 [#存储-1] RTM 的 Storage 功能提供了一套动态数据库机制,可以让开发者动态设置、存储、更新、删除 Channel Metadata 和 User Metadata 等数据,并监听由 Channel Metadata 或 User Metadata 变更而产生的事件通知。 ##### Channel Metadata [#channel-metadata-1] - `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 时,如果参数中的 `lock` 被设置,则开启 Lock 的校验,此时只有拥有此锁的用户才被允许成功调用对应的方法。 ##### User Metadata [#user-metadata-1] - `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 控制 [#cas-控制-1] Channel Metadata 和 User Metadata 都引进了版本控制逻辑 CAS(Compare And Set),该方法提供两种独立的版本控制字段,你可以根据实际业务场景设置任意一种或多种: - 通过 `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 会返回错误码。 #### 锁 [#锁-1] 临界资源一次只能供一个进程使用,如果不同的进程之间共享了某个临界资源,则各进程需要采取互斥的方式来防止彼此干扰。RTM 提供一整套 Lock 的方案,通过控制分布式系统的不同进程,你可以解决用户在访问共享资源时的竞争问题。Lock 为你提供了以下能力: - `setLock`:为指定频道设置锁。 - `acquireLock`:获取指定频道中指定的锁。 - `releaseLock`: 释放指定频道中指定的锁。 - `revokeLock`: 撤销指定频道中某个用户对此锁的占用权限以释放此锁。 - `getLocks`: 获取指定频道中所有锁的详情。 - `removeLock`:删除指定频道中指定的锁。 频道中锁的设置、获取、释放、撤销和删除操作都会上报对应的 `onLockEvent` 事件通知。你可以充分利用此特性优化业务的实现逻辑。