A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://www.electronjs.org/docs/latest/api/session below:

session | Electron

session

Manage browser sessions, cookies, cache, proxy settings, etc.

Process: Main

The session module can be used to create new Session objects.

You can also access the session of existing pages by using the session property of WebContents, or from the session module.

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')

const ses = win.webContents.session
console.log(ses.getUserAgent())
Methods​

The session module has the following methods:

session.fromPartition(partition[, options])​

Returns Session - A session instance from partition string. When there is an existing Session with the same partition, it will be returned; otherwise a new Session instance will be created with options.

If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. if there is no persist: prefix, the page will use an in-memory session. If the partition is empty then default session of the app will be returned.

To create a Session with options, you have to ensure the Session with the partition has never been used before. There is no way to change the options of an existing Session object.

session.fromPath(path[, options])​

Returns Session - A session instance from the absolute path as specified by the path string. When there is an existing Session with the same absolute path, it will be returned; otherwise a new Session instance will be created with options. The call will throw an error if the path is not an absolute path. Additionally, an error will be thrown if an empty string is provided.

To create a Session with options, you have to ensure the Session with the path has never been used before. There is no way to change the options of an existing Session object.

Properties​

The session module has the following properties:

session.defaultSession​

A Session object, the default session object of the app.

Class: Session​

Get and set properties of a session.

Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.

You can create a Session object in the session module:

const { session } = require('electron')
const ses = session.fromPartition('persist:name')
console.log(ses.getUserAgent())
Instance Events​

The following events are available on instances of Session:

Event: 'will-download'​

Returns:

Emitted when Electron is about to download item in webContents.

Calling event.preventDefault() will cancel the download and item will not be available from next tick of the process.

const { session } = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
  event.preventDefault()
  require('got')(item.getURL()).then((response) => {
    require('node:fs').writeFileSync('/somewhere', response.body)
  })
})
Event: 'extension-loaded'​

Returns:

Emitted after an extension is loaded. This occurs whenever an extension is added to the "enabled" set of extensions. This includes:

Event: 'extension-unloaded'​

Returns:

Emitted after an extension is unloaded. This occurs when Session.removeExtension is called.

Event: 'extension-ready'​

Returns:

Emitted after an extension is loaded and all necessary browser state is initialized to support the start of the extension's background page.

Event: 'file-system-access-restricted'​

Returns:

const { app, dialog, BrowserWindow, session } = require('electron')

async function createWindow () {
  const mainWindow = new BrowserWindow()

  await mainWindow.loadURL('https://buzzfeed.com')

  session.defaultSession.on('file-system-access-restricted', async (e, details, callback) => {
    const { origin, path } = details
    const { response } = await dialog.showMessageBox({
      message: `Are you sure you want ${origin} to open restricted path ${path}?`,
      title: 'File System Access Restricted',
      buttons: ['Choose a different folder', 'Allow', 'Cancel'],
      cancelId: 2
    })

    if (response === 0) {
      callback('tryAgain')
    } else if (response === 1) {
      callback('allow')
    } else {
      callback('deny')
    }
  })

  mainWindow.webContents.executeJavaScript(`
    window.showDirectoryPicker({
      id: 'electron-demo',
      mode: 'readwrite',
      startIn: 'downloads',
    }).catch(e => {
      console.log(e)
    })`, true
  )
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})
Event: 'preconnect'​

Returns:

Emitted when a render process requests preconnection to a URL, generally due to a resource hint.

Event: 'spellcheck-dictionary-initialized'​

Returns:

Emitted when a hunspell dictionary file has been successfully initialized. This occurs after the file has been downloaded.

Event: 'spellcheck-dictionary-download-begin'​

Returns:

Emitted when a hunspell dictionary file starts downloading

Event: 'spellcheck-dictionary-download-success'​

Returns:

Emitted when a hunspell dictionary file has been successfully downloaded

Event: 'spellcheck-dictionary-download-failure'​

Returns:

Emitted when a hunspell dictionary file download fails. For details on the failure you should collect a netlog and inspect the download request.

Event: 'select-hid-device'​

Returns:

Emitted when a HID device needs to be selected when a call to navigator.hid.requestDevice is made. callback should be called with deviceId to be selected; passing no arguments to callback will cancel the request. Additionally, permissioning on navigator.hid can be further managed by using ses.setPermissionCheckHandler(handler) and ses.setDevicePermissionHandler(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
    }
    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
      })
    }
    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)
  })
})
Event: 'hid-device-added'​

Returns:

Emitted after navigator.hid.requestDevice has been called and select-hid-device has fired if a new device becomes available before the callback from select-hid-device is called. This event is intended for use when using a UI to ask users to pick a device so that the UI can be updated with the newly added device.

Event: 'hid-device-removed'​

Returns:

Emitted after navigator.hid.requestDevice has been called and select-hid-device has fired if a device has been removed before the callback from select-hid-device is called. This event is intended for use when using a UI to ask users to pick a device so that the UI can be updated to remove the specified device.

Event: 'hid-device-revoked'​

Returns:

Emitted after HIDDevice.forget() has been called. This event can be used to help maintain persistent storage of permissions when setDevicePermissionHandler is used.

Event: 'select-serial-port'​

Returns:

Emitted when a serial port needs to be selected when a call to navigator.serial.requestPort is made. callback should be called with portId to be selected, passing an empty string to callback will cancel the request. Additionally, permissioning on navigator.serial can be managed by using ses.setPermissionCheckHandler(handler) with the serial permission.

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow({
    width: 800,
    height: 600
  })

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'serial') {
      
      return true
    }
    return false
  })

  
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'serial') {
      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
      })
    }
    return false
  })

  win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {
    event.preventDefault()
    const selectedPort = portList.find((device) => {
      return device.vendorId === '9025' && device.productId === '67'
    })
    if (!selectedPort) {
      callback('')
    } else {
      callback(selectedPort.portId)
    }
  })
})
Event: 'serial-port-added'​

Returns:

Emitted after navigator.serial.requestPort has been called and select-serial-port has fired if a new serial port becomes available before the callback from select-serial-port is called. This event is intended for use when using a UI to ask users to pick a port so that the UI can be updated with the newly added port.

Event: 'serial-port-removed'​

Returns:

Emitted after navigator.serial.requestPort has been called and select-serial-port has fired if a serial port has been removed before the callback from select-serial-port is called. This event is intended for use when using a UI to ask users to pick a port so that the UI can be updated to remove the specified port.

Event: 'serial-port-revoked'​

Returns:

Emitted after SerialPort.forget() has been called. This event can be used to help maintain persistent storage of permissions when setDevicePermissionHandler is used.


const { app, BrowserWindow } = require('electron')

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 800,
    height: 600
  })

  win.webContents.session.on('serial-port-revoked', (event, details) => {
    console.log(`Access revoked for serial device from origin ${details.origin}`)
  })
})


const portConnect = async () => {
  
  const port = await navigator.serial.requestPort()

  
  await port.open({ baudRate: 9600 })

  
  await port.forget()
}
Event: 'select-usb-device'​

Returns:

Emitted when a USB device needs to be selected when a call to navigator.usb.requestDevice is made. callback should be called with deviceId to be selected; passing no arguments to callback will cancel the request. Additionally, permissioning on navigator.usb can be further managed by using ses.setPermissionCheckHandler(handler) and ses.setDevicePermissionHandler(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 === 'usb') {
      
      return true
    }
    return false
  })

  
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'usb') {
      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
      })
    }
    return false
  })

  win.webContents.session.on('select-usb-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === 9025 && device.productId === 67
    })
    if (selectedDevice) {
      
      grantedDevices.push(selectedDevice)
      updateGrantedDevices(grantedDevices)
    }
    callback(selectedDevice?.deviceId)
  })
})
Event: 'usb-device-added'​

Returns:

Emitted after navigator.usb.requestDevice has been called and select-usb-device has fired if a new device becomes available before the callback from select-usb-device is called. This event is intended for use when using a UI to ask users to pick a device so that the UI can be updated with the newly added device.

Event: 'usb-device-removed'​

Returns:

Emitted after navigator.usb.requestDevice has been called and select-usb-device has fired if a device has been removed before the callback from select-usb-device is called. This event is intended for use when using a UI to ask users to pick a device so that the UI can be updated to remove the specified device.

Event: 'usb-device-revoked'​

Returns:

Emitted after USBDevice.forget() has been called. This event can be used to help maintain persistent storage of permissions when setDevicePermissionHandler is used.

Instance Methods​

The following methods are available on instances of Session:

ses.getCacheSize()​

Returns Promise<Integer> - the session's current cache size, in bytes.

ses.clearCache()​

Returns Promise<void> - resolves when the cache clear operation is complete.

Clears the session’s HTTP cache.

ses.clearStorageData([options])​

Returns Promise<void> - resolves when the storage data has been cleared.

ses.flushStorageData()​

Writes any unwritten DOMStorage data to disk.

ses.setProxy(config)​

Returns Promise<void> - Resolves when the proxy setting process is complete.

Sets the proxy settings.

You may need ses.closeAllConnections to close currently in flight connections to prevent pooled sockets using previous proxy from being reused by future requests.

ses.resolveHost(host, [options])​

Returns Promise<ResolvedHost> - Resolves with the resolved IP addresses for the host.

ses.resolveProxy(url)​

Returns Promise<string> - Resolves with the proxy information for url.

ses.forceReloadProxyConfig()​

Returns Promise<void> - Resolves when the all internal states of proxy service is reset and the latest proxy configuration is reapplied if it's already available. The pac script will be fetched from pacScript again if the proxy mode is pac_script.

ses.setDownloadPath(path)​

Sets download saving directory. By default, the download directory will be the Downloads under the respective app folder.

ses.enableNetworkEmulation(options)​

Emulates network with the given configuration for the session.

const win = new BrowserWindow()


win.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})


win.webContents.session.enableNetworkEmulation({ offline: true })
ses.preconnect(options)​

Preconnects the given number of sockets to an origin.

ses.closeAllConnections()​

Returns Promise<void> - Resolves when all connections are closed.

note

It will terminate / fail all requests currently in flight.

ses.fetch(input[, init])​

Returns Promise<GlobalResponse> - see Response.

Sends a request, similarly to how fetch() works in the renderer, using Chrome's network stack. This differs from Node's fetch(), which uses Node.js's HTTP stack.

Example:

async function example () {
  const response = await net.fetch('https://my.app')
  if (response.ok) {
    const body = await response.json()
    
  }
}

See also net.fetch(), a convenience method which issues requests from the default session.

See the MDN documentation for fetch() for more details.

Limitations:

By default, requests made with net.fetch can be made to custom protocols as well as file:, and will trigger webRequest handlers if present. When the non-standard bypassCustomProtocolHandlers option is set in RequestInit, custom protocol handlers will not be called for this request. This allows forwarding an intercepted request to the built-in handler. webRequest handlers will still be triggered when bypassing custom protocols.

protocol.handle('https', (req) => {
  if (req.url === 'https://my-app.com') {
    return new Response('<body>my app</body>')
  } else {
    return net.fetch(req, { bypassCustomProtocolHandlers: true })
  }
})
ses.disableNetworkEmulation()​

Disables any network emulation already active for the session. Resets to the original network configuration.

ses.setCertificateVerifyProc(proc)​

Sets the certificate verify proc for session, the proc will be called with proc(request, callback) whenever a server certificate verification is requested. Calling callback(0) accepts the certificate, calling callback(-2) rejects it.

Calling setCertificateVerifyProc(null) will revert back to default certificate verify proc.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

win.webContents.session.setCertificateVerifyProc((request, callback) => {
  const { hostname } = request
  if (hostname === 'github.com') {
    callback(0)
  } else {
    callback(-2)
  }
})

NOTE: The result of this procedure is cached by the network service.

ses.setPermissionRequestHandler(handler)​

Sets the handler which can be used to respond to permission requests for the session. Calling callback(true) will allow the permission and callback(false) will reject it. To clear the handler, call setPermissionRequestHandler(null). Please note that you must also implement setPermissionCheckHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied.

const { session } = require('electron')
session.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {
  if (webContents.getURL() === 'some-host' && permission === 'notifications') {
    return callback(false) 
  }

  callback(true)
})
ses.setPermissionCheckHandler(handler)​

Sets the handler which can be used to respond to permission checks for the session. Returning true will allow the permission and false will reject it. Please note that you must also implement setPermissionRequestHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied. To clear the handler, call setPermissionCheckHandler(null).

const { session } = require('electron')
const url = require('url')
session.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
  if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {
    return true 
  }

  return false 
})
ses.setDisplayMediaRequestHandler(handler[, opts])​

This handler will be called when web content requests access to display media via the navigator.mediaDevices.getDisplayMedia API. Use the desktopCapturer API to choose which stream(s) to grant access to.

useSystemPicker allows an application to use the system picker instead of providing a specific video source from getSources. This option is experimental, and currently available for MacOS 15+ only. If the system picker is available and useSystemPicker is set to true, the handler will not be invoked.

const { session, desktopCapturer } = require('electron')

session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
  desktopCapturer.getSources({ types: ['screen'] }).then((sources) => {
    
    callback({ video: sources[0] })
  })
  
  
  
  
}, { useSystemPicker: true })

Passing a WebFrameMain object as a video or audio stream will capture the video or audio stream from that frame.

const { session } = require('electron')

session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
  
  callback({ video: request.frame })
})

Passing null instead of a function resets the handler to its default state.

ses.setDevicePermissionHandler(handler)​

Sets the handler which can be used to respond to device permission checks for the session. Returning true will allow the device to be permitted and false will reject it. To clear the handler, call setDevicePermissionHandler(null). This handler can be used to provide default permissioning to devices without first calling for permission to devices (eg via navigator.hid.requestDevice). If this handler is not defined, the default device permissions as granted through device selection (eg via navigator.hid.requestDevice) will be used. Additionally, the default behavior of Electron is to store granted device permission in memory. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.

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') {
      
    } else if (permission === 'usb') {
      
    }
    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)
  })
})
ses.setUSBProtectedClassesHandler(handler)​

Sets the handler which can be used to override which USB classes are protected. The return value for the handler is a string array of USB classes which should be considered protected (eg not available in the renderer). Valid values for the array are:

Returning an empty string array from the handler will allow all USB classes; returning the passed in array will maintain the default list of protected USB classes (this is also the default behavior if a handler is not defined). To clear the handler, call setUSBProtectedClassesHandler(null).

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setUSBProtectedClassesHandler((details) => {
    
    
    
    
    
    return details.protectedClasses.filter((usbClass) => {
      
      return usbClass.indexOf('audio') === -1
    })
  })
})
ses.setBluetoothPairingHandler(handler) Windows Linux​

Sets a handler to respond to Bluetooth pairing requests. This handler allows developers to handle devices that require additional validation before pairing. When a handler is not defined, any pairing on Linux or Windows that requires additional validation will be automatically cancelled. macOS does not require a handler because macOS handles the pairing automatically. To clear the handler, call setBluetoothPairingHandler(null).

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()
})
ses.clearHostResolverCache()​

Returns Promise<void> - Resolves when the operation is complete.

Clears the host resolver cache.

ses.allowNTLMCredentialsForDomains(domains)​

Dynamically sets whether to always send credentials for HTTP NTLM or Negotiate authentication.

const { session } = require('electron')


session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')


session.defaultSession.allowNTLMCredentialsForDomains('*')
ses.setUserAgent(userAgent[, acceptLanguages])​

Overrides the userAgent and acceptLanguages for this session.

The acceptLanguages must a comma separated ordered list of language codes, for example "en-US,fr,de,ko,zh-CN,ja".

This doesn't affect existing WebContents, and each WebContents can use webContents.setUserAgent to override the session-wide user agent.

ses.isPersistent()​

Returns boolean - Whether or not this session is a persistent one. The default webContents session of a BrowserWindow is persistent. When creating a session from a partition, session prefixed with persist: will be persistent, while others will be temporary.

ses.getUserAgent()​

Returns string - The user agent for this session.

ses.setSSLConfig(config)​

Sets the SSL configuration for the session. All subsequent network requests will use the new configuration. Existing network connections (such as WebSocket connections) will not be terminated, but old sockets in the pool will not be reused for new connections.

ses.getBlobData(identifier)​

Returns Promise<Buffer> - resolves with blob data.

ses.downloadURL(url[, options])​

Initiates a download of the resource at url. The API will generate a DownloadItem that can be accessed with the will-download event.

ses.createInterruptedDownload(options)​

Allows resuming cancelled or interrupted downloads from previous Session. The API will generate 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.

ses.clearAuthCache()​

Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.

ses.setPreloads(preloads) Deprecated​

Adds scripts that will be executed on ALL web contents that are associated with this session just before normal preload scripts run.

Deprecated: Use the new ses.registerPreloadScript API.

ses.getPreloads() Deprecated​

Returns string[] an array of paths to preload scripts that have been registered.

Deprecated: Use the new ses.getPreloadScripts API. This will only return preload script paths for frame context types.

ses.registerPreloadScript(script)​

Registers 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.

Returns string - The ID of the registered preload script.

ses.unregisterPreloadScript(id)​

Unregisters script.

ses.getPreloadScripts()​

Returns PreloadScript[]: An array of paths to preload scripts that have been registered.

ses.setCodeCachePath(path)​

Sets the directory to store the generated JS code cache for this session. The directory is not required to be created by the user before this call, the runtime will create if it does not exist otherwise will use the existing directory. If directory cannot be created, then code cache will not be used and all operations related to code cache will fail silently inside the runtime. By default, the directory will be Code Cache under the respective user data folder.

Note that by default code cache is only enabled for http(s) URLs, to enable code cache for custom protocols, codeCache: true and standard: true must be specified when registering the protocol.

ses.clearCodeCaches(options)​

Returns Promise<void> - resolves when the code cache clear operation is complete.

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. You don't need to call any of the shared dictionary APIs in Electron to make use of this advanced web feature, but if you do, they allow deeper control and inspection of the shared dictionaries used during decompression.

To get detailed information about a specific shared dictionary entry, call getSharedDictionaryInfo(options).

Returns Promise<SharedDictionaryInfo[]> - an array of shared dictionary information entries in Chromium's networking service's storage.

To get information about all present shared dictionaries, call getSharedDictionaryUsageInfo().

Returns Promise<void> - resolves when the dictionary cache has been cleared, both in memory and on disk.

Returns Promise<void> - resolves when the dictionary cache has been cleared for the specified isolation key, both in memory and on disk.

ses.setSpellCheckerEnabled(enable)​

Sets whether to enable the builtin spell checker.

ses.isSpellCheckerEnabled()​

Returns boolean - Whether the builtin spell checker is enabled.

ses.setSpellCheckerLanguages(languages)​

The built in spellchecker does not automatically detect what language a user is typing in. In order for the spell checker to correctly check their words 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.

note

On macOS, the OS spellchecker is used and will detect your language automatically. This API is a no-op on macOS.

ses.getSpellCheckerLanguages()​

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.

note

On macOS, the OS spellchecker is used and has its own list of languages. On macOS, this API will return whichever languages have been configured by the OS.

ses.setSpellCheckerDictionaryDownloadURL(url)​

By default Electron will download hunspell dictionaries from the Chromium CDN. If you want to override this behavior you can use this API to point the dictionary downloader at your own hosted version of the hunspell dictionaries. We publish a hunspell_dictionaries.zip file with each release which contains the files you need to host here.

The file server must be case insensitive. If you cannot do this, you must upload each file twice: once with the case it has in the ZIP file and once with the filename as all lowercase.

If the files present in hunspell_dictionaries.zip are available at https://example.com/dictionaries/language-code.bdic then you should call this api with ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Please note the trailing slash. The URL to the dictionaries is formed as ${url}${filename}.

note

On macOS, the OS spellchecker is used and therefore we do not download any dictionary files. This API is a no-op on macOS.

ses.listWordsInSpellCheckerDictionary()​

Returns Promise<string[]> - An array of all words in app's custom dictionary. Resolves when the full dictionary is loaded from disk.

ses.addWordToSpellCheckerDictionary(word)​

Returns boolean - Whether the word was successfully written to the custom dictionary. This API will not work on non-persistent (in-memory) sessions.

note

On macOS and Windows, this word will be written to the OS custom dictionary as well.

ses.removeWordFromSpellCheckerDictionary(word)​

Returns boolean - Whether the word was successfully removed from the custom dictionary. This API will not work on non-persistent (in-memory) sessions.

note

On macOS and Windows, this word will be removed from the OS custom dictionary as well.

ses.loadExtension(path[, options]) Deprecated​

Returns Promise<Extension> - resolves when the extension is loaded.

This method will raise an exception if the extension could not be loaded. If there are warnings when installing the extension (e.g. if the extension requests an API that Electron does not support) then they will be logged to the console.

Note that Electron does not support the full range of Chrome extensions APIs. See Supported Extensions APIs for more details on what is supported.

Note that in previous versions of Electron, extensions that were loaded would be remembered for future runs of the application. This is no longer the case: loadExtension must be called on every boot of your app if you want the extension to be loaded.

const { app, session } = require('electron')
const path = require('node:path')

app.whenReady().then(async () => {
  await session.defaultSession.loadExtension(
    path.join(__dirname, 'react-devtools'),
    
    { allowFileAccess: true }
  )
  
  
})

This API does not support loading packed (.crx) extensions.

note

This API cannot be called before the ready event of the app module is emitted.

note

Loading extensions into in-memory (non-persistent) sessions is not supported and will throw an error.

Deprecated: Use the new ses.extensions.loadExtension API.

ses.removeExtension(extensionId) Deprecated​

Unloads an extension.

note

This API cannot be called before the ready event of the app module is emitted.

Deprecated: Use the new ses.extensions.removeExtension API.

ses.getExtension(extensionId) Deprecated​

Returns Extension | null - The loaded extension with the given ID.

note

This API cannot be called before the ready event of the app module is emitted.

Deprecated: Use the new ses.extensions.getExtension API.

ses.getAllExtensions() Deprecated​

Returns Extension[] - A list of all loaded extensions.

note

This API cannot be called before the ready event of the app module is emitted.

Deprecated: Use the new ses.extensions.getAllExtensions API.

ses.getStoragePath()​

Returns string | null - The absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.

ses.clearData([options])​

Returns Promise<void> - resolves when all data has been cleared.

Clears various different types of data.

This method clears more types of data and is more thorough than the clearStorageData method.

note

Cookies are stored at a broader scope than origins. When removing cookies and filtering by origins (or excludeOrigins), the cookies will be removed at the registrable domain level. For example, clearing cookies for the origin https://really.specific.origin.example.com/ will end up clearing all cookies for example.com. Clearing cookies for the origin https://my.website.example.co.uk/ will end up clearing all cookies for example.co.uk.

note

Clearing cache data will also clear the shared dictionary cache. This means that any dictionaries used for compression may be reloaded after clearing the cache. If you wish to clear the shared dictionary cache but leave other cached data intact, you may want to use the clearSharedDictionaryCache method.

For more information, refer to Chromium's BrowsingDataRemover interface.

Instance Properties​

The following properties are available on instances of Session:

ses.availableSpellCheckerLanguages Readonly​

A string[] array which consists of all the known available spell checker languages. Providing a language code to the setSpellCheckerLanguages API that isn't in this array will result in an error.

ses.spellCheckerEnabled​

A boolean indicating whether builtin spell checker is enabled.

ses.storagePath Readonly​

A string | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.

ses.cookies Readonly​

A Cookies object for this session.

ses.extensions Readonly​

A Extensions object for this session.

ses.serviceWorkers Readonly​

A ServiceWorkers object for this session.

ses.webRequest Readonly​

A WebRequest object for this session.

ses.protocol Readonly​

A Protocol object for this session.

const { app, session } = require('electron')
const path = require('node:path')

app.whenReady().then(() => {
  const protocol = session.fromPartition('some-partition').protocol
  if (!protocol.registerFileProtocol('atom', (request, callback) => {
    const url = request.url.substr(7)
    callback({ path: path.normalize(path.join(__dirname, url)) })
  })) {
    console.error('Failed to register protocol')
  }
})
ses.netLog Readonly​

A NetLog object for this session.

const { app, session } = require('electron')

app.whenReady().then(async () => {
  const netLog = session.fromPartition('some-partition').netLog
  netLog.startLogging('/path/to/net-log')
  
  const path = await netLog.stopLogging()
  console.log('Net-logs written to', path)
})

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4