Integration Guide (Electron)

The Instant Messaging (IM) service supports the development of desktop applications using the Electron framework, enabling capabilities that match traditional desktop communication software.

Note

Using the Electron solution requires that the application has enabled the desktop service.

Overview of the Electron Solution

Starting from version 5.4.0, the RC Web IMLib SDK supports the use of the @rongcloud/electron and @rongcloud/electron-renderer modules to develop desktop IM applications based on Electron. Leveraging its PaaS capabilities, RC addresses issues such as multi-process connection sharing and multi-process message synchronization, reducing the complexity for developers in building multi-window, multi-process desktop applications.

Compared to web applications based on the Web IMLib and Global IM UIKit SDK, the Electron framework solution primarily provides a series of interfaces based on local storage, which can be used to implement features such as fetching, searching, and deleting local messages/conversations.

Note

The Electron solution does not currently support ultra group functionality.

Supported Electron Versions

The Electron solution supports Windows, Linux, and Mac platforms.

Windows Supported Versions

Electron Version	Platform	Supported Architecture	Notes	Supported Version
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 version independent	Windows	x86	win32-ia32	5.8.3
Electron version independent	Windows	x64	win32-x64	5.8.3

Note

On the Windows platform, you need to use the corresponding architecture of Node. To check:

1. Run node -p process.arch in a command-line interface like CMD.
2. Ensure the current Node version matches the list above.

Linux Supported Versions

Electron Version	Platform	Supported Architecture	Notes	Supported Version
11.1.X	Linux	x64	linux-x64
11.1.X	Linux	arm64	linux-arm64
Electron version independent	Linux	x64	linux-x64	5.8.3
Electron version independent	Linux	arm64	linux-arm64	5.8.3

MacOS Supported Versions

Electron Version	Platform	Supported Architecture	Notes	Supported Version
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 version independent	MacOS	x64	darwin-x64	5.8.3
Electron version independent	MacOS	arm64	darwin-arm64	5.8.3

Install the SDK

You need to install the latest version of Web IMLib and the Electron solution (@rongcloud/electron and @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

Install .node Files

Starting from version 5.6.0, the @rongcloud/electron SDK will no longer include .node files for all platforms by default. After installing the SDK, it will automatically download the .node file that matches the current environment to the node_modules/@rongcloud/electron/binding directory. However, if the .node file for the current environment is not found, the download may fail. You can use the npx rc-install command to manually download the file:

// Before version 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

// After version 5.8.3
// npx rc-install [ --platform <platform>][ --arch <arch>]
npx rc-install --platform=darwin --arch=x64

You can view all supported .node files for each version on the electron node support list page. The .node file name format is: electron-v[Electron version]-[platform]-[CPU architecture].node.

Note

1. After downloading the SDK, check if the .node file for the current environment exists in the node_modules/@rongcloud/electron/binding directory.
2. After switching SDK versions, re-download the .node file.
3. To check the CPU architecture of the current environment: Run node -p process.arch in a command-line interface like CMD.
4. To check the platform of the current environment: Run node -p process.platform in a command-line interface like CMD.

Main Process Initialization

1. Reference the @rongcloud/electron package in the main process and initialize it after the ready event of the app is triggered.

   In main.js:

   // main.js
   const { app, BrowserWindow } = require('electron')
   const RCInit = require('@rongcloud/electron')
   
   let rcService
   
   app.on('ready', () => {
     // Initialize after the app's ready event is triggered
     rcService = RCInit({
       /**
        * 【Required】Appkey, required starting from version 5.6.0
        * [option]
        */
       appkey: '<appkey>',
       /**
        * 【Optional】The storage location of the message database. It is not recommended to modify this.
        * [option]
        */
       dbpath: app.getPath('userData'),
       /**
        * 【Optional】Log level
        * [option] 4 - DEBUG, 3 - INFO, 2(default) - WARN, 1 - ERROR
        */
       logOutputLevel: 2,
       /**
        * 【Optional】Whether to sync empty pinned conversations. Default is `false`
        * [option]
        */
       enableSyncEmptyTopConversation: false
     })
   
     // Initialize the UI window
     const browserWin = new BrowserWindow({
       webPreferences: {
         // Specify the preload.js file to preload, which references @rongcloud/electron-renderer
         preload: '<path/to/preload.js>',
         // Set contextIsolation to false
         contextIsolation: false,
         nodeIntegration: true
       }
     })
   
     app.on('before-quit', () => {
       // Clean up state when the app exits
       rcService.destroy()
     })
   })

2. When initializing the renderer process window, add the preloaded js file by setting webPreferences.preload, and reference @rongcloud/electron-renderer in the js file.

   In the preload.js file:

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

   If context isolation is enabled, add the following code (supported starting from version 5.9.6):

   // preload.js
   renderer.initContextBridge()

3. Import @rongcloud/imlib-next in the web page.

   import RongIMLib from '@rongcloud/imlib-next'

   If context isolation is enabled, add the following code (supported starting from version 5.9.6):

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

Initialize IMLib in the Renderer Process

When initializing the IMLib SDK, you need to provide the App Key.

Log in to the Console and note the App Key of the application as shown in the image below, which will be used during initialization.

Note

The App Key and Secret of the application are essential for obtaining credentials to connect to the RC server. Please ensure they are not leaked.

1. Initialize IMLib.

   // Application initialization. Ensure this process is executed only once.
   RongIMLib.init({ appkey: '<Your-App-Key>' });

2. After initialization, add event listeners to promptly receive relevant event notifications.

   // Add event listeners
   const Events = RongIMLib.Events
   
   RongIMLib.addEventListener(Events.CONNECTING, () => {
       console.log('Connecting to the server')
   })
   
   RongIMLib.addEventListener(Events.CONNECTED, () => {
       console.log('Connected to the server')
   })
   
   RongIMLib.addEventListener(Events.MESSAGES, (evt) => {
       console.log(evt.messages)
   })

Obtain User Token

The User Token is an authentication token corresponding to the User ID and serves as the unique identifier for the application's user in RC. The application client must establish an IM connection with RC before using the IM features, and the Token must be passed during the connection.

In actual business operations, the application client needs to call the IM Server API through the application server to obtain the Token. For details, refer to the Server API documentation User Registration.

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

Establish IM Connection

Use the Token obtained in the previous step to simulate a connection to the RC server for the user with userId 1.

RongIMLib.connect('<Your-Token>').then(res => {
    if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    console.log('Connection successful, connected user id: ', res.data.userId);
    } else {
    console.warn('Connection failed, code:', res.code)
    }
})

Next Steps

The above steps outline the quick integration process of the IMLib SDK on the Electron platform.

Pages in the documentation marked with (Electron) are specific to the Electron solution's functional interfaces.

Since the Electron platform provides local storage capabilities, some interfaces may differ in usage compared to the Web platform. Refer to the detailed descriptions of each interface for specific information.