快速上手
本教程是为了让新手快速了解融云即时通讯能力库(IMLib)。在本教程中,你可以体验集成 SDK 的基本流程和 IMLib 的基础通信能力。另外,我们还提供了微信小程序 Demo(GitHub)与支付宝小程序 Demo(GitHub),供您参考与体验。
融云开发者账户
融云开发者账户是使用融云 SDK 产品的必要条件。
在开始之前,请先前往融云官网注册开发者账户。注册后,控制台将自动为你创建一个应用,默认为开发环境应用,使用国内数据中心。请获取该应用的 App Key,在本教程中使用。
App Secret 用于生成数据签名,仅在请求融云服务端 API 接口时使用。本教程中暂不涉及。
如果你已拥有融云开发者账户,你可以直接选择合适的环境,创建应用。
您需要记录上图所示的应用 App Key,在本教程中使用。
应用的 AppKey 与 Secret 是获取连接融云服务器身份凭证的必要条件,请注意不要泄露。
导入 SDK
IMLib 对 Typescript 的使用者提供了友好的类型化支持,推荐开发者使用 Typescript 进行业务开发以提升代码健壮性及可维护性。
依赖安装
npm install @rongcloud/engine@latest @rongcloud/imlib-next@latest -S
代码集成
// 非 ESModule
const RongIMLib = require('@rongcloud/imlib-next')
// ESModule
import * as RongIMLib from '@rongcloud/imlib-next'
App Key
App Key
是使用 IMLib 进行即时通讯功能开发的必要条件,也是应用的唯一性标识。在集成使用 IMLib 之前,请务必先通过 控制台 注册并获取开发者的专属 App Key
。
只有在 App Key
相同的情况下,不同用户之间的消息才能互通。
初始化
在使用 IMLib 的能力之前,必须先调用 IMLib 的初始化接口,且务必保证该接口在应用全生命周期内仅被调用一次。
// 应用初始化以获取 RongIMLib 实例对象,请务必保证此过程只被执行一次
RongIMLib.init({ appkey: '<Your-App-Key>' });
设置监听
初始化完成后,添加事件监听器,及时获取相关事件通知。
// 添加事件监听
const Events = RongIMLib.Events
RongIMLib.addEventListener(Events.CONNECTING, () => {
console.log('正在链接服务器')
})
RongIMLib.addEventListener(Events.CONNECTED, () => {
console.log('已经链接到服务器')
})
RongIMLib.addEventListener(Events.MESSAGES, (evt) => {
console.log(evt.messages)
})
建立 IM 连接
App Key
是应用的唯一性标识,Token
则是用户的唯一性标识,是用户连接融云 IM 服务所必需的身份凭证。Token
一般由开发者的应用服务器调用融云 Server API 获取 Token 接口获取之后,由应用服务器下发到应用客户端。
以下示例代码假定客户端已获取 Token
RongIMLib.connect('<Your-Token>').then(res => {
if (res.code === RongIMLib.ErrorCode.SUCCESS) {
console.log('链接成功, 链接用户 id 为: ', res.data.userId);
} else {
console.warn('链接失败, code:', res.code)
}
})
获取会话列表
Web 端不具备持久化的数据存储能力,无法在本地持久化存储历史消息记录与会话列表,因此需要从融云服务端获取数据。从远端获取单群聊历史消息要求您已在控制台 IM 服务管理页面为当前使用的 App Key 开启单群聊消息云端存储服务。IM 旗舰版或IM 尊享版可开通该服务。具体功能与费用以融云官方价格说明页面及计费说明文档为准。
该功能需要在调用 RongIMLib.connect()
并且建立连接成功之后执行。
IMLib 通过会话数据中的 conversationType
与 targetId
两个属性值来标识会话的唯一性,对于两个属性的定义如下:
conversationType
用来标识会话类型(如:单聊、群聊...),其值为RongIMLib.ConversationType
中的常量定义targetId
用来标识与本端进行对话的人员或群组 Id:
- 当
conversationType
值为RongIMLib.ConversationType.PRIVATE
,targetId
为对方用户 Id - 当
conversationType
值为RongIMLib.ConversationType.GROUP
,targetId
为当前群 组 Id - 当
conversationType
值为RongIMLib.ConversationType.CHATROOM
,targetId
为聊天室 Id
// 获取会话列表
RongIMLib.getConversationList().then(({ code, data: conversationList }) => {
if (code === 0) {
console.log('获取会话列表成功', conversationList);
} else {
console.log('获取会话列表失败: ', error.code, error.msg);
}
});