快速入门

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

开发环境要求

一个有效的开发者账号。
一款支持 RTM SDK 的主流浏览器:

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

浏览器	兼容性
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. 前往阿里云 OSS ，ctrl + s 或 command + s 下载
1. 前往 github clone 或 Download 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 的应用才能互相通信。

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

// 定义登录配置
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>');

接收频道消息

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

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

加入频道

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

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

发送频道消息

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

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 实例。