快速开始

最近更新时间:2021-01-28 13:28:53

本文主要介绍在集成 anyRTC RTM Web SDK 实时消息之前,需要准备的开发环境要求和实现实时消息通讯的基本步骤和常用方法。

示例 DEMO

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

开发环境要求

  • 一个有效的 anyRTC 开发者账号

  • 一款支持 anyRTC RTM Web SDK 的浏览器,参考下表:

    浏览器兼容性
    Chrome 49+
    Safari 9+
    Firefox 52+
    微信浏览器
    QQ 浏览器 10.5+
    Internet Explorer 11+

配置开发环境

本小节介绍如何获取 AppID 以及如何快速集成到项目中。

获取应用 ID

参考以下步骤获取一个 AppID。若已经拥有 AppID,请跳过当前步骤,直接查看快速集成

快速集成

1. 获取 SDK

我们可以通过两种方式下载最新的 SDK:

  • 官网下载中心找到 RTM SDK 的 Web 端

  • 通过 npm 下载

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

    npm i ar-rtm-sdk
    

2. 引入 SDK

引入 SDK 也可以通过两种方式导入:

  • script 标签引入

    使用 <script> 方法引入的 SDK ,window 对象中会暴露一个 ArRTM 的全局变量。

    <script src="/path/to/ArRTM@latest.js"></script>
    
  • npm 引入

    1. 通过 npm 安装的可以直接引入
    import ArRTM from 'ar-rtm-sdk'
    
    1. 通过官网下载的 SDK
    import ArRTM from '/path/to/ArRTM@latest.js'
    

实时消息和基本频道操作

本节内容主要介绍如何实现点对点消息和频道消息的收发,提供相关示例代码。

初始化

在登录系统和收发消息之前,我们需要先创建本地客户端 rtmClient 的实例,可以通过 ArRTM.createInstance 创建。

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

创建实例是需要填入我们事先准备好的 App ID。

使用相同 App ID 的应用消息才能互通。

登录

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

client.login 方法提供两个参数:tokenuid

  • token: 如果应用已经开启了 权限密钥 ,需要配置第三方验证 token。为了保证

应用安全性,建议启用该功能。开发测试阶段不建议启用。

  • uid: User ID 必须为字符串,不可超过 64 字节,但是不支持字符串 “null”。

login 方法返回值是一个 Promise 对象,该对象提供两个方法: thencatchthen 提供两个参数,第一个是成功执行的回调,第二个参数为失败时执行的回调。catch 为方法异常时执行传入的回调函数;

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

SDK 还提供了退出接口 logout,如果需要切换账号,可以在退出登录切换 uid 再次调用 login 实现切换账号。

client.logout();

点对点消息

客户端登录成功之后,我们可以使用 client.sendMessageToPeer 方法实现点对点消息。该方法提供三个参数:

  • 相对应 RtmMessage 类型的对象。(现在只支持文本消息)
  • 接收消息人员的 User ID
  • 消息的属性配置。包括是否需要保存为历史消息、是否是离线消息等。

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

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

接收点对点消息

客户端登录成功之后,需要监听 MessageFromPeer 回调事件,来接收点对点消息。

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

监听该回调可以接收来自远端用户的实时消息。

频道消息

本节主要介绍频道的相关操作的接口。

创建并加入频道

创建频道:

const channel = client.createChannel('<CHANNEL_ID>'); // 此处传入频道 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 系统。
  • 回调多次监听会回调多次。
  • RTM 支持创建多个 rtmClient 实例。