notifications & device access

23 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Session instance events: will-download

The 'will-download' event is emitted when Electron is about to download an item in webContents. Event returns: event (Event), item (DownloadItem), webContents (WebContents). Calling event.preventDefault() will cancel the download and item will not be available from the next tick of the process.

Session instance events: extension-loaded, extension-unloaded, extension-ready

extension-loaded event is emitted after an extension is loaded, including when loaded from Session.loadExtension or reloaded from a crash or chrome.runtime.reload() call. extension-unloaded event is emitted after an extension is unloaded when Session.removeExtension is called. extension-ready event is emitted after an extension is loaded and all necessary browser state is initialized to support the extension's background page. All three events return: event (Event), extension (Extension).

Session instance events: file-system-access-restricted

The 'file-system-access-restricted' event is emitted when the File System API attempts to access a restricted path. Event returns: event (Event), details (Object with origin, isDirectory boolean, path), callback (Function). The callback accepts an action parameter: 'allow' to permit access despite restricted status, 'deny' to block access and trigger an AbortError, or 'tryAgain' to open a new file picker.

Session instance events: spellcheck-dictionary events

Four spellcheck-dictionary events exist: 'spellcheck-dictionary-initialized' emitted when a hunspell dictionary file has been successfully initialized after download; 'spellcheck-dictionary-download-begin' emitted when download starts; 'spellcheck-dictionary-download-success' emitted when successfully downloaded; 'spellcheck-dictionary-download-failure' emitted when download fails. All events return: event (Event), languageCode (string - the language code of the dictionary file).

Session instance events: select-hid-device

The 'select-hid-device' event is emitted when a HID device needs to be selected via navigator.hid.requestDevice. Event returns: event (Event), details (Object with deviceList of HIDDevice[], frame of WebFrameMain or null), callback (Function accepting optional deviceId string). Passing no arguments to callback cancels the request. Permissioning can be further managed with setPermissionCheckHandler() and setDevicePermissionHandler().

Session instance events: hid-device-added, hid-device-removed, hid-device-revoked

hid-device-added event is emitted after navigator.hid.requestDevice and select-hid-device have fired if a new device becomes available before the callback. hid-device-removed event is emitted if a device has been removed before the callback. hid-device-revoked event is emitted after HIDDevice.forget() is called. All three return: event (Event), details (Object with device HIDDevice, frame WebFrameMain or null, optional origin string for revoked event).

Session instance events: select-serial-port

The 'select-serial-port' event is emitted when a serial port needs to be selected via navigator.serial.requestPort. Event returns: event (Event), portList (SerialPort[]), webContents (WebContents), callback (Function accepting portId string). Passing an empty string to callback cancels the request. Permissioning on navigator.serial can be managed with setPermissionCheckHandler() with the 'serial' permission.

Session instance events: serial-port-added, serial-port-removed, serial-port-revoked

serial-port-added event is emitted after navigator.serial.requestPort and select-serial-port have fired if a new serial port becomes available before the callback. serial-port-removed event is emitted if a port has been removed before the callback. serial-port-revoked event is emitted after SerialPort.forget() is called. Added/removed events return: event (Event), port (SerialPort), webContents (WebContents). Revoked event returns: event (Event), details (Object with port SerialPort, frame WebFrameMain or null, origin string).

Session instance events: select-usb-device

The 'select-usb-device' event is emitted when a USB device needs to be selected via navigator.usb.requestDevice. Event returns: event (Event), details (Object with deviceList of USBDevice[], frame of WebFrameMain or null), callback (Function accepting optional deviceId string). Passing no arguments to callback cancels the request. Permissioning can be further managed with setPermissionCheckHandler() and setDevicePermissionHandler().

Session instance events: usb-device-added, usb-device-removed, usb-device-revoked

usb-device-added event is emitted after navigator.usb.requestDevice and select-usb-device have fired if a new device becomes available before the callback. usb-device-removed event is emitted if a device has been removed before the callback. usb-device-revoked event is emitted after USBDevice.forget() is called. Added/removed events return: event (Event), device (USBDevice), webContents (WebContents). Revoked event returns: event (Event), details (Object with device USBDevice, optional origin string).

Session instance event: select-webauthn-authenticator (macOS)

The 'select-webauthn-authenticator' event is emitted on macOS when both touchID and platformPasskeys are configured via app.configureWebAuthn and a WebAuthn request needs to choose which platform authenticator to use. Event returns: event (Event with relyingPartyId string, authenticators string[] with possible values 'touchID' and 'platformPasskeys', frame WebFrameMain or null), callback (Function accepting optional authenticatorName string). Passing no arguments or a name not matching will cancel and trigger NotAllowedError. If no listener is registered, platformPasskeys is used by default. If only one authenticator is available, this event is not emitted.

Session instance event: select-webauthn-account

The 'select-webauthn-account' event is emitted when navigator.credentials.get() resolves multiple discoverable WebAuthn credentials and the user must choose one. Event returns: event (Event), details (Object with relyingPartyId string, accounts WebAuthnAccount[], frame WebFrameMain or null), callback (Function accepting optional credentialId string). Callback must be invoked exactly once with the credentialId of the selected account; passing no arguments or non-matching credentialId cancels and triggers NotAllowedError. On macOS, Touch ID platform authenticator surfaces accounts once configured with app.configureWebAuthn. If no listener is registered, navigator.credentials.get() calls that resolve multiple discoverable credentials are cancelled with NotAllowedError.

ses.setDisplayMediaRequestHandler() method parameters and video/audio options

ses.setDisplayMediaRequestHandler(handler[, opts]) sets handler for navigator.mediaDevices.getDisplayMedia API access. handler is Function | null with parameters: request (Object with frame WebFrameMain or null, securityOrigin string, videoRequested boolean, audioRequested boolean, userGesture boolean), callback (Function accepting streams Object). Streams object has: video (Object | WebFrameMain, optional) with id and name strings from DesktopCapturerSource; audio (String | WebFrameMain, optional) - string can be 'loopback' or 'loopbackWithMute' (Windows only), or WebFrameMain to capture frame audio; enableLocalEcho (Boolean, optional) - if audio is WebFrameMain and true, local playback not muted. opts parameter (optional, macOS experimental): useSystemPicker (Boolean) - if true, use native system picker instead of handler, only for MacOS 15+. Passing null resets handler to default.

ses.setDevicePermissionHandler() method and what it does

ses.setDevicePermissionHandler(handler) sets the handler for responding to device permission checks. handler is Function<boolean> | null with details parameter (Object with deviceType string - 'hid', 'serial', or 'usb'; origin string - origin URL; device - HIDDevice, SerialPort, or USBDevice). Returns true to allow device, false to deny. Call setDevicePermissionHandler(null) to clear. This handler provides default permissioning to devices without first calling for permission (eg via navigator.hid.requestDevice), enabling developers to manage granted device permissions. If undefined, default device permissions as granted through device selection will be used. Default Electron behavior stores granted device permissions in memory.

ses.setUSBProtectedClassesHandler() method and USB class values

ses.setUSBProtectedClassesHandler(handler) sets the handler to override which USB classes are protected. handler is Function<string[]> | null with details parameter (Object with protectedClasses string[] - current list of protected USB classes). Returns string array of USB classes to protect. Valid class values: audio, audio-video, hid, mass-storage, smart-card, video, wireless. Returning empty array allows all USB classes; returning passed-in array maintains default list (also default if handler undefined). Call setUSBProtectedClassesHandler(null) to clear.

ses.setBluetoothPairingHandler() method (Windows, Linux)

ses.setBluetoothPairingHandler(handler) sets handler to respond to Bluetooth pairing requests on Windows and Linux. handler is Function | null with details parameter (Object with deviceId string, pairingKind string - 'confirm', 'confirmPin', or 'providePin'; frame WebFrameMain or null; optional pin string if pairingKind is confirmPin) and callback (Function with response Object containing confirmed boolean and optional pin string). When pairingKind is confirm or confirmPin, confirmed should indicate if pairing confirmed; for providePin, true when value provided and pin should contain required pin. When handler undefined, pairing requiring additional validation automatically cancelled. macOS handles pairing automatically without handler. Call setBluetoothPairingHandler(null) to clear.

Example: Set display media request handler

const { session, desktopCapturer } = require('electron') session.defaultSession.setDisplayMediaRequestHandler((request, callback) => { desktopCapturer.getSources({ types: ['screen'] }).then((sources) => { // Grant access to the first screen found. callback({ video: sources[0] }) }) // Use the system picker if available. // Note: this is currently experimental. If the system picker // is available, it will be used and the media request handler // will not be invoked. }, { useSystemPicker: true })

Example: Allow WebFrameMain audio capture with setDisplayMediaRequestHandler

const { session } = require('electron') session.defaultSession.setDisplayMediaRequestHandler((request, callback) => { // Allow the tab to capture itself. callback({ video: request.frame }) })

Example: Set device permission handler

const { app, BrowserWindow } = require('electron') let win = null app.whenReady().then(() => { win = new BrowserWindow() win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => { if (permission === 'hid') { return true } else if (permission === 'serial') { return true } else if (permission === 'usb') { return true } return false }) const grantedDevices = fetchGrantedDevices() win.webContents.session.setDevicePermissionHandler((details) => { if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') { if (details.device.vendorId === 123 && details.device.productId === 345) { return true } return grantedDevices.some((grantedDevice) => { return grantedDevice.vendorId === details.device.vendorId && grantedDevice.productId === details.device.productId && grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber }) } else if (details.deviceType === 'serial') { if (details.device.vendorId === 123 && details.device.productId === 345) { return true } } return false }) win.webContents.session.on('select-hid-device', (event, details, callback) => { event.preventDefault() const selectedDevice = details.deviceList.find((device) => { return device.vendorId === 9025 && device.productId === 67 }) callback(selectedDevice?.deviceId) }) })

Example: Set USB protected classes handler

const { app, BrowserWindow } = require('electron') let win = null app.whenReady().then(() => { win = new BrowserWindow() win.webContents.session.setUSBProtectedClassesHandler((details) => { // Allow all classes: // return [] // Keep the current set of protected classes: // return details.protectedClasses // Selectively remove classes: return details.protectedClasses.filter((usbClass) => { // Exclude classes except for audio classes return usbClass.indexOf('audio') === -1 }) }) })

Example: Set Bluetooth pairing handler

const { app, BrowserWindow, session } = require('electron') const path = require('node:path') function createWindow () { let bluetoothPinCallback = null const mainWindow = new BrowserWindow({ webPreferences: { preload: path.join(__dirname, 'preload.js') } }) mainWindow.webContents.session.setBluetoothPairingHandler((details, callback) => { bluetoothPinCallback = callback mainWindow.webContents.send('bluetooth-pairing-request', details) }) mainWindow.webContents.ipc.on('bluetooth-pairing-response', (event, response) => { bluetoothPinCallback(response) }) } app.whenReady().then(() => { createWindow() })

Example: Set WebAuthn authenticator handler (macOS)

const { app, BrowserWindow } = require('electron') app.whenReady().then(() => { app.configureWebAuthn({ touchID: { keychainAccessGroup: 'A1B2C3D4E5.com.example.app.webauthn' }, platformPasskeys: true }) const win = new BrowserWindow() win.webContents.session.on('select-webauthn-authenticator', (event, callback) => { // Use the first available authenticator for the request. callback(event.authenticators[0]) }) })

Example: Handle select-webauthn-account event

const { app, BrowserWindow } = require('electron') let win = null app.whenReady().then(() => { app.configureWebAuthn({ touchID: { keychainAccessGroup: 'A1B2C3D4E5.com.example.app.webauthn' } }) win = new BrowserWindow() win.webContents.session.on('select-webauthn-account', (event, details, callback) => { const selected = details.accounts.find((a) => a.name === 'alice@example.com') callback(selected?.credentialId) }) })

Give your agent this brain