快速上手
Web IMKit 基于 IMLib SDK 开发,在 IMLib SDK 基础上提供会话和消息相关的 UI 界面,可用于快速实现 Web 聊天界面的搭建。Web IMKit 提供了易于使用的构建组件和 UI 交互。
本教程介绍了快速集成 Web IMKit 的基本流程和 Web IMKit 提供的 UI 界面。
开源代码
Web IMKit SDK 从 5.48.0 版本开始开源。您可访问 Web IMKit 开源代码仓库(GitHub) 获取 SDK 源码,用于调试和定制开发。源码的使用与构建方式请参见仓库中的 README。
浏览器兼容说明
| Chrome | Safari | Edge | 微信浏览器 |
|---|---|---|---|
| 68 + | 13 + | 100 + | × |
前置条件
- 注册开发者账号。注册成功后,控制台会默认自动创建您的首个应用,默认生成开发环境下的 App Key,使用国内数据中心
- 获取开发环境的应用 App Key。如不使用默认应用,您也可以自己创建应用,并获取对应环境 App Key 和 App Secret。
- 开通单群聊消息云端存储增值服务。由于 Web 端不具备持久化的数据存储能力,无法在本地持久化存储历史消息记录与会话列表,因此需要从融云服务端获取数据。从远端获取单群聊历史消息和会话列表前,请在控制台 IM 服务的服务购买页面,为当前使用的 App Key 选择单群聊消息云端存储增值服务。
每个应用具有两个不同的 App Key,分别对应开发环境与生产环境,两个环境之间数据隔离。在您的应用正式上线前,可切换到使用生产环境的 App Key,以便上线前进行测试和最终发布。
安装依赖
安装 Web IMKit 需要同时集成即时通讯能力库 IMLib SDK。
NPM
推荐您通过包管理器安装 Web IMKit SDK,以获取更好的 IDE 语法提示支持及开发体验。
# 安装 IMLib
npm install @rongcloud/engine @rongcloud/imlib-next --save
# 安装 IMKit
npm install @rongcloud/im-kit --save
| @rongcloud/engine | |
| @rongcloud/imlib-next | |
| @rongcloud/im-kit |
CDN 文件
如果您不想通过包管理器安装 Web IMKit SDK,也可以通过 CDN 的方式引入,但是这种方式不支持 IDE 语法提示。
<!-- 引入 IMLib -->
<script src="https://cdn.ronghub.com/RongIMLib-5.36.7.prod.js"></script>
<!-- 引入 Web IMKit -->
<script src="https://cdn.ronghub.com/RongIMKit-5.36.0.prod.js"></script>
Vue 工程特殊配置
由于 Web IMKit 中使用 Web Components 定义自定义 UI 组件,而 Vue 会将任何非原生的 HTML 标签优先当作 Vue 组件处理,因此,当您使用 Vite、vue-cli 等构建工具时,需要对 Vue 项目进行配置,以便于编译识别。
SDK 中所有内部标准组件均以 rc- 开头。
vite
// vite.config.js
import vue from '@vitejs/plugin-vue'
export default {
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: tag => tag.startsWith('rc-'),
}
}
})
]
}
vue-cli
// vue.config.js
module.exports = {
chainWebpack: config => {
config.module
.rule('vue')
.use('vue-loader')
.tap(options => ({
...options,
compilerOptions: {
isCustomElement: tag => tag.startsWith('rc-')
}
}))
}
}
Webpack
// webpack.config.js
module: {
rules: [
{
test: /\.vue$/,
loader: "vue-loader",
options: {
compilerOptions: {
isCustomElement: tag => tag.startsWith("rc-"),
},
},
},
]
}
初始化
Web IMKit 依赖于 IMLib SDK 的即时通讯能力,因此您需要依次完成 IMLib SDK 和 Web IMKit 的初始化。
初始化 IMLib SDK
App Key 是您融云应用的唯一标识,请传入您应用的生产或开发环境的 App Key。
import * as RongIMLib from '@rongcloud/imlib-next';
// 您也可以通过如下方式进行 IMLib 引用,为便于后续理解文档示例,此处使用 import * as RongIMLib 方式引用
// import { init } from '@rongcloud/imlib-next';
// 初始化 IMLib
RongIMLib.init({ appkey: '<YOUR-APP-KEY>' });
IMLib SDK 的初始化配置(IInitOption)中封装了区域码(AreaCode)等配置。IMLib SDK 将通过区域码获取有效的导航服务地址、文件服务地址、数据统计服务地址、和日志服务地址等配置。
- 如果 App Key 属于中国(北京)数据中心,您无需传入任何配置,SDK 默认连接北京数据中心
- 如果 App Key 不属于中国(北京)数据中心,则您必须根据应用所属数据中心,传入有效的区域码(
AreaCode)。区域码取值示例:AreaCode.SG(新加坡)、AreaCode.NA(北美)