跳到主要内容
版本：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 包，并在 app 的 ready 事件通知后进行初始化。

    在 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 平台中使用有些差异，具体信息可参考各个接口详细说明。

最后于 更新