跳到主要内容
版本：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 - 至今：electron-<操作系统标识>-<CPU 架构>.node

主进程集成​

SDK 5.9.6 版本开始支持开启 Electron 上下文隔离，详细说明可参考 Electron 官方文档

在主进程中引用 @rongcloud/electron 包，并在 app 的 ready 事件中完成 SDK 的初始化。

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
    }
  })
})

注意，应用退出时，需要执行相应的销毁动作，否则退出时可能会偶发应用异常退出和崩溃。

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

preload.js​

在初始化 BrowserWindow 对象时，SDK 需要通过 webPreferences.preload 预载入部分代码到渲染进程内，以搭建主进程与渲染进程之间的 IPC 跨进程通信能力。

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

// 对于开启了 Electron 上下文隔离且 SDK 版本低于 5.36.0 的用户，需要额外调用 initContextBridge 方法完成代码注入。
// 5.36.0 及以上版本用户可忽略
renderer.initContextBridge()

渲染进程集成​

对于使用 5.36.0 及以上版本用户，可参考标准 Web IM 集成文档，正常集成业务即可。SDK 内部会根据运行时的环境分析，自动将 Web 页面实现切换到 Elecron 方案，无需额外修改。

对于使用 SDK 版本低于 5.36.0 的用户，当开启 Electron 上下文隔离时，需要在 Web 页面内增加如下调用代码。

JavaScript
// 5.36.0 以上或未开启 Electron 上下文隔离的情况下，无需引入
import { initRenderer } from '@rongcloud/electron-renderer/renderer';
initRenderer();

其他​

只有在集成了 Electron 解决方案的情况下，IM SDK 中的 electronExtension 中的对外方法才会生效。

JavaScript
import { electronExtension } from '@rongcloud/imlib-next';

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

由于 Electron 平台提供了本地存储能力，部分接口可能与 Web 平台的使用方式存在差异，具体信息请参考各个接口的详细说明。

最后于 更新