微信小程序实时消息 SDK

目录

1. 简介

2. 环境要求

3. 快速开始

4. 发送第一条消息

5. 更多信息

6. 微信小程序域名白名单

重要说明

本包专为微信小程序运行环境构建，不能作为 RTM Web SDK 的直接替代品使用。

功能限制： 当前小程序 SDK 不支持 StreamChannel、cloudProxy，也不支持任何私有化功能，包括私有化部署和私有化配置。请勿将使用这些 Web SDK 能力的代码直接复制到小程序项目中。

简介

微信小程序 RTM SDK 可帮助你在小程序中实现实时消息和事件驱动的互动功能。本 SDK 提供了适用于微信小程序运行环境的 npm 包、类型定义和 WebAssembly 资源。

你可以将其用于聊天、信令、实时状态更新、在线教育、互动游戏和智能设备等场景。

工作原理

创建 RTM 实例并登录后，订阅 Message Channel、注册事件监听并发布消息。RTM 会将消息实时分发给频道的订阅者。

下面的快速开始将介绍如何在微信小程序项目中完成基本的消息发布和订阅流程。

文档

你可以通过产品文档了解更多 RTM 相关信息。Web 包与小程序包支持的 API 范围不同，请以本 README 和已安装小程序包中的类型定义为准。

环境要求

集成 SDK 前，请确认项目满足以下要求。

支持的环境

• 已启用 npm 包支持的微信小程序项目。
• 当前稳定版本的微信开发者工具。
• 开发环境中已安装 Node.js 和 npm。
• 已开通 RTM 服务并具有有效 App ID 的 Agora 或声网项目。
• 已将所需的 request 和 WebSocket 域名添加到小程序服务器域名白名单。
• 已按照下文说明将 SDK 的 WebAssembly 文件放入小程序项目中。

快速开始

第一步：在控制台创建 Agora 或声网项目

安装 RTM SDK 前，请先在声网控制台创建项目。初始化 SDK 时需要使用项目的 App ID。在生产环境中，请使用由业务服务器生成的 RTM Token。

注意： 使用不同 App ID 的客户端无法互通。需要互发消息的所有客户端必须使用相同的 App ID。

第二步：安装 RTM SDK

请根据服务区域安装对应的软件包。

中国大陆地区使用声网服务的项目：

npm install shengwang-rtm-miniapp

中国大陆以外地区使用 Agora 服务的项目：

npm install agora-rtm-miniapp

将已安装软件包中的 WebAssembly 资源复制到项目的 wasm 目录。请根据安装的软件包运行对应命令：

node ./node_modules/shengwang-rtm-miniapp/scripts/load-wasm.js

node ./node_modules/agora-rtm-miniapp/scripts/load-wasm.js

如需将资源复制到其他目录，请通过 --project-target-dir 指定目标路径。安装软件包并复制资源后，在微信开发者工具中执行构建 npm。

第三步：导入 RTM SDK

import AgoraRTM from 'shengwang-rtm-miniapp';

以下示例使用 shengwang-rtm-miniapp。如果 TypeScript 项目无法识别默认导入，请将 allowSyntheticDefaultImports 设置为 true。

发送第一条消息

完成 RTM SDK 导入并准备好 WebAssembly 资源后，即可初始化客户端并发送消息。

第四步：初始化 RTM 客户端实例

使用 App ID 和用户 ID 创建 RTM 实例：

import AgoraRTM from 'shengwang-rtm-miniapp';

const { RTM } = AgoraRTM;
const appId = 'your-app-id';
const userId = 'your-user-id';
const messageChannelName = 'chat-room';
let rtm;

try {
  rtm = new RTM(appId, userId);
} catch (error) {
  console.error('RTM 初始化失败：', error);
}

请将 your-app-id 和 your-user-id 替换为项目的 App ID 和当前用户的用户 ID。

第五步：添加事件监听

登录前注册事件监听，以便小程序及时处理收到的消息和连接状态变化。

rtm.addEventListener('message', event => {
  console.log('收到消息：', event.publisher, event.message);
});

rtm.addEventListener('presence', event => {
  console.log('Presence 事件：', event);
});

rtm.addEventListener('linkState', event => {
  console.log('连接状态变化：', event.currentState, event.reasonCode);
});

第六步：登录 RTM 服务

SDK 初始化完成后，登录 RTM 服务。如果在登录前调用需要连接的 RTM 操作，SDK 会返回 RTM_ERROR_NOT_LOGIN (-10002)。

try {
  await rtm.login({ token: 'your-token' });
  console.log('RTM 登录成功');
} catch (error) {
  console.error('RTM 登录失败：', error);
}

第七步：收发消息

发送消息前先订阅 Message Channel，以便小程序接收其他用户发布的消息：

try {
  await rtm.subscribe(messageChannelName);
  console.log('已订阅频道：', messageChannelName);
} catch (error) {
  console.error('订阅失败：', error);
}

向频道发布字符串消息。对象类型的消息内容需要先序列化，再调用 publish。

const message = JSON.stringify({ text: '你好，微信小程序' });

try {
  await rtm.publish(messageChannelName, message);
  console.log('消息发送成功');
} catch (error) {
  console.error('消息发送失败：', error);
}

小程序不再需要接收该频道的消息时，取消订阅：

try {
  await rtm.unsubscribe(messageChannelName);
} catch (error) {
  console.error('取消订阅失败：', error);
}

更多信息

至此，你已经完成 RTM 小程序 SDK 的安装和 WebAssembly 资源准备，并实现了登录及 Message Channel 消息收发。你可以通过 RTM JavaScript API 参考了解相关 API 概念；使用具体 API 前，请先确认该 API 已包含在小程序包的类型定义中。

如有意见、问题或功能建议，请发送邮件至 [email protected]。

附录：微信小程序域名白名单

微信小程序项目需要配置以下 13 个域名。其中，12 个 HTTPS 域名需要添加到微信公众平台的 request 合法域名，1 个 WSS 域名需要添加到 socket 合法域名。

request 合法域名（HTTPS）

AP 域名（8 个）

用于登录、边缘节点分配和配置拉取，通过 wx.request 访问：

https://ap-web-1.agora.io;
https://ap-web-2.agora.io;
https://ap-web-3.agora.io;
https://ap-web-4.agora.io;
https://web-1.ap.sd-rtn.com;
https://web-2.ap.sd-rtn.com;
https://web-3.ap.sd-rtn.com;
https://web-4.ap.sd-rtn.com;

事件上报域名（2 个）

用于 SDK 事件上报，通过 wx.request 访问：

https://webcollector-rtm.agora.io;
https://rtm.statscollector.sd-rtn.com;

日志上报域名（2 个）

开启 logUpload 后用于 SDK 日志上报，通过 wx.request 访问：

https://logservice-rtm.agora.io;
https://rtm.logservice.sd-rtn.com;

socket 合法域名（WSS）

用于 RTM 长连接，通过 wx.connectSocket 访问：

wss://miniapp.agoraio.cn;

SDK 不使用 wx.uploadFile 或 wx.downloadFile，因此无需为这两个接口额外配置域名白名单。