跳到主要内容
版本: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 是否一致。
  • onTokenIncorrecttoken 无效回调,建议排查 控制台 是否设置了 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();