快速入门

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

开发环境要求

一个有效的开发者账号。
在控制台创建一个项目，鉴权机制选择 APP ID。
微信开发者工具
项目配置合法域名

前往小程序管理后台，找到「开发」 - 「开发设置」 - 「服务器域名」，点击修改，按照下方的域名进行设置并提交保存，注意事项请参考这里。
```
// request合法域名
https://rtmgw.agrtc.cn

// socket合法域名
wss://node1.rtm.agrtc.cn
wss://node2.rtm.agrtc.cn
wss://node3.rtm.agrtc.cn
wss://node4.rtm.agrtc.cn
wss://node5.rtm.agrtc.cn
wss://node6.rtm.agrtc.cn
wss://node7.rtm.agrtc.cn
wss://nodehk.agrtc.cn
wss://nodehk.agrtc.cn
```
注意：
- 上线必须设置，否则请求会被微信拦截；
- 项目测试阶段可以在「项目设置」中勾选 不校验合法域名、web-view（业务域名）、TLS版本以及 HTTPS 证书

如果你的网络环境部署了防火墙，请根据穿透企业防火墙打开相关端口。

项目测试阶段，我们默认使用 APPID 完成鉴权，也就是只需在 SDK 设置好 APPID 即可完成鉴权。如果你打算将项目上线，请在之后的开发过程中将鉴权机制更换为安全性更高的 APPID + 权限密钥 + Token。鉴权机制，详见鉴权认证文档。

快速集成

本小节介绍如何获取 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 支持以下方式：

ES6 方式引入

import ArRTM from '/<YOUR_PATH>/to/ArRTM@latest.js';

CommonJS 方式引入

var ArRTM = require('/<YOUR_PATH>/to/ArRTM@latest.js');

npm 方式引入
```
var ArRTM = require('ar-rtm-sdk');
```

操作流程

初始化客户端

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

// 创建 RtmClient 实例
const rtmClient = 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>');

加入频道

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

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