# 应用配置 (/zh-CN/realtime-media/rtm/build/rtm-initialization/application-setup/web)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在开始配置你的应用之前,你需要先了解用户 ID、服务类型等概念,然后下载并安装 SDK,再初始化一个 RTM 对象实例,最后实现事件监听函数以捕获 RTM 实时网络中的所有事件通知。
## 用户 ID(`userId`) [#用户-iduserid]
用户 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 并在整个生命周期内保持不变。
## 服务类型 [#服务类型-2]
基于不同的传输连接,RTM SDK 提供的功能可以被划分为两种服务类型: `MESSAGE` 服务和 `STREAM` 服务。
- `MESSAGE` 服务涵盖了 `Message Channel`、`User Channel`、`Presence`、`Storage`、`Lock`、`Token` 鉴权等功能特性,通过 `rtm` 实例调用 API。
- `STREAM` 服务则提供了 `Stream Channel`、`Topic` 等功能,通过 `RTMStreamChannel` 实例调用 API。
在 `MESSAGE` 服务中,所有功能特性将共享一条传输连接,该连接在 `login` 时建立,在 `logout` 时关闭。而在 `STREAM` 服务中,传输连接的数量取决于加入的 `STREAM CHANNEL` 数量,即每个加入的 `STREAM CHANNEL` 实例都拥有独立的连接,连接在 `join` 时建立,在 `leave` 时关闭。
所有传输连接都由 SDK 统一管理,并通过 `linkState` 事件通知给用户,详见[连接管理](/zh-CN/realtime-media/rtm/build/authentication-and-connection/link-basic)。深入理解 RTM 服务类型的区别,有助于你更准确地选择和使用相关能力。
此外,服务类型还涉及私有化配置的选择。用户可以选择私有化一个服务,或者同时私有化两种服务,具体取决于应用场景和预算。详见[私有化配置](/zh-CN/realtime-media/rtm/build/network-and-private-deployment/private-setup)。
## 安装 SDK [#安装-sdk]
你可以通过以下方式获取最新的 RTM Web SDK。
#### 方式一:使用 CDN 添加 SDK [#方式一使用-cdn-添加-sdk]
[点击此处](https://download.agora.io/rtm2/release/Agora_RTM_JavaScript_SDK_for_Web_v2.3.0.zip)下载最新版本的 JavaScript SDK,并在你的项目中添加以下代码引用它:
```javascript
// 使用 CDN 直接将以下代码添加到你的 Web 应用中,或下载 SDK 文件后在本地引用
// 将 x.y.z 替换为具体的 SDK 版本号,如 2.3.0
// 可通过发版说明获取最新版本号
```
#### 方式二:使用包管理器引入 SDK [#方式二使用包管理器引入-sdk]
1. 根据你的应用场景和开发需要,选择一种方式和工具安装 SDK。
**场景一**:项目仅使用 RTM 产品,且没有集成声网任何版本的 RTC 产品。
使用 npm
使用 pnpm
使用 Yarn
```shell
npm install agora-rtm
```
```shell
pnpm add agora-rtm
```
```shell
yarn add agora-rtm
yarn add agora-rtc-sdk-ng@4.22.0 --save-exact
```
**场景二**:项目中已经集成了 RTC 产品,需要新接入 RTM 产品。
使用 npm
使用 pnpm
使用 Yarn
```shell
npm install agora-rtm
```
```shell
pnpm add agora-rtm
```
如果项目使用的 RTC 版本与 RTM 中依赖的 RTC 版本不一致,会收到提示:`unmet peer agora-rtc-sdk-ng@4.22.0: found 4.16.0`。此时你需要升级 RTC 的版本:
```shell
pnpm update agora-rtc-sdk-ng@4.22.0
```
或者通过以下命令同时保留两个版本的 RTC 库:
```shell
pnpm add agora-rtc-sdk-ng-4.16@npm:agora-rtc-sdk-ng@4.16.0 --save-exact
pnpm add agora-rtc-sdk-ng@4.22.0 --save-exact
```
然后将代码中原来的 `import AgoraRTC from "agora-rtc-sdk-ng"` 替换为如下行:
```javascript
import AgoraRTC from "agora-rtc-sdk-ng-4.16"
```
:::warning[注意]
保留两个版本的 RTC 库会增加项目的包体积。
:::
```shell
yarn add agora-rtm
```
如果项目使用的 RTC 版本与 RTM 中依赖的 RTC 版本不一致,会收到提示:`unmet peer agora-rtc-sdk-ng@4.22.0: found 4.16.0`。此时你需要升级 RTC 的版本:
```shell
yarn upgrade agora-rtc-sdk-ng@4.22.0
```
或者通过以下命令同时保留两个版本的 RTC 库:
```shell
yarn add agora-rtc-sdk-ng-4.16@npm:agora-rtc-sdk-ng@4.16.0 --save-exact
yarn add agora-rtc-sdk-ng@4.22.0 --save-exact
```
然后将代码中原来的 `import AgoraRTC from "agora-rtc-sdk-ng"` 替换为如下行:
```javascript
import AgoraRTC from "agora-rtc-sdk-ng-4.16"
```
:::warning[注意]
保留两个版本的 RTC 库会增加项目的包体积。
:::
**场景三**:你的项目是全新的,且需要同时集成 RTM 和 RTC,以利用其共频道、数据优先级控制等能力。这种场景下建议你集成融合版本的 SDK。
使用 npm
使用 pnpm
使用 Yarn
```shell
npm install agora-rtx
```
```shell
pnpm add agora-rtx --shamefully-hoist
```
```shell
# 若版本为 2.2.0
# yarn add agora-rtx
# yarn add agora-rtc-sdk-ng@4.22.0 --save-exact
# 2.2.0 及之后版本
yarn add agora-rtx
```
2. 完成安装后,在你的 `app.js` 中引入 RTM:
```javascript
// 如果安装的是 agora-rtm
import AgoraRTM from 'agora-rtm';
// 如果安装的是融合版 agora-rtx
// import AgoraRTM from 'agora-rtx';
// import AgoraRTC from 'agora-rtc-sdk-ng';
```
详细流程参考[快速开始](/zh-CN/realtime-media/rtm/get-started/quick-start)。
## 初始化 RTM 实例 [#初始化-rtm-实例]
在使用 RTM 功能前,你需要使用 `appId` 和 `userId` 来初始化一个 RTM 实例。在后续的示例代码中,你需要将 `your_appId` 和 `your_userId` 字段都替换为你自己的 `appId` 和 `userId`。
:::info[信息]
初始化 RTM 对象时的 `appId` 和 `userId` 为必填参数,如果缺失,则初始化会失败。
:::
在一个客户端中,你只需要初始化一次 RTM 对象实例,即可在后续实现中通过该对象实例调用 RTM 的其他 API。
```javascript
const { RTM } = AgoraRTM;
// Fill in the App ID of your project.
const appId = "your_appId";
// Fill in your user ID.
const userId = "your_userId";
try {
const rtm = new RTM(appId, userId);
console.log("Create new RTM client Success!");
} catch (status) {
console.log("Error with status: ${status}");
}
```
我们推荐你使用 `try{...}/catch{...}` 范式捕获初始化过程中可能出现的异常。现在,你就可以使用 `rtm` 对象调用 RTM 的其他 API 接口了。
## 日志设置 [#日志设置]
当你的应用处于开发、测试阶段时,你可能需要 SDK 输出更详细的信息来定位并修复问题。你可以在初始化 RTM 实例的时候通过设置 `RTMConfig` 中的 `logLevel` 来开启日志输出并设置日志信息等级,之后即可在相应平台的日志输出位置查看日志信息。
```javascript showLineNumbers
const { RTM } = AgoraRTM;
const appId = "your_appId";
const userId = "your_userId";
const rtmConfig = { logLevel : "debug" };
const rtm = new RTM(appId, userId, rtmConfig);
```
日志有以下五种等级:
:::info[信息]
在你的应用上线时,你需要将日志等级参数设置为 `info`。
:::
| 属性值 | 描述 |
| --- | ------------- |
| `debug` | 输出所有日志。 |
| `info` | 输出 `error`、`warn`、`info` 级别的日志。 |
| `warn` | 输出 `error`、`warn` 级别的日志。 |
| `error` | 输出 `error` 级别的日志。 |
| `none` | 不输出任何日志。 |
你也可以查看[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)了解更详细地调试及错误处理方法。
## Cloud Proxy 设置 [#cloud-proxy-设置]
完整配置说明请参阅[网络配置中的 Cloud Proxy 设置](/zh-CN/realtime-media/rtm/build/network-and-private-deployment/network-configuration#cloud-proxy-设置)。
## Proxy 设置 [#proxy-设置]
完整配置说明请参阅[网络配置中的 Proxy 设置](/zh-CN/realtime-media/rtm/build/network-and-private-deployment/network-configuration#proxy-设置)。
## 防火墙白名单设置 [#防火墙白名单设置]
完整配置说明请参阅[网络配置中的防火墙白名单设置](/zh-CN/realtime-media/rtm/build/network-and-private-deployment/network-configuration#防火墙白名单设置)。