本页介绍在正式使用 Agora RTM Web SDK 进行实时消息通讯前，需要准备的开发环境要求及 SDK 集成方法等内容。

示例项目体验

你可以到 GitHub 下载最新版的 Agora-RTM-Tutorial-for-Web 查看完整的源码和代码逻辑。

如果你是第一次使用声网的服务，我们推荐观看下面的视频，了解关于声网服务的基本信息以及如何快速跑通示例项目。

开发环境要求

• 安装一款 Agora RTM Web SDK 支持的浏览器，如下表所示：

• 一个有效的 Agora 开发者账号。

设置开发环境

本节介绍如何获取 App ID 并将 RTM Web SDK 集成至你的项目中。

获取 App ID

参考以下步骤获取一个 App ID。若已有App ID，可以直接查看集成客户端。

集成客户端

方法 1：从官网获取 SDK

使用 <script> 方法引入的 SDK 会在 window 上生成名为 AgoraRTM 的全局变量。

1. 从 Agora 官方网站下载最新版 Agora RTM SDK for Web 压缩包。

2. 将下载下来的压缩包中路径为 libs/agora-rtm-sdk-1.4.1.js 的文件保存到你所操作的项目下。

3. 在项目相应的前端页面文件中，对刚才保存的 SDK 文件进行引用（其中 /path/to/agora-rtm-sdk-1.4.1.js 替换为可访问的 SDK 公开网址）：

    <script src="/path/to/agora-rtm-sdk-1.4.1.js"></script>

/// <reference path="path/to/agora-rtm-sdk.d.ts" />

方法 2：通过 npm 引入

该方法需要安装 npm。详见 Install npm。

1. 安装最新版的 SDK：
   npm i agora-rtm-sdk
2. 导出 AgoraRTM 模块：
   import AgoraRTM from 'agora-rtm-sdk'

实时消息和基本频道操作

本节主要提供实现实时消息和基本频道操作的示例代码以及相关注意事项。

初始化

登入 RTM 之前，调用 AgoraRTM.createInstance 方法创建一个 RtmClient 实例。

创建实例需要填⼊准备好的 App ID, 只有 App ID 相同的应⽤才能互通。

示例代码中的 client 变量为 RtmClient 实例，下同。

const client = AgoraRTM.createInstance('<APPID>');

监听连接状态改变

通过监听 RtmClient 上的 ConnectionStateChanged 事件可以获得 SDK 连接状态改变的通知。

client.on('ConnectionStateChanged', (newState, reason) => {
  console.log('on connection state changed to ' + newState + ' reason: ' + reason);
});

登录

Web 应用必须在登录 RTM 服务器之后，才可以使用 RTM 的点对点消息和群聊功能。

在 client.login 方法中传入一个有如下属性的对象：

• token: 如果安全要求不高，不填或将参数值设为 null；如果安全要求高，传入从你的服务端获得的 token 值。Token 需要在应用程序的服务器端生成，具体生成办法，详见 校验用户权限。
• uid: User ID 为字符串，必须是可见字符（可以带空格），不能为空或者多于64个字符，也不能是字符串 “null”。

该方法的返回值为 Promise。使用该 Promise 上的 then 方法传入回调；使用 catch 方法捕获异常并处理。也可以使用 ES7 的 async/await 语法来进行 SDK 异步方法的调用，这样就可以使用同步 try/catch 块来捕获异常（其他返回 Promise 的异步 API 也均如此）。

示例代码中均使用 then/catch 方法传入回调与捕获异常。

client.login({ token: '<TOKEN>', uid: '<UID>' }).then(() => {
  console.log('AgoraRTM client login success');
}).catch(err => {
  console.log('AgoraRTM client login failure', err);
});

如果需要退出登录，可以调用 logout 方法，退出登录之后可以调用 login 重新登录或者切换账号。

client.logout();

点对点消息

App 在成功登录 RTM 服务器之后，可以开始使用 RTM 的点对点消息功能。

发送点对点消息

调用 client 上的 sendMessageToPeer 方法发送点对点消息。在该方法中：

• 传入目标消息接收方的用户账号 ID。
• 传入符合 RtmMessage 接口的参数对象。

该方法返回一个 Promise：
该 Promise 执行（resolve）的值指示消息接收方是否已收到该消息。
该 Promise 拒绝（reject）的情况可能为超时、服务器拒绝或连接失败等。

client.sendMessageToPeer(
    { text: 'test peer message' }, // 符合 RtmMessage 接口的参数对象
    '<PEER_ID>', // 远端用户 ID
).then(sendResult => {
  if (sendResult.hasPeerReceived) {
    /* 远端用户收到消息的处理逻辑 */
  } else {
    /* 服务器已接收、但远端用户不可达的处理逻辑 */
  }
}).catch(error => {
  /* 发送失败的处理逻辑 */
});

接收点对点消息

监听 client 上的事件 MessageFromPeer 接收点对点消息。

client.on('MessageFromPeer', ({ text }, peerId) => { // text 为消息文本，peerId 是消息发送方 User ID
  /* 收到点对点消息的处理逻辑 */
});

频道消息

创建并加入频道

创建频道：

const channel = client.createChannel('<CHANNEL_ID>'); // 此处传入频道 ID

加入频道（channel 为刚才创建的频道实例，每个频道 ID 都需要创建一个独立的频道实例，下同）：

channel.join().then(() => {
  /* 加入频道成功的处理逻辑 */
}).catch(error => {
  /* 加入频道失败的处理逻辑 */
});

发送频道消息

加入频道成功后可发送频道消息。

channel.sendMessage({ text: 'test channel message' }).then(() => {
  /* 频道消息发送成功的处理逻辑 */
}).catch(error => {
  /* 频道消息发送失败的处理逻辑 */
});

接收频道消息

加入频道后可通过监听 RtmChannel 实例上的 ChannelMessage 事件接收到频道消息。

channel.on('ChannelMessage', ({ text }, senderId) => { // text 为收到的频道消息文本，senderId 为发送方的 User ID
  /* 收到频道消息的处理逻辑 */
});

退出频道

调用实例的 leave 方法可以退出该频道。退出频道之后可以调用 join 方法再重新加入频道。

channel.leave();

开发注意事项

• RTM 支持多个相互独立的 RtmClient 实例。

• 在收发点对点消息或进行其他频道操作前，请确保你已成功登录 Agora RTM 系统。

• 使用频道核心功能前必须通过调用 createChannel 方法创建频道实例。

• 你可以创建多个 RtmClient 客户端实例，但是每个客户端实例最多只能同时加入 20 个频道。每个频道都应有不同的 channelId 参数。

• 当你不再使用某个实例时，可以通过调用继承的 removeAllListeners 方法删除它的所有监听函数。

• 接收到的 RtmMessage 消息对象不能重复利用再用于发送。