快速上手
本教程旨在帮助开发者快速了解和掌握 IMLib SDK(融云即时通讯能力库)的基础集成流程与核心通信通能力。通过本教程,您将完成从 IMLib SDK导入、初始化、设置监听、建立连接和发送消息等全流程操作。
准备工作
- 访问融云控制台,注册您的开发者账号。注册成功后,控制台自动在开发环境中为您创建一个应用。
- 在控制台的基本信息页,获取您的应用在开发环境的 App Key。您可在基本信息页查看应用的信息,如 App Key、App Secret、所属数据中心(默认为北京)。
如您想自己创建应用参考如何创建应用,并获取对应环境 App Key 和 App Secret。
- 每个应用均拥有两个不同的 App Key,分别对应开发环境与生产环境,且两个环境之间数据相互隔离。在您的应用正式上线前,建议切换到生产环境的 App Key,以便完成上线前全流程测试和最终发布。
- App Secret 用于生成数据签名,仅在请求融云服务端 API 接口时使用。本教程中暂不涉及。应用的 App Key / Secret 是获取连接融云服务器身份凭证的必要条件,请注意不要泄露。
导入 SDK
IMLib 对 Typescript 的使用者提供了友好的类型化支持,推荐开发者使用 Typescript 进行业务开发以提升代码健壮性及可维护性。
NPM 引入(推荐)
-
依赖安装
bashnpm install @rongcloud/engine@latest @rongcloud/imlib-next@latest -S
-
代码集成
JavaScript// CommonJS
const RongIMLib = require('@rongcloud/imlib-next')
// ES Module
import * as RongIMLib from '@rongcloud/imlib-next'
CDN 链接引入
<script src="https://cdn.ronghub.com/RongIMLib-5.9.5.prod.js"></script>
初始化
在使用 IMLib 的能力之前,必须先调用 IMLib 的初始化接口,且务必保证该接口在应用全生命周期内仅被调用一次。
App Key 是使用 IMLib 进行即时通讯功能开发的必要条件,也是应用的唯一性标识。您必须拥有正确的 App Key,才能进行初始化。您可以登录融云控制台,查看您已创建的各个应用的 App Key。
只有在 App Key 相同的情况下,不同用户之间的消息才能互通。
// 应用初始化以获取 RongIMLib 实例对象,请务必保证此过程只被执行一次
RongIMLib.init({ appkey: '<Your-App-Key>' });
设置监听
初始化完成后,添加事件监听器,以便实时接收 SDK 触发的各类通知事件。
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 连接
- 为模拟用户通过融云 IM 服务器收发消息,您需要首先注册一个用户。在实际业务中,应用客户端通过应用服务端调用融云 IM Server API 获取 token。详见 Server API 文档注册用户。在本教程中,为了快速体验融云服务,您可在控制台「北极星」的 API 调试页面调用获取 Token 接口,获取到 userId 为 1 的用户的 Token。调用返回如下:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"code":200,
"userId":"1",
"token":"gxld6GHx3t1eDxof1qtxxYrQcjkbhl1V@sgyu.cn.example.com;sgyu.cn.example.com"
}
- 调用 connect 方法,将 userId 为 1 的用户连接融云 IM 服务。注:IMLib SDK 有重连机制,因此一个应用生命周期内调用一次 connect即可,详见连接。
RongIMLib.connect('<Your-Token>').then(res => {
if (res.code === RongIMLib.ErrorCode.SUCCESS) {
console.log('链接成功, 链接用户 id 为: ', res.data.userId);
} else {
console.warn('链接失败, code:', res.code)
}
})
获取会话列表
IMLib 通过会话数据中的 conversationType
与 targetId
两个属性值来标识会话的唯一性,对于两个属性的定义如下:
会话类型 | 枚举 | 枚举值 | targetId 说明 |
---|---|---|---|
单聊 | RongIMLib.ConversationType.PRIVATE | 1 | 对方用户 Id |
群聊 | RongIMLib.ConversationType.GROUP | 3 | 群组 Id |
聊天室 | RongIMLib.ConversationType.CHATROOM | 4 | 聊天室 Id |
// 获取会话列表
RongIMLib.getConversationList().then(({ code, data: conversationList }) => {
if (code === 0) {
console.log('获取会话列表成功', conversationList);
} else {
console.log('获取会话列表失败: ', error.code, error.msg);
}
});
发送消息
您可以模拟向 userId 为 2 的用户发送一条文本消息。除了文本消息,您还可发送图片、文件、语音、文件等不同类型的消息,详见消息类型。
// 指定消息发送的目标会话
const conversation = {
// targetId
targetId: '2',
// 会话类型:RongIMLib.ConversationType.PRIVATE | RongIMLib.ConversationType.GROUP
conversationType: RongIMLib.ConversationType.PRIVATE
};
// 构建文本消息
const message = new RongIMLib.TextMessage({ content: 'message content' })
// 发送消息
RongIMLib.sendMessage(conversation, message).then(({ code, data }) => {
if (code === 0) {
console.log('消息发送成功:', data)
} else {
console.log('消息发送失败:', code)
}
});
接收消息
当本端作为消息接收的一方,所接收的消息将通过 RongIMLib.addEventListener 和 Events.MESSAGES
注册的消息监听向业务层抛出。具体可参考上述设置监听小节
获取历史消息
示例:获取 targetId = 2 的历史消息。
const conversation = {
targetId: '2',
conversationType: RongIMLib.ConversationType.PRIVATE
};
const option = {
// 获取历史消息的时间戳,默认为 0,表示从当前时间获取
timestamp: +new Date(),
// 获取条数,有效值 1-100,默认为 20
count: 20,
};
RongIMLib.getHistoryMessages(conversation, option).then(result => {
const list = result.data.list; // 获取到的消息列表
const hasMore = result.data.hasMore; // 是否还有历史消息可获取
console.log('获取历史消息成功', list, hasMore);
}).catch(error => {
console.log('获取历史消息失败', error.code, error.msg);
});
断开连接
- 断开当前用户连接,连接断开后无法接收消息、发送消息、获取历史消息、获取会话列表...
- 在下次连接融云成功后,会收取上次离线后的消息,离线消息默认保存 7 天。
RongIMLib.disconnect().then(() => console.log('断开链接成功'));
后续步骤
以上步骤即 IMLib SDK 的快速集成与新手体验流程,您体验了基础 IM 通信能力,更多详细介绍请参考后续各章节详细说明。