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

集成方案（Electron）

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

使用前提

方案概述​

Electron 解决方案内置处理了多进程连接共享、多进程消息同步等问题，降低了开发者构建多窗口、多进程桌面端应用的复杂度。相较于 Web IMLib/IMKit SDK，Electron 方案具备完整的客户端数据持久化存储能力，并提供了基于本地数据库的增删改查功能，从而增强桌面客户端应用的使用体验。

Electron 版本支持​

SDK 5.8.3 之前的版本中，底层依赖基于 NAN（Native Abstractions for Node.js）封装的 C++ 原生库，因此 SDK 仅支持有限的几个 Electron 版本。您可以通过下面的链接了解各版本 SDK 对不同 Electron 版本和操作系统、CPU 架构的支持情况。

点击查看 5.8.3 之前 SDK 版本支持清单：[支持清单]

SDK 从 5.8.3 版本开始，对底层 C++ 原生库使用 N-API 进行了重新封装，不再限制业务层选用的 Electron 版本，仅关注操作系统和设备的 CPU 架构。

安装 SDK​

使用 Electron 解决方案时，需要同时安装以下依赖包：

重要提示

这些包之间是强耦合状态，融云研发团队仅承诺对外 API 接口的向前兼容性，内部包之间的兼容性不在考虑范围内。因此请务必始终保持它们的版本完全一致，以避免出现兼容性问题。

shell
# 基础引擎包，Electron 应用渲染进程、主进程内均会引用
npm install @rongcloud/engine@latest -S
# Web SDK API，仅需在渲染进程工程内引用即可，主进程内无法使用
npm install @rongcloud/imlib-next@latest -S
# Electron 主进程依赖包，仅需在 Electron 主进程内引用，渲染进程内无法使用
npm install @rongcloud/electron@latest -S
# 主进程、渲染进程内均需引用
npm install @rongcloud/electron-renderer@latest -S

加载 .node 原生库​

本段内容仅针对集成使用 SDK 5.6.0 - 5.8.6 版本的开发者，其他版本用户无需关注。

SDK 5.6.0 - 5.8.6 版本的 @rongcloud/electron 包中并未内置包含所有已支持的 Electron 版本、操作系统、CPU 架构的 .node 文件。使用该版本区间的 Electron 解决方案时，您需要在集成过程中按需加载所需的 .node 库文件。

您可以通过查看 node_modules/@rongcloud/electron/binding 目录，了解目前已加载的 .node 库文件，并通过 [支持清单] 按需选择下载更多其他平台或 Electron 版本库。

node 原生模块的命名规则为如下：

  1. 5.8.3 之前的版本：electron-v<Electron 版本>-<操作系统标识>-<CPU 架构>.node。
  2. 5.8.3 - 5.8.6：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，用于初始化 SDK。

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 平台的使用方式存在差异，具体信息请参考各个接口的详细说明。

最后于 更新