通知
RTM 1.x 将于近期下架，各版本退休日期和替代方案详见 退休政策 。
文档中心
云信令（原实时消息）
Console 官网 社区 技术支持
简体中文
search-icon

发版说明

更新时间 2023/03/13 03:10:20

1.5.1 版

该版本于 2022 年 9 月 1 日发布，提升了 SDK 的稳定性。

1.5.0 版

该版本于 2022 年 7 月 27 日发布。

功能下架

富媒体传输、历史消息 和 离线消息 功能于该版本正式下线。旧版本 SDK 会继续支持，已集成这些功能的用户不受影响。

API 变更

废弃

  • createFileMessageByMediaId
  • createFileMessageByUploading
  • createImageMessageByMediaId
  • createImageMessageByUploading
  • cancelMediaUpload
  • cancelMediaDownload
  • downloadMedia
  • downloadMediaToMemory
  • fileMessageReceived
  • imageMessageReceived
  • uploadingProgress
  • downloadingProgress
  • enableOfflineMessaging
  • enableHistoricalMessaging

已知问题和局限性

iOS 15 兼容性

SDK 自 1.4.6 版本起对 iOS 15 进行了兼容性适配。对于 1.4.4 及 1.4.5 版本，在 iOS 15 上高概率会发生崩溃。为避免该问题，请务必将 SDK 升级至 1.4.6 或之后版本。

1.4.10 版

该版本于 2022 年 03 月 01 日发布。

升级必看

自该版本起，支持在 M1 芯片的设备上运行 iOS 模拟器。

问题修复

修复了一些富媒体相关的崩溃问题。

1.4.9 版

该版本于 2021 年 11 月 19 日发布。

改进

提升了 IPv4/IPv6 双栈网络下登录成功率和连接稳定性。

问题修复

该版本修复了如下问题：

  • 与 RTC SDK 共同使用时内部类名冲突，导致运行 app 时出现非预期提示的问题。
  • 退出 app 时偶现的崩溃问题。

1.4.8 版

该版本于 2021 年 7 月 23 日发布。

更新 Info.plist 文件内的 SDK 版本信息到最新版本。

1.4.7 版

该版本于 2021 年 7 月 19 日发布。

改进

  • 修复了 iOS 15 兼容性适配引发的潜在崩溃问题，提高了 SDK 稳定性。
  • 提高了弱网状态下的登录成功率和消息投递成功率。

1.4.6 版

该版本于 2021 年 6 月 21 日发布，对 iOS 15 进行了兼容性适配。

1.4.5 版

该版本于 2021 年 4 月 30 日发布。

升级必看

集成变更

由于从 1.4.4 版本起， SDK 由静态库升级为动态库，且动态库使用 XCFramework 格式，如果你使用的第三方工具不支持 XCFramework 格式，声网提供如下脚本来解决该集成问题：

详见集成 SDK。

改进

修复了一些可能导致崩溃的问题，优化了稳定性。

问题修复

修复了使用 1.4.4 版本 SDK 集成的 iOS app，在 App Store 由于审核问题无法上架的问题。

1.4.4 版

该版本于 2021 年 4 月 20 日发布。

升级必看

  • 该版本将 SDK 由静态库升级为动态库，不再支持静态库。使用动态库可以提高库的安全等级，方便 app 上传至 App Store，且避免与第三方库产生不兼容等问题。
    如果你由之前版本的静态库升级为当前版本，需要重新集成。集成时添加动态库 AgoraRtmKit.xcframework 即可，无需添加其他依赖库。详见升级指南。
  • 所有动态库由 framework 格式修改为 XCFramework 格式。XCFramework 格式的动态库支持在真机和模拟器上运行项目。

改进

优化了弱网对抗能力，提高了弱网环境下的登录成功率和消息投递成功率。

问题修复

  • 修复了 SDK 内存泄露的问题。
  • 修复了一些崩溃问题。

1.4.3 版

该版本于 2021 年 2 月 10 日发布。

问题修复

该版本修复了以下问题：

  • Swift 环境下声网 RTC SDK 的 AgoraAreaCode 常量与声网 RTM SDK 的 AgoraRtmAreaCode 常量值命名冲突问题。自 v1.4.3 起，声网在 SDK 包中提供了 AgoraRtmKit_swift.h 文件，对 AgoraRtmAreaCode 常量值做了修改。使用 Swift 进行开发时，你可以通过引用此文件避免命名冲突。
  • 1.4.2 版声网 RTM SDK 因 OpenSSL 升级导致的闪退和崩溃问题。
  • 偶现的多线程访问冲突造成崩溃的问题。
  • 声网 RTM SDK 登录超时率较高的问题。

1.4.2 版

该版本于 2020 年 11 月 23 日发布。

改进

  • 优化了登录和消息发送的性能。
  • 为 AgoraRtmAreaCode 枚举类型定义了 AGORA_SDK_BOTH_RTM_AND_RTC 宏，可以用来解决 RTC 与 RTM 共同使用时命名冲突的问题。

问题修复

修复了一些崩溃问题。

1.4.1 版

该版本于 2020 年 9 月 30 日发布。

改进

优化了日志文件。

问题修复

解决了 iOS 14 下触发弹窗的问题。详见为什么在运行集成声网 RTM SDK 的 iOS app 时会看到查找本地网络设备的弹窗提示？。

1.4.0 版

该版本于 2020 年 9 月 1 日发布。

升级必看

  • 防火墙白名单端口变更。详见应用企业防火墙限制。
    • 新增 TCP 端口：8443, 9136, 9137, 9141。 新增 UDP 端口：8443。原因：用于支持传输加密能力。
    • 新增 UDP 端口：8130, 9120, 9121。原因：用于开启 UDP 通道，帮助提升 RTM 的弱网对抗能力。
    • 新增 UDP 端口：9700。原因：用于数据上报。
  • setLogFileSize 日志文件的大小默认值从 512 KB 增加到 10 MB。上限从 10 MB 增加到 1 GB。
  • 在销毁 AgoraRtmKit 实例之前，你需要调用 destroyChannelWithId 销毁所有现存的 AgoraRtmChannel 实例，否则可能会造成崩溃。

新增功能

  • 增加限定访问区域功能。你可以调用 setRtmServiceContext 方法设置声网 RTM SDK 的访问区域。设置之后，RTM SDK 只能连接位于限定区域的声网 RTM 服务器。
  • 增加链路加密功能。此功能默认开启。如果你要关闭此功能，请联系技术支持。

改进

  • 优化了弱网对抗能力，提高了弱网环境下的登录成功率和消息投递成功率。
  • 优化了重连机制。

API 变更

新增方法

setRtmServiceContext

1.3.0 版

该版本于 2020 年 5 月 11 日发布。

升级必看

  • 防火墙白名单的 TCP 协议需要新增 9140 端口，用于发送和接收图片及文件消息。详见应用企业防火墙限制。
  • 服务器端会屏蔽向 1.2.2 或更早版本的实时消息 SDK、信令 SDK 发送的图片或文件消息。

新增功能

1. 发送和接收文件消息

v1.3.0 支持上传和下载大小不超过 30 MB 的任意格式的非空文件，支持随时取消正在进行中的上传或下载任务。每个上传到声网服务器的文件都对应一个 media ID，在服务端保存 7 天。你可以通过 media ID 在 7 天有效期内从声网服务器下载对应的文件。

你只能通过 SDK 提供的下载方法下载文件。

v1.3.0 引入了 AgoraRtmFileMessage 消息接口用于保存和传递系统生成的 media ID。AgoraRtmFileMessage 接口继承自 AgoraRtmMessage 接口，所以你可以通过点对点消息或频道消息发送方法传递 AgoraRtmFileMessage 实例。你可以通过 AgoraRtmFileMessage 对象进行以下操作:

  • 设置相应的上传文件的显示文件名和显示缩略图。
  • 获取相应的上传文件的大小。
消息内容、显示文件名和显示缩略图的总大小不得超过 32 KB。

2. 发送和接收图片消息

v1.3.0 支持上传和下载大小不超过 30 MB 的任意格式的非空图片，支持随时取消正在进行中的上传或下载任务。每个上传到声网服务器的图片都对应一个 media ID，在服务端保存 7 天。你可以通过 media ID 在 7 天有效期内从声网服务器下载对应的图片。

你只能通过 SDK 提供的下载方法下载图片。

v1.3.0 引入了 AgoraRtmImageMessage 消息接口用于保存和传递系统生成的 media ID。AgoraRtmImageMessage 接口继承自 AgoraRtmMessage 接口，所以你可以通过点对点消息或频道消息发送方法传递 AgoraRtmImageMessage 实例。你可以通过 AgoraRtmImageMessage 对象进行以下操作:

  • 设置相应的上传图片的显示文件名和显示缩略图。
  • 获取相应的上传图片的大小。
  • 获取 SDK 自动计算的 JPEG、JPG、BMP、PNG 四种格式的图片宽高数据。
  • 自行设置图片的宽和高。你自行设置的宽高数据会覆盖 SDK 计算的宽高数据。
消息内容、显示文件名和显示缩略图的总大小不得超过 32 KB。

3. 通知上传或下载任务的进度

对于正在进行中的上传或下载任务，SDK 会通过主动回调每秒返回一次上传或下载的进度。当上传或下载任务暂停时， SDK 暂停返回相应回调，直至任务继续进行。

问题修复

  • 由于误判用户网络导致无法登录的问题。
  • 其它可能导致系统崩溃的问题。

API 变更

新增方法

新增回调

废弃方法

sendMessage:completion: 被重载方法 sendMessage:sendMessageOptions:completion: 替代。

1.2.2 版

该版本于 2019 年 12 月 13 日发布。

问题修复

修复了一个偶现的频道属性操作后无法收到回调的问题。

1.2.1 版

该版本于 2019 年 11 月 29 日 发布。

新增功能

支持与老信令 SDK 的 endCall 方法兼容

你可以调用 sendMessageToPeer 方法在发送文本消息时将消息设为 AgoraRTMLegacyEndcallCompatibleMessagePrefix_<channelId>_<your additional information> 格式即可。请以 endCall 对应频道的 ID 替换 <channelId>， <your additional information> 为附加文本信息。请注意：附加文本信息中不可使用下划线 "_" ，附加文本信息可以设为空字符串 "" 。

问题修复

  • 修复了一个用户使用 VPN 登录 RTM，关闭 VPN 后 RTM 重连失败的问题。
  • 修复了一个频道中用户断线重连，频道中其它用户有概率收到两次 MemberJoined 回调的问题。

1.2.0 版

该版本于 2019 年 11 月6 日发布。新增如下功能：

兼容性改动

废弃 AgoraRtmPeerOnlineStatus 类的 isOnline 属性。请改用 state 属性。

新增功能

1. 订阅或取消订阅指定单个或多个用户的在线状态。

该功能必须在登录声网 RTM 系统成功（收到 AgoraRtmLoginErrorOk ）后才能调用。

本版本支持订阅或取消订阅最多 512 个用户的在线状态，SDK 会通过 AgoraRtmSubscriptionRequestBlock 返回订阅或取消订阅结果。首次订阅成功时，SDK 会通过 PeersOnlineStatusChanged 回调返回所有被订阅用户的在线状态；之后每当有被订阅用户的在线状态出现变化，SDK 都会通过 onPeersOnlineStatusChanged 回调通知订阅方。

1用户登出声网 RTM 系统后，所有之前的订阅内容都会被清空；重新登录后，如需保留之前订阅内容则需重新订阅。
2重复订阅同一用户不会报错。

2. 获取某特定内容被订阅的用户列表

该功能必须在登录声网 RTM 系统成功（收到 AgoraRtmLoginErrorOk）后才能调用。

本版本支持根据被订阅类型获取被订阅用户列表。现实情况中，你可能多次订阅或取消订阅，可能重复订阅了相同用户，可能出现订阅或取消订阅不成功的情况，也可能根据不同的订阅类型订阅了不同的用户。这时，你可以通过本功能根据订阅类型获取当前被订阅用户列表。

被订阅类型由枚举类型 AgoraRtmPeerSubscriptionOptions 定义。本版本仅支持用户在线状态订阅一种类型，后继会不断扩展。

3. 创建自定义二进制消息

本版本支持创建自定义二进制消息，支持以点对点消息或频道消息形式发送多种文件格式。

本版本支持：

  • 创建不带文本描述信息的自定义二进制消息
  • 创建包含文本描述信息的自定义二进制消息
我们不对二进制消息的文本描述的大小单独进行限制，但是我们要求自定义二进制消息的总大小不超过 32 KB。

1.1.0 版

该版本于 2019 年 9 月 18 日发布。新增如下功能：

兼容性改动

  1. 废弃点对点消息发送方法 sendMessage:toPeer:completion:，改由重载方法 sendMessage:toPeer:sendMessageOptions:completion: 替代。
  2. AgoraRtmMessage 对象的 serverReceivedTs 方法由仅支持点对点消息改为同时支持点对点消息和频道消息。
  3. 点对点消息的超时时间由 5 秒延长为 10 秒。详见： AgoraRtmSendPeerMessageErrorTimeout
  4. 针对 joinWithCompletion 方法调用增加了加入相同频道的频率限制：每 5 秒 2 次。

新增功能


1. 查询频道成员人数

支持在不加入频道的情况下通过主动调用 getChannelMemberCount 接口查询单个或多个频道的频道人数。一次最多可查询 32 个频道的成员人数。


2. 频道成员人数自动更新

如果你已经加入某频道，你无需调用 getChannelMemberCount 接口查询当前频道人数。我们也不建议你通过监听 onMemberJoined 和 onMemberLeft 统计频道成员人数。从本版本开始，SDK 会在频道成员人数发生变化时通过 memberCount 回调接口通知频道成员并返回当前频道成员人数：

  • 频道成员人数小于等于 512 时，最高触发频率为每秒 1 次。
  • 频道成员人数超过 512 时，最高触发频率为每 3 秒 1 次。

请将该回调与 AgoraRtmGetMembersBlock 回调进行区分：

  • 前者为主动回调。SDK 向频道成员返回当前频道成员人数。
  • 后者由 getMembersWithCompletion 方法触发，返回频道成员列表，且当频道成员人数超过 512 时仅返回随机的 512 个成员列表。


3. 频道属性增删改查

支持设置或查询某个指定频道的属性。你可以用频道属性实现群公告、上下麦同步等功能。

每个频道属性为 key 和 value 的键值对。详见：AgoraRtmChannelAttribute。其中：

  • 每个属性的 key 为 32 字节可见字符，每个属性的 value 的字符串长度不得超过 8 KB。
  • 某个频道的全部属性长度不得超过 32 KB。
  • 某个频道属性的全部属性个数不得超过 32 个。

支持功能包括：

  • 全量设置某指定频道的属性。
  • 添加或更新某指定频道的属性。
  • 删除某指定频道的指定属性。
  • 清空某指定频道的属性。
  • 查询某指定频道的全部属性。
  • 查询某指定频道指定属性名的属性。

在进行频道属性的更新或删除操作时，你可以通过设置标志位 enableNotificationToChannelMembers 决定是否通知对应频道所有成员本次频道属性变更。

性能改进

点对点消息重发

本版本优化了点对点消息在弱网情况下的重发机制，并延长点对点消息超时时间为 10 秒，提高了在弱网情况下点对点消息的发送成功率。

频道消息缓存

声网 RTM 系统会对短期掉线后重连成功的频道成员补发最长 30 秒最多 32 条的频道消息，提高了弱网情况下频道消息的到达率。

API 变更

新增方法

新增回调

  • attributesUpdate：频道属性更新回调。返回所在频道的所有属性。
  • memberCount：频道成员人数更新回调。返回最新频道成员人数。

新增错误码

废弃方法

废弃错误码

1.0.1 版

该版本于 2019 年 8 月 1 日发布。

问题修复

  • 断网后 SDK 未返回 connectionStateChanged 回调。
  • iOS 平台偶现的崩溃。

1.0.0 版

该版本于 2019 年 7 月 24 日发布。

新增功能

新老互通

支持与声网 Signaling SDK 互通。

本版本在 AgoraRtmLocalInvitation 类中实现了 channelId 属性。

  • 如需与声网 Signaling SDK 互通，则必须设置 channelId 。不过即使被叫成功接受呼叫邀请，声网 RTM SDK 也不会将主叫或被叫加入指定频道。
  • 如果你的应用不涉及声网 Signaling SDK，我们推荐使用 AgoraRtmLocalInvitation 类中的 content 属性或者AgoraRtmRemoteInvitation 类中的 response 属性设置自定义内容。

设置日志文件地址

支持通过调用 setLogFile 方法变更本地日志的默认地址。该方法无需在 loginByToken 成功之后调用，我们建议在创建并初始化 AgoraRtmkit 实例后即调用该方法，否则会造成日志文件显示不完整。

设置日志输出等级

支持通过调用 setLogFilter 方法将日志内容按照 OFF、CRITICAL、ERROR、WARNING 和 INFO 不同等级输出。详见 AgoraRtmLogFilter 。

该方法无需在 loginByToken 成功之后调用。

设置日志文件大小

支持通过 setLogFileSize 方法设置日志文件大小。日志的默认大小为 512 KB。低于该默认大小的设置无效。

该方法无需在 loginByToken 成功之后调用。

查询 SDK 版本信息

支持通过调用静态方法 getSDKVersion 查询声网 RTM SDK 的版本信息。

功能改进

针对以下不同错误情况细化了错误代码

  • 声网 RTM 服务未初始化
  • 调用频率超过上限
  • 未调用 loginByToken 方法或 loginByToken 方法未调用成功

问题修复

  • 修复 iOS 平台偶现的崩溃。
  • 修复了一个可以用静态 App ID 和一个通过动态 App ID 生成的 Token 登录声网 RTM 系统的问题。

API 变更

0.9.3 版

该版本于 2019 年 6 月 7 日发布。

新增功能

发送（离线）点对点消息

本版本支持发送离线消息。在开通离线消息后，用户不必等到接收端上线才能发送点对点消息。如果对端离线，消息服务器会为每个接收端存储 200 条离线消息长达七天。消息以队列形式存储。当离线消息超限时，最新存储的消息会导致最老的消息丢失。当发送端设置了离线消息，而此时消息接收端不在线，发送端会收到错误码：AgoraRtmSendPeerMessageErrorCachedByServer

该方法的调用频率限制为每秒 60 条（点对点消息和频道消息一并计算在内）。

设置本地用户属性、查询指定用户属性

本版本支持设置和查询用户属性。每个用户属性为 key 和 value 的键值对。每个属性的 key 为 32 字节可见字符，每个属性的 value 的字符串长度不得超过 8 KB。单个用户的全部属性长度不得超过 16 KB。以下为本版本支持内容：

  • 全量设置本地用户属性
  • 增加或更新本地用户属性
  • 删除本地用户指定属性
  • 清空本地用户属性
  • 全量获取指定用户属性
  • 获取指定用户指定属性。
  • 用户属性的相关操作必须在登录声网 RTM 系统成功后才能进行，否则 SDK 会返回错误码：AgoraRtmAttributeOperationErrorNotReady
  • 设置的用户属性会在用户登出声网 RTM 系统后自动失效。
  • 单次用户属性设置操作不得超过 16 KB，否则 SDK 会返回错误码：AgoraRtmAttributeOperationErrorSizeOverflow 。
  • 用户属性设置相关操作的调用频率限制为每 5 秒 10 条，超限则 SDK 会返回错误码：AgoraRtmAttributeOperationErrorTooOften。
  • 获取用户属性相关操作的调用频率为每 5 秒 40 条，超限则 SDK 会返回错误码：AgoraRtmAttributeOperationErrorTooOften 。

API 变更

新增

改进

  • 支持在登录声网 RTM 系统之前创建频道实例。
  • 取消创建 RTM 频道最多 20 个的限制，但是同一用户只能同时加入 20 个频道，超限后会收到错误码 AgoraRtmJoinChannelErrorFailure 。

问题修复

  • 偶现的系统崩溃。
  • 用户登出后，其它用户查询该用户仍然显示在线，30 秒后查询不在线。

0.9.2 版

该版本于 2019 年 5 月 8 日发布。

当前版本不支持在 登录 RTM 系统前 创建频道实例 。

新增功能

查询用户在线状态

本版本引入了新的概念：在线和离线。一般情况下：

  • 在线：用户已登录到声网 RTM 系统。
  • 离线：用户已登出声网 RTM 系统或因其他原因，比如权限或网络原因，与声网 RTM 系统断开连接。

本版本增加了查询用户在线状态功能。你可以在登录声网 RTM 系统后查询最多 256 个指定用户的在线状态。详见： queryPeersOnlineStatus:completion: 接口。

  • 返回的阵列中的 Use ID 的顺序以输入顺序为准。
  • 该方法的调用频率限制为每 5 秒 10 次。详见 限制条件 。

更新 Token

在安全性要求较高的情况下，你需要输入 Token 登录声网 RTM 系统。 每个 Token 都会在生成 24 小时后过期，本版本提供了 更新 Token 的功能。

  • 在登录声网 RTM 系统时，如果你的 Token 已过期，SDK 会返回 AgoraRtmLoginErrorTokenExpired 错误码提示 Token 过期。
  • 在已登录声网 RTM 系统的情况下，Token 过期不会导致用户立即被踢出，但当用户重新登录声网 RTM 系统时需要调用。所以，我们建议你在收到 rtmKitTokenDidExpire: 回调后尽快更新 Token。

API 变更

查询用户在线状态相关

新增

更新 Token 相关

新增

呼叫邀请相关

新增以下错误码覆盖用户在没有登录声网 RTM 系统的情况下发送呼叫邀请的错误情况：

0.9.1 版

该版本于 2019 年 4 月 4 日发布。

本版本不包含 setLogFile 和 setLogFilter 方法。所有的日志信息默认保存在：

  • iOS 平台： /Library/Caches/agorartm.log 。
  • macOS 平台： ~/Library/Logs/agorartm.log 。

新增功能

本版本增加了呼叫邀请功能。结合音视频一对一或一对多通话场景，你可以创建、发送、取消、接受或拒绝一个呼叫邀请。

性能改进

  • 优化了对象关系帮助开发者快速搭建应用。
  • 简化了发送频道消息或点对点消息的流程。

API 变更

新增

删除

修正

0.9.0 版

该版本于 2019 年 2 月 4 日发布。

首次发布。

关键功能

  • 发送或接收点对点消息。
  • 加入或离开频道。
  • 发送或接收频道消息。