快速上手
本教程旨在帮助开发者快速了解和掌握 IMLib SDK(融云即时通讯能力库)的基础集成流程与核心通信能力。通过本教程,您将完成从 IMLib SDK 导入、初始化、设置监听、建立连接和收发消息等全流程操作。
uni-app 原生插件不能与 uni-app Imkit SDK 一起使用,uni-app Imkit SDK 是基于 Web IMLib SDK 开发的,uni-app 原生插件是基于 Android IOS 原生 SDK 开发的,所以只能使用其中一个,如果您单独使用 uni-app Imkit SDK 时,有聊天室等需求时,您可以调用 Web IMLib SDK 的 API 进行开发。
前置条件
- 注册开发者账号。注册成功后,控制台会默认创建您的首个应用,默认生成开发环境下的 App Key,使用国内数据中心。
- 获取开发环境的应用 App Key。如不使用默认应用,请参考 如何创建应用,并获取对应环境 App Key 和 App Secret。
每个应用具有两个不同的 App Key,分别对应开发环境与生产环境,两个环境之间数据隔离。在您的应用正式上线前,可切换到使用生产环境的 App Key,以 便上线前进行测试和最终发布。 应用的 App Key / Secret 是获取连接融云服务器身份凭证的必要条件,请注意不要泄露。
阅读 SDK 变更说明。SDK 在 5.2.4、5.4.0 均有较大变更,请确保您已充分了解相关差异,例如接口回调的方式变更等。
Demo 项目
融云 IMLib for uni-app SDK 提供了一个不含任何聊天界面的 Demo 项目,集中演示了各个接口的调用方法。
https://github.com/rongcloud/im-uni-app-wrapper
安装插件
-
在 DCloud 插件市场 搜索并安装 RCUniIMV2 原生插件,或者手动下载安装插件放入
nativeplugins
目录下。 -
在 manifest.json -> APP 原生插件配置 -> 加入原生插件
RCUniIMV2
。 -
运行 -> 运行到手机 -> 制作自定义调试基座。
-
安装即时通讯 Typescript 依赖项
请从 uni-app 插件市场安装 RongCloud-IMWrapper-V2
如果您曾使用 NPM 安装过即时通讯依赖项
@rongcloud/imlib-uni
,请在升级时替换为从插件市场安装的方式,并注意修改初始化代码。 -
在项目中集成引用
JavaScriptimport RCIMIWEngine from "@/uni_modules/RongCloud-IMWrapper-V2/js_sdk/RCIMEngine"
初始化 IMLib SDK
为确保您可以正常连接融云服务器和使用融云即时通讯服务(IM 服务),您须调用 create
方法初始化 IMLib SDK。初始化前,您须在融云控制台中获取 App Key,并设置好 RCIMIWEngineOptions
(初始化配置)。详见初始化。
RCIMIWEngineOptions 中封装了 RCIMIWAreaCode
(数据中心的区域码),naviServer
(导航服务地址)、fileServer
(文件服务地址)、statisticServer
(数据统计服务地址),enablePush
(推送的开关)。详见引擎配置。(注意: RCIMIWAreaCode
跟 naviServer
只设置其中一个即可)。
如果您使用北京数据中心,则不需设置 RCIMIWAreaCode
或者 naviServer
,IMLib SDK 默认连接北京数据中心。
let appKey = 'Your_AppKey'
let options = {};
// 可以将创建好的 engnie 保存到全局变量中,以便多页面使用
let engine = await RCIMIWEngine.create(appKey, options);
监听消息
通过设置消息接收监听器,用户可接收所有类型的实时消息和离线消息。
-
message
接收到的消息对象 -
left
当客户端连接成功后,服务端会将 所有补偿消息以消息包的形式下发给客户端,最多每 200 条消息为一个消息包,即一个 Package, 客户端接受到消息包后,会逐条解析并通知应用。left 为当前消息包(Package)里还剩余的消息条数 -
offline
消息是否离线消息 -
hasPackage
是否在服务端还存在未下发的消息包TypeScriptengine.setOnMessageReceivedListener((res) => {
//...
});