快速上手
本教程将帮助您快速集成融云即时通讯 UI 组件库（uni-app IMKit）。通过本教程，您可以了解完整的集成流程并体验 IMKit 提供的 UI 界面。
平台支持
| 支持平台 | 支持情况 |
|---|---|
| Android | ✅ |
| iOS | ✅ |
H5 | ✅ |
| 小程序 | ✅ |
配置项要求
在开始集成之前，请确保您的开发环境满足以下要求：
| 配置项 | 要求 | 版本说明 |
|---|---|---|
| 集成开发环境 | HBuilderX | 建议升级到最新版本，最低版本要求 4.57 及以上 |
| 开发语言 | TypeScript | 5.1.0+ |
| Node.js 版本 | v18 及以上 | 18.1.0+ |
| 框架 | Vue3 和 Vue2 | - |
1. 前置条件
- 注册开发者账号。注册成功后，控制台会默认自动创建您的首个应用，默认生成开发环境下的 App Key，使用国内数据中心。
- 获取开发环境的应用 App Key。如不使用默认应用，您可以创建应用，并获取对应环境 App Key 和 App Secret。
- 开通单群聊消息云端存储增值服务。由于 uni-app IMKit 基于 Web IMLib，获取会话列表和历史消息需要从融云服务端获取数据，请在控制台 IM 服务的服务购买页面为当前使用的 App Key 选择单群聊消息云端存储增值服务。
提示
每个应用具有两个不同的 App Key，分别对应开发环境与生产环境，两个环境之间数据隔离。在您的应用正式上线前，可切换到使用生产环境的 App Key，以便上线前进行测试和最终发布。
2. 创建项目
使用 HBuilderX 创建 uni-app 项目：
- 打开 HBuilderX。
- 点击菜单栏的文件 > 新建 > 项目。
- 选择 uni-app 模板。
- 填写项目名称，选择默认模板。
- 点击创建完成项目创建。
3. 下载资源
下载源码及 demo 资源 https://github.com/rongcloud/rc-uikit-uniapp
- RCUIKit 源码：包含 UI Kit 的核心实现
- Demo 源码：包含完整的示例项目
将下载的 RCUIKit 源码目录完整复制到您的 uni-app 项目根目录下。
4. 配置路由
在 pages.json 中添加以下配置：
JSON
{
"pages": [ //pages数组中第一项表示应用启动页，参考：https://uniapp.dcloud.io/collocation/pages
{
// 会话列表页
"path": "RCUIKit/pages/conversation/index",
"style": {
"navigationStyle": "custom"
}
},
{
// 会话页
"path": "RCUIKit/pages/chat/index",
"style": {
"navigationBarTitleText": "uni-uikit-demo",
"navigationStyle": "custom",
"app-plus": {
"bounce": "none"
}
}
},
{
// 转发消息页
"path": "RCUIKit/pages/chat/forward-message",
"style": {
"navigationStyle": "custom"
}
},
{
// 视频播放页
"path": "RCUIKit/pages/chat/video-play",
"style": {
"navigationStyle": "custom"
}
},
{
// 消息阅读状态页
"path": "RCUIKit/pages/chat/read-receipt-status",
"style": {
"navigationStyle": "custom"
}
}
]
}
这些路由的用途和关联关系详见UI 页面。如需定位 RCUIKit 页面和组件源码，请参见RCUIKit 源码结构；如需了解 Store 的使用方式，请参见消息与会话管理。
5. 项目配置
在项目的 manifest.json 文件中，添加以下配置：
-
设置
networkTimeout用于控制请求超时时间，如未设置可能会影响媒体消息的上传逻辑。设置如下：JSON"networkTimeout" : {
"request" : 60000, // 单位：毫秒
"uploadFile" : 60000 // 媒体文件上传超时(1分钟)，如不满足可按需调整
}, -
设置所需模块，用于音频、视频、推送等模块的使用。设置如下：
JSON/* 模块配置 */
"modules" : {
"Record" : {},
"Camera" : {},
"VideoPlayer" : {},
"Push" : {}
}, -
应用打包配置如下：
JSON/* android打包配置 */
"android" : {
"permissions" : [
"<uses-permission android:name=\"android.permission.POST_NOTIFICATIONS\"/>"
]
},JSON/* ios打包配置 */
"ios" : {
"capabilities" : {
"entitlements" : {}
},
"dSYMs" : false,
"privacyDescription" : {
"NSPhotoLibraryUsageDescription" : "需要访问相册",
"NSPhotoLibraryAddUsageDescription" : "需要访问相册",
"NSCameraUsageDescription" : "需要访问摄像头",
"NSMicrophoneUsageDescription" : "需要访问麦克风"
}
},
完整配置可参考：
JSON
{
"name" : "UniKit Demo",
"appid" : "",
"description" : "",
"versionName" : "1.0.0",
"versionCode" : "100",
"transformPx" : false,
"locale" : "zh-Hans", // 设置默认语言，
"networkTimeout" : {
"request" : 60000,
"uploadFile" : 60000 // 5 分钟
},
/* 5+App特有相关 */
"app-plus" : {
"usingComponents" : true,
"nvueStyleCompiler" : "uni-app",
"compilerVersion" : 3,
"splashscreen" : {
"alwaysShowBeforeRender" : true,
"waiting" : true,
"autoclose" : true,
"delay" : 0
},
/* 模块配置 */
"modules" : {
"Record" : {},
"Camera" : {},
"VideoPlayer" : {},
"Push" : {}
},
/* 应用发布信息 */
"distribute" : {
/* android打包配置 */
"android" : {
"permissions" : [
"<uses-permission android:name=\"android.permission.CHANGE_NETWORK_STATE\"/>",
"<uses-permission android:name=\"android.permission.MOUNT_UNMOUNT_FILESYSTEMS\"/>",
"<uses-permission android:name=\"android.permission.VIBRATE\"/>",
"<uses-permission android:name=\"android.permission.READ_LOGS\"/>",
"<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\"/>",
"<uses-feature android:name=\"android.hardware.camera.autofocus\"/>",
"<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/>",
"<uses-permission android:name=\"android.permission.CAMERA\"/>",
"<uses-permission android:name=\"android.permission.GET_ACCOUNTS\"/>",
"<uses-permission android:name=\"android.permission.READ_PHONE_STATE\"/>",
"<uses-permission android:name=\"android.permission.CHANGE_WIFI_STATE\"/>",
"<uses-permission android:name=\"android.permission.WAKE_LOCK\"/>",
"<uses-permission android:name=\"android.permission.FLASHLIGHT\"/>",
"<uses-feature android:name=\"android.hardware.camera\"/>",
"<uses-permission android:name=\"android.permission.WRITE_SETTINGS\"/>",
"<uses-permission android:name=\"android.permission.POST_NOTIFICATIONS\"/>"
]
},
/* ios打包配置 */
"ios" : {
"capabilities" : {
"entitlements" : {}
},
"dSYMs" : false,
"privacyDescription" : {
"NSPhotoLibraryUsageDescription" : "需要访问相册",
"NSPhotoLibraryAddUsageDescription" : "需要访问相册",
"NSCameraUsageDescription" : "需要访问摄像头",
"NSMicrophoneUsageDescription" : "需要访问麦克风"
}
},
/* SDK配置 */
"sdkConfigs" : {
"push" : {},
"ad" : {}
}
}
},
/* 快应用特有相关 */
"quickapp" : {},
/* H5 特有相关 ：关闭 treeshaking 是为了规避 uni[methond]() is not a function 的问题 */
"h5" : {
"optimization" : {
"treeShaking" : {
"enable" : false
}
}
},
/* 小程序特有相关 */
"mp-weixin" : {
"libVersion" : "latest",
"appid" : "",
"setting" : {
"urlCheck" : false,
"es6" : true,
"minified" : true,
"ignoreDevUnusedFiles" : false,
"ignoreUploadUnusedFiles" : false
},
"usingComponents" : true
},
"mp-alipay" : {
"usingComponents" : true
},
"mp-baidu" : {
"usingComponents" : true
},
"mp-toutiao" : {
"usingComponents" : true
},
"uniStatistics" : {
"enable" : false
},
"vueVersion" : "3"
}
6. 导入 SDK
6.1 通过 npm 安装核心 SDK
HBuilderX 创建项目时默认不会创建 package.json 文件，请在项目根目录下创建 package.json 文件, 并添加以下内容：
| 依赖包 | 说明 |
|---|---|
| @rongcloud/engine | 融云 Web SDK 引擎核心包 |
| @rongcloud/imlib-next | 融云 Web IMLib 核心包 |
| @rongcloud/imkit-store | 融云 UI Kit 状态管理包 |
注意
以下仅为 package.json 所需内容的示例，版本要求可参考 demo 中的 package.json 文件。
JSON
{
"name": "your_project_name",
"version": "1.0.0",
"scripts": {
},
"dependencies": {
"@rongcloud/engine": "^5.22.0",
"@rongcloud/imlib-next": "^5.22.0",
"@rongcloud/imkit-store": "^1.0.1",
"base-64": "^1.0.0",
"mobx": "^6.13.7"
}
}
执行安装依赖
sh
npm install
6.2 初始化 Web IMLib SDK
在 App.vue 中导入 @rongcloud/imlib-next 并调用 RongIMLib.init 进行初始化， 初始化所需 appkey 从融云开发者后台获取，详细请参考前置条件。
typescript
import * as RongIMLib from '@rongcloud/imlib-next';
uni.$RongIMLib = RongIMLib;
// 应用 App Key
const APP_KEY = 'your_app_key';
// lib 初始化
uni.$RongIMLib.init({
appkey: APP_KEY, // 从融云开发者后台获取
});
6.3 初始化 kit-store
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
logLevel | LogL | 否 | 日志输出等级，默认 LogL.WARN，有效值为 LogL.DEBUG、LogL.INFO、LogL.WARN、LogL.ERROR |
hooks | IKitServiceHooks | 否 | 业务数据模块钩子，用于向 SDK 注入用户信息、群组信息等 |
注意
需要对接业务数据可查看 【业务数据管理】 文档
typescript
import { RCKitStoreInstaller } from '@rongcloud/imkit-store';
// Kit store 初始化
const store = RCKitStoreInstaller();
uni.$RongKitStore = store;
7. 获取用户 Token
用户 Token 是与用户 ID 对应的身份验证令牌，是应用程序的用户在融云的唯一身份标识。应用客户端在使用融云即时通讯功能前必须与融云建立 IM 连接，连接时必须传入 Token。
在实际业务运行过程中，应用客户端需要通过应用的服务端调用 IM Server API 申请取得 Token。详见 Server API 文档 注册用户。
在本教程中，为了快速体验和测试 SDK，您可以前往控制台的密钥管理页面，在 管理测试用户 区域输入用户 ID 1，点击 获取 Token 生成该用户的 Token。
8. 连接 IM
在应用启动时初始化并连接融云服务器：
typescript
// 连接 IM 'your_token' 临时测试可从开发者后台获取
const TOKEN = 'your_token';
uni.$RongIMLib.connect(TOKEN).then((res) => {
const { code, data } = res;
if (code !== uni.$RongIMLib.ErrorCode.SUCCESS) {
uni.showToast({
title: `登录失败 code: ${code}`, icon: 'none',
});
}
});
9. 配置样式
在 App.vue 中配置样式：
注意
- 请勿修改
RCUIKit/styles/common.scss文件，否则可能会影响 UI 库的正常使用。 - 使用
@use './RCUIKit/styles/common.scss';导入样式文件，需要使用scss编译器。
css
<style lang="scss">
/*每个页面公共css */
@use './RCUIKit/styles/common.scss';
#app {
/* #ifdef H5 */
height: 100%;
/* #endif */
/* #ifndef H5 */
height: 100vh;
/* #endif */
overflow: hidden;
}
</style>
10. 启动 Demo
- 在 HBuilderX 中打开项目
- 点击"运行" -> "运行到浏览器"或"运行到手机或模拟器"
- 等待项目编译完成并启动
11. 测试收发消息
在实际业务运行过程中，应用客户端可以通过用户 ID、群聊会话 ID、或聊天室 ID 等接收消息。
在本教程中，为了快速体验和测试 SDK，我们在需先按控制台内嵌指南嵌入到管理后台的 IM Server API 调试页面（page_code: im_server_api）中向当前登录的用户发送一条文本消息，模拟单聊会话。
-
在需先按控制台内嵌指南嵌入到管理后台的 IM Server API 调试页面（page_code: im_server_api）中操作。
-
在消息标签下，找到 消息服务 > 发送单聊消息 接口。
以下模拟了从 UserId 为 2 的用户向 UserId 为 1 的用户发送一条文本消息。
-
客户端接收到消息 后，自动在会话列表页面展示新的单聊会话。
-
点击会话，即可进入消息列表页面，发送消息。
测试步骤
- 使用两个不同的用户 Token (对应不同用户ID) 进行登录。
- 在需先按控制台内嵌指南嵌入到管理后台的 IM Server API 调试页面（page_code: im_server_api）中发送测试消息。
- 在应用中查看消息是否收到。
- 收到存储类消息生成会话列表，使用 IMKit 测试发送接收消息。