全部文档

更新时间: 2021-03-08

# 兼容说明

# 导入 SDK

# 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

# 建立 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 通过会话数据中的 conversationType 与 targetId 两个属性值来标识会话的唯一性，对于两个属性的定义如下：

  1. conversationType 用来标识会话类型（如：单聊、群聊...），其值为 RongIMLib.CONVERSATION_TYPE 中的常量定义
  2. targetId 用来标识与本端进行对话的人员或群组 Id：
  • 当 conversationType 值为 RongIMLib.CONVERSATION_TYPE.PRIVATE，targetId 为对方用户 Id
  • 当 conversationType 值为 RongIMLib.CONVERSATION_TYPE.GROUP，targetId 为当前群组 Id
  • 当 conversationType 值为 RongIMLib.CONVERSATION_TYPE.CHATROOM，targetId 为聊天室 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

文档是否解决您的问题 ?

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