Saltar al contenido principal

session

Administra las sesiones del navegador, cookies, cache, configuración del proxy, etc.

Proceso: principal</0>

El módulo session puede ser usado para crear nuevos objetos session.

También puede acceder el session de las páginas existentes utilizando la propiedad session de WebContents, o desde el módulo session.

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())

Métodos​

El módulo session tiene los siguientes métodos:

session.fromPartition(partition[, options])​

  • partition string
  • options Object (opcional)
    • cache boolean - Whether to enable cache.

Regresa Session - Una instancia de session de la cadena partition. Cuando hay una Session existente con la misma partition, se devolverá la misma; de otra manera, una nueva instancia Session será creada con options.

Si la partition comienza con persist:, la página usará una sesión persistente disponible a todas las páginas en la aplicación con la misma partition. si no hay un prefijo persist:, la página usará una sesión en memoria. Si la partition está vacía entonces la sesión de la aplicación será usada por defecto.

Al crear una Session con options, tiene que asegurar que la Session con la partition nunca ha sido usada antes. No hay manera de cambiar las options de un objeto Session existente.

session.fromPath(path[, options])​

  • path string
  • options Object (opcional)
    • cache boolean - Whether to enable cache.

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. No hay manera de cambiar las options de un objeto Session existente.

Propiedades​

El módulo session tiene las siguientes propiedades:

session.defaultSession​

Un objeto Session, es el objeto de session de la aplicación por defecto.

Class: Session​

Obtener y configurar las propiedades de una sesión.

Proceso: Main
Esta clase no está exportada desde el módulo 'electron'. Sólo está disponible como un valor de retorno de otros métodos en la API de Electron.

Puede crear un objeto Session en el módulo session:

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

Eventos de Instancia​

Los siguientes eventos están disponibles en instancias de Session:

Evento: 'will-download'​

Devuelve:

Emitido cuando Electron está por descargar un elemento en Contenido web.

Llamando event.preventDefault() Se cancelará la descarga y el elemento no estará disponible para el siguiente tick del proceso.

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)
  })
})

Evento: 'extension-loaded'​

Devuelve:

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

  • Extensions being loaded from Session.loadExtension.
  • Extensions being reloaded:

Evento: 'extension-unloaded'​

Devuelve:

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

Evento: 'extension-ready'​

Devuelve:

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

Evento: 'preconnect'​

Devuelve:

  • event
  • preconnectUrl string - The URL being requested for preconnection by the renderer.
  • allowCredentials boolean - True if the renderer is requesting that the connection include credentials (see the spec for more details.)

Emitido cuando un render process solicita preconexión a una URL, generalmente debido a resource hint.

Evento: 'spellcheck-dictionary-initialized'​

Devuelve:

  • event
  • languageCode string - The language code of the dictionary file

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

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

Devuelve:

  • event
  • languageCode string - The language code of the dictionary file

Emitido cuando un archivo de diccionario hunspell se comienza a descargar

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

Devuelve:

  • event
  • languageCode string - The language code of the dictionary file

Emitido cuando un archivo de diccionario hunspell se ha descargado correctamente

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

Devuelve:

  • event
  • languageCode string - The language code of the dictionary file

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'​

Devuelve:

Emitido cuando un dispositivo HID necesita ser seleccionado cuando se realizó una llamada a navigator.hid.requestDevice. callback debería ser llamada con el deviceId a ser seleccionado; al no pasar argumentos a callback se cancelará la solicitud. 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') {
      // Add logic here to determine if permission should be given to allow HID selection
      return true
    }
    return false
  })

  // Optionally, retrieve previously persisted devices from a persistent store
  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) {
        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
        return true
      }

      // Search through the list of devices that have previously been granted permission
      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)
  })
})

Evento: 'hid-device-added'​

Devuelve:

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.

Evento: 'hid-device-removed'​

Devuelve:

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'​

Devuelve:

  • event
  • details Object
    • device HIDDevice
    • origin string (optional) - The origin that the device has been revoked from.

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

Evento: 'select-serial-port'​

Devuelve:

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') {
      // Add logic here to determine if permission should be given to allow serial selection
      return true
    }
    return false
  })

  // Optionally, retrieve previously persisted devices from a persistent store
  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) {
        // Always allow this type of device (this allows skipping the call to `navigator.serial.requestPort` first)
        return true
      }

      // Search through the list of devices that have previously been granted permission
      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)
    }
  })
})

Evento: 'serial-port-added'​

Devuelve:

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.

Evento: 'serial-port-removed'​

Devuelve:

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'​

Devuelve:

  • event
  • details Object

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

// Browser Process
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}`)
  })
})
// Renderer Process

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

  // Wait for the serial port to open.
  await port.open({ baudRate: 9600 })

  // ...later, revoke access to the serial port.
  await port.forget()
}

Event: 'select-usb-device'​

Devuelve:

Emitted when a USB device needs to be selected when a call to navigator.usb.requestDevice is made. callback debería ser llamada con el deviceId a ser seleccionado; al no pasar argumentos a callback se cancelará la solicitud. 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') {
      // Add logic here to determine if permission should be given to allow USB selection
      return true
    }
    return false
  })

  // Optionally, retrieve previously persisted devices from a persistent store (fetchGrantedDevices needs to be implemented by developer to fetch persisted permissions)
  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) {
        // Always allow this type of device (this allows skipping the call to `navigator.usb.requestDevice` first)
        return true
      }

      // Search through the list of devices that have previously been granted permission
      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) {
      // Optionally, add this to the persisted devices (updateGrantedDevices needs to be implemented by developer to persist permissions)
      grantedDevices.push(selectedDevice)
      updateGrantedDevices(grantedDevices)
    }
    callback(selectedDevice?.deviceId)
  })
})

Event: 'usb-device-added'​

Devuelve:

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'​

Devuelve:

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'​

Devuelve:

  • event
  • details Object
    • device USBDevice
    • origin string (optional) - The origin that the device has been revoked from.

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

Métodos de Instancia​

Los siguientes métodos están disponibles para instancias de Sesión:

ses.getCacheSize()​

Devuelve Promise<Integer> - El tamaño de cache de la sesión actual, en bytes.

ses.clearCache()​

Devuelve Promise<void> - Se resuelve cuando la operación de limpieza de cache es completada.

Borra la memoria caché del HTTP de la sesión.

ses.clearStorageData([options])​

  • options Object (opcional)
    • origin string (optional) - Should follow window.location.origin’s representation scheme://host:port.
    • storages string[] (optional) - The types of storages to clear, can be cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage. If not specified, clear all storage types.
    • quotas string[] (optional) - The types of quotas to clear, can be temporary, syncable. If not specified, clear all quotas.

Devuelve Promise<void> - Se resuelve cuando los datos del almacenamiento ha sido borrado.

ses.flushStorageData()​

Escribe cualquier dato DOMStorage que no lo haya sido en disco.

ses.setProxy(config)​

Devuelve Promise<void> - Se resuelve cuando el proceso de configuración del proxy está completo.

Configurar proxy.

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])​

  • host string - Hostname to resolve.
  • options Object (opcional)
    • queryType string (optional) - Requested DNS query type. If unspecified, resolver will pick A or AAAA (or both) based on IPv4/IPv6 settings:
      • A - Fetch only A records
      • AAAA - Fetch only AAAA records.
    • source string (optional) - The source to use for resolved addresses. Default allows the resolver to pick an appropriate source. Only affects use of big external sources (e.g. calling the system for resolution or using DNS). Even if a source is specified, results can still come from cache, resolving "localhost" or IP literals, etc. Uno de los siguiente valores:
      • any (default) - Resolver will pick an appropriate source. Results could come from DNS, MulticastDNS, HOSTS file, etc
      • system - Results will only be retrieved from the system or OS, e.g. via the getaddrinfo() system call
      • dns - Results will only come from DNS queries
      • mdns - Results will only come from Multicast DNS queries
      • localOnly - No external sources will be used. Results will only come from fast local sources that are available no matter the source setting, e.g. cache, hosts file, IP literal resolution, etc.
    • cacheUsage string (optional) - Indicates what DNS cache entries, if any, can be used to provide a response. Uno de los siguiente valores:
      • allowed (default) - Results may come from the host cache if non-stale
      • staleAllowed - Results may come from the host cache even if stale (by expiration or network changes)
      • disallowed - Results will not come from the host cache.
    • secureDnsPolicy string (optional) - Controls the resolver's Secure DNS behavior for this request. Uno de los siguiente valores:
      • allow (default)
      • disable

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

ses.resolveProxy(url)​

  • url URL

Devuelve Promise<string> - Se resuelve con la información del proxy para 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)​

  • ruta cadena - la ubicación de descarga.

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

ses.enableNetworkEmulation(options)​

  • options Object
    • offline boolean (optional) - Whether to emulate network outage. Por defecto es falso.
    • latency Double (optional) - RTT in ms. Defaults to 0 which will disable latency throttling.
    • downloadThroughput Double (optional) - Download rate in Bps. Defaults to 0 which will disable download throttling.
    • uploadThroughput Double (optional) - Upload rate in Bps. Defaults to 0 which will disable upload throttling.

Emula la red con la configuración dada por la sesión.

const win = new BrowserWindow()

// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
win.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})

// Para emular la caída de la red.
win.webContents.session.enableNetworkEmulation({ offline: true })

ses.preconnect(options)​

  • options Object
    • url string - URL for preconnect. Only the origin is relevant for opening the socket.
    • numSockets number (optional) - number of sockets to preconnect. Must be between 1 and 6. Defaults to 1.

Preconecta el número dado de sockets a un origen.

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.

Ejemplo:

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

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

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

Limitaciones:

  • net.fetch() does not support the data: or blob: schemes.
  • The value of the integrity option is ignored.
  • The .type and .url values of the returned Response object are incorrect.

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)​

  • proc Function | null
    • Objeto request
      • hostname string
      • certificate Certificate
      • validatedCertificate Certificate
      • isIssuedByKnownRoot boolean - true if Chromium recognises the root CA as a standard root. If it isn't then it's probably the case that this certificate was generated by a MITM proxy whose root has been installed locally (for example, by a corporate proxy). No podrás confiar en el resultado si el verificationResult no aparece como OK.
      • verificationResult string - OK if the certificate is trusted, otherwise an error like CERT_REVOKED.
      • errorCode Integer - Código de error.
    • callback Function
      • verificationResult Integer - Value can be one of certificate error codes from here. Apart from the certificate error codes, the following special codes can be used.
        • 0 - Indica éxito y deshabilita la verificación Certificate Transparency.
        • -2 - Indica falla.
        • -3 - Usa el resultado de verificación de chromium.

Establece el certificado de verificar proc de la sesión, el proc será cancelada con proc(request, callback) cuando sea solicitado una verificación del certificado del servidor. Llamando callback(0) se acepta el certificado, llamando callback(-2) se rechaza.

Llamando setCertificateVerifyProc(null) se reveritrá la verificación de certificado por defecto.

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)​

  • handler Function | null
    • contenido web contenido web - contenido web solicitando el permiso. Por favor, tenga en cuenta que si la solicitud viene de un subframe debe utilizar requestUrl para comprobar el origen de la solicitud.
    • permission string - The type of requested permission.
      • clipboard-read - Request access to read from the clipboard.
      • clipboard-sanitized-write - Request access to write to the clipboard.
      • display-capture - Request access to capture the screen via the Screen Capture API.
      • fullscreen - Request control of the app's fullscreen state via the Fullscreen API.
      • geolocation - Request access to the user's location via the Geolocation API
      • idle-detection - Request access to the user's idle state via the IdleDetector API.
      • media - Request access to media devices such as camera, microphone and speakers.
      • mediaKeySystem - Request access to DRM protected content.
      • midi - Request MIDI access in the Web MIDI API.
      • midiSysex - Request the use of system exclusive messages in the Web MIDI API.
      • notifications - Request notification creation and the ability to display them in the user's system tray using the Notifications API
      • pointerLock - Request to directly interpret mouse movements as an input method via the Pointer Lock API. These requests always appear to originate from the main frame.
      • keyboardLock - Request capture of keypresses for any or all of the keys on the physical keyboard via the Keyboard Lock API. These requests always appear to originate from the main frame.
      • openExternal - Request to open links in external applications.
      • speaker-selection - Request to enumerate and select audio output devices via the speaker-selection permissions policy.
      • storage-access - Allows content loaded in a third-party context to request access to third-party cookies using the Storage Access API.
      • top-level-storage-access - Allow top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same related website set using the Storage Access API.
      • window-management - Request access to enumerate screens using the getScreenDetails API.
      • unknown - Una solicitud de premiso no reconocida.
      • fileSystem - Request access to read, write, and file management capabilities using the File System API.
    • callback Function
      • permiso concedido booleano - Permiso o denegado de permiso.
    • details PermissionRequest | FilesystemPermissionRequest | MediaAccessPermissionRequest | OpenExternalPermissionRequest - Additional information about the permission being requested.

Configurar el controlador que será usado para responder las peticiones de permisos para la sesión. Llamando callback(true) se permitirá el permiso y callback(false) se rechazará. Para limpiar el manejador, llamar a setPermissionRequestHandler(null). Por favor, tenga en cuenta que debe implementar también setPermissionCheckHandler para obtener el manejo completo de los permisos. La mayoría de las APIs web hacen una verificación de permiso y luego hacen una solicitud de permiso si la verificación es denegada.

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

  callback(true)
})

ses.setPermissionCheckHandler(handler)​

  • handler Function<boolean> | null
    • webContents (WebContents | null) - WebContents verificando el permiso. Por favor, tenga en cuenta que si la solicitud viene de un subframe debe utilizar requestUrl para comprobar el origen de la solicitud. Todos los sub frames de origen cruzado que realizan comprobaciones de permisos pasarán un webContents null a este controlador, mientras que otras comprobaciones de permisos, como notifications siempre pasarán null. Debería usar embeddingOrigin y requestingOrigin para determinar que origen se encuentra en el marco propietario y en el marco solicitante respectivamente.
    • permission string - Type of permission check.
      • clipboard-read - Request access to read from the clipboard.
      • clipboard-sanitized-write - Request access to write to the clipboard.
      • geolocation - Access the user's geolocation data via the Geolocation API
      • fullscreen - Control of the app's fullscreen state via the Fullscreen API.
      • hid - Access the HID protocol to manipulate HID devices via the WebHID API.
      • idle-detection - Access the user's idle state via the IdleDetector API.
      • media - Access to media devices such as camera, microphone and speakers.
      • mediaKeySystem - Access to DRM protected content.
      • midi - Enable MIDI access in the Web MIDI API.
      • midiSysex - Use system exclusive messages in the Web MIDI API.
      • notifications - Configure and display desktop notifications to the user with the Notifications API.
      • openExternal - Open links in external applications.
      • pointerLock - Directly interpret mouse movements as an input method via the Pointer Lock API. These requests always appear to originate from the main frame.
      • serial - Read from and write to serial devices with the Web Serial API.
      • storage-access - Allows content loaded in a third-party context to request access to third-party cookies using the Storage Access API.
      • top-level-storage-access - Allow top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same related website set using the Storage Access API.
      • usb - Expose non-standard Universal Serial Bus (USB) compatible devices services to the web with the WebUSB API.
    • requestingOrigin string - La URL de origen para la comprobación de permisos
    • details Object - Some properties are only available on certain permission types.
      • embeddingOrigin string (opcional) - El origen del marco que incrusta el marco que hizo la verificación de permisos. Sólo se establece cross-origin submarcos haciendo comprobaciones de permisos.
      • securityOrigin string (opcional) - El origen de seguridad de la comprobación media.
      • mediaType string (opcional) - El tipo de acceso a los medios que se solicita puede ser video, audio o unknown
      • requestingUrl string (opcional) - La última URL que representa el marco cargado. Esto no es proveído para cross-origin submarcos haciendo comprobaciones de permiso.
      • isMainFrame boolean - Si el marco que realiza la solicitud es el marco principal

Establece el manejador que puede ser usado para responder a las comprobaciones para session. Retornando true permitirá el permiso y false lo rechará. Por favor, tenga en cuenta que debe implementar también setPermissionRequestHandler para obtener el manejo completo de los permisos. La mayoría de las APIs web hacen una verificación de permiso y luego hacen una solicitud de permiso si la verificación es denegada. Para borrar el manejador, llame 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 // concedido
  }

  return false // denegado
})

ses.setDisplayMediaRequestHandler(handler)​

  • handler Function | null
    • Objeto request
      • frame WebFrameMain - Frame that is requesting access to media.
      • securityOrigin String - Origin of the page making the request.
      • videoRequested Boolean - true if the web content requested a video stream.
      • audioRequested Boolean - true if the web content requested an audio stream.
      • userGesture Boolean - Whether a user gesture was active when this request was triggered.
    • callback Function
      • Objeto streams
        • video Object | WebFrameMain (optional)
          • id String - The id of the stream being granted. This will usually come from a DesktopCapturerSource object.
          • name String - The name of the stream being granted. This will usually come from a DesktopCapturerSource object.
        • audio String | WebFrameMain (optional) - If a string is specified, can be loopback or loopbackWithMute. Specifying a loopback device will capture system audio, and is currently only supported on Windows. If a WebFrameMain is specified, will capture audio from that frame.
        • enableLocalEcho Boolean (optional) - If audio is a WebFrameMain and this is set to true, then local playback of audio will not be muted (e.g. using MediaRecorder to record WebFrameMain with this flag set to true will allow audio to pass through to the speakers while recording). Por defecto es false.

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.

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] })
  })
})

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) => {
  // Allow the tab to capture itself.
  callback({ video: request.frame })
})

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

ses.setDevicePermissionHandler(handler)​

  • handler Function<boolean> | null
    • details Object
      • deviceType string - The type of device that permission is being requested on, can be hid, serial, or usb.
      • origin string - La URL de origen de verificación del permiso del dispositivo.
      • device HIDDevice | SerialPort | USBDevice - the device that permission is being requested for.

Establece el manejador que puede ser usado para responder a las comprobaciones de permiso para la session. Devolver true permitirá que el dispositivo se permitido y false lo rechazará. Para borrar el manejador, llame a setDevicePermissionHandler(null). Este manejador puede ser usado para otorgar permisos por defecto a dispositivos sin solicitar primero el permiso a dispositivos (por ejemplo a través de navigator.hid.requestDevice). Si este manejador no esta definido, los permisos por defecto para el dispositivo serán otorgados a través de la selección de dispositivo (por ejemplo a través de navigator.hid.requestDevice). Additionally, the default behavior of Electron is to store granted device permission in memory. Si se es necesario almacenarlo a más largo plazo, un desarrollador puede almacenar los permisos otorgados (por ejemplo, cuando se maneja el evento select-hid-device) y luego leerlo desde ese almacenamiento con 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') {
      // Add logic here to determine if permission should be given to allow HID selection
      return true
    } else if (permission === 'serial') {
      // Add logic here to determine if permission should be given to allow serial port selection
    } else if (permission === 'usb') {
      // Add logic here to determine if permission should be given to allow USB device selection
    }
    return false
  })

  // Optionally, retrieve previously persisted devices from a persistent store
  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) {
        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
        return true
      }

      // Search through the list of devices that have previously been granted permission
      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) {
        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
        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)​

  • handler Function<string[]> | null
    • details Object
      • protectedClasses string[] - The current list of protected USB classes. Possible class values include:
        • audio
        • audio-video
        • hid
        • mass-storage
        • smart-card
        • video
        • wireless

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:

  • audio
  • audio-video
  • hid
  • mass-storage
  • smart-card
  • video
  • wireless

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) => {
    // 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
    })
  })
})

ses.setBluetoothPairingHandler(handler) Windows Linux​

  • handler Function | null
    • details Object
      • deviceId string
      • pairingKind string - The type of pairing prompt being requested. Uno de los siguiente valores:
        • confirm This prompt is requesting confirmation that the Bluetooth device should be paired.
        • confirmPin This prompt is requesting confirmation that the provided PIN matches the pin displayed on the device.
        • providePin This prompt is requesting that a pin be provided for the device.
      • frame WebFrameMain
      • pin string (optional) - The pin value to verify if pairingKind is confirmPin.
    • callback Function
      • response Object
        • confirmed boolean - false should be passed in if the dialog is canceled. If the pairingKind is confirm or confirmPin, this value should indicate if the pairing is confirmed. If the pairingKind is providePin the value should be true when a value is provided.
        • pin string | null (optional) - When the pairingKind is providePin this value should be the required pin for the Bluetooth device.

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
    // Send a IPC message to the renderer to prompt the user to confirm the pairing.
    // Note that this will require logic in the renderer to handle this message and
    // display a prompt to the user.
    mainWindow.webContents.send('bluetooth-pairing-request', details)
  })

  // Listen for an IPC message from the renderer to get the response for the Bluetooth pairing.
  mainWindow.webContents.ipc.on('bluetooth-pairing-response', (event, response) => {
    bluetoothPinCallback(response)
  })
}

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

ses.clearHostResolverCache()​

Devuelve Promise<void> - Se resuelve cuando la operación es completada.

Borra la caché de resolución de host.

ses.allowNTLMCredentialsForDomains(domains)​

  • domains string - A comma-separated list of servers for which integrated authentication is enabled.

Configura dinámicamente cada vez que se envíen credenciales para HTTP NTLM o negociaciones de autenticación.

const { session } = require('electron')
// consider any url ending with `example.com`, `foobar.com`, `baz`
// for integrated authentication.
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')

// considera todas las Urls para autenticación integrada.
session.defaultSession.allowNTLMCredentialsForDomains('*')

ses.setUserAgent(userAgent[, acceptLanguages])​

  • userAgent cadena
  • lenguajes aceptados cadena (opcional)

Reemplaza el userAgent y los lenguajes aceptados para esta sesión.

Los lenguajes aceptados deben estar ordenados en una lista separada por coma de códigos de lenguaje, por ejemplo "en-US,fr,de,ko,zh-CN,ja".

Esto no afecta el contenido web existente, y cada contenido web puede usar webContents.setUserAgent para sobreescribir el agente de sesión de usuario.

ses.isPersistent()​

Devuelve boolean - Si la sesión es persistente o no. 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)​

  • Objeto config
    • minVersion string (opcional) - Puede ser tls1, tls1.1, tls1.2 o tls1.3. The minimum SSL version to allow when connecting to remote servers. Por defecto a tls1.
    • maxVersion string (opcional) - Puede ser tls1.2 o tls1.3. The maximum SSL version to allow when connecting to remote servers. Por defecto es tls1.3.
    • disabledCipherSuites Integer[] (optional) - List of cipher suites which should be explicitly prevented from being used in addition to those disabled by the net built-in policy. Supported literal forms: 0xAABB, where AA is cipher_suite[0] and BB is cipher_suite[1], as defined in RFC 2246, Section 7.4.1.2. Unrecognized but parsable cipher suites in this form will not return an error. Ex: To disable TLS_RSA_WITH_RC4_128_MD5, specify 0x0004, while to disable TLS_ECDH_ECDSA_WITH_RC4_128_SHA, specify 0xC002. Note that TLSv1.3 ciphers cannot be disabled using this mechanism.

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)​

  • identificador cadena - UUID válido.

Devuelve Promise<Buffer> - Se resuelve con datos blob.

ses.downloadURL(url[, options])​

  • url string
  • options Object (opcional)
    • headers Record<string, string\> (optional) - HTTP request headers.

Inicia una descargar del recurso en url. La API generará un DownloadItem que puede ser accedido con el evento will-download.

Note: Esto no realiza ninguna comprobación de seguridad relacionada con la pagina de origen a diferencia de webContents.downloadURL.

ses.createInterruptedDownload(options)​

  • options Object
    • ruta cadena - ruta de acceso absoluta de la descarga.
    • Cadeba URL cadena[] - cadena de URL completa para la descarga.
    • mimeType cadena (opcional)
    • offset Entero - rango de inicio para la descarga.
    • longitud Entero - longitud total de la descarga.
    • lastModified string (opcional) - Último valor del encabezado modificado.
    • eTag string (opcional) - Valor ETag del encabezado.
    • Tiempo de inicio Doble (opcional) - Tiempo en que se inició la descarga en números de segundo desde epoch de UNIX.

Permite cancelar o interrumpir descargas de una Sesión previa. La API generará un elemento de descarga que puede ser accesado con el evento se descargará. El Elemento de descarga no tendrá ningún contenido web asociado con el y el estado inicial será interrumpido. La descarga empezará solo cuando la reanudación de la API sea llamada en el elemento descargado.

ses.clearAuthCache()​

Devuelve Promise<void> - resuelve cuando se ha borrado el caché de autenticación HTTP de la sesión.

ses.setPreloads(preloads)​

  • preloads string[] - Un array de ruta absoluta para precargar scripts

Agrega scripts que se ejecutarán en TODOS los contenidos web que están asociados con esta sesión justo antes de que se ejecuten los scripts de preload normales.

ses.getPreloads()​

Devuelve un array de rutas string[] para precargar guiones que han sido registrado.

ses.setCodeCachePath(path)​

  • path String - Absolute path to store the v8 generated JS code cache from the renderer.

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)​

  • options Object
    • urls String[] (optional) - An array of url 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.

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

ses.setSpellCheckerEnabled(enable)​

  • enable boolean

Sets whether to enable the builtin spell checker.

ses.isSpellCheckerEnabled()​

Returns boolean - Whether the builtin spell checker is enabled.

ses.setSpellCheckerLanguages(languages)​

  • languages string[] - Un array de códigos de idiomas para habilitar corrector ortográfico.

El corrector ortográfico integrado no detecta automáticamente en que idioma un usuario esta escribiendo. Para que el corrector ortográfico compruebe correctamente sus palabras, usted debe llamar a esta API con un array de códigos de idiomas. Usted puede obtener la lista de los códigos de idiomas soportados con la propiedad ses.availableSpellCheckerLanguages.

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

ses.getSpellCheckerLanguages()​

Devuelve string[] - Un array de códigos de idiomas para los que el corrector ortográfico esta habilitado. Si esta lista está vacía, el corrector ortográfico volverá a usar en-US. Por defecto al iniciar si esta lista de opción es una lista vacía Electron tratará de llenar esta opción con el locale actual del sistema operativo. Este configuración es persistente entre reinicios.

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)​

  • url string - Una URL base para Electron desde donde descargar los diccionarios hunspell.

Por defecto Electron descargará diccionarios hunspell desde la CDN de Chromium. Si usted quiere sobrescribir este comportamiento puede usar esta API para apuntar el descargador de diccionarios a su propia versión alojada de diccionarios hunspell. 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.

Si los archivos presentes en hunspell_dictionaries.zip están disponible en https://example.com/dictionaries/language-code.bdic entonces entonces debería llamar esta api con ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Por favor, tenga en cuenta la barra final. La URL a los diccionarios esta formada como ${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()​

Devuelve Promise<string[]> - Un array de todas las palabras en el diccionario personalizado de la aplicación. Resolves when the full dictionary is loaded from disk.

ses.addWordToSpellCheckerDictionary(word)​

  • word string - La palabra que desea agregar al diccionario

Devuelve boolean - Si la palabra fue correctamente escrita al diccionario personalizado. Esta API no funcionará en sesiones no persistentes (en-memoría).

Note: En macOS y Windows 10 esta palabra será escrita al diccionario personalizado del sistema operativo también

ses.removeWordFromSpellCheckerDictionary(word)​

  • word string - The word you want to remove from the dictionary

Devuelve boolean - Si la palabra fue eliminada con éxito del diccionario personalizado. Esta API no funcionará en sesiones no persistentes (en-memoría).

Note: On macOS and Windows 10 this word will be removed from the OS custom dictionary as well

ses.loadExtension(path[, options])​

  • path string - Path to a directory containing an unpacked Chrome extension
  • options Object (opcional)
    • allowFileAccess boolean - Si permitir que la extensión lea los archivos locales sobre el protocolo file:// e inyecte scripts contenido dentro de las páginas file://. Esto es necesario por ejemplo para cargar las extensiones devtools en las URLs file://. Por defecto es falso.

Devuelve Promise<Extension> - se resuelve cuando la extensión está cargada.

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. Vea el APIs de extensiones soportadas para más detalles sobre que es soportado.

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 is required to load the devtools extension on file:// URLs.
    { allowFileAccess: true }
  )
  // Note that in order to use the React DevTools extension, you'll need to
  // download and unzip a copy of the extension.
})

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

Nota: Esta API no puede ser llamada antes de que el evento ready del módulo de app sea emitido.

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

ses.removeExtension(extensionId)​

  • extensionId string - ID of extension to remove

Descarga una extensión.

Nota: Esta API no puede ser llamada antes de que el evento ready del módulo de app sea emitido.

ses.getExtension(extensionId)​

  • extensionId string - ID of extension to query

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

Nota: Esta API no puede ser llamada antes de que el evento ready del módulo de app sea emitido.

ses.getAllExtensions()​

Devuelve Extension[] - Una lista de todas las extensiones cargadas.

Nota: Esta API no puede ser llamada antes de que el evento ready del módulo de app sea emitido.

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.

Propiedades de la instancia​

Las siguientes propiedades están disponibles en instancias de Sesión:

ses.availableSpellCheckerLanguages SoloLectura​

Un array string[] que consiste en todos los idiomas conocidos disponibles para el corrector ortográfico. Proporcionar un código de lenguaje a la API setSpellCheckerLanguages que no este en este array resultará en un 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 SoloLectura​

Un objeto Cookies para esta sesión.

ses.serviceWorkers Readonly​

Un objeto ServiceWorkers para esta sesión.

ses.webRequest SoloLectura​

Un objeto WebRequest para esta sesión.

ses.protocol SoloLectura​

Un objeto Protocol para esta sesión.

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 SoloLectura​

Un objeto NetLog para esta sesión.

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

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