# 初始配置 (/zh-CN/api-reference/rtm/web/configuration) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). RTM SDK API 参考介绍了实时消息相关 API 的接口描述、接口方法、基本用法示例代码和返回值。 在初始化 RTM 客户端实例之前,你需要首先在代码中引入 RTM Javascript 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/build/rtm-initialization/application-setup) ## Initialization [#initialization] ### 接口描述 [#接口描述] 创建并初始化 RTM 客户端实例,初始化实例的时候你需要提供 `appId` 和 `userId` 等参数,你可以在声网控制台创建项目并获得 App ID。 :::info[信息] - 创建并初始化客户端实例需要在调用 RTM 的其他 API 之前进行。 - 为区分各用户和设备,你需要确保 `userId` 全局唯一,并且在用户或设备的生命周期内保持不变。 ::: ### 接口方法 [#接口方法] 你可以通过以下方式创建并初始化实例: ```javascript class RTM( constructor( appId: string, userId: string, rtmConfig?: { encryptionMode: string, cipherKey: string, salt: Uint8Array, useStringUserId: boolean, presenceTimeout: number, logUpload: boolean, logLevel: string, cloudProxy: boolean } ); ) ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --------- | --------- | ------ | ---- | --------- | | `appId` | string | 必填 | - | 你在声网控制台创建项目时获得的 App ID。 | | `userId` | string | 必填 | - | 用户 ID,用于标识用户或设备。为区分各用户和设备,你需要确保 `userId` 全局唯一,并且在用户或设备的生命周期内保持不变。 | | `rtmConfig` | `RTMConfig` | 选填 | - | 其它初始化的配置参数,详见 [`RTMConfig`](#rtmconfig)。 | ### 基本用法 [#基本用法] ```javascript const { RTM } = AgoraRTM; const rtm = new RTM("yourAppId", "Tony"); ``` ### 返回值 [#返回值] 一个 RTM 客户端实例,用以在后续调用 RTM 其他 API。 ## RTMConfig [#rtmconfig] ### 接口描述 [#接口描述-1] `RTMConfig` 用于设置 RTM 初始化时配置其他额外属性,这些配置属性会在整个 RTM 客户端的生命周期中生效,影响 RTM 客户端的行为。 ### 接口方法 [#接口方法-1] 你可以通过以下方式创建 `RTMConfig` 实例: ```javascript const { RTMConfig } = AgoraRTM; ``` | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `encryptionMode` | string | 选填 | - | 端侧消息加密模式。如果不设置或设置为 `NONE`,则表示不启用端侧加密功能。支持的取值见[端侧加密模式](/zh-CN/api-reference/rtm/web/enumv#端侧加密模式)。 | | `salt` | Uint8Array | 选填 | - | 加密需要用到的盐,必须为 32 字节的二进制数组。 | | `cipherKey` | string | 选填 | - | 加解密需要用到的密钥。如果启用了加密功能,此属性必须设置。 | | `presenceTimeout` | number | 选填 | `300` | Presence 的超时时间。单位为秒,取值范围为 [5,300]。即 RTM 服务器在判定客户端超时后,延迟多久向其他用户发送 `REMOTE_TIMEOUT` 事件通知。如果客户端在该参数设置的时间内重新建立连接并返回频道,则 RTM 服务器不会向频道中其他人发送 `REMOTE_TIMEOUT` 事件通知,也不会删除该用户的临时用户数据。 | | `logUpload` | boolean | 选填 | `false` | [configuration-javascript-html-0-5-4 details](#table-slot-configuration-javascript-html-0-5-4) | | `cloudProxy` | boolean | 选填 | `false` | [configuration-javascript-html-0-6-4 details](#table-slot-configuration-javascript-html-0-6-4) | | `useStringUserId` | boolean | 选填 | `true` | [configuration-javascript-html-0-7-4 details](#table-slot-configuration-javascript-html-0-7-4) | | `logLevel` | string | 选填 | - | 开启及设置 SDK 的输出日志输出等级。支持的取值见[日志输出等级](/zh-CN/api-reference/rtm/web/enumv#日志输出等级)。 | | `heartbeatInterval` | number | 选填 | `5` | [configuration-javascript-html-0-9-4 details](#table-slot-configuration-javascript-html-0-9-4) | | `privateConfig` | object | 选填 | - | 当使用 RTM 的私有化部署功能时,需要配置此项参数。 | **configuration-javascript-html-0-5-4 details** 是否上传日志: - `true`: 启用日志上传 - `false`: 关闭日志上传。 **configuration-javascript-html-0-6-4 details** 是否开启云代理: - `true`: 开启。 - `false`: 关闭。 :::info[信息] 该功能仅适用于 Message Channel。从 v2.3.0 起,SDK 不再自动回退到 Cloud Proxy。需要使用时,必须在初始化 RTM 实例时将该参数显式设置为 `true`。 ::: **configuration-javascript-html-0-7-4 details** 是否使用 string 类型的用户 ID: - `true`: 使用 string 类型的用户 ID。 - `false`: 使用 number 类型的用户 ID,SDK 会自动将 string 类型的 `userId` 转换为 number 类型。此时,`userId` 参数必须是数字字符串(例如:"123456"),否则初始化会失败。 **configuration-javascript-html-0-9-4 details** SDK 心跳时间。单位为秒,取值范围为 [5,1800]。即客户端向 RTM 服务器发送心跳包的时间间隔。如果客户端在该参数设置的时间内没有向 RTM 服务器发送心跳包,则 RTM 服务器会判定客户端超时。 :::info[信息] 该参数会影响 PCU 计数,从而影响计费。 ::: `privateConfig` 包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `serviceType` | string[] | 选填 | - | 服务类型。支持的取值见[服务类型](/zh-CN/api-reference/rtm/web/enumv#rtmservicetype)。 | | `accessPointHosts` | string[] | 选填 | - | 使用 RTM 服务的服务器列表。仅支持填入域名。 | | `eventUploadHosts` | string[] | 选填 | - | 使用事件上报的服务器列表。仅支持填入域名。 | | `logUploadHosts` | string[] | 选填 | - | 使用日志上传的服务器列表。仅支持填入域名。 | | `originDomains` | string[] | 选填 | - | 连接 RTM 基础服务时使用的后缀域名列表。仅支持填入域名。 | | `domainMode` | number | 选填 | `1` | [configuration-javascript-html-1-6-4 details](#table-slot-configuration-javascript-html-1-6-4) | **configuration-javascript-html-1-6-4 details** RTM 私有化场景下 SDK 边缘节点服务器的域名格式。支持以下取值: - `1`:(默认) 自定义格式,例如 `ip.**`。 - `2`:老版本私有化格式,例如 `ip.edge.**`。 :::warning[注意] 如果你需要升级私有化部署的 RTM WEB SDK 至 2.2.4 及以后版本,为保证兼容性,需要将 `domainMode` 设置为 `2`。如果省略该参数或使用默认值 `1`,可能无法连接到 RTM 服务器。 ::: ### 基本用法 [#基本用法-1] ```javascript const { RTM, EncryptionMode } = AgoraRTM; const rtmConfig = { encryptionMode : EncryptionMode.AES_256_GCM, salt : yourSalt, cipherKey : "yourCipherKey", presenceTimeout : 300, logUpload : true, logLevel : "debug", cloudProxy : false, useStringUserId : false, privateConfig: { serviceType: ["MESSAGE", "STREAM"], domainMode: 2 }, heartbeatInterval: 5 }; const rtm = new RTM("yourAppId", "Tony", rtmConfig); ``` ## 事件监听 [#事件监听] ### 接口描述 [#接口描述-2] RTM 总共有 7 种事件通知类型,如下表所示: | 事件类型 | 描述 | |--------------| ---------- | | message | 接收用户所订阅的 Message Channel 及 Topic 中的所有消息事件通知。 | | presence | 接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Presence 事件通知。 | | topic | 接收用户所加入的 Stream Channel 中所有 Topic 变更事件通知。 | | storage | 接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Channel Metadata 事件通知,及订阅用户的 User Metadata 事件通知。 | | lock | 接收用户所订阅的 Message Channel 及加入的 Stream Channel 中所有的 Lock 事件通知。 | | linkState | 接收客户端网络连接状态变更的事件通知。 | | tokenPrivilegeWillExpire | 接收客户端 Token 将要过期的事件通知。 | ### 添加监听 [#添加监听] 你可以调用 `addEventListener` 方法监听指定的事件通知。示例代码如下: ```javascript // add the message event listener // Message rtm.addEventListener("message", event => { const channelType = event.channelType; // Which channel type it is, Should be "STREAM", "MESSAGE" or "USER" . const channelName = event.channelName; // Which channel does this message come from const topic = event.topicName; // Which Topic does this message come from, it is valid when the channelType is "STREAM". const messageType = event.messageType; // Which message type it is, Should be "STRING" or "BINARY" . const customType = event.customType; // User defined type const publisher = event.publisher; // Message publisher const message = event.message; // Message payload const timestamp = event.timestamp; // Event timestamp }); // Presence rtm.addEventListener("presence", event => { const action = event.eventType; // Which action it is ,should be one of 'SNAPSHOT'、'INTERVAL'、'JOIN'、'LEAVE'、'TIMEOUT、'STATE_CHANGED'、'OUT_OF_SERVICE'. const channelType = event.channelType; // Which channel type it is, Should be "STREAM", "MESSAGE" or "USER" . const channelName = event.channelName; // Which channel does this event come from const publisher = event.publisher; // Who trigger this event const states = event.stateChanged; // User state payload, only for stateChanged event const interval = event.interval; // Interval payload, only for interval event const totalOccupancy = interval?.totalOccupancy; // Total occupancy of the channel, only for interval event const snapshot = event.snapshot; // Snapshot payload, only for snapshot event const timestamp = event.timestamp; // Event timestamp }); // Topic rtm.addEventListener("topic", event => { const action = event.evenType; // Which action it is ,should be one of 'SNAPSHOT'、'JOIN'、'LEAVE'. const channelName = event.channelName; // Which channel does this event come from const publisher = event.userId; // Who trigger this event const topicInfos = event.topicInfos; // Topic information payload const totalTopics = event.totalTopics; // How many topics const timestamp = event.timestamp; // Event timestamp }); // Storage rtm.addEventListener("storage", event => { const channelType = event.channelType; // Which channel type it is, Should be "STREAM", "MESSAGE" or "USER" . const channelName = event.channelName; // Which channel does this event come from const publisher = event.publisher; // Who trigger this event const storageType = event.storageType; // Which category the event is, should be 'USER'、'CHANNEL' const action = event.eventType; // Which action it is ,should be one of "SNAPSHOT"、"SET"、"REMOVE"、"UPDATE" or "NONE" const data = event.data; // 'USER_METADATA' or 'CHANNEL_METADATA' payload const timestamp = event.timestamp; // Event timestamp }); // Lock rtm.addEventListener("lock", event => { const channelType = event.channelType; // Which channel type it is, Should be "STREAM", "MESSAGE" or "USER" . const channelName = event.channelName; // Which channel does this event come from const publisher = event.publisher; // Who trigger this event const action = event.evenType; // Which action it is ,should be one of 'SET'、'REMOVED'、'ACQUIRED'、'RELEASED'、'EXPIRED'、'SNAPSHOT' const lockName = event.lockName; // Which lock it effect const ttl = event.ttl; // The ttl of this lock const snapshot = event.snapshot; // Snapshot payload const owner = event.owner; // The owner of this lock const timestamp = event.timestamp; // Event timestamp }); // Link State Change rtm.addEventListener('linkState', event => { const currentState = event.currentState; const previousState = event.previousState; const serviceType = event.serviceType; const operation = event.operation; const reason = event.reason; const reasonCode = event.reasonCode; const affectedChannels = event.affectedChannels; const unrestoredChannels = event.unrestoredChannels; const timestamp = event.timestamp; const isResumed = event.isResumed; }); // Token Privilege Will Expire rtm.addEventListener("tokenPrivilegeWillExpire", (channelName) => { const channelName = channelName; // Which Channel Token Will Expire }); ``` `PresenceEvent.interval` 的类型为 `IntervalDetail | null`,仅当 `eventType` 为 `INTERVAL` 时有值。 `IntervalDetail` 数据类型包含以下属性: | 属性 | 类型 | 描述 | | ---- | ---- | ---- | | `join` | `UserList` | 在上一个周期内加入频道的用户列表。 | | `leave` | `UserList` | 在上一个周期内离开频道的用户列表。 | | `timeout` | `UserList` | 在上一个周期内超时的用户列表。 | | `userStateList` | `UserState[]` | 在上一个周期内状态变更的用户列表。包含用户 ID 和状态键值对。 | | `totalOccupancy` | number | 当前频道的总在线人数。在大频道优化模式下,该值表示频道内所有在线用户的数量,不受最多同步 512 名用户明细的限制;但该值可能有短暂延迟。 | ### 删除监听 [#删除监听] 你可以调用 `{config. removedelegate["javascript"]}` 方法删除指定的事件监听。示例代码如下: ```javascript rtm.removeEventListener("linkState", linkStateHandler); ``` ## login [#login] ### 接口描述 [#接口描述-3] 创建并初始化 RTM 实例之后,你需要执行 `login` 操作以登录 RTM 服务。登录成功将使客户端与 RTM 服务器建立起长连接,之后客户端才能正常访问 RTM 资源。 :::info[信息] 用户成功登录 RTM 服务后,应用的 PCU 会增加,这将影响你的账单数据。 ::: ### 接口方法 [#接口方法-2] 你可以通过以下方法登录 RTM 系统: ```javascript rtm.login(options?: object): Promise; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --------- | ---- | ------ | ---- | ----- | | `options` | object | 选填 | - | 登录选项。 | `options` 对象包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `token` | string | 选填 | - | [configuration-javascript-html-2-1-4 details](#table-slot-configuration-javascript-html-2-1-4) | **configuration-javascript-html-2-1-4 details** 初始化 RTM 客户端的 Token。 - 如果你的项目开启了 Token 鉴权,你可以填入 [RTM 临时 Token](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service#5-获取临时-token) 或 Token 服务器生成的 RTM 正式 Token。详见[客户端鉴权](/zh-CN/realtime-media/rtm/build/authentication-and-connection/user-authentication)和[部署 RTM Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。 - 如果你的项目未开启 Token 鉴权,你可以不填,或填入开通了 RTM 服务的项目 App ID。 ### 基本用法 [#基本用法-2] ```javascript try{ const result = await rtm.login({ token: "your_token" }); console.log(result); } catch (status){ console.log(status); } ``` ### 返回值 [#返回值-1] 如果方法调用成功,则返回一个 `LoginResponse` 类型数据: ```javascript type LoginResponse = { timestamp: number // 预留字段 } ``` 如果方法调用失败,则返回一个 `ErrorInfo` 类型数据: ```javascript type ErrorInfo = { error: boolean; // 本次操作是否出错 operation: string; // 本次操作的 API 名称 errorCode: number; // 错误码 reason: string; // 错误描述 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 ## logout [#logout] ### 接口描述 [#接口描述-4] 当你不再需要操作后,可以登出系统。本操作会影响你账单中的 PCU 计费项。 ### 接口方法 [#接口方法-3] 你可以通过以下接口退出登录: ```javascript rtm.logout(): Promise; ``` ### 基本用法 [#基本用法-3] ```javascript try{ const result = await rtm.logout(); console.log(result); } catch (status){ console.log(status); } ``` ### 返回值 [#返回值-2] 如果方法调用成功,则返回一个 `LogoutResponse` 类型数据: ```javascript type LoginResponse = { timestamp: number // 预留字段 } ``` 如果方法调用失败,则返回一个 `ErrorInfo` 类型数据: ```javascript type ErrorInfo = { error: boolean; // 本次操作是否出错 operation: string; // 本次操作的 API 名称 errorCode: number; // 错误码 reason: string; // 错误描述 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。