跳到主要内容

快速上手

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

前置条件

  • 注册开发者账号。注册成功后,控制台会默认自动创建您的首个应用,默认生成开发环境下的 App Key,使用国内数据中心。

  • 获取开发环境的应用 App Key。如不使用默认应用,请参考 如何创建应用,并获取对应环境 App Key 和 App Secret

    注意

    每个应用具有两个不同的 App Key,分别对应开发环境与生产环境,两个环境之间数据隔离。在您的应用正式上线前,可切换到使用生产环境的 App Key,以便上线前进行测试和最终发布。

  • 阅读 SDK 变更说明。SDK 在 5.2.4、5.4.0 均有较大变更,请确保您已充分了解相关差异,例如接口回调的方式变更等。

Demo 项目

融云 IMLib for uni-app SDK 提供了一个不含任何聊天界面的 Demo 项目,集中演示了各个接口的调用方法。

https://github.com/rongcloud/im-uni-app-wrapper

安装插件

  1. DCloud 插件市场 搜索并安装 RCUniIMV2原生插件,或者手动下载安装插件放入 nativeplugins 目录下。

  2. 在 manifest.json -> APP 原生插件配置 -> 加入原生插件 RCUniIMV2

  3. 运行 -> 运行到手机 -> 制作自定义调试基座。

  4. 安装即时通讯 Typescript 依赖项

    请从 uni-app 插件市场安装 RongCloud-IMWrapper-V2

    如果您曾使用 NPM 安装过即时通讯依赖项 @rongcloud/imlib-uni,请在升级时替换为从插件市场安装的方式,并注意修改初始化代码。

  5. 在项目中集成引用

    import RCIMIWEngine from "@/uni_modules/RongCloud-IMWrapper-V2/js_sdk/RCIMEngine"

初始化

在使用 SDK 所有功能之前,必须先调用此方法初始化 SDK。

初始化时需要传入上文获取的 App Key。引擎配置请参见引擎配置

let appKey = 'Your_AppKey'
let options = {};
// 可以将创建好的 engnie 保存到全局变量中,以便多页面使用
let engine = await RCIMIWEngine.create(appKey, options);

以上提供了一个简化的初始化示例,关于初始化的更多配置请参见初始化

获取用户 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"}

建立 IM 连接

  1. 使用 setOnConnectionStatusChangedListener 监听 IM 连接状态的变化,连接状态发生变化时返回 RCIMIWConnectionStatus。详见连接状态监听

    engine.setOnConnectionStatusChangedListener((res) => {
    //...
    });
  2. 使用上方获取的 Token,模拟 userId 为 1 的用户连接到融云服务器。调用结果会直接通过 connect 方法中传入的 RCIMIWConnectCallback 返回。

    let callback = {
    onDatabaseOpened:(res) => {
    //...
    },
    onConnected:(res) => {
    //...
    }};
    let code = await engine.connect(token, timeout, callback);

SDK 已实现自动重连机制,请参见连接

监听消息

实现此功能需要开发者实现消息监听回调。

设置消息接收监听器,用于接收所有类型的实时或者离线消息。

  1. message 接收到的消息对象

  2. left 当客户端连接成功后,服务端会将所有补偿消息以消息包的形式下发给客户端,最多每 200 条消息为一个消息包,即一个 Package, 客户端接受到消息包后,会逐条解析并通知应用。left 为当前消息包(Package)里还剩余的消息条数

  3. offline 消息是否离线消息

  4. hasPackage 是否在服务端还存在未下发的消息包

    engine.setOnMessageReceivedListener((res) => {
    //...
    });

发送消息

注意

SDK 5.4.0 版本及以后,大部分接口新增了 callback 参数,方法调用成功后的数据会在 callback 中回调。

发送普通消息使用 SendMessage 方法。发送结果通过 RCIMIWSendMessageCallback 中的方法返回。您可以通过消息介绍了解如何构建普通消息,例如文本消息、引用消息、自定义消息等。

let message = await engine.createTextMessage(
type,
targetId,
channelId,
text,
);

let callback = {
onMessageSaved:(res) => {
//...
},
onMessageSent:(res) => {
//...
}};
let code = await engine.sendMessage(message, callback);

发送媒体消息使用 SendMediaMessage 方法。发送进度及结果通过 RCIMIWSendMediaMessageListener 中的方法返回。您可以通过消息介绍了解如何构建媒体消息,例如图片消息、语音消息、视频消息、文件消息、GIF 消息等。

uni.chooseImage({
count: 1,
success: async (res) => {
if (res.tempFilePaths.length < 0) return;
//转为平台路径
let path = 'file:///' + plus.io.convertLocalFileSystemURL(res.tempFilePaths[0])
//创建图片消息
let message = await engine.createImageMessage(type, targetId, channelId, path);
}
});

let listener = {
onMediaMessageSaved:(res) => {
//...
},
onMediaMessageSending:(res) => {
//...
},
onSendingMediaMessageCanceled:(res) => {
//...
},
onMediaMessageSent:(res) => {
//...
}};
let code = await engine.sendMediaMessage(message, listener);

退出登录

let code = await engine.disconnect(receivePush);

引擎销毁

let code = await engine.destroy();