集成方案（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.X	Windows	x86	win32-ia32	-
14.0.X	Windows	x86	win32-ia32	-
16.0.X	Windows	x86	win32-ia32	-
20.0.X	Windows	x86	win32-ia32	5.6.0
20.0.X	Windows	x64	win32-x64	5.8.2
不依赖 Electron 版本	Windows	x86	win32-ia32	5.8.3
不依赖 Electron 版本	Windows	x64	win32-x64	5.8.3

Linux 支持版本

Electron 版本	平台	架构	备注	SDK 支持版本
11.1.X	Linux	x64	linux-x64	-
11.1.X	Linux	arm64	linux-arm64	-
不依赖 Electron 版本	Linux	x64	linux-x64	5.8.3
不依赖 Electron 版本	Linux	arm64	linux-arm64	5.8.3

MacOS 支持版本

Electron 版本	平台	架构	备注	SDK 支持版本
11.1.X	MacOS	x64	darwin-x64	-
14.0.X	MacOS	x64	darwin-x64	-
16.0.X	MacOS	x64	darwin-x64	-
20.0.X	MacOS	x64	darwin-x64	5.6.0
20.0.X	MacOS	arm64	darwin-arm64	5.6.0
不依赖 Electron 版本	MacOS	x64	darwin-x64	5.8.3
不依赖 Electron 版本	MacOS	arm64	darwin-arm64	5.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/engine	5.4.0 起	支持 @rongcloud/electron 与 @rongcloud/electron-renderer
@rongcloud/imlib-next	5.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，在初始化时使用。

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