Electron SDK Guide

Electron main/renderer split, screen capture and packaging notes.

Interface sections generated from the public SDK definitions

Version v1.1.0 · Updated 2026-10-26 · revision 1

The Electron platform is the Web SDK public surface plus a desktop capture bridge. The renderer still uses the AgoraRTC-shaped API from @nimeet/rtc-web; the desktop side additionally provides "enumerate window/screen sources" and "source-pinned screen sharing", because the browser's getDisplayMedia cannot target one specific window.

Prerequisites#

• Node.js ≥ 22 and pnpm 10; Electron ≥ 28 (all three of main process, preload and renderer need changes).
• contextIsolation: true (the default). This SDK's desktop bridge is injected through the preload script and does not rely on nodeIntegration.
• You already have an appId and a backend that can issue tokens (see Enable services and get credentials).

Install#

pnpm add @nimeet/sdk-electron @nimeet/rtc-web

The three entry points are used in three places: @nimeet/sdk-electron/main (main process), @nimeet/sdk-electron/preload (preload) and @nimeet/sdk-electron (renderer / shared utilities).

Get a token#

Exactly as on Web: tokens are issued by your backend calling POST /v1/tokens, and the renderer only receives { appId, rtcToken, rtcUid }. The main process must not hold customerSecret either — it would show up in crash dumps and in user-readable files.

Join a channel#

The main process registers the desktop bridge:

// main.js (main process)
const { app, BrowserWindow, ipcMain, desktopCapturer } = require('electron');
const { registerDesktopBridge } = require('@nimeet/sdk-electron/main');

app.whenReady().then(() => {
  registerDesktopBridge({ ipcMain, desktopCapturer });
});

The preload script exposes the minimal surface:

// preload.js (preload)
const { contextBridge, ipcRenderer } = require('electron');
const { exposeDesktopBridge } = require('@nimeet/sdk-electron/preload');

exposeDesktopBridge(contextBridge, ipcRenderer);

In the renderer, join with the Web-shaped client (the same methods as the Web SDK):

import AgoraRTC from '@nimeet/rtc-web';

const client = AgoraRTC.createClient({ mode: 'rtc', codec: 'vp8' });
client.on('user-published', async (user, mediaType) => {
  await client.subscribe(user, mediaType);
  if (mediaType === 'video') user.videoTrack?.play('remote-player');
});
const uid = await client.join(appId, 'weekly-sync', rtcToken, rtcUid);

Publish and subscribe#

Camera and microphone work as on Web; screen sharing uses a "source" instead of the default picker:

import { pickPrimarySource, groupSources } from '@nimeet/sdk-electron';

// window.nimeetDesktop is injected by the preload script
const sources = await window.nimeetDesktop.getSources({ types: ['screen', 'window'] });
const groups = groupSources(sources);          // group by "screen / window" for the dropdown
const primary = pickPrimarySource(sources);    // the primary screen, used as the default

const screenTrack = await AgoraRTC.createScreenVideoTrack(
  { electronScreenSourceId: primary.id },
  'disable',
);
await client.publish(screenTrack);

electronScreenSourceId is the "pinned source" (the field name comes from ScreenVideoTrackInitConfig): it does not change while the user switches windows — the most important difference between the desktop platform and the browser's getDisplayMedia.

Events#

The same event set as Web (user-joined / user-published / connection-state-change / token-privilege-will-expire / network-quality…), plus two extra channel events provided by the desktop bridge (prefix nimeet:desktop:):

Error handling#

There are three common error sources, and they are best handled separately:

1. RTC errors: the same AgoraRTCError as Web (a code string);
2. IPC errors: the main process did not register the bridge → window.nimeetDesktop is undefined in the renderer; the preload was not injected → same as above;
3. System permissions: when macOS "Screen Recording" is not granted, the source list is empty rather than raising an error.

const sources = await window.nimeetDesktop?.getSources({ types: ['screen'] }) ?? [];
if (sources.length === 0) {
  // macOS: guide the user to System Settings → Privacy & Security → Screen Recording, tick this app and restart
}

Troubleshooting#

Next steps#

• Full interfaces and overloads: API reference for this platform
• Error codes and troubleshooting: Error code table, FAQ
• Issue tokens on your server: Token authentication

Platform information

The public interfaces are aligned with the Agora electron API; installation and runtime requirements are listed under Prerequisites above.

Availability

This platform's SDK: Generally available. The examples use the public API; runtime capability follows the published SDK package.

join-channel flow

The method names, parameter types and return values match the API reference for the same platform. Where a method has several overloads, the most common one is shown here; see the API reference for all overloads.

muteRemoteAudioStream(uid: number, mute: boolean): number
initialize(): number
renewToken(token: string): number
enableVideo(): number
joinChannel(token: string, channelId: string, uid: number, options: ChannelMediaOptions): number
leaveChannel(options?: LeaveChannelOptions): number
setChannelProfile(profile: ChannelProfileType): number
setClientRole(role: ClientRoleType, options?: ClientRoleOptions): number
setupLocalVideo(canvas: VideoCanvas): number

Events and callbacks

Callbacks are registered on IRtcEngineEventHandler; naming differs by platform, and the full list is in the API reference for the same platform.

Error codes

the platform REST layer uses REST error codes；the SDK layer maps connection/authentication failures to Agora error numbers, for the mapping table see SDK error identifiers per platform。