更新时间: 2021-04-21

# 兼容说明

Chrome Firefox Safari IE Edge QQ 浏览器 微信 浏览器 Android
✔️ ✔️ ✔️ 9+ ✔️ ✔️ ✔️ 4.4+

# 导入 SDK

IMLib 4.0 底层使用 Typescript 进行了重构,对 Typescript 的使用者提供了友好的类型化支持,推荐开发者使用 Typescript 进行业务开发以提升代码健壮性及可维护性。

NPM 引入(推荐)

  1. 依赖安装
npm install @rongcloud/imlib-v4
已复制
1
  1. 代码集成
// 非 ESModule
const RongIMLib = require('@rongcloud/imlib-v4')
// ESModule
import * as RongIMLib from '@rongcloud/imlib-v4'
已复制
1
2
3
4

CDN 引入

<!-- 压缩版 -->
<script src="https://cdn.ronghub.com/RongIMLib-4.4.1.prod.js"></script>
已复制
1
2

# App Key

App Key 是使用 IMLib 进行即时通讯功能开发的必要条件,也是应用的唯一性标识。在集成使用 IMLib 之前,请务必先通过 融云开发者后台 (opens new window)注册并获取开发者的专属 App Key

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

# 初始化

IMLib 提供的所有能力基于 IMLib 初始化后获取的实例对象,因此在使用 IMLib 的能力之前,必须先调用 IMLib 的初始化接口,且务必保证该接口在应用全生命周期内仅被调用一次

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

后续所有代码示例中的 im 均指通过初始化获取到的 RongIMLib 实例对象

# 设置监听

初始化完成后,应在建立连接之前im 对象添加事件监听器,及时获取相关事件通知。

// 添加事件监听
im.watch({
  // 监听会话列表变更事件
  conversation (event) {
    // 假定存在 getExistedConversationList 方法,以获取当前已存在的会话列表数据
    const conversationList = getExistedConversationList()
    // 发生变更的会话列表
    const updatedConversationList = event.updatedConversationList;
    // 通过 im.Conversation.merge 计算最新的会话列表
    const latestConversationList = im.Conversation.merge({ conversationList, updatedConversationList })
  },
  // 监听消息通知
  message (event) {
    // 新接收到的消息内容
    const message = event.message;
  },
  // 监听 IM 连接状态变化
  status (event) {
    console.log('connection status:', event.status);
  },
  // 监听聊天室 KV 数据变更
  chatroom (event) {
    /**
     * 聊天室 KV 存储数据更新
     * @example
     * [
     *  {
     *    "key": "name",
     *    "value": "我是小融融",
     *    "timestamp": 1597591258338, 
     *    "chatroomId": "z002", 
     *    "type": 1 // 1: 更新( 含:修改和新增 )、2: 删除
     *  },
     * ]
     */
    const updatedEntries = event.updatedEntries
  },
  expansion (event) {
    /**
     * 更新的消息拓展数据
     * @example {
     *    expansion: { key: 'value' },      // 设置或更新的扩展值
     *    messageUId: 'URIT-URIT-ODMF-DURR' // 设置或更新扩展的消息 uid
     * }
     */
    const updatedExpansion = event.updatedExpansion;
    /**
     * 删除的消息拓展数据
     * @example {
     *    deletedKeys: ['key1', 'key2'],    // 设置或更新的扩展值
     *    messageUId: 'URIT-URIT-ODMF-DURR' // 设置或更新扩展的消息 uid
     * }
     */
    const deletedExpansion = event.deletedExpansion;
  }
});
已复制
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

# 建立 IM 连接

App Key 是应用的唯一性标识,Token 则是用户的唯一性标识,是用户连接融云 IM 服务所必需的身份凭证。Token 一般由开发者的应用服务器调用融云 Server API 获取 Token 接口获取之后,由应用服务器下发到应用客户端。

以下示例代码假定客户端已获取 Token

im.connect({ token: '<Your-Token>' }).then(user => {
  console.log('链接成功, 链接用户 id 为: ', user.id);
}).catch(error => {
  console.log('链接失败: ', error.code, error.msg);
});
已复制
1
2
3
4
5

# 获取会话列表

Web 端不具备持久化的数据存储能力,需要开发者开启 IM 商用版 - 单群聊云存储 (opens new window)功能才能生效。 该功能需要在调用 im.connect() 并且建立连接成功之后执行。

IMLib 通过会话数据中的 conversationTypetargetId 两个属性值来标识会话的唯一性,对于两个属性的定义如下:

  1. conversationType 用来标识会话类型(如:单聊、群聊...),其值为 RongIMLib.CONVERSATION_TYPE 中的常量定义
  2. targetId 用来标识与本端进行对话的人员或群组 Id:
  • conversationType 值为 RongIMLib.CONVERSATION_TYPE.PRIVATEtargetId 为对方用户 Id
  • conversationType 值为 RongIMLib.CONVERSATION_TYPE.GROUPtargetId 为当前群组 Id
  • conversationType 值为 RongIMLib.CONVERSATION_TYPE.CHATROOMtargetId 为聊天室 Id
// 获取会话列表
im.Conversation.getList().then(conversationList => {
  console.log('获取会话列表成功', conversationList);
}).catch(error => {
  console.log('获取会话列表失败: ', error.code, error.msg);
});
已复制
1
2
3
4
5
6

# 发送消息

该功能需要在调用 im.connect() 并且建立连接成功之后执行。 IMLib 内置消息类型可通过 RongIMLib.MESSAGE_TYPE 获取其常量定义

// 获取指定会话的抽象实例,对于会话的操作基于此实例完成
const conversation = im.Conversation.get({
  // targetId
  targetId: '<TargetId>',
  // 会话类型:RongIMLib.CONVERSATION_TYPE.PRIVATE | RongIMLib.CONVERSATION_TYPE.GROUP
  type: '<Conversation-Type>'
});
// 向会话内发消息
conversation.send({
  // 消息类型,其中 RongIMLib.MESSAGE_TYPE 为 IMLib 内部的内置消息类型常量定义
  messageType: RongIMLib.MESSAGE_TYPE.TEXT, // 'RC:TxtMsg'
  // 消息内容
  content: {
    content: 'Hello RongCloud' // 文本内容
  }
}).then(function(message){
  console.log('发送文字消息成功', message);
}).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
18
19
20

# 接收消息

当本端作为消息接收的一方,所接收的消息将通过 im.watch() 注册的消息监听向业务层抛出。具体可参考上述 设置监听 部分

# 获取历史消息

Web 端不具备持久化的数据存储能力,需要开发者开启 IM 商用版 - 单群聊云存储 (opens new window)功能才能生效。 该功能需要在调用 im.connect() 并且建立连接成功之后执行。

const conversation = im.Conversation.get({
  targetId: '<TargetId>',
  type: '<Conversation-Type>'
});
const option = {
  // 获取历史消息的时间戳,默认为 0,表示从当前时间获取
  timestamp: +new Date(),
  // 获取条数,有效值 1-20,默认为 20
  count: 20,
};
conversation.getMessages(option).then(result => {
  const list = result.list;       // 获取到的消息列表
  const hasMore = result.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

# 断开连接

断开当前用户连接,连接断开后无法接收消息、发送消息、获取历史消息、获取会话列表... 在下次连接融云成功后,会收取上次离线后的消息,离线消息默认保存 7 天。

im.disconnect().then(() => console.log('断开链接成功'));
已复制
1

文档是否解决您的问题 ?

如果遇到产品相关问题,您可 提交工单 寻求帮助