# 迁移指南 (/zh-CN/realtime-media/rtm/reference/migration-guide) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" /> 自 2023 年 6 月起,声网针对市场及行业需求,先后推出了 RTM v2(以下简称 v2)系列版本。此系列版本在功能、性能、体验上都有创新性提升: - **功能覆盖**:该版本通过引入 `Channel`、`Message`、`Topic`、`Presence`、`Storage` 和 `Lock` 等功能模块,能覆盖更多业务场景,你可以把更多的精力集中在自己的业务创新上。 - **性能提升**:我们在新版本中重构了后台架构,通过优化网络连接进一步提升性能,提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力,让你无需为业务质量担忧。 - **体验优化**:我们重新设计并简化了 API 接口;优化了包括用户指南、API 参考在内的所有文档,提供了更全面的示例程序,支持开发者低成本学习使用 SDK,快速完成集成,提高开发效率。 本文提供 RTM v1 和 v2 的主要区别及相关示例代码,从而帮助用户顺利地从 v1 迁移到 v2。 ## 开通服务 [#开通服务] 开通 v2 和 v1 的步骤相同: 1. 注册并登录声网控制台 2. 创建声网项目 3. 进入功能配置,开通 RTM 服务 4. 获取开发所需参数,例如 App ID 如果你没有声网账号,点击[此处](https://sso.shengwang.cn/cn/v4/signup/with-sms)注册账号。关于如何开通服务和如何创建项目,详见[开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service)。 ## 集成 SDK [#集成-sdk] v2 和 v1 的 SDK 包名不同,你需要注意区分。二者都支持 CDN 和 Maven 集成。自 v2.3.1 起,通过 Maven 集成 RTM SDK 时,需要先按[实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start)中的集成说明添加声网 Maven 仓库 `https://download.shengwang.cn/maven/`,并保留项目已有的仓库。各版本的依赖声明如下: - v1 的引用方式: ```java showLineNumbers ... dependencies { ... // 将 x.y.z 替换为具体的 SDK 版本号,如 1.5.1 implementation 'io.agora.rtm:rtm-sdk:x.y.z' } ``` - v2 的引用方式: ```groovy lineNumbers dependencies { // 将下方版本号替换为需要的 SDK 版本号,如 2.3.1 // 对于 2.2.7 及之后版本 implementation 'cn.shengwang.rtm:android-java:2.3.1' // 对于 2.2.6 及之前版本 // implementation 'io.agora:agora-rtm:x.y.z' } ``` :::info[信息] v2 的 SDK 包名为 `agora-rtm`,而 v1 的 SDK 包名为 `rtm-sdk`。 ::: ## 初始化实例 [#初始化实例] 相比于 v1,v2 对初始化参数做了很大的调整,增加了很多新特性,例如端侧加密、云代理等,详见 [API 参考](/zh-CN/api-reference/rtm/android/configuration#create)。此外,v2 还丰富了接口调用的错误信息,你可以通过 `ErrorInfo` 数据结构获取错误码、错误原因及 API 操作名称,以便于你能更快地排查故障。结合[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)文档,你也可以快速找到解决方法。 :::info[信息] RTM v2 版本在命名字符集的支持上与 v1 版本存在差异。例如,v2 版本不支持以 `"_"` 开头或包含 `"."` 字符的频道名、用户名和 Topic 名等。在从 v1 升级到 v2 或混合使用这两个版本时,需注意字符集差异可能导致的不兼容问题。建议在迁移时统一使用 v2 版本[支持的字符集](/zh-CN/realtime-media/rtm/build/channels-and-topics/channel-basic#合法字符)。 ::: - v1 的示例代码如下: ```java try { rtmClient = RtmClient.createInstance(getBaseContext(), "your_appId", new RtmClientListener() { @Override public void onConnectionStateChanged(int state, int reason) { } @Override public void onMessageReceived(RtmMessage rtmMessage, String peerId) { } @Override public void onTokenExpired() { } @Override public void onTokenPrivilegeWillExpire() { } @Override public void onPeersOnlineStatusChanged(Map status) { } }); } catch (Exception e) { throw new RuntimeException("RTM initialization failed!"); } ``` - v2 的示例代码如下: ```java RtmConfig rtmConfig = new RtmConfig.Builder("your_appId", "your_userId") .eventListener(eventListener) .build(); try { rtmClient = RtmClient.create(rtmConfig); } catch (Exception e) { e.printStackTrace(); } ``` ## 登录服务 [#登录服务] v2 登录服务的方法和 v1 有区别,如下所示: - v1 的示例代码如下: ```java rtmClient.login("your_token", "your_userId", new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理登录结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` - v2 的示例代码如下: ```java rtmClient.login("your_token", new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理登录结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` ## 事件通知 [#事件通知] 相比于 v1,v2 重新设计了系统事件通知方式和 API 接口,对事件通知类型进行了更详细的分类和聚合,对事件通知的负载数据结构进行了优化。 v2 的事件通知类型有 8 种,如下所示: | 事件类型 | 描述 | |--------------| ---------- | | `onMessageEvent` | 消息事件通知:接收用户所订阅的 Message Channel 及 Topic 中的所有消息事件通知。 | | `onPresenceEvent` | 用户出席与自定义状态变更事件通知(简称 Presence 事件通知):接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Presence 事件通知。 | | `onTopicEvent` | Topic 变更事件通知:接收用户所加入的 Stream Channel 中所有 Topic 变更事件通知。 | | `onStorageEvent` | 频道属性和用户属性事件通知:接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Channel Metadata 事件通知,及订阅用户的 User Metadata 事件通知。 | | `onLockEvent` | 锁变更事件通知:接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Lock 事件通知。 | | `onConnectionStateChanged` | (已废弃)网络连接状态变更事件通知:接收客户端网络连接状态变更的事件通知。 | | `onLinkStateEvent` | 接收客户端网络连接状态变更的事件通知,包含变更前后的连接状态、服务类型、导致变更的操作类型、变更原因、频道列表等信息。 | | `onTokenPrivilegeWillExpire` | 接收客户端 Token 将要过期的事件通知。 | 关于事件通知的更多信息及负载数据结构见[事件监听](/zh-CN/api-reference/rtm/android/configuration#事件监听)。 以监听频道消息 `onMessageEvent` 事件通知为例,示例代码如下: - v1: ```java rtmChannel = rtmClient.createChannel("channelName", new RtmChannelListener() { @Override public void onMessageReceived(final RtmMessage message, final RtmChannelMember fromMember) { // 处理消息事件 } // 添加其他事件通知 }); ``` - v2: ```java RtmEventListener eventListener = new RtmEventListener() { @Override public void onMessageEvent(MessageEvent event) { // 处理消息事件 } // 添加其他事件通知 }; // 方式一:调用 create 方法初始化 RTM Client 实例时添加事件监听 RtmConfig rtmConfig = new RtmConfig.Builder("your_appId", "your_userId") .eventListener(eventListener) .build(); try { rtmClient = RtmClient.create(rtmConfig); } catch (Exception e) { e.printStackTrace(); } // 方式二:在 App 生命周期的任意时间中添加事件监听 rtmClient.addEventListener(eventListener); ``` 从上面的示例代码可以看出以下显著区别: - v1 的频道消息事件通知绑定在具体的 `channel` 实例上,用户需要先调用 `createChannel()` 方法创建 `channel` 实例,然后注册 `onMessageReceived` 回调处理事件,SDK 会在收到消息后通过该回调通知处理程序,并且多个频道要实现绑定多次。而 v2 的消息事件通知绑定在客户端实例上,是全局设置,调用 `addEventListener()` 方法注册回调程序,只需要绑定一次,就可以监听所有订阅的频道或 Topic。 - v1 的消息事件通知负载数据结构包含的信息相对较少,而 v2 的消息事件通知负载数据结构包含了更多的信息,可以帮助你更好地实现自己的业务。 ## 频道消息 [#频道消息] 在 1.x 中,发送频道消息的步骤如下: 1. 创建一个频道实例 2. 加入频道 3. 发送频道消息 这种设计会有个弊端,你无法实现发送消息而不收到消息。因为发送消息和接收消息没有解耦。v2 采用了基于 Pub/Sub 的新设计,将频道消息的发送和接收解耦:你无需加入频道即可向指定频道发送消息,你只需订阅指定频道即可接收该频道中的消息,两种操作互不影响。 - v1 的示例代码如下: ```java // 创建频道 rtmChannel = rtmClient.createChannel("channelName", new RtmChannelListener() { @Override public void onMessageReceived(final RtmMessage message, final RtmChannelMember fromMember) { // 处理消息事件 } // 添加其他事件通知 }); // 加入频道 rtmChannel.join(new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理加入频道结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); // 发送消息 RtmMessage message = rtmClient.createMessage(); message.setText("Hello World!"); rtmChannel.sendMessage(message, new ResultCallback() { @Override public void onSuccess(Void aVoid) { // 处理消息发送结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` - v2 的示例代码如下: ```java // 在 Message Channel 中发送消息 String message = "Hello world"; PublishOptions options = new PublishOptions(); options.customType = 'PlainText'; rtmClient.publish("channelName", message, options, new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理消息发送结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); // 订阅 Message Channel SubscribeOptions options = new SubscribeOptions(); options.setWithMessage(true); rtmClient.subscribe("channelName", options, new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理消息订阅结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` ## 点对点消息 [#点对点消息] v1 版本中的点对点消息 API 用于向指定的用户发送消息,例如,你如果需要向用户 ID 为 `Tony` 的用户发送消息,你可以按照如下方式实现: ```java // v1 RtmMessage message = rtmClient.createMessage(); message.setText("Hello World!"); SendMessageOptions options = new SendMessageOptions(); rtmClient.sendMessageToPeer("Tony", message, options, new ResultCallback() { @Override public void onSuccess(Void aVoid) { // 处理消息发送结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` 自 2.2.0 版本起,我们对点对点消息进行了调整,将其定义为用户频道(User Channel):通过 `publish` 方法发送消息,通过 `onMessageEvent` 事件通知接收消息。这一新方法的实现效果与 v1 版本中的点对点消息功能完全一致,你可以按以下方式实现: ```java // v2 // 适用于 2.2.0 及之后版本 PublishOptions options = new PublishOptions(); options.setChannelType(RtmChannelType.USER); options.setCustomType("PlainText"); rtmClient.publish("Tony", "Hello world", options, new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理消息发送结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` 当然,你也可以通过 Message Channel 来实现收件箱功能。只不过这种方式,发送方无法收到送达回执。 ```java // v2 // 1. 订阅自己的收件箱 String channelName = "inbox_Tony"; SubscribeOptions options = new SubscribeOptions(); options.setWithMessage(true); rtmClient.subscribe(channelName, options, new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理订阅结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); // 2. 向 Lily 发送消息 String channelName = "inbox_Lily"; String message = "This is a message"; PublishOptions options = new PublishOptions(); rtmClient.publish(channelName, message, options, new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理消息发送结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` ## 图片与文件消息 [#图片与文件消息] 出于对用户数据和隐私保护合规性、成本优化的考虑,RTM 自 1.5.0 版本起不再直接支持传输图片和文件消息,相关的 API 也已经下架。你可以结合 RTM 和第三方对象存储服务(例如 Amazon S3 或者阿里云 OSS)来构建图片与文件消息功能,在获得极佳的实时消息传输体验的同时,还能实现更灵活的技术构建方案,例如,实现 CDN 静态资源加速、图片文本审核等业务需求。以下示例代码向你展示如何使用 v2 和 Amazon S3 对象存储服务实现图片和文件消息的构建和发送: ```java // 1. 上传文件至 Amazon S3 // 2. 通知 RTM JSONObject jsonObject = new JSONObject(); // 文件类型,接收方可以根据此字段解析消息包结构 jsonObject.put("type", "file"); // 你在 Amazon S3 上的 bucket 名称,接收方需要此字段来下载文件 jsonObject.put("bucket", "uploadParams.Bucket"); // 文件在 Amazon S3 存储的 Key,接收方需要此字段来下载文件 jsonObject.put("key", "uploadParams.Key"); // 文件内容类型 jsonObject.put("contentType", "uploadParams.ContentType"); // 文件 URL 地址 jsonObject.put("url", "data.Location"); PublishOptions options = new PublishOptions(); rtmClient.publish("receiver", jsonObject.toString(), options, new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理消息发送结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` :::info[信息] 使用 Amazon S3 实现静态文件存储时,你需要进入 Amazon S3 控制台,然后设置正确的用户权限和访问策略。详见[访问控制最佳实践](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/access-control-best-practices.html)。 ::: ## 用户出席与自定义状态 [#用户出席与自定义状态] 在 v1 中,你可以订阅或查询多个用户的在线状态、查询频道人数或频道在线成员列表等。v2 不仅保留了这些能力,还在 v1 的基础上进行了升级和扩展,新设计了 Presence 模块。Presence 模块提供监控用户上线、下线及用户临时状态变更的能力,你可以实时获取以下信息: - 用户加入或离开指定频道 - 自定义临时用户状态及其变更 - 查询指定用户加入或订阅了哪些频道 - 查询指定频道有哪些用户加入及其用户临时状态数据 你可以调用 `whoNow` 方法,实时查询指定频道的在线用户数量、在线用户列表及在线用户的临时状态等信息。 ```java // v2 PresenceOptions options = new PresenceOptions(); options.setIncludeUserId(true); options.setIncludeState(true); options.setPage("yourBookMark"); rtmClient.getPresence().whoNow("channelName", RtmChannelType.MESSAGE, options, new ResultCallback() { @Override public void onSuccess(WhoNowResult result) { // 处理 whoNow 调用结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` 你可以调用 `whereNow` 方法,实时获取指定用户所在频道的列表。 ```java // v2 rtmClient.getPresence().whereNow("Tony", new ResultCallback>() { @Override public void onSuccess(ArrayList channels) { // 处理 whereNow 调用结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` 为满足业务场景对用户状态的设置需求,v2 提供了设置临时用户状态的能力,你可以通过 `setState` 方法自定义临时用户状态。用户可以为自己添加分数、游戏状态、位置、心情、连麦状态等自定义状态。 ```java // v2 HashMap stateItems = new HashMap(); stateItems.put("mood", "pumped"); rtmClient.getPresence().setState("channelName", RtmChannelType.MESSAGE, stateItems, new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理 setState 调用结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` 你也可以随时通过 `getState` 方法获取用户的在线状态,或者通过 `removeState` 方法删除用户的状态。用户临时状态变更后,RTM 服务器会触发 `REMOTE_STATE_CHANGED` 类型的 `onPresenceEvent` 事件通知。具体用法见[临时用户状态](/zh-CN/realtime-media/rtm/build/state-and-attributes/temporary-user-state)。 在 v2 中,实时监听频道中用户加入、离开、超时掉线或临时状态变更通知会更加方便,你只需实现如下步骤: 1. 实现 Presence 事件监听程序 2. 加入频道时,开启 `withPresence` 开关 ```java // v2 // 1. 实现 Presence 事件监听程序 RtmEventListener eventListener = new RtmEventListener() { @Override public void onPresenceEvent(PresenceEvent event) { // 处理 Presence 事件通知 } }; rtmClient.addEventListener(eventListener); // 2. 订阅频道时,开启 withPresence 开关 SubscribeOptions options = new SubscribeOptions(); options.setWithPresence(true); rtmClient.subscribe("channelName", options, new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理消息订阅结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` v2 对实时通知进行了全新的设计,在频道中采取两种模式将 Presence 事件通知到订阅用户:**实时通知模式 (Announce)** 和**定时通知模式 (Interval)**。你可以在控制台的项目设置中通过**实时通知最大人数**大小来决定两种模式相互切换的条件。其中,定时通知模式可防止频道内在线用户过多而导致的事件嘈杂,详见[事件通知模式](/zh-CN/realtime-media/rtm/build/state-and-attributes/presence-events#事件通知模式)。 ## 用户属性与频道属性 [#用户属性与频道属性] 基于 v1 的用户属性和频道属性功能,v2 新增了版本控制和锁控制等能力,并优化了 API 接口形式,让功能的使用更加简单。v2 中把用户属性和频道属性挂载在 Storage 模块下,以设置频道属性为例,示例代码如下: ```java // v2 // 创建 Metadata 实例 Metadata metadata = new Metadata(); // 设置 Major Revision metadata.setMajorRevision(174298270); // 添加Metadata Item ArrayList items = new ArrayList(); items.add(new MetadataItem("Apple", "100", 174298200)); items.add(new MetadataItem("Banana", "200", 174298100)); metadata.setItems(items); // 记录设置 Metadata Item 的时间戳和用户 ID MetadataOptions options = new MetadataOptions(); options.setRecordTs(true); options.setRecordUserId(true); rtmClient.getStorage().setChannelMetadata("channelName", RtmChannelType.MESSAGE, metadata, options, "lockName", new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理 setChannelMetadata 结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` 如何获取、更新、删除频道属性,如何使用 CAS 控制、锁控制等可以参考[频道属性](/zh-CN/realtime-media/rtm/build/state-and-attributes/channel-metadata)。用户属性的使用与频道属性是类似的,详见[用户属性](/zh-CN/realtime-media/rtm/build/state-and-attributes/user-metadata)。 v2 通过 `onStorageEvent` 类型的事件通知将频道属性和用户属性分发给用户,监听 `onStorageEvent` 事件通知的步骤如下: 1. 实现 Storage 事件监听程序 2. 加入频道时,开启 `withMetadata` 开关 ```java // v2 // 1. 实现 Storage 事件监听程序 RtmEventListener eventListener = new RtmEventListener() { @Override public void onStorageEvent(StorageEvent event) { // 处理 Storage 事件通知 } // 添加其他事件通知 }; rtmClient.addEventListener(eventListener); // 2. 加入频道时,开启 withMetadata 开关 SubscribeOptions options = new SubscribeOptions(); options.setWithMetadata(true); rtmClient.subscribe("channelName", options, new ResultCallback() { @Override public void onSuccess(Void responseInfo) { // 处理消息订阅结果 } @Override public void onFailure(ErrorInfo errorInfo) { // 处理报错 } }); ``` ## 访问区域限定 [#访问区域限定] RTM 支持限定访问区域功能,以适应不同国家或地区的法律法规。开启限定访问区域功能后,不论用户在哪个区域使用你的 App,SDK 都只会访问指定区域的声网服务器。v2 实现访问区域限定的代码和 v1 有区别。 - v1 的示例代码如下: ```java // v1 RtmServiceContext context = new RtmServiceContext(); context.areaCode = RtmAreaCode.AREA_CODE_GLOB; setRtmServiceContext(context); ``` - v2 的示例代码如下: ```java // v2 RtmConfig rtmConfig = new RtmConfig.Builder(appId, userId) .areaCode(EnumSet.of(RtmAreaCode.AS)) .eventListener(eventListener) .build(); ``` ## 其他新特性 [#其他新特性] 除上述版本之间的功能差异之外,v2 还额外增加了很多被广泛验证和使用的新功能,你可以根据项目的需要选择和使用,相信革新版本的 v2 一定可以帮助你快速接入实时互动领域。v2 所具备的功能特性见[特性列表](/zh-CN/realtime-media/rtm/reference/capabilities-and-compatibility/feature-list)。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" /> 自 2023 年 6 月起,声网针对市场及行业需求,先后推出了 RTM v2(以下简称 v2)系列版本。此系列版本在功能、性能、体验上都有创新性提升: - **功能覆盖**:该版本通过引入 `Channel`、`Message`、`Topic`、`Presence`、`Storage` 和 `Lock` 等功能模块,能覆盖更多业务场景,你可以把更多的精力集中在自己的业务创新上。 - **性能提升**:我们在新版本中重构了后台架构,通过优化网络连接进一步提升性能,提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力,让你无需为业务质量担忧。 - **体验优化**:我们重新设计并简化了 API 接口;优化了包括用户指南、API 参考在内的所有文档,提供了更全面的示例程序,支持开发者低成本学习使用 SDK,快速完成集成,提高开发效率。 本文提供 RTM v1 和 v2 的主要区别及相关示例代码,从而帮助用户顺利地从 v1 迁移到 v2。 ## 开通服务 [#开通服务-1] 开通 v2 和 v1 的步骤相同: 1. 注册并登录声网控制台 2. 创建声网项目 3. 进入功能配置,开通 RTM 服务 4. 获取开发所需参数,例如 App ID 如果你没有声网账号,点击[此处](https://sso.shengwang.cn/cn/v4/signup/with-sms)注册账号。关于如何开通服务和如何创建项目,详见[开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service)。 ## 集成 SDK [#集成-sdk-1] v2 和 v1 的 SDK 包名不同,你需要注意区分。二者都支持 CDN 和 CocoaPods 集成。自 v2.3.1 起,通过 CocoaPods 集成 RTM SDK 时,需要添加声网源 `https://download.shengwang.cn/cocoapods/`,并保留项目已有的源。各版本的依赖声明如下: - v1 的引用方式: ```ruby platform :ios, '11.0' target 'Your App' do # 将 x.y.z 替换为具体的 SDK 版本号,如 1.5.1 pod 'AgoraRtm_iOS', 'x.y.z' end ``` - v2 的引用方式: ```ruby source 'https://download.shengwang.cn/cocoapods/' platform :ios, '11.0' target 'Your App' do # 对于 2.2.8 及之后的版本: # RtmKit 为 RTM 主库,RtmBasic 为 aosl 基础库 pod 'ShengWang-Rtm', '2.3.1', :subspecs => ['RtmKit'] pod 'ShengWang-Rtm', '2.3.1', :subspecs => ['RtmBasic'] # 对于 2.2.7 版本: # pod 'ShengwangRtm', 'x.y.z' # 对于 2.2.6 及之前的版本: # pod 'AgoraRtm', 'x.y.z' # 如需获取 2.2.0 之前的版本,请将包名修改为 AgoraRtm_iOS end ``` ## 初始化实例 [#初始化实例-1] 相比于 v1,v2 对初始化参数做了很大的调整,增加了很多新特性,例如端侧加密、云代理等,详见 [API 参考](/zh-CN/api-reference/rtm/ios/configuration#create)。此外,v2 还丰富了接口调用的错误信息,你可以通过 `AgoraRtmErrorInfo` 数据结构获取错误码、错误原因及 API 操作名称,以便于你能更快地排查故障。结合[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)文档,你也可以快速找到解决方法。 :::info[信息] RTM v2 版本在命名字符集的支持上与 v1 版本存在差异。例如,v2 版本不支持以 `"_"` 开头或包含 `"."` 字符的频道名、用户名和 Topic 名等。在从 v1 升级到 v2 或混合使用这两个版本时,需注意字符集差异可能导致的不兼容问题。建议在迁移时统一使用 v2 版本[支持的字符集](/zh-CN/realtime-media/rtm/build/channels-and-topics/channel-basic#合法字符)。 ::: - v1 的示例代码如下: ```objc self.appID = @"your_appid"; _kit = [[AgoraRtmKit alloc] initWithAppId:self.appID delegate:self]; ``` - v2 的示例代码如下: ```objc AgoraRtmClientConfig* rtm_cfg = [[AgoraRtmClientConfig alloc] initWithAppId:@"your_appid" userId:@"your_userid"]; NSError* initError = nil; AgoraRtmClientKit* rtm = [[AgoraRtmClientKit alloc] initWithConfig:rtm_cfg delegate:handler error:&initError]; ``` ## 登录服务 [#登录服务-1] v2 登录服务的方法和 v1 有区别,如下所示: - v1 的示例代码如下: ```objc self.uid = self.UserIDTextField.text; self.token = @"your_token"; [_kit loginByToken:(self.token) user:(self.uid) completion:^(AgoraRtmLoginErrorCode errorCode) { if (errorCode != AgoraRtmLoginErrorOk){ self.text = [NSString stringWithFormat:@"Login failed for user %@. Code: %ld",self.uid, (long)errorCode]; NSLog(@"%@", self.text); } else { NSLog(@"%@", self.text); self.text = [NSString stringWithFormat:@"Login successful for user %@. Code: %ld",self.uid, (long)errorCode]; } }]; ``` - v2 的示例代码如下: ```objc [rtm loginByToken:@"token" completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"login success!!"); } else { NSLog(@"login failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` ## 事件通知 [#事件通知-1] 相比于 v1,v2 重新设计了系统事件通知方式和 API 接口,对事件通知类型进行了更详细的分类和聚合,对事件通知的负载数据结构进行了优化。 v2 的事件通知类型有 8 种,如下所示: | 事件类型 | 描述 | |--------------| ---------- | | `didReceiveMessageEvent` | 消息事件通知:接收用户所订阅的 Message Channel 及 Topic 中的所有消息事件通知。 | | `didReceivePresenceEvent` | 用户出席与自定义状态变更事件通知(简称 Presence 事件通知):接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Presence 事件通知。 | | `didReceiveTopicEvent` | Topic 变更事件通知:接收用户所加入的 Stream Channel 中所有 Topic 变更事件通知。 | | `didReceiveStorageEvent` | 频道属性和用户属性事件通知:接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Channel Metadata 事件通知,及订阅用户的 User Metadata 事件通知。 | | `didReceiveLockEvent` | 锁变更事件通知:接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Lock 事件通知。 | | `connectionChangedToState` | (已废弃)网络连接状态变更事件通知:接收客户端网络连接状态变更的事件通知。 | | `didReceiveLinkStateEvent` | 接收客户端网络连接状态变更的事件通知,包含变更前后的连接状态、服务类型、导致变更的操作类型、变更原因、频道列表等信息。 | | `tokenPrivilegeWillExpire` | 接收客户端 Token 将要过期的事件通知。 | 关于事件通知的更多信息及负载数据结构见[事件监听](/zh-CN/api-reference/rtm/ios/configuration#事件监听)。 以监听频道消息 `didReceiveMessageEvent` 事件通知为例,示例代码如下: - v1: ```objc @interface ChannelListener () @end @implementation ChannelListener - (void)channel:(AgoraRtmChannel *)channel messageReceived:(AgoraRtmMessage *)message fromMember:(AgoraRtmMember *)member { self.text = [NSString stringWithFormat:@"Message received in channel: %@ from user: %@ content: %@",member.channelId, member.userId, message.text]; [self AddMsgToRecord:(self.text)]; } @end ChannelListener* handler = [[ChannelListener alloc] init]; channel = [rtm createChannelWithId:self.channelID delegate:handler]; ``` - v2: ```objc @interface RtmListener : NSObject @end @implementation RtmListener -(void) rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveMessageEvent:(AgoraRtmMessageEvent *)event {} @end // 方式一:调用 initWithAppId 方法初始化 RTM Client 实例时添加事件监听 AgoraRtmClientConfig* rtm_cfg = [[AgoraRtmClientConfig alloc] initWithAppId:@"your_appid" userId:@"your_userid"]; RtmListener* handler = [[RtmListener alloc] init]; NSError* initError = nil; AgoraRtmClientKit* rtm = [[AgoraRtmClientKit alloc] initWithConfig:rtm_cfg delegate:handler error:&initError]; // 方式二:在 App 生命周期的任意时间中添加事件监听 [rtm addDelegate:handler]; ``` 从上面的示例代码可以看出以下显著区别: - v1 的频道消息事件通知绑定在具体的 `channel` 实例上,用户需要先调用 `createChannelWithId:delegate` 方法创建 `channel` 实例,然后注册 `messageReceived` 回调处理事件,SDK 会在收到消息后通过该回调通知处理程序,并且多个频道要实现绑定多次。而 v2 的消息事件通知绑定在客户端实例上,是全局设置:在创建并初始化 `AgoraRtmClientKit` 实例时注册事件监听实例,只需要绑定一次,就可以监听所有订阅的频道或 Topic。 - v1 的消息事件通知负载数据结构包含的信息相对较少,而 v2 的消息事件通知负载数据结构包含了更多的信息,可以帮助你更好地实现自己的业务。 ## 频道消息 [#频道消息-1] 在 1.x 中,发送频道消息的步骤如下: 1. 创建一个频道实例 2. 加入频道 3. 发送频道消息 这种设计会有个弊端,你无法实现发送消息而不收到消息。因为发送消息和接收消息没有解耦。v2 采用了基于 Pub/Sub 的新设计,将频道消息的发送和接收解耦:你无需加入频道即可向指定频道发送消息,你只需订阅指定频道即可接收该频道中的消息,两种操作互不影响。 - v1 的示例代码如下: ```objc // 创建 RTM 频道 _channel = [_kit createChannelWithId:self.channelID delegate:self]; // 加入 RTM 频道 [_channel joinWithCompletion:^(AgoraRtmJoinChannelErrorCode errorCode) { if(errorCode == AgoraRtmJoinChannelErrorOk){ self.text = [NSString stringWithFormat:@"Successfully joined channel %@ Code: %ld",self.channelID,(long)errorCode]; NSLog(@"%@", self.text); } else { self.text = [NSString stringWithFormat:@"Failed to join channel %@ Code: %ld",self.channelID, (long)errorCode]; NSLog(@"%@", self.text); } }]; // 发送频道消息 [_channel sendMessage:[[AgoraRtmMessage alloc] initWithText:self.channelMsg] sendMessageOptions:self.options completion:^(AgoraRtmSendChannelMessageErrorCode errorCode) { if (errorCode == AgoraRtmSendChannelMessageErrorOk) { self.text = [NSString stringWithFormat:@"Message sent to channel %@ : %@", self.channelID, self.channelMsg]; } else { self.text = [NSString stringWithFormat:@"Message failed to send to channel %@ : %@ ErrorCode: %ld", self.channelID, self.channelMsg, (long)errorCode]; } }]; ``` - v2 的示例代码如下: ```objc // 发送频道消息 NSString* message = @"Hello Agora!"; NSString* channel = @"your_channel"; [rtm publish:channel message:message option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"publish success!!"); } else { NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; // 订阅频道 AgoraRtmSubscribeOptions* opt = [[AgoraRtmSubscribeOptions alloc] init]; opt.features = AgoraRtmSubscribeChannelFeatureMessage|AgoraRtmSubscribeChannelFeaturePresence; [rtm subscribeWithChannel:@"you_channel" option:opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"subscribe success!!"); } else { NSLog(@"subscribe failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` ## 点对点消息 [#点对点消息-1] v1 版本中的点对点消息 API 用于向指定的用户发送消息,例如,你如果需要向用户 ID 为 `Tony` 的用户发送消息,你可以按照如下方式实现: ```objc // v1 self.peerMsg = self.PeerMsgTextField.text; self.peerID = self.PeerIDTextField.text; [_kit sendMessage:[[AgoraRtmMessage alloc] initWithText:self.peerMsg] toPeer:self.peerID completion:^(AgoraRtmSendPeerMessageErrorCode errorCode) { if (errorCode == AgoraRtmSendPeerMessageErrorOk) { self.text = [NSString stringWithFormat:@"Message sent from user: %@ to user: %@ content: %@", self.uid, self.peerID, self.peerMsg]; } else { self.text = [NSString stringWithFormat:@"Message failed to send from user: %@ to user: %@ content: %@ Error: %ld", self.uid, self.peerID, self.peerMsg, (long)errorCode]; } }]; ``` 自 2.2.0 版本起,我们对点对点消息进行了调整,将其定义为用户频道(User Channel):通过 `publish` 方法发送消息,通过 `didReceiveMessageEvent` 事件通知接收消息。这一新方法的实现效果与 v1 版本中的点对点消息功能完全一致,你可以按以下方式实现: ```objc // v2 // 适用于 2.2.0 及之后版本 NSString* message = @"Hello Agora!"; NSString* user = @"Tony"; AgoraRtmPublishOptions* publish_option = [[AgoraRtmPublishOptions alloc] init]; publish_option.channelType = AgoraRtmChannelTypeUser; [rtm publish:user message:message option:publish_option completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"publish success!!"); } else { NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` 当然,你也可以通过 Message Channel 来实现收件箱功能。只不过这种方式,发送方无法收到送达回执。 ```objc // v2 // 1. 订阅自己收件箱 [_kit subscribeWithChannel:"inbox_Tony" option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if(errorInfo == nil) { self.text = [NSString stringWithFormat:@"Successfully subscribe channel %@",self.channelID]; NSLog(@"%@", self.text); } else { self.text = [NSString stringWithFormat:@"Failed to subscribe channel %@ Code: %ld",self.channelID, (long)errorInfo.errorCode]; NSLog(@"%@", self.text); } }]; // 消息内容 NSString* payload = @"{ type: "PrivateMessage", message: "This is a message", sender: "Tony" }"; // 2. 向 Lily 发送消息 [rtm publish:"inbox_Lily" message:message option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"publish success!!"); } else { NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` ## 图片与文件消息 [#图片与文件消息-1] 出于对用户数据和隐私保护合规性、成本优化的考虑,RTM 自 1.5.0 版本起不再直接支持传输图片和文件消息,相关的 API 也已经下架。你可以结合 RTM 和第三方对象存储服务(例如 Amazon S3 或者阿里云 OSS)来构建图片与文件消息功能,在获得极佳的实时消息传输体验的同时,还能实现更灵活的技术构建方案,例如,实现 CDN 静态资源加速、图片文本审核等业务需求。以下示例代码向你展示如何使用 v2 和 Amazon S3 对象存储服务实现图片和文件消息的构建和发送: ```objc // 文件上传成功后,自定义 RTM 文件消息负载结构 NSString* imageMessagePayload = @"{ // 文件类型,接收方可以根据此字段解析消息包结构 type:'File', // 你在 Amazon S3 上的 bucket 名称,接收方需要此字段来下载文件 bucket:uploadParams.Bucket, // 文件在 Amazon S3 存储的 Key,接收方需要此字段来下载文件 key:uploadParams.Key, // 文件类型 contentType:uploadParams.ContentType, // 文件 URL 地址 url:data.Location, // 发送方的用户 ID sender:userId }"; // 使用 RTM v2 发送文件消息负载 AgoraRtmPublishOptions* option = [[AgoraRtmPublishOptions alloc] init]; option.customType = @"File"; [rtm publish:channelName message:imageMessagePayload option:option completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"publish success!!"); } else { NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` :::info[信息] 使用 Amazon S3 实现静态文件存储时,你需要进入 Amazon S3 控制台,然后设置正确的用户权限和访问策略。详见[访问控制最佳实践](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/access-control-best-practices.html)。 ::: ## 用户出席与自定义状态 [#用户出席与自定义状态-1] 在 v1 中,你可以订阅或查询多个用户的在线状态、查询频道人数或频道在线成员列表等。v2 不仅保留了这些能力,还在 v1 的基础上进行了升级和扩展,新设计了 Presence 模块。Presence 模块提供监控用户上线、下线及用户临时状态变更的能力,你可以实时获取以下信息: - 用户加入或离开指定频道 - 自定义临时用户状态及其变更 - 查询指定用户加入或订阅了哪些频道 - 查询指定频道有哪些用户加入及其用户临时状态数据 你可以调用 `whoNow` 方法,实时查询指定频道的在线用户数量、在线用户列表及在线用户的临时状态等信息。 ```objc // v2 AgoraRtmPresenceOptions* presence_opt = [[AgoraRtmPresence alloc] init]; presence_opt.includeState = false; presence_opt.includeUserId = false; [[rtm getPresence] whoNow:@"your_channel" channelType:AgoraRtmChannelTypeMessage options:presence_opt completion:^(AgoraRtmWhoNowResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"whoNow success!!"); int user_count = response.totalOccupancy; } else { NSLog(@"whoNow failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` 你可以调用 `whereNow` 方法,实时获取指定用户所在频道的列表。 ```objc // v2 [[rtm getPresence] whereNow:@"userId" completion:^(AgoraRtmWhereNowResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"whereNow success!!"); int channel_count = response.totalChannel; NSArray * channels = response.channels; } else { NSLog(@"whereNow failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` 为满足业务场景对用户状态的设置需求,v2 提供了设置临时用户状态的能力,你可以通过 `setState` 方法自定义临时用户状态。用户可以为自己添加分数、游戏状态、位置、心情、连麦状态等自定义状态。 ```objc // v2 NSDictionary *states = @{@"key1": @"value1", @"key2": @"value2"}; [[rtm getPresence] setState:@"your_channel" channelType:AgoraRtmChannelTypeMessage items:states completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"setState success!!"); } else { NSLog(@"setState failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` 你也可以随时通过 `getState` 方法获取用户的在线状态,或者通过 `removeState` 方法删除用户的状态。用户临时状态变更后,RTM 服务器会触发 `AgoraRtmPresenceEventTypeRemoteStateChanged` 类型的 `didReceivePresenceEvent` 事件通知。具体用法见[临时用户状态](/zh-CN/realtime-media/rtm/build/state-and-attributes/temporary-user-state)。 在 v2 中,实时监听频道中用户加入、离开、超时掉线或临时状态变更通知会更加方便,你只需实现如下步骤: 1. 实现 Presence 事件监听程序 2. 加入频道时,开启 `withPresence` 开关 ```objc // v2 // 1. 实现 Presence 事件监听程序 @interface RtmListener : NSObject @end @implementation RtmListener // Presence 事件通知 -(void) rtmKit:(AgoraRtmClientKit *)rtmKit didReceivePresenceEvent:(AgoraRtmPresenceEvent *)event { // 实现代码 } @end // 2. 加入频道时,开启 withPresence 开关 AgoraRtmSubscribeOptions* option = [[AgoraRtmSubscribeOptions alloc] init]; option.features = AgoraRtmSubscribeChannelFeaturePresence; [rtm subscribeWithChannel:@"you_channel" option:opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"subscribe success!!"); } else { NSLog(@"subscribe failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` v2 对实时通知进行了全新的设计,在频道中采取两种模式将 Presence 事件通知到订阅用户:**实时通知模式 (Announce)** 和**定时通知模式 (Interval)**。你可以在控制台的项目设置中通过**实时通知最大人数**大小来决定两种模式相互切换的条件。其中,定时通知模式可防止频道内在线用户过多而导致的事件嘈杂,详见[事件通知模式](/zh-CN/realtime-media/rtm/build/state-and-attributes/presence-events#事件通知模式)。 ## 用户属性与频道属性 [#用户属性与频道属性-1] 基于 v1 的用户属性和频道属性功能,v2 新增了版本控制和锁控制等能力,并优化了 API 接口形式,让功能的使用更加简单。v2 中把用户属性和频道属性挂载在 Storage 模块下,以设置频道属性为例,示例代码如下: ```objc // v2 // 创建 Metadata AgoraRtmMetadata* metadata = [[AgoraRtmMetadata alloc] init]; // 设置 Metadata Item AgoraRtmMetadataItem* apple = [[AgoraRtmMetadataItem alloc] init]; apple.key = @"Apple"; apple.value = @"100"; apple.revision = 174298200; AgoraRtmMetadataItem* banana = [[AgoraRtmMetadataItem alloc] init]; banana.key = @"Banana"; banana.value = @"200"; banana.revision = 174298100; NSArray *item_array = [NSArray arrayWithObjects:apple,banana]; metadata.items = item_array; metadata.majorRevision = 174298100; // 记录设置 Metadata Item 的时间戳和用户 ID AgoraRtmMetadataOptions* metadata_opt = [[AgoraRtmMetadataOptions alloc] init]; metadata_opt.recordUserId = true; metadata_opt.recordTs = true; [[rtm getStorage] setChannelMetadata:@"channel_name" channelType:AgoraRtmChannelTypeMessage data:metadata options:metadata_opt lock:@"lockName" completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"setChannelMetadata success!!"); } else { NSLog(@"setChannelMetadata failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` 如何获取、更新、删除频道属性,如何使用 CAS 控制、锁控制等可以参考[频道属性](/zh-CN/realtime-media/rtm/build/state-and-attributes/channel-metadata)。用户属性的使用与频道属性是类似的,详见[用户属性](/zh-CN/realtime-media/rtm/build/state-and-attributes/user-metadata)。 v2 通过 `didReceiveStorageEvent` 类型的事件通知将频道属性和用户属性分发给用户,监听 `didReceiveStorageEvent` 事件通知的步骤如下: 1. 实现 Storage 事件监听程序 2. 加入频道时,开启 `withMetadata` 开关 ```objc // v2 // 1. 实现 Storage 事件监听程序 @interface RtmListener : NSObject @end @implementation RtmListener // Storage 事件通知 -(void) rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveStorageEvent:(AgoraRtmStorageEvent *)event { // 实现代码 } @end // 2. 加入频道时,添加 Metadata 的 feature AgoraRtmSubscribeOptions* option = [[AgoraRtmSubscribeOptions alloc] init]; option.features = AgoraRtmSubscribeChannelFeatureMetadata; [rtm subscribeWithChannel:@"you_channel" option:opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) { if (errorInfo == nil) { NSLog(@"subscribe success!!"); } else { NSLog(@"subscribe failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason); } }]; ``` ## 访问区域限定 [#访问区域限定-1] RTM 支持限定访问区域功能,以适应不同国家或地区的法律法规。开启限定访问区域功能后,不论用户在哪个区域使用你的 App,SDK 都只会访问指定区域的声网服务器。v2 实现访问区域限定的代码和 v1 有区别。 - v1 的示例代码如下: ```objc AgoraRtmServiceContext* context = [[AgoraRtmServiceContext alloc] init]; context.areaCode = AgoraAreaCodeGLOB; [AgoraRtmKit setRtmServiceContext:context]; ``` - v2 的示例代码如下: ```objc AgoraRtmClientConfig* rtm_config = [[AgoraRtmClientConfig alloc] initWithAppId:_appID userId:_uid]; rtm_config.areaCode = AgoraRtmAreaCodeGLOB; NSError* initError = nil; AgoraRtmClientKit* rtm = [[AgoraRtmClientKit alloc] initWithConfig:rtm_config delegate:self error:&initError]; ``` ## 其他新特性 [#其他新特性-1] 除上述版本之间的功能差异之外,v2 还额外增加了很多被广泛验证和使用的新功能,你可以根据项目的需要选择和使用,相信革新版本的 v2 一定可以帮助你快速接入实时互动领域。v2 所具备的功能特性见[特性列表](/zh-CN/realtime-media/rtm/reference/capabilities-and-compatibility/feature-list)。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" /> 自 2023 年 6 月起,声网针对市场及行业需求,先后推出了 RTM v2(以下简称 v2)系列版本。此系列版本在功能、性能、体验上都有创新性提升: - **功能覆盖**:该版本通过引入 `Channel`、`Message`、`Topic`、`Presence`、`Storage` 和 `Lock` 等功能模块,能覆盖更多业务场景,你可以把更多的精力集中在自己的业务创新上。 - **性能提升**:我们在新版本中重构了后台架构,通过优化网络连接进一步提升性能,提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力,让你无需为业务质量担忧。 - **体验优化**:我们重新设计并简化了 API 接口,支持业界最流行的 Async/Await 编程模式;优化了包括用户指南、API 参考在内的所有文档,提供了更全面的示例程序,支持开发者低成本学习使用 SDK,快速完成集成,提高开发效率。 本文提供 RTM v1 和 v2 的主要区别及相关示例代码,从而帮助用户顺利地从 v1 迁移到 v2。 ## 开通服务 [#开通服务-2] 开通 v2 和 v1 的步骤相同: 1. 注册并登录声网控制台 2. 创建声网项目 3. 进入功能配置,开通 RTM 服务 4. 获取开发所需参数,例如 App ID 如果你没有声网账号,点击[此处](https://sso.shengwang.cn/cn/v4/signup/with-sms)注册账号。关于如何开通服务和如何创建项目,详见[开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service)。 ## 集成 SDK [#集成-sdk-2] v2 和 v1 的 SDK 包名不同,你需要注意区分。不变的是,二者都支持 CDN 和 npm 两种集成方式。 使用 CDN 使用 npm - v1 的引用方式: ```javascript showLineNumbers // 使用 CDN 直接将以下代码添加到你的 Web 应用中,或下载 SDK 文件后在本地引用 // 将 x.y.z 替换为具体的 SDK 版本号,如 1.5.1 ``` - v2 的引用方式: ```javascript showLineNumbers // 使用 CDN 直接将以下代码添加到你的 Web 应用中,或下载 SDK 文件后在本地引用 // 将 x.y.z 替换为具体的 SDK 版本号,如 2.1.9 ``` - v1 的用法: ```javascript showLineNumbers // 1. 在终端通过 npm 包管理器安装 SDK npm install agora-rtm-sdk // 2. 在你的 app.js 中导入 import AgoraRTM from 'agora-rtm-sdk'; ``` - v2 的用法: ```javascript showLineNumbers // 1. 在终端通过 npm 包管理器安装 SDK npm install agora-rtm // 2. 在你的 app.js 中导入 import AgoraRTM from 'agora-rtm'; ``` :::info[信息] v2 的 SDK 包名为 `agora-rtm`,而 v1 的 SDK 包名为 `agora-rtm-sdk`。 ::: ## 初始化实例 [#初始化实例-2] 相比于 v1,v2 对初始化参数做了很大的调整,增加了很多新特性,例如端侧加密、云代理等,详见 [API 参考](/zh-CN/api-reference/rtm/web/configuration#Init)。此外,v2 还对 `try{...}catch{...}` 编程模式中捕获的错误信息进行了优化:将可能出现的错误进行了分类,并通过 `ErrorInfo` 数据结构回调,以便于你能更快地排查故障。结合[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)文档,你也可以快速找到解决方法。 :::info[信息] RTM v2 版本在命名字符集的支持上与 v1 版本存在差异。例如,v2 版本不支持以 `"_"` 开头或包含 `"."` 字符的频道名、用户名和 Topic 名等。在从 v1 升级到 v2 或混合使用这两个版本时,需注意字符集差异可能导致的不兼容问题。建议在迁移时统一使用 v2 版本[支持的字符集](/zh-CN/realtime-media/rtm/build/channels-and-topics/channel-basic#合法字符)。 ::: - v1 的示例代码如下: ```javascript let options = { uid: "", token: "" } // 填入你从控制台获得的 App ID const appID = ""; // 填入你的用户 ID options.uid = ""; // 填入你的 Token options.token = ""; // 初始化客户端实例 const rtm = AgoraRTM.createInstance(appID); ``` - v2 的示例代码如下: ```javascript // 初始化客户端实例 const { RTM } = AgoraRTM; // 填入你从控制台获得的 App ID const appId = "your_appId"; // 填入你的用户 ID const userId = "your_userId"; try { const rtm = new RTM(appId, userId); } catch (status) { console.log(status); } ``` ## 登录服务 [#登录服务-2] v2 采用了标准的 Async/Await 模式,支持异步编程。v2 登录服务的方法和 v1 有区别,如下所示: - v1 的示例代码如下: ```javascript await rtm.login(options) ``` - v2 的示例代码如下: ```javascript const token = 'your_token' try { const result = await rtm.login({ token }); console.log(result); } catch (status) { console.log(status); } ``` ## 事件通知 [#事件通知-2] 相比于 v1,v2 重新设计了系统事件通知方式和 API 接口,对事件通知类型进行了更详细的分类和聚合,对事件通知的负载数据结构进行了优化。 v2 的事件通知类型有 8 种,如下所示: | 事件类型 | 描述 | |--------------| ---------- | | message | 消息事件通知:接收用户所订阅的 Message Channel 及 Topic 中的所有消息事件通知。 | | presence | 用户出席与自定义状态变更事件通知(简称 Presence 事件通知):接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Presence 事件通知。 | | topic | Topic 变更事件通知:接收用户所加入的 Stream Channel 中所有 Topic 变更事件通知。 | | storage | 频道属性和用户属性事件通知:接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Channel Metadata 事件通知,及订阅用户的 User Metadata 事件通知。 | | lock | 锁变更事件通知:接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Lock 事件通知。 | | status | 网络连接状态变更事件通知:接收客户端网络连接状态变更的事件通知。 | | `linkState` | 接收客户端网络连接状态变更的事件通知,包含变更前后的连接状态、服务类型、导致变更的操作类型、变更原因、频道列表等信息。 | | tokenPrivilegeWillExpire | 接收客户端 Token 将要过期的事件通知。 | 关于事件通知的更多信息及负载数据结构见[事件监听](/zh-CN/api-reference/rtm/web/configuration#事件监听)。 以监听 `message` 事件通知为例,示例代码如下: - v1: ```javascript let channel = rtm.createChannel("demoChannel"); channel.on('ChannelMessage', function (message, memberId) { console.log(memberId + ": " + message.text); }) ``` - v2: ```javascript rtm.addEventListener("message", event => { const channelType = event.channelType; const channelName = event.channelName; const topic = event.topicName; const messageType = event.messageType; const customType = event.customType; const publisher = event.publisher; const message = event.message; const timestamp = event.timestamp; }); ``` 从上面的示例代码可以看出以下显著区别: - v1 的消息事件通知绑定在具体的 `channel` 实例上,用户需要先调用 `createChannel()` 方法创建 `channel` 实例,然后才能调用 `channel.on()` 方法绑定事件通知处理程序,并且多个频道要实现绑定多次。而 v2 的消息事件通知绑定在客户端实例上,是全局设置,调用 `addEventListener()` 方法注册回调程序,只需要绑定一次,就可以监听所有订阅的频道或 Topic。 - v1 的消息事件通知负载数据结构包含的信息相对较少,而 v2 的消息事件通知负载数据结构包含了更多的信息,可以帮助你更好地实现自己的业务。 ## 频道消息 [#频道消息-2] 在 1.x 中,发送频道消息的步骤如下: 1. 创建一个频道实例 2. 加入频道 3. 发送频道消息 这种设计会有个弊端,你无法实现发送消息而不收到消息。因为发送消息和接收消息没有解耦。v2 采用了基于 Pub/Sub 的新设计,将频道消息的发送和接收解耦:你无需加入频道即可向指定频道发送消息,你只需订阅指定频道即可接收该频道中的消息,两种操作互不影响。 - v1 的示例代码如下: ```javascript let channel = rtm.createChannel("demoChannel"); await channel.join(); let payload = "Hello World!"; await channel.sendMessage({ text: payload }).then(() => { console.log("Channel message:" + payload + " from " + channel.channelId); } ``` - v2 的示例代码如下: ```javascript // 发送频道消息 const payload = "Hello World!"; try { const result = await rtm.publish("demoChannel", payload, { channelType: 'MESSAGE' }); console.log(result); } catch (status) { console.log(status); } // 订阅频道 try { const result = await rtm.subscribe("chat_room"); console.log(result); } catch (status) { console.log(status); } ``` ## 点对点消息 [#点对点消息-2] v1 版本中的点对点消息 API 用于向指定的用户发送消息,例如,你如果向用户 ID 为 `Tony` 的用户发送消息,你可以按照如下方式实现: ```javascript // v1 rtm .sendMessageToPeer( { text: "test peer message" }, // 一个 RtmMessage 实例 "PeerId", // 远端用户的用户 ID ) .then((sendResult) => { if (sendResult.hasPeerReceived) { // 你需自行实现远端用户收到消息事件的逻辑 } else { // 你需自行实现服务器已收到消息、远端用户未收到消息的逻辑 } }) .catch((error) => { // 你需自行实现点对点消息发送失败的逻辑 }); ``` 自 2.2.0 版本起,我们对点对点消息进行了调整,将其定义为用户频道(User Channel):通过 `publish` 方法发送消息,通过 `message` 事件通知接收消息。这一新方法的实现效果与 v1 版本中的点对点消息功能完全一致,你可以按以下方式实现: ```javascript // v2 // 适用于 2.2.0 及之后版本 rtm .publish( "test peer message", "PeerId", // 远端用户的用户 ID { channelType: "USER" }, ) .then((sendResult) => { // 你需自行实现远端用户收到消息事件的逻辑 }) .catch((error) => { // 你需自行实现点对点消息发送失败的逻辑 }); ``` 当然,你也可以通过 Message Channel 来实现收件箱功能。只不过这种方式,发送方无法收到送达回执。 ```javascript // v2 // 1. 订阅自己的收件箱 const result = await rtm.subscribe("inbox_Tony"); // 消息内容 const payload = JSON.stringify( { type: "PrivateMessage", message: "This is a message", sender: "Tony", } ); try { // 2. 向用户 ID 为 Lily 的用户发送私密消息,这条消息只有 Lily 能收到 const result = await rtm.publish("inbox_Lily", payload, { channelType: 'MESSAGE' }); console.log(result); } catch (status) { console.log(status); } ``` ## 图片与文件消息 [#图片与文件消息-2] 出于对用户数据和隐私保护合规性、成本优化的考虑,RTM 自 1.5.0 版本起不再直接支持传输图片和文件消息,相关的 API 也已经下架。你可以结合 RTM 和第三方对象存储服务(例如 Amazon S3 或者阿里云 OSS)来构建图片与文件消息功能,在获得极佳的实时消息传输体验的同时,还能实现更灵活的技术构建方案,例如,实现 CDN 静态资源加速、图片文本审核等业务需求。以下示例代码向你展示如何使用 v2 和 Amazon S3 对象存储服务实现图片和文件消息的构建和发送: ```javascript const sendFileMessageAsync = async () => { try { // 使用 document-picker 组件选取设备上的需要上传的文件 const result = await DocumentPicker.getDocumentAsync({ // 可以选择任何类型的文件 type: "*/*", }); if (result.canceled === false) { const file = result.assets[0].file; if (file) { const uploadParams = { // 填写你在 Amazon S3 上的 bucket 名称 Bucket: "your-awsbucket", // 文件在 Amazon S3 上的键 Key: file.name, Body: file, ContentType: file.type, }; // 上传文件到 S3 上 s3.upload(uploadParams, (err, data) => { if (err) { console.error("Error uploading file:", err); } else { console.log("File uploaded successfully. S3 URL:", data.Location); // 文件上传成功后,自定义 RTM 文件消息负载结构 const imageMessagePayload = { // 文件类型,接收方可以根据此字段解析消息包结构 type: "File", // 你在 Amazon S3 上的 bucket 名称,接收方需要此字段来下载文件 bucket: uploadParams.Bucket, // 文件在 Amazon S3 存储的 Key,接收方需要此字段来下载文件 key: uploadParams.Key, // 文件类型 contentType: uploadParams.ContentType, // 文件 URL 地址 url: data.Location, // 发送方的用户 ID sender: userId, }; // 使用 RTM v2 发送文件消息负载 rtm.publish(channelName, JSON.stringify(imageMessagePayload), { customType: "File", channelType: "MESSAGE", }); } }); } } else { console.log("Document pick cancelled"); } } catch (err) { console.error("Error picking document:", err); } }; ``` :::info[信息] 使用 Amazon S3 实现静态文件存储时,你需要进入 Amazon S3 控制台,然后设置正确的用户权限和访问策略。详见[访问控制最佳实践](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/access-control-best-practices.html)。 ::: ## 用户出席与自定义状态 [#用户出席与自定义状态-2] 在 v1 中,你可以订阅或查询多个用户的在线状态、查询频道人数或频道在线成员列表等。v2 不仅保留了这些能力,还在 v1 的基础上进行了升级和扩展,新设计了 Presence 模块。Presence 模块提供监控用户上线、下线及用户临时状态变更的能力,你可以实时获取以下信息: - 用户加入或离开指定频道 - 自定义临时用户状态及其变更 - 查询指定用户加入或订阅了哪些频道 - 查询指定频道有哪些用户加入及其用户临时状态数据 你可以调用 `whoNow` 方法,实时查询指定频道的在线用户数量、在线用户列表及在线用户的临时状态等信息。 ```javascript // v2 const options = { includeUserId : true, includeState : true, page : "yourBookMark" } try{ const result = await rtm.presence.whoNow( "chat_room", "MESSAGE", options ); console.log(result); } catch(status){ console.log(status); } ``` 你可以调用 `whereNow` 方法,实时获取指定用户所在频道的列表。 ```javascript // v2 try{ const result = await rtm.presence.whereNow( "Tony" ); console.log(result); } catch(status){ console.log(status); } ``` 为满足业务场景对用户状态的设置需求,v2 提供了设置临时用户状态的能力,你可以通过 `setState` 方法自定义临时用户状态。用户可以为自己添加分数、游戏状态、位置、心情、连麦状态等自定义状态。 ```javascript // v2 var newState = { "mood":"pumped", "isTyping":false}; try{ const result = await rtm.Presence.setState("chat_room", "MESSAGE", newState); console.log(result); } catch(status){ console.log(status); } ``` 你也可以随时通过 `getState` 方法获取用户的在线状态,或者通过 `removeState` 方法删除用户的状态。用户临时状态变更后,RTM 服务器会触发 `REMOTE_STATE_CHANGED` 类型的 `presence` 事件通知。具体用法见[临时用户状态 ](/zh-CN/realtime-media/rtm/build/state-and-attributes/temporary-user-state)。 在 v2 中,实时监听频道中用户加入、离开、超时掉线或临时状态变更通知会更加方便,你只需实现如下步骤: 1. 实现 Presence 事件监听程序 2. 加入频道时,开启 `withPresence` 开关 ```javascript // v2 // 1. 实现 Presence 事件监听程序 rtm.addEventListener("presence", event => { const action = event.eventType; const channelType = event.channelType; const channelName = event.channelName; const publisher = event.publisher; const states = event.stateChanged; const interval = event.interval; const snapshot = event.snapshot; // 你的实现代码 }); // 2. 订阅频道时,开启 withPresence 开关 const options ={ withPresence : true }; try { const result = await rtm.subscribe("chat_room", options); console.log(result); } catch (status) { console.log(status); } ``` v2 对实时通知进行了全新的设计,在频道中采取两种模式将 Presence 事件通知到订阅用户:**实时通知模式 (Announce)** 和**定时通知模式 (Interval)**。你可以在控制台的项目设置中通过**实时通知最大人数**大小来决定两种模式相互切换的条件。其中,定时通知模式可防止频道内在线用户过多而导致的事件嘈杂,详见[事件通知模式](/zh-CN/realtime-media/rtm/build/state-and-attributes/presence-events#事件通知模式)。 ## 用户属性与频道属性 [#用户属性与频道属性-2] 基于 v1 的用户属性和频道属性功能,v2 新增了版本控制和锁控制等能力,并优化了 API 接口形式,让功能的使用更加简单。v2 中把用户属性和频道属性挂载在 Storage 模块下,以设置频道属性为例,示例代码如下: ```javascript // v2 const properties = { key : "Quantity", value : "20" }; const announcement = { key : "Announcement", value : "Welcome to our shop!" }; const price = { key : "T-shirt", value : "100" }; const data = [properties, announcement, price]; const options = { addTimeStamp : true, addUserId : true }; try { const result = await rtm.storage.setChannelMetadata("channel1", "MESSAGE", data, options); console.log(JSON.stringify(result)); } catch (status) { console.log(JSON.stringify(status)); } ``` 如何获取、更新、删除频道属性,如何使用 CAS 控制、锁控制等可以参考[频道属性](/zh-CN/realtime-media/rtm/build/state-and-attributes/channel-metadata)。用户属性的使用与频道属性是类似的,详见[用户属性](/zh-CN/realtime-media/rtm/build/state-and-attributes/user-metadata)。 v2 通过 `storage` 类型的事件通知将频道属性和用户属性分发给用户,监听 `storage` 事件通知的步骤如下: 1. 实现 Storage 事件监听程序 2. 加入频道时,开启 `withMetadata` 开关 ```javascript // v2 // 1. 实现 Storage 事件监听程序 rtm.addEventListener("storage", event => { const channelType = event.channelType; const channelName = event.channelName; const publisher = event.publisher; const storageType = event.storageType; const action = event.eventType; const data = event.data; // 你的实现代码 }); // 2. 加入频道时,开启 withMetadata 开关 const options ={ withMetadata : false }; try { const result = await rtm.subscribe("chat_room", options); console.log(result); } catch (status) { console.log(status); } ``` ## 访问区域限定 [#访问区域限定-2] RTM 支持限定访问区域功能,以适应不同国家或地区的法律法规。开启限定访问区域功能后,不论用户在哪个区域使用你的 App,SDK 都只会访问指定区域的声网服务器。v1 实现访问区域限定的代码如下: ```javascript AgoraRTM.setArea({ areaCodes: ["GLOBAL"], excludedArea: "CHINA" }) ``` v2 同样支持限定访问区域功能,且用法完全一致。 ## 其他新特性 [#其他新特性-2] 除上述版本之间的功能差异之外,v2 还额外增加了很多被广泛验证和使用的新功能,你可以根据项目的需要选择和使用,相信革新版本的 v2 一定可以帮助你快速接入实时互动领域。v2 所具备的功能特性见[特性列表](/zh-CN/realtime-media/rtm/reference/capabilities-and-compatibility/feature-list)。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="cpp" /> 自 2023 年 6 月起,声网针对市场及行业需求,先后推出了 RTM v2(以下简称 v2)系列版本。此系列版本在功能、性能、体验上都有创新性提升: - **功能覆盖**:该版本通过引入 `Channel`、`Message`、`Topic`、`Presence`、`Storage` 和 `Lock` 等功能模块,能覆盖更多业务场景,你可以把更多的精力集中在自己的业务创新上。 - **性能提升**:我们在新版本中重构了后台架构,通过优化网络连接进一步提升性能,提供长时间低延迟、高可靠、大并发、易扩展的实时网络接入能力,让你无需为业务质量担忧。 - **体验优化**:我们重新设计并简化了 API 接口;优化了包括用户指南、API 参考在内的所有文档,提供了更全面的示例程序,支持开发者低成本学习使用 SDK,快速完成集成,提高开发效率。 本文提供 RTM v1 和 v2 的主要区别及相关示例代码,从而帮助用户顺利地从 v1 迁移到 v2。 ## 开通服务 [#开通服务-3] 开通 v2 和 v1 的步骤相同: 1. 注册并登录声网控制台 2. 创建声网项目 3. 进入功能配置,开通 RTM 服务 4. 获取开发所需参数,例如 App ID 如果你没有声网账号,点击[此处](https://sso.shengwang.cn/cn/v4/signup/with-sms)注册账号。关于如何开通服务和如何创建项目,详见[开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service)。 ## 集成 SDK [#集成-sdk-3] v2 和 v1 的 SDK 包名、集成方式都不变。详见[项目配置](/zh-CN/realtime-media/rtm/get-started/quick-start#1-项目配置)。 ## 初始化实例 [#初始化实例-3] 相比于 v1,v2 对初始化参数做了很大的调整,增加了很多新特性,例如端侧加密、云代理等,详见 [API 参考](/zh-CN/api-reference/rtm/cpp/configuration#create)。此外,v2 还丰富了接口调用的错误信息,你可以通过 `RTM_ERROR_CODE` 数据类型获取错误码,以便于你能更快地排查故障。结合[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)文档,你也可以快速找到解决方法。 :::info[信息] RTM v2 版本在命名字符集的支持上与 v1 版本存在差异。例如,v2 版本不支持以 `"_"` 开头或包含 `"."` 字符的频道名、用户名和 Topic 名等。在从 v1 升级到 v2 或混合使用这两个版本时,需注意字符集差异可能导致的不兼容问题。建议在迁移时统一使用 v2 版本[支持的字符集](/zh-CN/realtime-media/rtm/build/channels-and-topics/channel-basic#合法字符)。 ::: - v1 的示例代码如下: ```cpp class RtmEventHandler : public agora::rtm::IRtmServiceEventHandler { // ... }; // 创建 RTM 实例 agora::rtm::IRtmService* p_rs = agora::rtm::createRtmService(); rtmService.reset(p_rs, [](agora::rtm::IRtmService* p) { p->release(); }); // 初始化 RTM 实例 if (rtmService->initialize("your_appId", new RtmEventHandler()) { // 处理初始化报错 } ``` - v2 的示例代码如下: ```cpp class RtmEventHandler : public IRtmEventHandler { // ... }; // 创建并初始化 RTM 实例 RtmConfig config; config.appId = "your_appid"; config.userId = "your_name"; config.eventHandler = new RtmEventHandler(); int errorCode = 0; IRtmClient* rtmClient = createAgoraRtmClient(config, errorCode); if (!rtmClient || errorCode != 0) { // 处理初始化报错 } ``` ## 登录服务 [#登录服务-3] v2 登录服务的方法和 v1 有区别,如下所示: - v1 的示例代码如下: ```cpp // 方法调用 if (rtmService->login("your_token", "your_userId")) { // 处理登录报错 } // 异步回调 class RtmEventHandler : public agora::rtm::IRtmServiceEventHandler { virtual void onLoginSuccess() override { // 登录成功 } virtual void onLoginFailure(agora::rtm::LOGIN_ERR_CODE errorCode) override { // 登录失败 } // ... }; ``` - v2 的示例代码如下: ```cpp // 方法调用 uint64_t requestId = 0; rtmClient->login("your_token", requestId); // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onLoginResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) { if (errorCode != RTM_ERROR_OK) { // 登录失败 } else { // 登录成功 } } // ... }; ``` ## 事件通知 [#事件通知-3] 相比于 v1,v2 重新设计了系统事件通知方式和 API 接口,对事件通知类型进行了更详细的分类和聚合,对事件通知的负载数据结构进行了优化。 v2 的事件通知类型有 8 种,如下所示: | 事件类型 | 描述 | |--------------| ---------- | | `onMessageEvent` | 消息事件通知:接收用户所订阅的 Message Channel 及 Topic 中的所有消息事件通知。 | | `onPresenceEvent` | 用户出席与自定义状态变更事件通知(简称 Presence 事件通知):接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Presence 事件通知。 | | `onTopicEvent` | Topic 变更事件通知:接收用户所加入的 Stream Channel 中所有 Topic 变更事件通知。 | | `onStorageEvent` | 频道属性和用户属性事件通知:接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Channel Metadata 事件通知,及订阅用户的 User Metadata 事件通知。 | | `onLockEvent` | 锁变更事件通知:接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Lock 事件通知。 | | `onConnectionStateChanged` | (已废弃)网络连接状态变更事件通知:接收客户端网络连接状态变更的事件通知。 | | `onLinkStateEvent` | 接收客户端网络连接状态变更的事件通知,包含变更前后的连接状态、服务类型、导致变更的操作类型、变更原因、频道列表等信息。 | | `onTokenPrivilegeWillExpire` | 接收客户端 Token 将要过期的事件通知。 | 关于事件通知的更多信息及负载数据结构见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。 以监听频道消息 `onMessageEvent` 事件通知为例,示例代码如下: - v1: ```cpp class ChannelEventHandler: public agora::rtm::IChannelEventHandler { public: ChannelEventHandler(string channel) { channel_ = channel; } ~ChannelEventHandler() {} virtual void onMessageReceived(const char* userId, const agora::rtm::IMessage *msg) override { // 处理接收到的消息 } // ... }; std::string channelName = "channelName"; agora::rtm::IChannel * channel = rtmService->createChannel(channelName, new ChannelEventHandler(channelName)); ``` - v2: ```cpp class RtmEventHandler: public IRtmEventHandler { void onMessageEvent(const MessageEvent &event) { // 处理接收到的消息 } // ... }; RtmConfig config; config.eventHandler = new RtmEventHandler(); ``` 从上面的示例代码可以看出以下显著区别: - v1 的频道消息事件通知绑定在具体的 `channel` 实例上,用户需要先调用 `createChannel()` 方法创建 `channel` 实例,然后注册 `onMessageReceived` 回调处理事件,SDK 会在收到消息后通过该回调通知处理程序,并且多个频道要实现绑定多次。而 v2 的消息事件通知绑定在客户端实例上,是全局设置,只需要绑定一次,就可以监听所有订阅的频道或 Topic。 - v1 的消息事件通知负载数据结构包含的信息相对较少,而 v2 的消息事件通知负载数据结构包含了更多的信息,可以帮助你更好地实现自己的业务。 ## 频道消息 [#频道消息-3] 在 1.x 中,发送频道消息的步骤如下: 1. 创建一个频道实例 2. 加入频道 3. 发送频道消息 这种设计会有个弊端,你无法实现发送消息而不收到消息。因为发送消息和接收消息没有解耦。v2 采用了基于 Pub/Sub 的新设计,将频道消息的发送和接收解耦:你无需加入频道即可向指定频道发送消息,你只需订阅指定频道即可接收该频道中的消息,两种操作互不影响。 - v1 的示例代码如下: ```cpp // 创建频道 std::string channelName = "channelName"; agora::rtm::IChannel * channel = rtmService->createChannel(channelName, new ChannelEventHandler(channelName)); // 加入频道 channel->join(); // 发送频道消息 std::string message = "Hello World!"; agora::rtm::IMessage* rtmMessage = rtmService->createMessage(); rtmMessage->setText(message.c_str()); channel->sendMessage(rtmMessage); rtmMessage->release(); ``` - v2 的示例代码如下: ```cpp // 发送频道消息 std::string message = "hello world"; PublishOptions options; options.messageType = RTM_MESSAGE_TYPE_STRING; options.channelType = RTM_CHANNEL_TYPE_MESSAGE; options.customType = "PlainText"; uint64_t requestId; rtmClient->publish("channelName", message.c_str(), message.size(), options, requestId); // 发送频道消息的异步回调 class RtmEventHandler : public IRtmEventHandler { void onPublishResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { // publish message failed } else { // publish message success } } // ... }; // 订阅频道 SubscribeOptions options; options.withMessage = true; uint64_t requestId; rtmClient->subscribe("channelName", options, requestId); // 订阅频道的异步回调 class RtmEventHandler : public IRtmEventHandler { void onSubscribeResult(const uint64_t requestId, const char *channelName, RTM_ERROR_CODE errorCode) { if (errorCode != RTM_ERROR_OK) { // subscribe failed } else { // subscribe success } } // ... }; ``` ## 点对点消息 [#点对点消息-3] v1 版本中的点对点消息 API 用于向指定的用户发送消息,例如,你如果需要向用户 ID 为 `Tony` 的用户发送消息,你可以按照如下方式实现: ```cpp // v1 std::string message = "Hello World!"; agora::rtm::IMessage* rtmMessage = rtmService->createMessage(); rtmMessage->setText(message.c_str()); int ret = rtmService->sendMessageToPeer("Tony", rtmMessage); rtmMessage->release(); if (ret) { // 发送消息失败 } ``` 自 2.2.1 版本起,我们对点对点消息进行了调整,将其定义为用户频道(User Channel):通过 `publish` 方法发送消息,通过 `onMessageEvent` 事件通知接收消息。这一新方法的实现效果与 v1 版本中的点对点消息功能完全一致,你可以按以下方式实现: ```cpp // v2 // 适用于 2.2.0 及之后版本 PublishOptions options; options.messageType = RTM_MESSAGE_TYPE_STRING; options.channelType = RTM_CHANNEL_TYPE_USER; options.customType = "PlainText"; std::string message = "Hello world"; uint64_t requestId; rtmClient->publish("Tony", message.c_str(), message.size(), options, requestId); ``` 当然,你也可以通过 Message Channel 来实现收件箱功能。只不过这种方式,发送方无法收到送达回执。 ```cpp // v2 // 1. 订阅自己的收件箱 SubscribeOptions options; options.withMessage = true; uint64_t requestId; rtmClient->subscribe("inbox_Tony", options, requestId); // 2. 向 Lily 发送消息 std::string message = "This is a message"; PublishOptions options; uint64_t requestId; rtmClient->publish("inbox_Lily", message.c_str(), message.size(), options, requestId); ``` ## 图片与文件消息 [#图片与文件消息-3] 出于对用户数据和隐私保护合规性、成本优化的考虑,RTM 自 1.5.0 版本起不再直接支持传输图片和文件消息,相关的 API 也已经下架。你可以结合 RTM 和第三方对象存储服务(例如 Amazon S3 或者阿里云 OSS)来构建图片与文件消息功能,在获得极佳的实时消息传输体验的同时,还能实现更灵活的技术构建方案,例如,实现 CDN 静态资源加速、图片文本审核等业务需求。以下示例代码向你展示如何使用 v2 和 Amazon S3 对象存储服务实现图片和文件消息的构建和发送: ```cpp // 1. 上传文件至 Amazon S3 // 2. 通知 RTM nlohmann::json jsonObject; // 文件类型,接收方可以根据此字段解析消息包结构 jsonObject.put("type", "file"); // 你在 Amazon S3 上的 bucket 名称,接收方需要此字段来下载文件 jsonObject.put("bucket", "uploadParams.Bucket"); // 文件在 Amazon S3 存储的 Key,接收方需要此字段来下载文件 jsonObject.put("key", "uploadParams.Key"); // 文件内容类型 jsonObject.put("contentType", "uploadParams.ContentType"); // 文件 URL 地址 jsonObject.put("url", "data.Location"); PublishOptions options; uint64_t requestId; rtmClient->publish("receiver", jsonObject.dump().c_str(), jsonObject.dump().size(), options, requestId); ``` :::info[信息] 使用 Amazon S3 实现静态文件存储时,你需要进入 Amazon S3 控制台,然后设置正确的用户权限和访问策略。详见[访问控制最佳实践](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/access-control-best-practices.html)。 ::: ## 用户出席与自定义状态 [#用户出席与自定义状态-3] 在 v1 中,你可以订阅或查询多个用户的在线状态、查询频道人数或频道在线成员列表等。v2 不仅保留了这些能力,还在 v1 的基础上进行了升级和扩展,新设计了 Presence 模块。Presence 模块提供监控用户上线、下线及用户临时状态变更的能力,你可以实时获取以下信息: - 用户加入或离开指定频道 - 自定义临时用户状态及其变更 - 查询指定用户加入或订阅了哪些频道 - 查询指定频道有哪些用户加入及其用户临时状态数据 你可以调用 `whoNow` 方法,实时查询指定频道的在线用户数量、在线用户列表及在线用户的临时状态等信息。 ```cpp // v2 // 方法调用 PresenceOptions options; options.includeState = true; options.includeUserId = true; options.page = "yourBookMark"; uint64_t requestId rtmClient->getPresence()->whoNow("channelName", RTM_CHANNEL_TYPE_MESSAGE, options, requestId); // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onWhoNowResult(const uint64_t requestId, const UserState *userStateList, const size_t count, const char *nextPage, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { // 查询在线用户失败 } else { // 处理 whoNow 结果 } } // ... }; ``` 你可以调用 `whereNow` 方法,实时获取指定用户所在频道的列表。 ```cpp // v2 // 方法调用 uint64_t requestId; rtmClient->getPresence()->whereNow("tony", requestId); // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onWhereNowResult(const uint64_t requestId, const ChannelInfo *channels, const size_t count, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { // 查询用户所在频道失败 } else { // 处理 whereNow 结果 } } // ... }; ``` 为满足业务场景对用户状态的设置需求,v2 提供了设置临时用户状态的能力,你可以通过 `setState` 方法自定义临时用户状态。用户可以为自己添加分数、游戏状态、位置、心情、连麦状态等自定义状态。 ```cpp // v2 // 方法调用 std::vector stateItems; StateItem item; item.key = "mood"; item.value = "pumped"; stateItems.push_back(item); uint64_t requestId; rtmClient->getPresence()->setState("channelName", RTM_CHANNEL_TYPE_MESSAGE, stateItems.data(), stateItems.size(), requestId); // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onPresenceSetStateResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { // 设置状态失败 } else { // 设置状态成功 } } // ... }; ``` 你也可以随时通过 `getState` 方法获取用户的在线状态,或者通过 `removeState` 方法删除用户的状态。用户临时状态变更后,RTM 服务器会触发 `RTM_PRESENCE_EVENT_TYPE_REMOTE_STATE_CHANGED` 类型的 `onPresenceEvent` 事件通知。具体用法见[临时用户状态](/zh-CN/realtime-media/rtm/build/state-and-attributes/temporary-user-state)。 在 v2 中,实时监听频道中用户加入、离开、超时掉线或临时状态变更通知会更加方便,你只需实现如下步骤: 1. 实现 Presence 事件监听程序 2. 加入频道时,开启 `withPresence` 开关 ```cpp // v2 // 1. 实现 Presence 事件监听程序 class RtmEventHandler : public IRtmEventHandler { void onPresenceEvent(const PresenceEvent& event) override { // 处理 Presence 事件 } // ... }; RtmConfig config; config.eventHandler = new RtmEventHandler(); // 2. 订阅频道时,开启 withPresence 开关 SubscribeOptions options; options.withPresence = true; uint64_t requestId; rtmClient->subscribe("channelName", options, requestId); ``` v2 对实时通知进行了全新的设计,在频道中采取两种模式将 Presence 事件通知到订阅用户:**实时通知模式 (Announce)** 和**定时通知模式 (Interval)**。你可以在控制台的项目设置中通过**实时通知最大人数**大小来决定两种模式相互切换的条件。其中,定时通知模式可防止频道内在线用户过多而导致的事件嘈杂,详见[事件通知模式](/zh-CN/realtime-media/rtm/build/state-and-attributes/presence-events#事件通知模式)。 ## 用户属性与频道属性 [#用户属性与频道属性-3] 基于 v1 的用户属性和频道属性功能,v2 新增了版本控制和锁控制等能力,并优化了 API 接口形式,让功能的使用更加简单。v2 中把用户属性和频道属性挂载在 Storage 模块下,以设置频道属性为例,示例代码如下: ```cpp // v2 // 方法调用 // 创建 Metadata Metadata metadata; // 设置 Major Revision data.majorRevision = 174298270; // 设置 Metadata Item std::vector items; MetadataItem item0("Apple", "100", 174298200); MetadataItem item1("Banana", "200", 174298100); items.emplace_back(item0); items.emplace_back(item1); metadata.items = items.data(); metadata.itemCount = items.size(); // 记录设置 Metadata Item 的时间戳和用户 ID MetadataOptions options; options.recordTs = true; options.recordUserId = true; uint64_t requestId; rtmClient->getStorage()->setChannelMetadata("channelName", RTM_CHANNEL_TYPE_MESSAGE, metadata, options, "lockName", requestId); // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onSetChannelMetadataResult(const uint64_t requestId, const char *channelName, RTM_CHANNEL_TYPE channelType, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { // 设置频道属性失败 } else { // 设置频道属性成功 } // ... } }; ``` 如何获取、更新、删除频道属性,如何使用 CAS 控制、锁控制等可以参考[频道属性](/zh-CN/realtime-media/rtm/build/state-and-attributes/channel-metadata)。用户属性的使用与频道属性是类似的,详见[用户属性](/zh-CN/realtime-media/rtm/build/state-and-attributes/user-metadata)。 v2 通过 `onStorageEvent` 类型的事件通知将频道属性和用户属性分发给用户,监听 `onStorageEvent` 事件通知的步骤如下: 1. 实现 Storage 事件监听程序 2. 加入频道时,开启 `withMetadata` 开关 ```cpp // v2 // 1. 实现 Storage 事件监听程序 class RtmEventHandler : public IRtmEventHandler { void onStorageEvent(const StorageEvent& event) override { // 处理 Storage 事件 } // ... }; RtmConfig config; config.eventHandler = new RtmEventHandler(); // 2. 加入频道时,开启 withMetadata 开关 SubscribeOptions options; options.withMetadata = true; uint64_t requestId; rtmClient->subscribe("channelName", options, requestId); ``` ## 访问区域限定 [#访问区域限定-3] RTM 支持限定访问区域功能,以适应不同国家或地区的法律法规。开启限定访问区域功能后,不论用户在哪个区域使用你的 App,SDK 都只会访问指定区域的声网服务器。v2 实现访问区域限定的代码和 v1 有区别。 - v1 的示例代码如下: ```cpp // v1 agora::rtm::RtmServiceContext context; context.areaCode = agora::rtm::AREA_CODE_GLOB; setRtmServiceContext(context); ``` - v2 的示例代码如下: ```cpp // v2 RtmConfig config; config.areaCode = RTM_AREA_CODE_GLOB; ``` ## 其他新特性 [#其他新特性-3] 除上述版本之间的功能差异之外,v2 还额外增加了很多被广泛验证和使用的新功能,你可以根据项目的需要选择和使用,相信革新版本的 v2 一定可以帮助你快速接入实时互动领域。v2 所具备的功能特性见[特性列表](/zh-CN/realtime-media/rtm/reference/capabilities-and-compatibility/feature-list)。 <_PlatformProcessedMarker close="true" />