应用配置

在开始配置你的应用之前，你需要先了解用户 ID、服务类型等概念，然后下载并安装 SDK，再初始化一个 RTM 对象实例，最后实现事件监听函数以捕获 RTM 实时网络中的所有事件通知。

用户 ID（userId）

用户 ID 是一个用于标识用户和设备的 ASCII 码字符串，长度最多为 64 个字符。在初始化 RTM 客户端实例时，你需要自行定义用户 ID 并将其传递给 userId 参数。RTM 规定在同一个 App ID（appId）下，每个用户或设备都必须具有唯一的全局用户 ID。

为了正确使用 RTM，你需要了解用户、设备和客户端的概念：

• 用户: 是指应用的实际使用者。
• 设备: 是指实际接入 RTM 网络的终端，包括但不限于手机、电脑、智能手表等 IoT 设备。
• 客户端: 是指运行在设备上的 RTM 对象实例。

一个用户可能拥有多台设备，而一台设备也有可能被多人拥有。为更好地区分不同的设备和用户，RTM 规定同一个用户 ID 不能在多台设备上同时登录 RTM 服务、一台设备上不能同时存在多个 RTM 客户端。如果一个用户拥有多台设备，则需要为每台设备都分配唯一的用户 ID。如果两台拥有相同用户 ID 的设备同时登录 RTM 服务，那么先登录上的设备会被后登录的设备挤下线，而被强制下线的设备会收到相应的事件通知。

在实际场景中，业务层的用户名和 RTM 的用户 ID 可能不同，你需要自行实现二者的映射与绑定逻辑。例如，用户先通过用户名登录你的业务服务器，服务器再生成对应的用户 ID，然后使用该用户 ID 初始化并登录 RTM 服务。

此外，用户 ID 也会影响计费和在线状态通知等功能的使用，所以声网建议你为用户和设备分配全局唯一的用户 ID 并在整个生命周期内保持不变。

服务类型

基于不同的传输连接，RTM SDK 提供的功能可以被划分为两种服务类型： MESSAGE 服务和 STREAM 服务。

• MESSAGE 服务涵盖了 Message Channel、User Channel、Presence、Storage、Lock、Token 鉴权等功能特性，通过 AgoraRtmClientKit 实例调用 API。
• STREAM 服务则提供了 Stream Channel、Topic 等功能，通过 AgoraRtmStreamChannel 实例调用 API。

在 MESSAGE 服务中，所有功能特性将共享一条传输连接，该连接在 loginByToken 时建立，在 logout 时关闭。而在 STREAM 服务中，传输连接的数量取决于加入的 STREAM CHANNEL 数量，即每个加入的 STREAM CHANNEL 实例都拥有独立的连接，连接在 joinWithOption 时建立，在 leave 时关闭。所有传输连接都由 SDK 统一管理，并通过 didReceiveLinkStateEvent 事件通知给用户，详见连接管理。深入理解 RTM 服务类型的区别，将有助于更有效地利用 RTM 提供的卓越功能。

此外，服务类型还涉及私有化配置的选择。用户可以选择私有化一个服务，或者同时私有化两种服务，具体取决于应用场景和预算。详见私有化配置。

连接协议配置

为保证连接的稳定性和服务的持续可用性，RTM 客户端与边缘服务器建立连接时会为每种服务（MESSAGE 服务和 STREAM 服务）分别建立两条传输链路。默认情况下，这两条链路分别基于 TCP 协议和 UDP 协议，这种设计使得任何一条链路出现网络问题都不会影响传输效果。相较于其他基于 WebSocket 的消息传输方案，RTM 的冗余链路设计能够最大程度地提升传输稳定性和消息到达率。

在某些情况下，用户可能会发现他们的网络不支持 UDP 端口的传输，这可能是暂时的，也可能是永久性的。在这种情况下，为了确保双链路设计能够最大程度地发挥作用，SDK 允许用户将两条链路都配置成 TCP 协议，只需在 AgoraRtmClientConfig 中设置 protocolType 字段即可。以下是一个将双链路都配置为 TCP 协议的代码示例：

Objective-C

AgoraRtmClientConfig* rtm_config = [[AgoraRtmClientConfig alloc] initWithAppId:@"your_appid" userId:@"your_userid"];
rtm_config.protocolType = AgoraRtmProtocolTypeTcpOnly;

信息

SDK 不支持将两条链路同时配置为 UDP 协议。

安装 SDK

你可以通过以下方式获取最新的 RTM Objective-C SDK。

使用 CDN

1. 点击此处下载最新版本的 Objective-C SDK。
2. 复制 SDK 包中 /libs 路径下所有的 xcframework 文件至项目路径下。
3. 打开 Xcode，进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单。
4. 点击 + > Add Other… > Add Files 添加所有的 xcframework 文件，并确保添加的动态库 Embed 属性设置为 Embed & Sign。

添加完成后，项目会自动链接所需系统库。

使用 Cocoapods

1. 开始前请确保你已安装 Cocoapods，如尚未安装 Cocoapods，参考 Getting Started with CocoaPods 安装说明。

2. 在终端里进入项目根目录，并运行 pod init 命令。项目文件夹下会生成一个 Podfile 文本文件。

3. 打开 Podfile 文件，修改文件为如下内容。注意将 Your App 替换为你的 Target 名称。

   Ruby

   platform :ios, '11.0'
   target 'Your App' do
      # 将 x.y.z 替换为具体的 SDK 版本号，如 2.2.0
      # 可通过发版说明获取最新版本号
      # 当前示例仅适用于 2.2.0 及之后版本
      # 如需获取 2.2.0 之前的版本，请将包名修改为 AgoraRtm_iOS
      pod 'AgoraRtm', 'x.y.z'
   
      # 如果你使用的是 2.2.2 或之后版本的 RTM SDK，且项目中同时使用了 RTC SDK v4.3.0 或以上版本
      # pod 'AgoraRtm', 'x.y.z', :subspecs => ['RtmKit']
   end

4. 在终端内运行 pod install 命令安装声网 SDK。成功安装后，Terminal 中会显示 Pod installation complete!。

5. 成功安装后，项目文件夹下会生成一个后缀为 .xcworkspace 的文件，通过 Xcode 打开该文件进行后续操作。

详细流程参考快速开始。

初始化 RTM 实例

在使用 RTM 功能前，你需要使用 appId 和 userId 来初始化一个 RTM 实例。在后续的示例代码中，你需要将 your_appId 和 your_userId 字段都替换为你自己的 appId 和 userId。

信息

初始化 RTM 对象时的 appId 和 userId 为必填参数，如果缺失，则初始化会失败。

在一个客户端中，你只需要初始化一次 RTM 对象实例，即可在后续实现中通过该对象实例调用 RTM 的其他 API。

Objective-C

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];

现在，你就可以使用 AgoraRtmClientKit 对象调用 RTM 的其他 API 接口了。

日志设置

当你的应用处于开发、测试阶段时，你可能需要 SDK 输出更详细的信息来定位并修复问题。你可以在初始化 RTM 实例的时候通过设置 AgoraRtmClientConfig 中的 AgoraRtmLogLevel 来开启日志输出并设置日志信息等级，之后即可在浏览器的控制台中查看日志信息。

Objective-C

AgoraRtmClientConfig* rtm_cfg = [[AgoraRtmClientConfig alloc] initWithAppId:@"your_appid" userId:@"your_userid"];

// set log config
AgoraRtmLogConfig* log_cfg = [[AgoraRtmLogConfig alloc] init];
log_cfg.level= AgoraRtmLogLevelError;
log_cfg.filePath= @"your_path";
log_cfg.fileSizeInKB = 512;

rtm_cfg.logConfig = log_cfg;

NSError* initError = nil;
AgoraRtmClientKit* rtm = [[AgoraRtmClientKit alloc] initWithConfig:rtm_cfg delegate:handler error:&initError];
if (rtm != nil) {
    NSLog(@"init rtm success!!");
} else {
    NSLog(@"init rtm failed!!");
}

日志有以下五种等级：

信息

在你的应用上线时，你需要将日志等级参数设置为 AgoraRtmLogLevelInfo。

枚举值	描述
AgoraRtmLogLevelNone	0x0000: 不输出任何日志。
AgoraRtmLogLevelInfo	0x0001: 输出 AgoraRtmLogLevelFatal、AgoraRtmLogLevelError、AgoraRtmLogLevelWarn、AgoraRtmLogLevelInfo 级别的日志。我们推荐你将日志级别设为该等级。
AgoraRtmLogLevelWarn	0x0002: 仅输出 AgoraRtmLogLevelFatal、AgoraRtmLogLevelError、AgoraRtmLogLevelWarn 级别的日志。
AgoraRtmLogLevelError	0x0004: 仅输出 AgoraRtmLogLevelFatal、AgoraRtmLogLevelError 级别的日志。
AgoraRtmLogLevelFatal	0x0008: 仅输出 AgoraRtmLogLevelFatal 级别的日志。

Proxy 设置

在一些网络服务受限的环境下，你可能需要设置代理服务才能访问外部资源。RTM 支持设置 Proxy 代理服务，你只需要在初始化 RTM 实例的时候开启这项功能即可。

Objective-C

AgoraRtmClientConfig* rtm_cfg = [[AgoraRtmClientConfig alloc] initWithAppId:@"your_appid" userId:@"your_userid"];

// set proxy config
AgoraRtmProxyConfig* proxy_config = [[AgoraRtmProxyConfig alloc] init];
proxy_config.proxyType = AgoraRtmProxyTypeHttp;
proxy_config.server = @"your_proxy_server";
proxy_config.port = 8080; //your server's port
proxy_config.account = @"username";
proxy_config.password = @"password";
rtm_cfg.proxyConfig = proxy_config;
rtm_cfg.logConfig = log_cfg;

NSError* initError = nil;
AgoraRtmClientKit* rtm = [[AgoraRtmClientKit alloc] initWithConfig:rtm_cfg delegate:handler error:&initError];
if (rtm != nil) {
    NSLog(@"init rtm success!!");
} else {
    NSLog(@"init rtm failed!!");
}

防火墙白名单设置

大型企业、医院、高校、银行等安全需求较高的机构会部署防火墙将办公环境与外网隔离开来，保护内部信息安全。为避免这些企业用户因防火墙无法使用声网的服务，你需要设置防火墙白名单。

信息

本节展示的目标端口可能会根据实际情况调整。如果遇到问题，联系 rtm-support@agora.io。

Message Channel

Message Channel 是 RTM 的基础服务，只要你使用了 RTM，就需要将以下内容添加到防火墙白名单：

域名

Shell

.agora.io

端口

目标端口	协议	操作
443; 7384; 8443; 9130; 9131; 9136; 9137; 9140, 9141	TCP	允许
1080; 3000; 8000; 8130; 8443; 9120; 9121; 9700; 25000	UDP	允许

Stream Channel

如果你还使用了 Stream Channel，你还需要将以下内容添加到防火墙白名单：

端口

目标端口	协议	操作
4001 - 4150	UDP	允许