Aller au contenu principal

session

Gère les sessions du navigateur, les cookies, le cache, les paramètres de proxy, etc.

Processus : Main

Le module session peut être utilisé pour créer des objets Session.

Vous pouvez également accéder à la session des pages existantes à l’aide de la propriété session des WebContents, ou le module session.

const { BrowserWindow } = require('electron')

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

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

Méthodes

Le module session dispose des méthodes suivantes :

session.fromPartition(partition[, options])

  • partition string
  • options Object (facultatif)
    • cache booléen - Indique si il faut activer le cache.

Retourne Session - Une instance de session de la chaîne de caractères partition. Quand il y a une Session existante avec la même partition, elle sera retournée; sinon une nouvelle instance Session sera créée avec options.

Si partition commence par persist:, la page utilisera une session persistante disponible pour toutes les pages de l'application avec la même partition. s'il n'y a pas de persist: préfixe, la page utilisera une session en mémoire. Si le partition est vide puis la session par défaut de l'application sera retournée.

Pour créer une Session avec options, vous devez vous assurer que la Session avec la partition n'a jamais été utilisée auparavant. Il n'y a pas moyen de changer les options d'un objet Session existant.

Propriétés

Le module session dispose des propriétés suivantes :

session.defaultSession

Un objet Session, l'objet d'une session par défaut de l'application.

Classe : Session

Les propriétés getter et setter d'une session.

Processus : Principal
Cette classe n'est pas exportée depuis le module 'electron'. Il n'est disponible qu'en tant que valeur de retour des autres méthodes dans l'API Electron.

Vous pouvez créer un objet Session avec le module session :

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

Événements d’instance

Les événements suivants sont disponibles pour les instances de Session :

Événement : 'will-download'

Retourne :

Émis lorsque Electron est sur le point de télécharger item dans webContents.

Faire appel à Event.preventDefault () annule le téléchargement et item ne sera pas disponible dans le battement suivant du processus.

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

Événement : 'extension-loaded'

Retourne :

Émis après le chargement d’une extension. Cela se produit chaque fois qu’une extension ajoutée à l’ensemble d’extensions « activées ». Ceci comprend :

  • Extensions chargées à partir session.loadExtension.
  • Extensions rechargées :

Événement : 'extension-unloaded'

Retourne :

Émis après le déchargement d’une extension. Cela se produit lorsque Session.removeExtension est appelée.

Événement : 'extension-ready'

Retourne :

Émis après le chargement d’une extension et l’initialisation de tout l’état du navigateur nécessaire pour prendre en charge le démarrage de la page d’arrière-plan de l’extension.

Événement : 'preconnect'

Retourne :

  • event 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.)

Émis lorsqu'un processus de rendu demande de préconnexion à une URL, généralement à cause de un hintressource .

Événement : 'spellcheck-dictionary-initialized'

Retourne :

  • event 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.

Événement : 'spellcheck-dictionary-download-begin'

Retourne :

  • event Event
  • languageCode string - Code de langue du fichier de dictionnaire

Émis lors du début de téléchargement d'un fichier de dictionnaire hunspell

Événement : 'spellcheck-dictionary-download-success'

Retourne :

  • event Event
  • languageCode string - Code de langue du fichier de dictionnaire

Émis lorsqu'un fichier de dictionnaire hunspell a été téléchargé avec succès

Événement : 'spellcheck-dictionary-download-failure'

Retourne :

  • event Event
  • languageCode string - Code de langue du fichier de dictionnaire

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

Événement : 'select-hid-device'

Retourne :

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') {
// Ajouter ici la logique pour déterminer si la permission d'autoriser le sélection HID doit être donnée
return true
}
return false
})

//Vous pouvez également récupérer des appareils précédemment persistants à //partir d’un store persistant
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) {
// Toujours autoriser ce type d'appareil (cela permet de se passer de l'appel à
//`navigator.hid.requestDevice` first)
return true
}

// Recherche parmis la liste des appareils à qui on a déja donné cette 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(selectedPort?.deviceId)
})
})

Événement : 'hid-device-added'

Retourne :

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.

Événement : 'hid-device-removed'

Retourne :

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.

Événement : 'hid-device-revoked'

Retourne :

  • event Event
  • Objet details
    • device HIDDevice[]
    • origin string (facultatif) - Origine à, partir de laquelle l’appareil a été révoqué.

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

Événement : 'select-serial-port'

Retourne :

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

Événement : 'serial-port-added'

Retourne :

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.

Événement : 'serial-port-removed'

Retourne :

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'

Retourne :

  • event Event
  • Objet details

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

// Processus de Navigateur
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}`)
})
})
// Processus de rendu

const portConnect = async () => {
// Demande un port.
const port = attendre navigator.serial.requestPort()

// Attente de l'ouverture du port série.
await port.open({ baudRate: 9600 })

// ...plus tard supprime l'acces au port série.
await port.forget()
}

Méthodes d’instance

Les méthodes suivantes sont disponibles pour les instances de Session :

ses.getCacheSize()

Retourne Promise<Integer> - la taille actuelle du cache de la session, en octets.

ses.clearCache()

Retourne Promise<void> - résout lorsque l'opération de nettoyage du cache est terminée.

Efface le cache HTTP de la session.

ses.clearStorageData([options])

  • options Object (facultatif)
    • origin string (optional) - Should follow window.location.origin’s representation scheme://host:port.
    • storages string[] (optional) - The types of storages to clear, can contain: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage. Si ce n'est pas spécifié, effacez tous les types de stockage.
    • quotas string[] (optional) - The types of quotas to clear, can contain: temporary, persistent, syncable. S'il n'est pas spécifié, effacez tous les quotas.

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

ses.flushStorageData()

Écrit toutes les données du DOMStorage non écrites sur le disque.

ses.setProxy(config)

  • config Object
    • mode string (optional) - The proxy mode. Should be one of direct, auto_detect, pac_script, fixed_servers or system. If it's unspecified, it will be automatically determined based on other specified options.
      • direct In direct mode all connections are created directly, without any proxy involved.
      • auto_detect In auto_detect mode the proxy configuration is determined by a PAC script that can be downloaded at http://wpad/wpad.dat.
      • pac_script In pac_script mode the proxy configuration is determined by a PAC script that is retrieved from the URL specified in the pacScript. C'est le mode par défaut si pacScript est spécifié.
      • fixed_servers En mode fixed_servers, la configuration du proxy est spécifiée dans proxyRules. Il s'agit du mode par défaut si proxyRules est spécifié.
      • system In system mode the proxy configuration is taken from the operating system. Note that the system mode is different from setting no proxy configuration. In the latter case, Electron falls back to the system settings only if no command-line options influence the proxy configuration.
    • pacScript string (optional) - The URL associated with the PAC file.
    • proxyRules string (optional) - Rules indicating which proxies to use.
    • proxyBypassRules string (optional) - Rules indicating which URLs should bypass the proxy settings.

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

Indique les paramètres de proxy.

When mode is unspecified, pacScript and proxyRules are provided together, the proxyRules option is ignored and pacScript configuration is applied.

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

Les proxyRules doivent suivre les règles ci-dessous :

proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]

Par exemple :

  • http=foopy:80;ftp=foopy2 - Use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.
  • foopy:80 - Use HTTP proxy foopy:80 for all URLs.
  • foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing over to bar if foopy:80 is unavailable, and after that using no proxy.
  • socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.
  • http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail over to the SOCKS5 proxy bar.com if foopy is unavailable.
  • http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no proxy if foopy is unavailable.
  • http=foopy;socks=foopy2 - Use HTTP proxy foopy for http URLs, and use socks4://foopy2 for all other URLs.

Le proxyBypassRules est une liste de règles séparées par des virgules, comme décrites ci-dessous :

  • [ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]

    Correspond à tous les noms d'hôte qui correspondent au pattern HOSTNAME_PATTERN.

    Examples: "foobar.com", "foobar.com", ".foobar.com", "foobar.com:99", "https://x..y.com:99"

  • "." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]

    Correspond à un suffixe de domaine particulier.

    Exemples: ".google.com", ".com", "http://.google.com"

  • [ SCHEME "://" ] IP_LITERAL [ ":" PORT ]

    Correspond aux URLs qui sont des adresses IP littérales.

    Exemples: "127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"

  • IP_LITERAL "/" PREFIX_LENGTH_IN_BITS

    Match any URL that is to an IP literal that falls between the given range. IP range is specified using CIDR notation.

    Exemples: "192.168.1.1/16", "fefe:13::abc/33".

  • <local>

    Match local addresses. The meaning of <local> is whether the host matches one of: "127.0.0.1", "::1", "localhost".

ses.resolveProxy(url)

  • url 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. Le script pac sera à nouveau extrait de pacScript si le mode proxy est pac_script.

ses.setDownloadPath(path)

  • path string - Emplacement du téléchargement.

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

ses.enableNetworkEmulation(options)

  • Objet options
    • offline boolean (optional) - Whether to emulate network outage. Defaults to false.
    • 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.

Emule le réseau avec la configuration donnée pour la session.

// Pour émuler une connexion GPRS avec un débit de 50kbps et une latence de 500 ms.
window.webContents.session.enableNetworkEmulation({
latency: 500,
downloadThroughput: 6400,
uploadThroughput: 6400
})

// Pour simuler une panne réseau.
window.webContents.session.enableNetworkEmulation({ offline: true })

ses.preconnect(options)

  • Objet options
    • 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. 1 par défaut.

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

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

ses.setCertificateVerifyProc(proc)

  • proc Function | null
    • request Object
      • 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). This should not be trusted if the verificationResult is not OK.
      • verificationResult string - OK if the certificate is trusted, otherwise an error like CERT_REVOKED.
      • errorCode Integer - Code d'erreur.
    • callback Function
      • verificationResult Entier - La valeur peut être l’un des codes d’erreur de certificat que l'on peut trouver ici. En dehors des codes d'erreur du certificat, les codes spéciaux suivants peuvent être utilisés.
        • 0 - Indique la réussite et désactive la vérification de transparence de certificat.
        • -2 - Indique l'échec.
        • -3 - Utilise le résultat de la vérification de Chromium.

Définit le proc de vérification du certificat pour session, le proc sera appelé avec proc(request, callback) chaque fois qu'une vérification de certificat de serveur est demandée. L'appel à callback(0) accepte le certificat, appeler callback(-2) le rejette.

L'appel à setCertificateVerifyProc(null) réinitialisera au proc de vérification du certificat par défaut.

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

REMARQUE : Le résultat de cette procédure est mis en cache par le service réseau.

ses.setPermissionRequestHandler(handler)

  • handler Function | null
    • webContents WebContents - WebContents qui demandent la permission. Veuillez noter que si la demande provient d'une sous-frame, vous devez utiliser requestingUrl pour vérifier l'origine de la demande.
    • permission string - Type d’autorisation demandée.
      • clipboard-read - Demande d'accès à la lecture depuis le presse-papiers.
      • média - Demande l'accès à des périphériques multimédia tels que la caméra, le microphone et les haut-parleurs.
      • display-capture - Demande d'accès pour capturer l'écran.
      • mediaKeysystem - Demande d’accès au contenu protégé par DRM.
      • geolocation - Demande d'accès à l'emplacement actuel de l'utilisateur.
      • notifications - Demande la création de notifications et la possibilité de les afficher dans la barre d’état système de l’utilisateur.
      • midi - Demande d'accès MIDI dans l'API webmidi.
      • midiSysex - Demande l'utilisation des messages exclusifs du système dans l'API webmidi.
      • pointerLock - Demande d'interpréter directement les mouvements de la souris comme une méthode de saisie. Cliquez ici pour en savoir plus. Ces requêtes semblent toujours provenir de la frame principale.
      • fullscreen - Demande de l'application pour passer en mode plein écran.
      • openExternal - Demande d’ouverture de liens dans des applications externes.
      • unknown - Une demande d’autorisation non reconnue
    • callback Function
      • permissionGranted booléen - Autoriser ou refuser la permission.
    • Objet details - Certaines propriétés ne sont disponibles que sur certains types de permissions.
      • externalURL string (facultatif) : Url de la demande de openExternal .
      • securityOrigin string (facultatif) - La source de sécurité de la requête media.
      • mediaTypes string[] (facultatif) - Types d'accès aux médias demandés, les éléments peuvent être video ou audio
      • requestingUrl string - La dernière URL chargée par la frame chargée
      • isMainFrame booléen - Indique sir la frame à l'origine de la requête est la frame principale

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. Pour effacer le gestionnaire, appelez 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) // interdit.
}

callback(true)
})

ses.setPermissionCheckHandler(handler)

  • handler Function<boolean> | null
    • webContents (WebContents | null) - WebContents demandant la permission. Veuillez noter que si la demande provient d'une sous-frame, vous devez utiliser requestingUrl pour vérifier l'origine de la demande. Toutes les frames de cross origin effectuant des vérifications de permission passeront un null webContents à ce gestionnaire, alors que certaines autres vérifications de permissions, telles que notifications , passeront toujours null. You should use embeddingOrigin and requestingOrigin to determine what origin the owning frame and the requesting frame are on respectively.
    • permission string - Type of permission check. Valid values are midiSysex, notifications, geolocation, media,mediaKeySystem,midi, pointerLock, fullscreen, openExternal, hid, or serial.
    • requestingOrigin string - The origin URL of the permission check
    • Objet details - Certaines propriétés ne sont disponibles que sur certains types de permissions.
      • embeddingOrigin string (optional) - The origin of the frame embedding the frame that made the permission check. Only set for cross-origin sub frames making permission checks.
      • securityOrigin string (optional) - The security origin of the media check.
      • mediaType string (optional) - The type of media access being requested, can be video, audio or unknown
      • requestingUrl string (optional) - The last URL the requesting frame loaded. This is not provided for cross-origin sub frames making permission checks.
      • isMainFrame booléen - Indique sir la frame à l'origine de la requête est la frame principale

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. Pour effacer le gestionnaire, appelez 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 // granted
}

return false // denied
})

ses.setDisplayMediaRequestHandler(handler)

  • handler Function | null
    • request Object
      • 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
      • Objet 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.

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
    • Objet details
      • deviceType string - Tpe de périphérique sur lequel la permission est demandée, peut être hid ou serial.
      • origin string - URL à l'origine de la demande de vérification d'autorisation du périphérique.
      • device HIDDevice | SerialPort- périphérique pour lequel l'autorisation est demandée.

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. Pour effacer le gestionnaire, appelez 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 permision 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') {
// 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
}
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(selectedPort?.deviceId)
})
})

ses.setBluetoothPairingHandler(handler) Windows Linux

  • handler Function | null
    • Objet details
      • deviceId string
      • pairingKind string - The type of pairing prompt being requested. Une des valeurs suivantes:
        • 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
      • Objet response
        • 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, ipcMain, session } = require('electron')

let bluetoothPinCallback = null

function createWindow () {
const mainWindow = new BrowserWindow({
webPreferences: {
preload: path. oin(__dirname, 'preload. s')
}
})
}

// Écoutez d'un message IPC du moteur de rendu pour obtenir la réponse pour le jumelage Bluetooth.
ipcMain.on('bluetooth-pairing-response', (event, response) => {
bluetoothPinCallback(response)
})

mainWindow.webContents.session.setBluetoothPairingHandler((details, callback) => {
bluetoothPinCallback = callback
// Send a IPC message to the renderer to prompt the user to confirm the pairing.
// Notez que cela nécessitera dans le moteur de rendu du code pour gérer ce message et
// l'affichage d'une invite à l'utilisateur.
mainWindow.webContents.send('bluetooth-pairing-request', details)
})

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

ses.clearHostResolverCache()

Retourne une Promise<void> - Elle se résout lorsque l'opération est terminée.

Vide le cache de résolution de l'hôte.

ses.allowNTLMCredentialsForDomains(domains)

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

Définit dynamiquement s'il faut toujours envoyer des identifiants pour l'authentification HTTP NTLM ou Négocier .

const { session } = require('electron')
// considère n'importe quelle url se terminant par `example.com`, `foobar.com`, `baz`
// pour une authentification intégrée.
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')

// considère toutes les urls pour une authentification intégrée.
session.defaultSession.allowNTLMCredentialsForDomains('*')

ses.setUserAgent(userAgent[, acceptLanguages])

  • userAgent string
  • acceptLanguages string (optional)

Remplace les userAgent et acceptLanguages pour cette session.

Le acceptLanguages doit être une liste ordonnée de codes de langue séparés par des virgules, pour exemple "en-US,fr,de,ko,zh-CN,ja".

Cela n'affecte pas les WebContents, et chaque WebContents peut utiliser webContents.setUserAgent pour remplacer l'agent utilisateur à l'échelle de la session.

ses.isPersistent()

Retourne boolean - Indique si cette session est persistante ou non. Par défaut, la session du webContents d'une BrowserWindow est persistante. Lors de la création d'une session à partir d'une partition, les sessions préfixées avec persist: seront persistantes, tandis que les autres seront temporaires.

ses.getUserAgent()

Returns string - The user agent for this session.

ses.setSSLConfig(config)

  • config Object
    • minVersion string (optional) - Can be tls1, tls1.1, tls1.2 or tls1.3. The minimum SSL version to allow when connecting to remote servers. Defaults to tls1.
    • maxVersion string (optional) - Can be tls1.2 or tls1.3. The maximum SSL version to allow when connecting to remote servers. Defaults to 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)

  • identifier string - Valid UUID.

Retourne Promise<Buffer> - résout avec des données Blob.

ses.downloadURL(url)

  • url string

Lance le téléchargement de la ressource située à l'url. L'API va générer un DownloadItem accessible par l'événement will-download .

Note: Ceci n'effectue aucune vérification de sécurité concernant l'origine d'une page, contrairement à webContents.downloadURL.

ses.createInterruptedDownload(options)

  • Objet options
    • path string - Absolute path of the download.
    • urlChain string[] - Complete URL chain for the download.
    • mimeType string (optional)
    • offset Integer - Portée de départ pour le téléchargement.
    • length Integer - Longueur totale du le téléchargement.
    • lastModified string (facultatif) - Valeur de l'en-tête Last-Modified.
    • eTag string (facultatif) - Valeur de l'en-tête ETag.
    • startTime Double (facultatif) - Heure du début de téléchargement, en nombre de secondes depuis la date initiale UNIX (1er janvier 1970 à 0 heure (UTC)).

Autorise la reprise des téléchargements annulés ou interrompus depuis la Sessionprécédente. 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()

Retourne Promise<void> - résout lorsque le cache d'authentification HTTP de la session a été effacé.

ses.setPreloads(preloads)

  • preloads string[] - An array of absolute path to preload scripts

Ajoute des scripts qui seront exécutés sur TOUS les contenus web qui sont associés à cette session juste avant l'exécution normale des scripts preload.

ses.getPreloads()

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

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.

ses.clearCodeCaches(options)

  • Objet options
    • urls String[] (optional) - An array of url corresponding to the resource whose generated code cache needs to be removed. Si la liste est vide, toutes les entrées du répertoire de cache seront supprimées.

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[] - An array of language codes to enable the spellchecker for.

Le correcteur orthographique intégré ne détecte pas automatiquement la langue dans laquelle un utilisateur tape. 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)

  • url string - A base URL for Electron to download hunspell dictionaries from.

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)

  • word string - The word you want to add to the dictionary

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 10 this word will be written to the OS custom dictionary as well

ses.removeWordFromSpellCheckerDictionary(word)

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

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 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 (facultatif)
    • allowFileAccess boolean - Whether to allow the extension to read local files over file:// protocol and inject content scripts into file:// pages. This is required e.g. for loading devtools extensions on file:// URLs. false par défaut.

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

Cette méthode déclenche une exception si l’extension n’a pas pu être chargée. 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('path')

app.on('ready', 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.

Remarque : Cette API ne peut pas être appelée avant que l'événement prêt du module app ne soit émis.

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

Unloads an extension.

Remarque : Cette API ne peut pas être appelée avant que l'événement prêt du module app ne soit émis.

ses.getExtension(extensionId)

  • extensionId string - ID of extension to query

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

Remarque : Cette API ne peut pas être appelée avant que l'événement prêt du module app ne soit émis.

ses.getAllExtensions()

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

Remarque : Cette API ne peut pas être appelée avant que l'événement prêt du module app ne soit émis.

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.

Propriétés d'instance

Les propriétés suivantes sont disponibles pour les instances de 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

Un objet Cookies pour cette session.

ses.serviceWorkers Readonly

Un objet ServiceWorkers pour cette session.

ses.webRequest Readonly

Un objet WebRequest pour cette session.

ses.protocol Readonly

Un objet Protocole pour cette session.

const { app, session } = require('electron')
const path = require('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(`${__dirname}/${url}`) })
})) {
console.error('Failed to register protocol')
}
})

ses.netLog Readonly

Un objet NetLog pour cette session.

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