跳到主要内容

版本:5.X

集成方案(Electron)

即时通讯业务支持使用 Electron 框架开发桌面端应用,实现与传统桌面通讯软件匹配的能力。

注意

使用 Electron 解决方案要求应用已开通桌面版服务。

Electron 解决方案概述

融云 Web IMLib SDK 从 5.4.0 版本开始,支持配合使用 @rongcloud/electron@rongcloud/electron-renderer 模块,开发基于 Electron 的桌面版即时通讯应用。融云通过自身 PaaS 能力,解决了多进程连接共享、多进程消息同步问题,降低了开发者构建多窗口、多进程桌面端应用的复杂度。

相较于基于 Web IMLib/IMKit SDK 的 Web 应用,Electron 框架解决方案主要提供了基于本地存储的一系列接口,可用于实现本地消息/会话的获取、搜索、删除等特性。

注意

Electron 解决方案暂不支持超级群业务。

Electron 版本支持

Electron 解决方案支持 Windows、Linux、Mac 平台。

Windows 支持版本

Electron 版本平台支持架构备注支持版本
11.1.XWindowsx86win32-ia32
14.0.XWindowsx86win32-ia32
16.0.XWindowsx86win32-ia32
20.0.XWindowsx86win32-ia325.6.0
20.0.XWindowsx64win32-x645.8.2
不依赖 Electron 版本Windowsx86win32-ia325.8.3
不依赖 Electron 版本Windowsx64win32-x645.8.3

注意

在 windows 平台需使用相应架构的 node。检查方法:

  1. 在 CMD 等命令行界面运行 node -p process.arch
  2. 查看当前 node 版本,需与列表中相匹配。

Linux 支持版本

Electron 版本平台支持架构备注支持版本
11.1.XLinuxx64linux-x64
11.1.XLinuxarm64linux-arm64
不依赖 Electron 版本Linuxx64linux-x645.8.3
不依赖 Electron 版本Linuxarm64linux-arm645.8.3

MacOS 支持版本

Electron 版本平台支持架构备注支持版本
11.1.XMacOSx64darwin-x64
14.0.XMacOSx64darwin-x64
16.0.XMacOSx64darwin-x64
20.0.XMacOSx64darwin-x645.6.0
20.0.XMacOSarm64darwin-arm645.6.0
不依赖 Electron 版本MacOSx64darwin-x645.8.3
不依赖 Electron 版本MacOSarm64darwin-arm645.8.3

安装 SDK

您需要安装 Web IMLib 最新版,以及 Electron 解决方案(@rongcloud/electron@rongcloud/electron-renderer。)

npm install @rongcloud/engine@latest -S
npm install @rongcloud/imlib-next@latest -S
npm install @rongcloud/electron@latest -S
npm install @rongcloud/electron-renderer@latest -S

安装 .node 文件

自 5.6.0 版本起,在 @rongcloud/electron SDK 中将默认不携带全部平台的 .node 文件,安装完该 SDK 后会自动下载匹配当前环境的 .node 文件到 node_modules/@rongcloud/electron/binding 目录下,但可能因未匹配到当前环境的 .node 文件而导致下载失败,您可使用 npx rc-install 命令主动下载:

// 5.8.2 版本之前
// npx rc-install --electron-version <electron-version>[ --platform <platform>][ --arch <arch>]
npx rc-install --electron-version=16.0.1 --platform=darwin --arch=x64

// 5.8.3 版本之后
// npx rc-install [ --platform <platform>][ --arch <arch>]
npx rc-install --platform=darwin --arch=x64

您可在 electron node 支持列表 页面查看各版本支持的全部 .node 文件, .node 文件名称说明:electron-v[Electron版本]-[平台]-[CPU架构].node

注意

  1. 在下载完 SDK 后需检查下 node_modules/@rongcloud/electron/binding 目录下是否有当前环境下的 .node 文件。
  2. 在切换 SDK 版本后需重新下载 .node 文件。
  3. 查看当前环境的 CPU 架构信息:在 CMD 等命令行界面运行 node -p process.arch
  4. 查看当前环境的系统平台信息:在 CMD 等命令行界面运行 node -p process.platform

主进程初始化

  1. 在主进程中引用 @rongcloud/electron 包,并在 appready 事件通知后进行初始化。

    main.js 中:

    // main.js
    const { app, BrowserWindow } = require('electron')
    const RCInit = require('@rongcloud/electron')

    let rcService

    app.on('ready', () => {
    // 在 app 的 ready 事件通知后进行初始化
    rcService = RCInit({
    /**
    * 【必填】Appkey , 自 5.6.0 版本起,必须填该参数
    * [option]
    */
    appkey: '<appkey>',
    /**
    * 【选填】消息数据库的存储位置,不推荐修改
    * [option]
    */
    dbpath: app.getPath('userData'),
    /**
    * 【选填】日志等级
    * [option] 4 - DEBUG, 3 - INFO, 2(default) - WARN, 1 - ERROR
    */
    logOutputLevel: 2,
    /**
    * 【选填】是否同步空的置顶会话,默认值为 `false`
    * [option]
    */
    enableSyncEmptyTopConversation: false
    })

    // 初始化 UI 窗口
    const browserWin = new BrowserWindow({
    webPreferences: {
    // 指定预加载的 preload.js 文件,在其中引用 @rongcloud/electron-renderer
    preload: '<path/to/preload.js>',
    // 需要将 contextIsolation 设置为 false
    contextIsolation: false,
    nodeIntegration: true
    }
    })

    app.on('before-quit', () => {
    // 在 app 退出时清理状态
    rcService.destroy()
    })
    })
  2. 在初始化渲染进程窗口时,通过设置 webPreferences.preload 来添加预加载的 js 文件,并在 js 中引用 @rongcloud/electron-renderer

    preload.js 文件中:

    // preload.js
    const renderer = require('@rongcloud/electron-renderer');

    如果开启了上下文隔离,则还需要加入以下代码(5.9.6 版本开始支持):

    // preload.js
    renderer.initContextBridge()
  3. 在 Web 页面中引入 @rongcloud/imlib-next

    import RongIMLib from '@rongcloud/imlib-next'

    如果开启了上下文隔离,则还需要加入以下代码(从 5.9.6 版本开始支持):

    import { initRenderer } from '@rongcloud/electron-renderer/renderer';
    initRenderer();

在渲染进程中初始化 IMLib

初始化 IMLib SDK 时需要传入 App Key。

请登录控制台,记录下图所示的应用 App Key,在初始化时使用。

admin-05

注意

应用的 AppKey 与 Secret 是获取连接融云服务器身份凭证的必要条件,请注意不要泄露。

  1. 初始化 IMLib。

    // 应用初始化,请务必保证此过程只被执行一次
    RongIMLib.init({ appkey: '<Your-App-Key>' });
  2. 初始化完成后,添加事件监听器,及时获取相关事件通知。

    // 添加事件监听
    const Events = RongIMLib.Events

    RongIMLib.addEventListener(Events.CONNECTING, () => {
    console.log('正在连接服务器')
    })

    RongIMLib.addEventListener(Events.CONNECTED, () => {
    console.log('已经连接到服务器')
    })

    RongIMLib.addEventListener(Events.MESSAGES, (evt) => {
    console.log(evt.messages)
    })

获取用户 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 连接

使用以上步骤中获取的 Token,模拟 userId 为 1 的用户连接到融云服务器。

RongIMLib.connect('<Your-Token>').then(res => {
if (res.code === RongIMLib.ErrorCode.SUCCESS) {
console.log('连接成功, 连接用户 id 为: ', res.data.userId);
} else {
console.warn('连接失败, code:', res.code)
}
})

后续步骤

以上步骤即 IMLib SDK 在 Electron 平台的快速集成流程。

文档目录中标注了(Electron)的页面均为 Electron 解决方案专属的功能接口文档。

因在 Electron 平台提供了本地存储的能力,所以部分接口可能与 Web 平台中使用有些差异,具体信息可参考各个接口详细说明。