session.fromPartition() method
session.fromPartition(partition[, options]) creates or returns a Session instance from a partition string. Parameters: partition (string), options (Object optional with cache boolean). Returns a Session object. When partition has 'persist:' prefix, the session is persistent and available to all pages with that partition. Without 'persist:' prefix, it uses in-memory session. Empty partition returns the default app session. To create a Session with options, ensure the partition has never been used before; options cannot be changed on existing Session objects.
session.fromPath() method
session.fromPath(path[, options]) creates or returns a Session instance from an absolute path. Parameters: path (string, must be absolute), options (Object optional with cache boolean). Returns a Session object. Throws error if path is not absolute or is an empty string. To create a Session with options, ensure the path has never been used before; options cannot be changed on existing Session objects.
ses.getCacheSize() method
Returns Promise<Integer> resolving with the session's current cache size in bytes.
ses.clearCache() method
Returns Promise<void> resolving when the cache clear operation is complete. Clears the session's HTTP cache.
ses.setPermissionCheckHandler() permission types
Permission types for setPermissionCheckHandler: clipboard-read, clipboard-sanitized-write, geolocation, fullscreen, hid, idle-detection, media, mediaKeySystem, midi, midiSysex, notifications, openExternal, pointerLock, serial, storage-access, top-level-storage-access, usb, deprecated-sync-clipboard-read, fileSystem.
ses.clearStorageData() method
ses.clearStorageData([options]) clears session storage data. Parameters: options (Object optional) with origin (string optional, follows window.location.origin format), storages (string[] optional for types: 'cookies', 'filesystem', 'indexdb', 'localstorage', 'shadercache', 'serviceworkers', 'cachestorage'; if not specified, clears all). Returns Promise<void> resolving when storage data is cleared.
ses.flushStorageData() method
Writes any unwritten DOMStorage data to disk.
ses.setProxy() method
ses.setProxy(config) sets proxy settings. Parameter: config (ProxyConfig). Returns Promise<void> resolving when proxy setting is complete. You may need to call ses.closeAllConnections to close in-flight connections to prevent pooled sockets using previous proxy from being reused by future requests.
ses.resolveHost() method
ses.resolveHost(host, [options]) resolves a hostname. Parameters: host (string), options (Object optional) with queryType (string 'A' or 'AAAA'), source (string: 'any' default, 'system', 'dns', 'mdns', 'localOnly'), cacheUsage (string: 'allowed' default, 'staleAllowed', 'disallowed'), secureDnsPolicy (string: 'allow' default, 'disable'). Returns Promise<ResolvedHost> resolving with resolved IP addresses.
ses.resolveProxy() method
ses.resolveProxy(url) resolves proxy information for a URL. Parameter: url (URL). Returns Promise<string> resolving with proxy information.
ses.forceReloadProxyConfig() method
Returns Promise<void> resolving when all internal states of proxy service is reset and latest proxy configuration is reapplied if available. The pac script will be fetched from pacScript again if proxy mode is pac_script.
ses.setDownloadPath() method
ses.setDownloadPath(path) sets the download saving directory. Parameter: path (string). By default, the download directory is the Downloads folder under the respective app folder.
ses.enableNetworkEmulation() method
ses.enableNetworkEmulation(options) emulates network with given configuration. Parameter: options (Object) with offline (boolean optional, default false), latency (Double optional in ms, default 0), downloadThroughput (Double optional in Bps, default 0), uploadThroughput (Double optional in Bps, default 0).
ses.preconnect() method
ses.preconnect(options) preconnects given number of sockets to an origin. Parameter: options (Object) with url (string, only origin is relevant), numSockets (number optional, 1-6, default 1).
ses.closeAllConnections() method
Returns Promise<void> resolving when all connections are closed. Note: It will terminate/fail all requests currently in flight.
ses.fetch() method
ses.fetch(input[, init]) sends a request using Chromium's network stack, similarly to fetch() in the renderer. Parameters: input (string or GlobalRequest), init (RequestInit & {bypassCustomProtocolHandlers?: boolean} optional). Returns Promise<GlobalResponse>. Differs from Node's fetch() which uses Node.js HTTP stack. By default, requests can be made to custom protocols and file:, and trigger webRequest handlers. When bypassCustomProtocolHandlers option is set, custom protocol handlers are not called but webRequest handlers still trigger.
ses.fetch() limitations
ses.fetch() does not support data: or blob: schemes. The integrity option value is ignored. The .type and .url values of returned Response object are incorrect.
ses.disableNetworkEmulation() method
Disables any network emulation already active for the session. Resets to the original network configuration.
ses.setCertificateVerifyProc() method
ses.setCertificateVerifyProc(proc) sets certificate verify procedure. Parameter: proc (Function|null) taking request (Object with hostname, certificate, validatedCertificate, isIssuedByKnownRoot boolean, verificationResult string like 'OK' or error, errorCode Integer) and callback (Function taking verificationResult Integer: 0=success/disables transparency verification, -2=failure, -3=uses chromium verification). Calling setCertificateVerifyProc(null) reverts to default. Result is cached by network service.
ses.setPermissionRequestHandler() method
ses.setPermissionRequestHandler(handler) sets handler for permission requests. Parameter: handler (Function|null) taking webContents, permission (string), callback (Function taking boolean), details (PermissionRequest|FilesystemPermissionRequest|MediaAccessPermissionRequest|OpenExternalPermissionRequest). Calling callback(true) allows permission, callback(false) denies. To clear, pass null. Must also implement setPermissionCheckHandler for complete permission handling.
ses.setPermissionCheckHandler() method
ses.setPermissionCheckHandler(handler) sets handler for permission checks. Parameter: handler (Function<boolean>|null) taking webContents (WebContents|null), permission (string), requestingOrigin (string), details (Object with embeddingOrigin, securityOrigin, mediaType, requestingUrl, isMainFrame, filePath, isDirectory, fileAccessType optional). Returns true to allow, false to deny. To clear, pass null. Must also implement setPermissionRequestHandler for complete permission handling.
ses.setPermissionCheckHandler() isMainFrame pitfall
isMainFrame will always be false for a fileSystem request as a result of Chromium limitations.
ses.setDisplayMediaRequestHandler() method
ses.setDisplayMediaRequestHandler(handler[, opts]) sets handler for display media requests. Parameter: handler (Function|null) taking request (Object with frame [WebFrameMain|null], securityOrigin String, videoRequested Boolean, audioRequested Boolean, userGesture Boolean) and callback (Function taking streams Object with video and audio). opts (Object optional, macOS Experimental) with useSystemPicker (Boolean, default false, macOS only). Passing null resets handler. useSystemPicker uses system picker on macOS 15+ instead of providing specific video source.
ses.setDisplayMediaRequestHandler() video stream callback
In setDisplayMediaRequestHandler callback, video stream can be Object with id (String from DesktopCapturerSource), name (String from DesktopCapturerSource), or WebFrameMain to capture that frame.
ses.setDisplayMediaRequestHandler() audio stream callback
In setDisplayMediaRequestHandler callback, audio stream can be String ('loopback' or 'loopbackWithMute' for system audio on Windows), or WebFrameMain to capture audio from that frame. enableLocalEcho Boolean (optional) controls whether local playback is muted when audio is WebFrameMain, default false.
ses.setDevicePermissionHandler() method
ses.setDevicePermissionHandler(handler) sets handler for device permission checks. Parameter: handler (Function<boolean>|null) taking details (Object with deviceType string 'hid'/'serial'/'usb', origin string, device [HIDDevice|SerialPort|USBDevice]). Returns true to allow device, false to deny. To clear, pass null. Can provide default permissioning without requiring user selection, allowing skipping navigator.hid.requestDevice calls. Default Electron behavior stores granted permissions in memory.
ses.setUSBProtectedClassesHandler() method
ses.setUSBProtectedClassesHandler(handler) sets handler to override which USB classes are protected. Parameter: handler (Function<string[]>|null) taking details (Object with protectedClasses string[]). Returns string array of protected USB classes. Valid values: audio, audio-video, hid, mass-storage, smart-card, video, wireless. Empty array allows all classes. Returning passed array maintains defaults (also default if handler not defined). To clear, pass null.
ses.setBluetoothPairingHandler() method (Windows, Linux only)
ses.setBluetoothPairingHandler(handler) sets handler for Bluetooth pairing requests. Parameter: handler (Function|null) taking details (Object with deviceId string, pairingKind string 'confirm'/'confirmPin'/'providePin', frame [WebFrameMain|null], pin string optional) and callback (Function taking response Object with confirmed boolean, pin string|null optional). Handler allows developers to handle devices requiring additional validation before pairing. When not defined, pairing requiring validation is automatically cancelled on Linux/Windows. macOS handles automatically. To clear, pass null.
ses.clearHostResolverCache() method
Returns Promise<void> resolving when operation is complete. Clears the host resolver cache.
ses.allowNTLMCredentialsForDomains() method
ses.allowNTLMCredentialsForDomains(domains) dynamically sets whether to always send credentials for HTTP NTLM or Negotiate authentication. Parameter: domains (string, comma-separated list of servers for integrated authentication). Use '*' for all URLs.
ses.setUserAgent() method
ses.setUserAgent(userAgent[, acceptLanguages]) overrides userAgent and acceptLanguages for this session. Parameters: userAgent (string), acceptLanguages (string optional, comma-separated ordered list of language codes like 'en-US,fr,de,ko,zh-CN,ja'). Does not affect existing WebContents; each can use webContents.setUserAgent to override session-wide user agent.
ses.isPersistent() method
Returns boolean indicating whether session is persistent. Default webContents session of BrowserWindow is persistent. Sessions from partition with 'persist:' prefix are persistent; others are temporary.
ses.getUserAgent() method
Returns string, the user agent for this session.
ses.setSSLConfig() method
ses.setSSLConfig(config) sets SSL configuration for the session. Parameter: config (Object) with minVersion (string 'tls1'/'tls1.1'/'tls1.2'/'tls1.3' optional, default 'tls1'), maxVersion (string 'tls1.2'/'tls1.3' optional, default 'tls1.3'), disabledCipherSuites (Integer[] optional for cipher suites in hex form like 0xAABB per RFC 2246). All subsequent network requests use new configuration. Existing connections not terminated; old sockets not reused.
ses.getBlobData() method
ses.getBlobData(identifier) retrieves blob data. Parameter: identifier (string, valid UUID). Returns Promise<Buffer> resolving with blob data.
ses.downloadURL() method
ses.downloadURL(url[, options]) initiates a download of the resource at url. Parameters: url (string), options (Object optional with headers Record<string, string> optional). Generates DownloadItem accessible via will-download event. Note: Does not perform security checks relating to page origin, unlike webContents.downloadURL.
session.createInterruptedDownload() parameters
The createInterruptedDownload() method accepts an options object with the following properties: path (string, required) - absolute path of the download; urlChain (string[], required) - complete URL chain for the download; mimeType (string, optional); offset (integer, required) - start range for the download; length (integer, required) - total length of the download; lastModified (string, optional) - Last-Modified header value; eTag (string, optional) - ETag header value; startTime (double, optional) - time when download was started in number of seconds since UNIX epoch.
session.createInterruptedDownload() returns DownloadItem
The createInterruptedDownload() method generates a DownloadItem that can be accessed with the will-download event. The DownloadItem will not have any WebContents associated with it and the initial state will be interrupted. The download will start only when the resume API is called on the DownloadItem.
session.clearAuthCache()
The clearAuthCache() method returns Promise<void> and resolves when the session's HTTP authentication cache has been cleared.
session.setPreloads() deprecated
The setPreloads(preloads) method is deprecated. It accepts preloads as string[] - an array of absolute paths to preload scripts. It adds scripts that will be executed on ALL web contents associated with this session just before normal preload scripts run. Use the new ses.registerPreloadScript API instead.
session.getPreloads() deprecated
The getPreloads() method is deprecated. It returns string[] - an array of paths to preload scripts that have been registered. This method will only return preload script paths for frame context types. Use the new ses.getPreloadScripts API instead.
session.registerPreloadScript()
The registerPreloadScript(script) method registers a preload script that will be executed in its associated context type in this session. For frame contexts, this will run prior to any preload defined in the web preferences of a WebContents. It accepts script as a PreloadScriptRegistration object and returns string - the ID of the registered preload script.
session.unregisterPreloadScript()
The unregisterPreloadScript(id) method unregisters a script. It accepts id as a string - the preload script ID to unregister.
session.getPreloadScripts()
The getPreloadScripts() method returns PreloadScript[] - an array of preload scripts that have been registered.
session.setCodeCachePath()
The setCodeCachePath(path) method sets the directory to store the generated JS code cache for this session. It accepts path as a string - absolute path to store the v8 generated JS code cache from the renderer. The directory is not required to be created by the user before this call; the runtime will create it if it does not exist or will use the existing directory. If the directory cannot be created, code cache will not be used and all operations related to code cache will fail silently. By default, the directory will be 'Code Cache' under the respective user data folder. Code cache is only enabled for http(s) URLs by default; to enable code cache for custom protocols, 'codeCache: true' and 'standard: true' must be specified when registering the protocol.
session.clearCodeCaches()
The clearCodeCaches(options) method clears code cache. It accepts options object with urls (string[], optional) - an array of URLs corresponding to the resource whose generated code cache needs to be removed; if the list is empty then all entries in the cache directory will be removed. It returns Promise<void> - resolves when the code cache clear operation is complete.
session.getSharedDictionaryUsageInfo()
The getSharedDictionaryUsageInfo() method returns Promise<SharedDictionaryUsageInfo[]> - an array of shared dictionary information entries in Chromium's networking service's storage. Shared dictionaries are used to power advanced compression of data sent over the wire, specifically with Brotli and ZStandard.
session.getSharedDictionaryInfo()
The getSharedDictionaryInfo(options) method returns Promise<SharedDictionaryInfo[]> - an array of shared dictionary information entries in Chromium's networking service's storage. It accepts options object with frameOrigin (string, required) - the origin of the frame where the request originates, defined by its scheme, host, and port, and topFrameSite (string, required) - the site of the top-level browsing context focusing on the broader site scope.
session.clearSharedDictionaryCache()
The clearSharedDictionaryCache() method returns Promise<void> - resolves when the dictionary cache has been cleared, both in memory and on disk.
session.clearSharedDictionaryCacheForIsolationKey()
The clearSharedDictionaryCacheForIsolationKey(options) method returns Promise<void> - resolves when the dictionary cache has been cleared for the specified isolation key, both in memory and on disk. It accepts options object with frameOrigin (string, required) - the origin of the frame where the request originates, and topFrameSite (string, required) - the site of the top-level browsing context.
session.setSpellCheckerEnabled()
The setSpellCheckerEnabled(enable) method sets whether to enable the builtin spell checker. It accepts enable as a boolean.
session.isSpellCheckerEnabled()
The isSpellCheckerEnabled() method returns boolean - whether the builtin spell checker is enabled.
session.clearData() returns Promise
The clearData() method returns Promise<void> - resolves when all data has been cleared. It clears various different types of data and is more thorough than the clearStorageData method.
session.setSpellCheckerLanguages()
The setSpellCheckerLanguages(languages) method sets which languages the spell checker is enabled for. It accepts languages as string[] - an array of language codes to enable the spellchecker for. The built-in spellchecker does not automatically detect what language a user is typing in; you must call this API with an array of language codes. You can get the list of supported language codes with the ses.availableSpellCheckerLanguages property. On macOS, the OS spellchecker is used and will detect language automatically, making this API a no-op on macOS.
session.getSpellCheckerLanguages()
The getSpellCheckerLanguages() method returns string[] - an array of language codes the spellchecker is enabled for. If this list is empty the spellchecker will fallback to using en-US. By default on launch, if this setting is an empty list, Electron will try to populate this setting with the current OS locale. This setting is persisted across restarts. On macOS, the OS spellchecker is used and has its own list of languages; this API will return whichever languages have been configured by the OS.
session.setSpellCheckerDictionaryDownloadURL()
The setSpellCheckerDictionaryDownloadURL(url) method sets a base URL for Electron to download hunspell dictionaries from. It accepts url as a string. By default Electron downloads hunspell dictionaries from the Chromium CDN. The file server must be case insensitive; if it cannot be, you must upload each file twice: once with the case it has in the ZIP file and once with the filename as all lowercase. The URL to the dictionaries is formed as ${url}${filename}. On macOS, the OS spellchecker is used and therefore no dictionary files are downloaded, making this API a no-op on macOS.
session.listWordsInSpellCheckerDictionary()
The listWordsInSpellCheckerDictionary() method returns Promise<string[]> - an array of all words in the app's custom dictionary. It resolves when the full dictionary is loaded from disk.
session.addWordToSpellCheckerDictionary()
The addWordToSpellCheckerDictionary(word) method adds a word to the spell checker dictionary. It accepts word as a string - the word to add to the dictionary. It returns boolean - whether the word was successfully written to the custom dictionary. This API will not work on non-persistent (in-memory) sessions. On macOS and Windows, this word will be written to the OS custom dictionary as well.
session.removeWordFromSpellCheckerDictionary()
The removeWordFromSpellCheckerDictionary(word) method removes a word from the spell checker dictionary. It accepts word as a string - the word to remove from the dictionary. It returns boolean - whether the word was successfully removed from the custom dictionary. This API will not work on non-persistent (in-memory) sessions. On macOS and Windows, this word will be removed from the OS custom dictionary as well.
session.loadExtension() deprecated
The loadExtension(path[, options]) method is deprecated. It loads a Chrome extension from a directory. It accepts path as string - path to a directory containing an unpacked Chrome extension; and options as optional object with allowFileAccess (boolean, optional, defaults to false) - whether to allow the extension to read local files over file:// protocol and inject content scripts into file:// pages. It returns Promise<Extension> - resolves when the extension is loaded. Extensions must be loaded on every boot of the app if you want them to be loaded. This API does not support loading packed (.crx) extensions. In-memory (non-persistent) sessions are not supported. Use the new ses.extensions.loadExtension API instead.