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

发版说明

更新时间 2023/03/13 03:11:16

1.5.1 版

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

1.5.0 版

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

功能下架

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

API 变更

废弃

  • createFileMessageByMediaId
  • createFileMessageByUploading
  • createImageMessageByMediaId
  • createImageMessageByUploading
  • cancelMediaUpload
  • cancelMediaDownload
  • downloadMediaToMemory
  • downloadMediaToFile
  • enableOfflineMessaging
  • enableHistoricalMessaging
  • onFileMessageReceived
  • onFileMessageReceivedFromPeer
  • onImageMessageReceived
  • onImageMessageReceivedFromPeer
  • onMediaUploadingProgress
  • onMediaDownloadingProgress

1.4.10 版

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

问题修复

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

1.4.9 版

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

改进

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

1.4.7 版

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

提高了弱网状态下的登录成功率和消息投递成功率。

1.4.6 版

该版本于 2021 年 6 月 21 日发布。

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

1.4.5 版

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

改进

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

1.4.4 版

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

改进及问题修复

  • 优化了弱网对抗能力，提高了弱网环境下的登录成功率和消息投递成功率。
  • 修复了一些崩溃问题。

1.4.3 版

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

问题修复

该版本修复了以下问题：

  • 偶现的多线程访问冲突造成崩溃的问题。
  • 声网 RTM SDK 登录超时率较高的问题。

1.4.2 版

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

改进

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

1.4.1 版

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

改进

优化了日志文件。

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。

新增功能

  • 增加限定访问区域功能。你可以调用 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 引入了 IFileMessage 消息类用于保存和传递系统生成的 media ID。IFileMessage 继承自 IMessage 类，所以你可以通过点对点消息或频道消息发送方法传递 IFileMessage 实例。你可以通过 IFileMessage 对象进行以下操作:

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

2. 发送和接收图片消息

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

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

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

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

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

问题修复

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

API 变更

新增方法

新增回调

废弃方法

sendMessage 被重载方法 sendMessage 替代。

1.2.2 版

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

兼容性改动

废弃用于创建 IAgoraService 的 createAgoraService 方法以及用于初始化 IAgoraService 的 initialize 方法。从本版本开始，你只需要调用用于创建 IRtmService 的 createRtmService 方法以及用于初始化 IRtmService 的 initialize 方法就可以开始使用 IRtmService 实例。

问题修复

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

1.2.1 版

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

新增功能

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

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

问题修复

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

1.2.0 版

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

兼容性改动

废弃 isOnline

在调用 queryPeersOnlineStatus 方法查询单个或多个用户在线状态后，SDK 会通过 onQueryPeersOnlineStatusResult 回调返回被查询用户的在线状态。你可以通过回调返回的 PeerOnlineStatus 结构体数组中的 isOnline 字段查询指定用户是否在线。

本版本中，我们在这个 PeerOnlineStatus 结构体中增加了枚举类型 PEER_ONLINE_STATE ，细分并重新定义了以下三种用户在线状态：

  • 在线（online）： 用户已登录声网 RTM 系统。
  • 连接状态不稳定（unreachable）：服务器连续 6 秒未收到来自 SDK 的数据包。
  • 用户不在线（offline）：用户未登录或已登出声网 RTM 系统，或服务器连续 30 秒未收到来自 SDK 的数据包。

新增的 PEER_ONLINE_STATE 枚举类型主要与订阅功能 subscribePeersOnlineStatus 配合使用，你可以在 onPeersOnlineStatusChanged 回调返回的 PeerOnlineStatus 结构体数组中查到用户的在线状态。

总而言之：

  • 在主动查询用户在线状态时，我们推荐你通过 PEER_ONLINE_STATE 查询，不过系统不会返回 unreachable 状态。
  • 在订阅了指定用户的在线状态后，我们推荐你通过 PEER_ONLINE_STATE 获取用户在线状态，方便 App 在用户连接状态不佳时快速响应，提高整体用户体验。

新增功能

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

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

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

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

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

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

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

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

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

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

本版本支持：

  • 创建不带文本描述信息的自定义二进制消息（createMessage）
  • 创建包含文本描述信息的自定义二进制消息（createMessage）

如果在创建自定义二进制消息时未设置文本描述，你可以在消息实例 IMessage 创建成功后通过调用 setText 方法设置自定义二进制消息的文本描述。

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

4. 创建文本消息

之前版本中，我们先通过 createMessage 方法创建一个空文本消息实例再通过调用 IMessage 类的对象方法 setText 设置文本内容，本版本提供了更加便利的 createMessage 方法可以在创建文本消息的同时直接设定文本消息内容。

文本消息大小不得超过 32 KB。

API 变更

新增方法

新增回调

新增错误码

新增枚举类型

废弃成员变量

1.1.0 版

该版本于 2019 年 9 月 30 日初次发布。新增以下功能：

新老互通

支持与声网 Signaling SDK 互通。

本版本在 ILocalCallInvitation 类中实现了 setChannelId 和 getChannelId 方法。

  • 如需与声网 Signaling SDK 互通，则必须调用 setChannelId 方法设置频道 ID。不过即使被叫成功接受呼叫邀请，声网 RTM SDK 也不会将主叫或被叫加入指定频道。
  • 如果你的应用不涉及声网 Signaling SDK，我们推荐使用 ILocalCallInvitation::setContent 或者 IRemoteCallInvitation::setResponse 方法设置自定义内容。

发送（离线）点对点消息

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

查询频道成员人数

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

查询用户在线状态

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

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

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


频道属性增删改查

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

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

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

支持功能包括：

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

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

呼叫邀请

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

加入或离开频道

发送或接收频道消息

频道成员人数自动更新

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

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

更新 Token

设置日志文件地址

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

设置日志输出等级

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

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

设置日志文件大小

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

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

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