快速集成

本教程将帮助您快速集成融云即时通讯 UI 组件库（uni-app IMKit）。通过本教程，您可以了解完整的集成流程并体验 IMKit 提供的 UI 界面。

平台支持

支持平台	支持情况
Android	✅
iOS	✅
H5	✅
小程序	✅

配置项要求

在开始集成之前，请确保您的开发环境满足以下要求：

配置项	要求	版本说明
集成开发环境	HBuilderX	建议升级到最新版本，最低版本要求 4.57 及以上
开发语言	TypeScript	5.1.0+
Node.js 版本	v18 及以上	18.1.0+
框架	Vue3	-

1. 前置条件

注册开发者账号。注册成功后，控制台会默认自动创建您的首个应用，默认生成开发环境下的 App Key，使用国内数据中心。
获取开发环境的应用 App Key。如不使用默认应用，请参考如何创建应用，并获取对应环境 App Key 和 App Secret。

提示

每个应用具有两个不同的 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"
			}
		}
	]
}

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	5.20.0-c-unikit.1	融云 Web SDK 引擎核心包
@rongcloud/imlib-next	5.20.0-c-unikit.1	融云 Web IMLib 核心包
@rongcloud/imkit-store	1.0.0	融云 UI Kit 状态管理包

JSON
{
  "name": "your_project_name",
  "version": "1.0.0",
  "scripts": {
  },
  "dependencies": {
    "@rongcloud/engine": "5.20.0-c-unikit.1",
    "@rongcloud/imlib-next": "5.20.0-c-unikit.1",
    "@rongcloud/imkit-store": "^1.0.0",
    "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，我们将使用控制台「北极星」开发者工具箱，从 API 调试页面调用获取 Token 接口，获取到 userId 为 1 的用户的 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 调试]页面向当前登录的用户发送一条文本消息，模拟单聊会话。

访问控制台「北极星」开发者工具箱的 [IM Server API 调试]页面。
在消息标签下，找到 消息服务 > 发送单聊消息 接口。

以下模拟了从 UserId 为 2 的用户向 UserId 为 1 的用户发送一条文本消息。
客户端接收到消息后，自动在会话列表页面展示新的单聊会话。
点击会话，即可进入消息列表页面，发送消息。

测试步骤

使用两个不同的用户 Token (对应不同用户ID) 进行登录。
在控制台「北极星」开发者工具箱中发送测试消息。
在应用中查看消息是否收到。
收到存储类消息生成会话列表，使用 IMKit 测试发送接收消息。

12. 实现消息推送

当您的应用编译为 Android 或 iOS 应用时，如需实现消息推送功能，您可参考离线推送文档，集成融云推送插件。

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

Global IM UIKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

验证码短信

平台支持​

配置项要求​

1. 前置条件​

2. 创建项目​

3. 下载资源​

4. 配置路由​

5. 项目配置​

6. 导入 SDK​

6.1 通过 npm 安装核心 SDK​

6.2 初始化 Web IMLib SDK​

6.3 初始化 kit-store​

7. 获取用户 Token​

8. 连接 IM​

9. 配置样式​

10. 启动 Demo​

11. 测试收发消息​

12. 实现消息推送​