快速入门

最近更新时间:2021-04-01 14:58:00

本文主要介绍如何将 RTM Web SDK 实时消息集成到你的项目中以及相关注意事项。

开发环境要求

  • 一个有效的 开发者账号

  • 一款支持 RTM SDK 的主流浏览器:

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

快速集成

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

获取 AppID

参考以下步骤获取一个 AppID。若已经拥有 AppID,请跳过当前步骤,直接查看操作流程

  • 1. 创建项目

    首先我们需要在开发者控制台创建一个「项目」

  • 2. 获取 APP ID

    获取项目的「APP ID」

引入 SDK

1: 获取 SDK

你可以通过如下几种方式获取最新的 SDK:

    1. 官网下载中心找到 「RTM SDK 下载」 的Web端
    1. 前往阿里云 OSSctrl + scommand + s 下载
    1. 前往 github cloneDownload ZIP 下载
    1. 通过 npm 市场下载

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

    npm i ar-rtm-sdk
    

2: 导入 SDK

导入 SDK 支持以下方式:

  • script 标签引入

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

    <script src="/<YOUR_PATH>/to/ArRTM@latest.js"></script>
    
  • ES6 方式引入

    import ArRTM from '/<YOUR_PATH>/to/ArRTM@latest.js';
    
  • CommonJS 方式引入

    var ArRTM = require('/<YOUR_PATH>/to/ArRTM@latest.js');
    
  • npm 方式引入

    // ES6
    import ArRTM from 'ar-rtm-sdk';
    // 或者是 commonJS
    var ArRTM = require('ar-rtm-sdk');
    

操作流程

初始化客户端

通过 ArRTM.createInstance 创建本地客户端 rtmClient 的实例。

// 创建实例是需要填入我们事先准备好的 App ID。
const client = ArRTM.createInstance('<APPID>');

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

登录

rtmClient 的实例提供了 login 方法可以登录 RTM 系统,login 方法支持传入一个对象作为参数,对象包含两个属性 tokenuid:

  • token:非必填,用于 Token 鉴权,提供应用信息的安全级别。如果应用已经开启了权限密钥,登录时需要配置 token RTM 服务器会对 token 进行验证。为了保证应用安全性,建议启用该功能(开发测试阶段不建议启用)。
  • uid: 必填,用来标识用户身份,无缝对接业务系统。必须为字符串,不可超过 48 字节,但是不支持字符串 "null"。

登录 RTM 服务器之后,才可以实现 RTM 的点对点消息和群聊功能。

// 定义登录配置
const options = {
  token: '<TOKEN>',
  uid: '<UID>'
};
// 登录
client.login(options).then(() => {
  console.log('ArRTM client login success');
}).catch(err => {
  console.log('ArRTM client login failure', err);
});

监听连接状态改变

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

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

点对点消息

点对点消息包括:发送点对点消息,接收点对点消息。

接收点对点消息

客户端登录成功之后,需要监听 MessageFromPeer 回调事件,来接收点对点消息(远端用户发送给自己)。

切勿多次监听,否则会回调多次,如果监听多次可以使用 off 方法来取消监听。

client.on('MessageFromPeer', ({ text }, peerId) => {
  // text 为消息文本,peerId 是消息发送方 User ID
  console.log("消息来自:", peerId)console.log("消息内容:", text)});

发送点对点消息

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

  • 相对应 RtmMessage 类型的对象。(目前仅支持文本消息)
  • 接收消息人员的 User ID
  • 消息的属性配置。包括是否是离线消息等。
client.sendMessageToPeer(
  { text: 'this is an peer message' }, // 发送文本消息
  '<PEER_ID>', // 远端接收消息的用户 ID
  {
    enableHistoricalMessaging: false, // 是否保存为历史消息
    enableOfflineMessaging: false     // 是否设置为离线消息
  }
).then(sendResult => {
  // 消息发送成功,服务器已接收
  if (sendResult.hasPeerReceived) {
    // 对方已收到消息
  } else {
    // 服务器已接收、但消息不可达
  }
}).catch(error => {
  // 超时、服务器拒绝或连接失败
});

频道消息

SDK 不仅支持频道消息,同时还支持群组消息,又称频道消息。

创建频道

一个客户端可以加入多个频道,需要业务系统自己维护。

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

加入频道

通过创建频道的实例,如果有多个频道,需要创建多个独立的频道实例。

channel.join().then(() => {
  // 加入频道成功
}).catch(error => {
  // 加入频道失败
});

接收频道消息

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

channel.on('ChannelMessage', ({ text }, senderId) => {
  // text 为收到的频道消息文本,senderId 为发送方的 User ID
  console.log("消息来自:", senderId)console.log("消息内容:", text)});

发送频道消息

客户端加入频道成功后可以发送频道消息,频道消息发送成功,会广播给频道内的所有成员。

channel.sendMessage(
  { text: 'this is a channel message' }, // 发送文本消息
  {
    enableHistoricalMessaging: false // 是否保存为历史消息
  }
).then(() => {
  // 频道消息发送成功
}).catch(error => {
  // 频道消息发送失败
});

退出频道

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

channel.leave();

登出

rtmClient 的实例提供了 logout 方法可以登出 RTM 系统。

如果需要切换账号,可以在退出登录切换 uid 再次调用 login 实现切换账号。

client.logout();

开发注意事项

  • 在收发点对点消息,或者频道操作前,需要确保已经成功登录 RTM 系统。
  • 回调多次监听会回调多次。
  • RTM 支持创建多个 rtmClient 实例。