跳到主要内容
版本：5.X

集成方案（Electron）

融云即时通讯业务支持基于 Electron 框架开发桌面端应用，助力实现媲美传统桌面通讯软件的功能体验。

提示
  • 如需使用 Electron 解决方案，需先开通桌面版服务。
  • 当前 Electron 方案暂不支持超级群业务。

方案概述​

融云通过自身 PaaS 能力，解决了多进程连接共享、多进程消息同步问题，降低了开发者构建多窗口、多进程桌面端应用的复杂度。

相较于基于 Web IMLib/IMKit SDK 的 Web 应用，Electron 方案额外提供了基于本地存储的接口，支持本地消息/会话的查询、搜索、删除等功能。

Electron 版本支持​

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

Windows 支持版本​

提示

Windows 平台需使用与架构匹配的 Node 版本，执行 node -p process.arch 查看当前架构。

Electron 版本平台架构备注SDK 支持版本
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

Linux 支持版本​

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

MacOS 支持版本​

Electron 版本平台架构备注SDK 支持版本
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 相关模块：

shell
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
IMLib从版本支持情况
@rongcloud/engine5.4.0 起支持 @rongcloud/electron 与 @rongcloud/electron-renderer
@rongcloud/imlib-next5.4.0 起支持 @rongcloud/electron 与 @rongcloud/electron-renderer

安装 .node 文件​

从 5.6.0 起，@rongcloud/electron 不再内置所有平台的 .node 文件，安装完成后 SDK 会自动下载适配当前环境的 .node 文件到 node_modules/@rongcloud/electron/binding。

如自动下载失败，可手动执行：

shell
// 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
提示
  • 安装后确认 node_modules/@rongcloud/electron/binding 目录下是否存在对应 .node 文件
  • 切换 SDK 版本后需重新执行下载
  • 查看当前 CPU 架构：node -p process.arch
  • 查看系统平台：node -p process.platform
  • 可在支持列表查看对应版本可用的 .node 文件
  • .node 文件名称说明：electron-v[Electron版本]-[平台]-[CPU架构].node

主进程初始化​

  1. 在主进程中引用 @rongcloud/electron 包，并在 app 的 ready 事件回调中初始化：

    在 main.js 中：

    javascript
    // 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>',
          // Electron 开始上下文隔离，false 表示关闭，true 表示开启
          contextIsolation: false,
          nodeIntegration: true
        }
      })

      app.on('before-quit', () => {
        // 在 app 退出时清理状态
        rcService.destroy()
      })
    })

  2. 在初始化渲染进程窗口时，通过设置 webPreferences.preload 来添加预加载的 js 文件，并在 js 中引用 @rongcloud/electron-renderer。

    在 preload.js 文件中：

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

    如果开启了上下文隔离，则还需要加入以下代码（5.9.6 版本开始支持）：

    javascript
    // preload.js
    renderer.initContextBridge()

  3. 在 Web 页面中引入 @rongcloud/imlib-next。

    JavaScript
    import RongIMLib from '@rongcloud/imlib-next'

    如果开启了上下文隔离，则还需要加入以下代码（5.9.6 版本开始支持）：

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

在渲染进程中初始化 IMLib​

请登录控制台，记录 App Key，在初始化时使用。

admin-05

  1. 初始化 IMLib：

    javascript
    // 应用初始化，请务必保证此过程只被执行一次
    RongIMLib.init({ appkey: '<Your-App-Key>' });

  2. 添加事件监听器：

    javascript
    // 添加事件监听
    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 是用户在融云 IM 服务中的唯一身份标识，客户端连接 IM 服务前，需先从服务端通过 API 获取，详见 Server API 文档 注册用户。

快速测试时，可使用控制台「北极星」开发者工具箱获取 Token

接口响应示例：

HTTP
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 建立连接：

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

最后于 更新