Electron integration

Electron · supported

Supported baseline: Electron 28+, Node.js 20+, Linux x64 or Windows x64. macOS is not distributed by SDK 1.0.0.

Install matching packages

Configure the private @p2psdk npm scope supplied during onboarding, then install both packages at the same version:

npm install --save-exact \
  @p2psdk/[email protected] \
  @p2psdk/[email protected]

electron remains your application's dependency. Do not expose either P2PSDK package to a renderer.

Create from the main process

import { app, BrowserWindow } from 'electron';
import { createP2PSdkWithConsent } from '@p2psdk/electron';

let mainWindow;
let sdk;

await app.whenReady();

mainWindow = new BrowserWindow({
  webPreferences: {
    nodeIntegration: false,
    contextIsolation: true,
    sandbox: true,
    preload: PRELOAD_PATH,
  },
});

const result = await createP2PSdkWithConsent({
  apiKey: process.env.P2P_API_KEY,
  consentUrl: process.env.P2P_SDK_CONSENT_URL,
  consentVersion: process.env.P2P_SDK_CONSENT_VERSION,
  consentPublicKeyPem: process.env.P2P_SDK_CONSENT_PUBLIC_KEY_PEM,
  parentWindow: mainWindow,
  debug: !app.isPackaged,
  backgroundMode: true,
  onConnect: () => mainWindow?.webContents.send('p2psdk:connected'),
  onDisconnect: (reason) =>
    mainWindow?.webContents.send('p2psdk:disconnected', reason),
});

if (result.isAccepted && result.sdk) {
  sdk = result.sdk;
  sdk.connect();
} else {
  console.warn('P2PSDK not created:', result.status, result.message);
}

Use the exact consent configuration supplied during onboarding. The public verification key may ship with the app; private signing material must not.

The helper uses nodeIntegration: false, contextIsolation: true, and sandbox: true, blocks off-origin navigation, rejects popups, verifies the accepted decision, and stores state under Electron userData by default.

Do not implement consent in the renderer or pass a manual receipt from renderer state. Send only lifecycle status through a narrow, validated preload API.

Result handling

Handle accepted, declined, revoked, cancelled, and error explicitly. Never call connect() without an accepted result and SDK instance.

Background mode

With backgroundMode: true, a connected instance prevents Electron's default all-windows-closed quit path. The main process can continue while product windows are closed. This does not install autostart, survive force quit, create an OS service, or prevent sleep.

disconnect(), free(), and final close release the background session.

Revoke

import { revokeP2PSdkConsent } from '@p2psdk/electron';

const result = await revokeP2PSdkConsent(
  {
    apiKey: process.env.P2P_API_KEY,
    consentVersion: process.env.P2P_SDK_CONSENT_VERSION,
  },
  sdk,
);

if (result.isRevoked) {
  sdk = undefined;
}

Set P2P_SDK_CONSENT_REVOKE_URL before calling revoke. Failure leaves the decision and instance available for retry.

Final shutdown

app.on('before-quit', () => {
  sdk?.disconnect();
  sdk?.free();
  sdk = undefined;
});

Packaging checklist

Include the matching prebuilds/linux-x64/libp2p_sdk.so or prebuilds/win32-x64/p2p_sdk.dll.
Confirm the renderer cannot import P2PSDK or receive API keys/receipts.
Test accept, decline, cancel, invalid decision, restart, all-windows-closed behavior, revoke, and final quit.
Search packaged logs and source maps for API keys, receipts, tokens, and registry credentials.