• IMLib / IMKit >
 
• 无 UI SDK（IMLib） >
 
• 快速上手

本教程是为了让新手快速了解融云即时通讯能力库（IMLib）。在本教程中，你可以体验集成 SDK 的基本流程和 IMLib 的基础通信能力。

前置条件

创建融云开发者账号，获取 App Key。

控制台将自动为新账号创建一个应用。默认使用国内数据中心，默认提供开发环境。如果您已拥有融云开发者账户，您可以直接创建应用。

导入 SDK

NPM 引入（推荐）

1. 依赖安装

    
   npm install @rongcloud/engine@latest @rongcloud/imlib-next@latest -S
                 
   
                   
   已复制
                   复制代码
                 
                 
   1
   
   
   

2. 代码集成

    
   // CMD
   const RongIMLib = require('@rongcloud/imlib-next')
   
   // ES
   import * as RongIMLib from '@rongcloud/imlib-next'
   
                 
   
                   
   已复制
                   复制代码
                 
                 
   1
   2
   3
   4
   5
   6
   
   
   

CDN 链接引入

 
<script src="https://cdn.ronghub.com/RongIMLib-5.9.5.prod.js"></script>
              

                
已复制
                复制代码
              
              
1

初始化

在使用 IMLib 的能力之前，必须先调用 IMLib 的初始化接口，且务必保证该接口在应用全生命周期内仅被调用一次。

App Key 是使用 IMLib 进行即时通讯功能开发的必要条件，也是应用的唯一性标识。您必须拥有正确的 App Key，才能进行初始化。您可以登录融云控制台，查看您已创建的各个应用的 App Key。

只有在 App Key 相同的情况下，不同用户之间的消息才能互通。

 
// 应用初始化以获取 RongIMLib 实例对象，请务必保证此过程只被执行一次
RongIMLib.init({ appkey: '<Your-App-Key>' });
              

                
已复制
                复制代码
              
              
1
2

设置监听

初始化完成后，添加事件监听器，及时获取相关事件通知。

 
// 添加事件监听
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)
})
              

                
已复制
                复制代码
              
              
1
2
3
4
5
6
7
8
9
10
11
12
13
14

获取用户 Token

用户 Token 是与用户 ID 对应的身份验证令牌，是应用程序的用户在融云的唯一身份标识。应用客户端在使用融云即时通讯功能前必须与融云建立 IM 连接，连接时必须传入 Token。

在实际业务运行过程中，应用客户端需要通过应用的服务端调用 IM Server API 申请取得 Token。详见 Server API 文档 注册用户。

在本教程中，为了快速体验和测试 SDK，我们将使用控制台「北极星」开发者工具箱，从 API 调试页面调用 获取 Token 接口，获取到 userId 为 1 的用户的 Token。提交后，可在返回正文中取得 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"}
              

                
已复制
                复制代码
              
              
1
2
3
4

建立 IM 连接

使用以上步骤中获取的 Token, 模拟 userId 为 1 的用户连接到融云服务器。

 
RongIMLib.connect('<Your-Token>').then(res => {
    if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    console.log('链接成功, 链接用户 id 为: ', res.data.userId);
    } else {
    console.warn('链接失败, code:', res.code)
    }
})
              

                
已复制
                复制代码
              
              
1
2
3
4
5
6
7

获取会话列表

Web 端不具备持久化的数据存储能力，无法在本地持久化存储历史消息记录与会话列表，因此需要从融云服务端获取数据。从远端获取单群聊历史消息要求您已在控制台 IM 服务管理页面为当前使用的 App Key 开启单群聊消息云端存储服务。IM 旗舰版或IM 尊享版可开通该服务。具体功能与费用以融云官方价格说明页面及计费说明文档为准。

IMLib 通过会话数据中的 conversationType 与 targetId 两个属性值来标识会话的唯一性，对于两个属性的定义如下：

1. conversationType 用来标识会话类型（如：单聊、群聊...），其值为 RongIMLib.ConversationType 中的常量定义

2. 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);
  }
});
              

                
已复制
                复制代码
              
              
1
2
3
4
5
6
7
8

发送消息

以发送文本消息为例：

 
// 指定消息发送的目标会话
const conversation = {
  // targetId
  targetId: '<TargetId>',
  // 会话类型：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)
  }
});
              

                
已复制
                复制代码
              
              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

接收消息

当本端作为消息接收的一方，所接收的消息将通过 RongIMLib.addEventListener 和 Events.MESSAGES 注册的消息监听向业务层抛出。具体可参考上述 设置监听 部分

获取历史消息

Web 端不具备持久化的数据存储能力，无法在本地持久化存储历史消息记录与会话列表，因此需要从融云服务端获取数据。从远端获取单群聊历史消息要求您已在控制台 IM 服务管理页面为当前使用的 App Key 开启单群聊消息云端存储服务。IM 旗舰版或IM 尊享版可开通该服务。具体功能与费用以融云官方价格说明页面及计费说明文档为准。

 
const conversation = {
  targetId: '<TargetId>',
  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);
});
              

                
已复制
                复制代码
              
              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

断开连接

 
RongIMLib.disconnect().then(() => console.log('断开链接成功'));
              

                
已复制
                复制代码
              
              
1

后续步骤

以上步骤即 IMLib SDK 的快速集成与新手体验流程，您体验了基础 IM 通信能力和 UI 界面，更多详细介绍请参考后续各章节详细说明。