跳到主要内容
版本：2.X

SDK 快速集成

关于停止维护 IMLib v2 旧版 SDK 的声明​

注意

  • Web IMLib v2 版本目前已停止维护，建议您优先选择最新的 IMLib 版本。
  • 已集成 IMLib v2 版本的用户，转为使用 Adapter 方式进行支持。集成旧版 2x SDK 的客户可以通过 RongIMLib-v2-Adapter 无缝替换升级。详见 升级说明。
  • 未来我们将在 RongIMLib-v2-Adapter 上进行问题修复，但不会增加新功能。

导入 SDK​

NPM 引入（推荐）

  1. 依赖安装

    npm install @rongcloud/imlib-v2-adapter

  2. 代码集成。

    // 非 ESModule
    const RongIMLib = require('@rongcloud/imlib-v2-adapter')
    // ESModule
    import * as RongIMLib from '@rongcloud/imlib-v2-adapter'

CDN 引入方式详见引入 SDK。

初始化​

从 融云开发者控制台 注册后可得到 Appkey。

开发者在使用融云 SDK 所有功能之前，开发者必须先调用此方法初始化 SDK。 在应用整个生命周期中，开发者只需要将 SDK 初始化一次。

RongIMLib.RongIMClient.init('appKey'); //控制台 -> 基本信息 获取

设置监听​

需先设置监听再连接服务器。

/* 连接状态监听器 */
RongIMClient.setConnectionStatusListener({
  onChanged: function (status) {
    /* status 标识当前连接状态 */
    console.log('连接成功');
  }
});
/* 消息监听器 */
RongIMClient.setOnReceiveMessageListener({
  onReceived: function (message) {
    console.log(message);
  }
});

连接融云​

  • token ：用户令牌，相当于当前用户连接融云的身份凭证。在连接融云服务器之前，需要 App Server 通过融云 Server API 获取 Token，客户端获取到这个 Token 即可连接融云服务器。
  • onSuccess ：连接成功回调，会返回 token 对应的 userId。
  • onError ：连接失败回调，请您检查客户端初始化使用的 AppKey 和获取 token 用的 AppKey 是否一致。
  • onTokenIncorrect ：token 无效回调，建议排查 控制台 是否设置了 Token 有效期，或重新获取 Token 再建立连接 。
/* 控制台获取或 Server API */
var token = 'token';
RongIMClient.connect(token, {
  onSuccess: function(userId) {
    console.log('连接成功, 用户 ID 为', userId);
    // 连接已成功, 此时可通过 getConversationList 获取会话列表并展示
  },
  onTokenIncorrect: function() {
    console.log('连接失败, 失败原因: token 无效');
  },
  onError: function(errorCode) {
    console.log('连接失败, 失败原因: ', errorCode);
  }
});

获取会话列表​

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

获取会话列表需要在 connect 成功后执行。

RongIMClient.getInstance().getConversationList({
  onSuccess: function(list) {
      // list => 会话列表集合
      // 获取成功, 此处可通过处理 list 在 UI 上展示会话列表
  },
  onError: function(error) {
      // do something
  }
}, null);

发送消息​

发送单聊文本消息需要在 connect 成功后执行。

向用户 B 发送一条文本消息，发送成功会走 onSuccess 回调函数，发送失败会走 onError 失败回调，用户可根据 errorCode 进行异常信息调试。

var msg = new RongIMLib.TextMessage({ content: 'hello RongCloud!', extra: '附加信息' });
var conversationType = RongIMLib.ConversationType.PRIVATE; // 单聊
var targetId = 'userB'; // 用户 B 的 userId
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, {
    onSuccess: function (message) {
        // message 为发送的消息对象并且包含服务器返回的消息唯一 ID 和发送消息时间戳
        console.log('发送成功');
    },
    onError: function (errorCode, message) {
        console.log(errorCode)
    }
});

接收消息​

用户 B 连接服务器成功后，可通过消息监听函数 RongIMClient.setOnReceiveMessageListener 接收用户 A 发送的消息,收到消息会自动触发 onReceived 回调函数。

获取历史消息​

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

获取历史消息需要在 connect 成功后执行。

var conversationType = RongIMLib.ConversationType.PRIVATE; //单聊, 其他会话选择相应的消息类型即可
var targetId = "userA"; // 想获取自己和谁的历史消息，targetId 赋值为对方的 userId。类型： string
var timestamp = 0; // 若从头开始获取历史消息，请赋值为 0；
var count = 20; // 每次获取的历史消息条数，范围 0-20 条，可以多次获取
RongIMLib.RongIMClient.getInstance().getHistoryMessages(conversationType, targetId, timestamp, count, {
    onSuccess: function(list, hasMsg) {
        // list => Message 数组。
        // hasMsg => 是否还有历史消息可以获取。
    },
    onError: function(error) {
        console.log('GetHistoryMessages, errorcode:' + error);
    }
});

断开连接​

断开当前用户连接。调用后不再接收消息, 不可发送消息, 不可获取历史消息, 不可获取会话列表

在下次连接融云成功后，会收取上次离线后的消息，离线消息最多可以保存 7 天。

RongIMClient.getInstance().disconnect();