メインコンテンツへ飛ぶ

session

ブラウザーセッション、クッキー、キャッシュ、プロキシの設定などを管理します。

プロセス: Main

session モジュールは、新しい session オブジェクトを作成するのに使用できます。

WebContentssession プロパティ、または session モジュールから、既存のページの 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())

メソッド

session モジュールには以下のメソッドがあります。

session.fromPartition(partition[, options])

  • partition string
  • options Object (任意)
    • cache boolean - キャッシュを有効にするかどうか。

戻り値 Session - partition 文字列からの Session のインスタンス。 同じ partition を持つ既存の session が存在する場合は、それが返されます。 それ以外の場合は、options で新しい session インスタンスが作成されます。

partitionpersist: 始まりの場合、ページはアプリの全ページで利用可能な永続的なセッションを同じ partition で使用します。 persist: プレフィックスがない場合、ページは、インメモリセッションを使用します。 partition が空の場合は、アプリのデフォルトのセッションが返されます。

optionsSession を作成するには、以前に partition との Session が使用されていないことを確認する必要があります。 既存の Session オブジェクトの options を変更する方法はありません。

プロパティ

session モジュールには以下のプロパティがあります。

session.defaultSession

アプリのデフォルトの Session オブジェクト。

クラス: Session

セッションのプロパティを取得し、設定します。

プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。

session モジュールでは、Session オブジェクトを作成できます。

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

インスタンスイベント

Session のインスタンスでは、以下のイベントが利用できます。

イベント: 'will-download'

戻り値:

Electron が webContents 内で item をダウンロードするときに発生します。

event.preventDefault() を呼び出すと、ダウンロードをキャンセルし、item はプロセスの次のティックから使用できなくなります。

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

イベント: 'extension-loaded'

戻り値:

拡張機能が読み込まれた後に発生します。 これは、拡張機能が "有効な" 拡張機能のセットに追加されるたびに発生します。 これは以下のものが含まれます。

  • Session.loadExtension から拡張機能が読み込まれるとき。
  • 拡張機能が再読み込みされるとき。

イベント: 'extension-unloaded'

戻り値:

拡張機能が取り除かれた後に発生します。 これは Session.removeExtension が呼ばれたときに発生します。

イベント: 'extension-ready'

戻り値:

拡張機能が読み込まれ、必要なブラウザの状態がすべて初期化され、拡張機能のバックグラウンドページの開始をサポートするようになった後に発生します。

イベント: 'preconnect'

戻り値:

  • event Event
  • preconnectUrl string - レンダラーによって事前接続に要求されている URL。
  • allowCredentials boolean - レンダラーが接続に資格情報を含めることを要求している場合は true です (詳細については、仕様 を参照してください)。

一般的に リソースヒント が原因で、レンダリングプロセスが URL への事前接続を要求したときに生成されます。

イベント: 'spellcheck-dictionary-initialized'

戻り値:

  • event Event
  • languageCode string - 辞書ファイルの言語コード

hunspell 辞書ファイルの初期化に成功したときに発生します。 これはファイルをダウンロードした後に発生します。

イベント: 'spellcheck-dictionary-download-begin'

戻り値:

  • event Event
  • languageCode string - 辞書ファイルの言語コード

hunspell 辞書ファイルのダウンロードが始まったときに発生します

イベント: 'spellcheck-dictionary-download-success'

戻り値:

  • event Event
  • languageCode string - 辞書ファイルの言語コード

hunspell 辞書ファイルのダウンロードに成功したときに発生します

イベント: 'spellcheck-dictionary-download-failure'

戻り値:

  • event Event
  • languageCode string - 辞書ファイルの言語コード

hunspell 辞書ファイルのダウンロードが失敗したときに発生します。 失敗の詳細は、netlog を収集してダウンロードリクエストを調べる必要があります。

イベント: 'select-hid-device'

戻り値:

navigator.hid.requestDevice の呼び出し時に HID デバイスを選択する必要がある場合に発生します。 callback は選択する deviceId で呼び出してください。callback に引数を渡さなければ、リクエストをキャンセルします。 また、ses.setPermissionCheckHandler(handler)ses.setDevicePermissionHandler(handler)` を使うことで、navigator.hid の権限をさらに管理できます。

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') {
// ここにロジックを追加して、HID の選択を許可すべきかどうか判断してください。
return true
}
return false
})

// 任意ですが、以前に永続化されたデバイスを永続化ストアから取得します。
const grantedDevices = fetchGrantedDevices()

win.webContents.session.setDevicePermissionHandler((details) => {
if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
if (details.device.vendorId === 123 && details.device.productId === 345) {
// この種類のデバイスを常に許可します (これにより、最初の `navigator.hid.requestDevice` の呼び出しをスキップできます)。
return true
}

// 過去に許可されたデバイスの一覧を検索します。
return grantedDevices.some((grantedDevice) => {
return grantedDevice.vendorId === details.device.vendorId &&
grantedDevice.productId === details.device.productId &&
grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
})
}
return false
})

win.webContents.session.on('select-hid-device', (event, details, callback) => {
event.preventDefault()
const selectedDevice = details.deviceList.find((device) => {
return device.vendorId === '9025' && device.productId === '67'
})
callback(selectedDevice?.deviceId)
})
})

イベント: 'hid-device-added'

戻り値:

navigator.hid.requestDevice が呼ばれた後や、select-hid-device から呼ばれるコールバックが利用可能なる前に新しいデバイスが利用可能になると、select-hid-device が発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、新しく追加されたデバイスで UI を更新するために使用することを意図しています。

イベント: 'hid-device-removed'

戻り値:

navigator.hid.requestDevice が呼ばれたときや、select-hid-device のコールバックが呼ばれる前にデバイスが取り除かれた場合に、select-hid-device が発生した後に発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、指定されたデバイスを取り除いて UI を更新するために使用することを意図しています。

イベント: 'hid-device-revoked'

戻り値:

  • event Event
  • details Object
    • device HIDDevice[]
    • origin string (任意) - デバイスが失効したオリジンです。

HIDDevice.forget() が呼ばれた後に発生します。 このイベントは、setDevicePermissionHandler が使用されたときに権限の永続ストレージの維持に利用できます。

イベント: 'select-serial-port'

戻り値:

navigator.serial.requestPort の呼び出し時にシリアルポートを選択する必要がある場合に発生します。 callback は選んだ portId で呼び出されなければなりません。空の文字列を callback に渡すとリクエストがキャンセルされます。 さらに、ses.setPermissionCheckHandler(handler)serial パーミッションで使用することで navigator.serial のパーミッションを管理できます。

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

let win = null

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

win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
if (permission === 'serial') {
// ここにロジックを追加して、シリアルの選択を許可すべきかどうか判断します
return true
}
return false
})

// 任意で、永続ストアから以前に永続化されたデバイスを取得します
const grantedDevices = fetchGrantedDevices()

win.webContents.session.setDevicePermissionHandler((details) => {
if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'serial') {
if (details.device.vendorId === 123 && details.device.productId === 345) {
// このタイプのデバイスを常に許可します (これにより最初の `navigator.serial.requestPort` の呼び出しを省略できます)
return true
}

// 過去に許可されたデバイスのリストを検索する
return grantedDevices.some((grantedDevice) => {
return grantedDevice.vendorId === details.device.vendorId &&
grantedDevice.productId === details.device.productId &&
grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
})
}
return false
})

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

イベント: 'serial-port-added'

戻り値:

navigator.serial.requestPort が呼ばれた後や、select-serial-port から呼ばれるコールバックが利用可能なる前に新しいシリアルポートが利用可能になると、select-serial-port が発生します。 このイベントは、UI でユーザーにポートの選択を求め、新しく追加されたポートで UI を更新するために使用することを意図しています。

イベント: 'serial-port-removed'

戻り値:

navigator.serial.requestPort が呼ばれたときや、select-serial-port のコールバックが呼ばれる前にシリアルポートが取り除かれた場合に、select-serial-port が発生した後に発生します。 このイベントは、UI でユーザーにポートの選択を求め、指定されたポートを取り除いて UI を更新するために使用することを意図しています。

イベント: 'serial-port-revoked'

戻り値:

  • event Event
  • details Object

SerialPort.forget() が呼ばれた後に発生します。 このイベントは、setDevicePermissionHandler が使用されたときに権限の永続ストレージの維持に利用できます。

// ブラウザープロセス
const { app, BrowserWindow } = require('electron')

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

win.webContents.session.on('serial-port-revoked', (event, details) => {
console.log(`Access revoked for serial device from origin ${details.origin}`)
})
})
// レンダラープロセス

const portConnect = async () => {
// ポートを要求します。
const port = await navigator.serial.requestPort()

// シリアルポートが開くまで待機します。
await port.open({ baudRate: 9600 })

// ...その後、シリアルポートへのアクセスを失効します。
await port.forget()
}

イベント: 'select-usb-device'

戻り値:

navigator.usb.requestDevice の呼び出し時に USB デバイスを選択する必要がある場合に発生します。 callback は選択する deviceId で呼び出してください。callback に引数を渡さなければ、リクエストをキャンセルします。 また、ses.setPermissionCheckHandler(handler)ses.setDevicePermissionHandler(handler)` を使うことで、navigator.usb の権限をさらに管理できます。

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') {
// ここにロジックを追加して、USB の選択を許可すべきかどうかを判断してください。
return true
}
return false
})

// 任意ですが、以前に永続化されたデバイスを永続化ストアから取得します (永続化された権限の取得には、開発者が fetchGrantedDevices を実装する必要があります)。
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) {
// この種類のデバイスを常に許可します (これにより、最初の `navigator.usb.requestDevice` の呼び出しをスキップできます)。
return true
}

// 過去に許可されたデバイスの一覧を検索します
return grantedDevices.some((grantedDevice) => {
return grantedDevice.vendorId === details.device.vendorId &&
grantedDevice.productId === details.device.productId &&
grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
})
}
return false
})

win.webContents.session.on('select-usb-device', (event, details, callback) => {
event.preventDefault()
const selectedDevice = details.deviceList.find((device) => {
return device.vendorId === '9025' && device.productId === '67'
})
if (selectedDevice) {
// 任意ですが、これを永続化されたデバイスとして追加します (パーミッションの永続化には、開発者が updateGrantedDevices を実装する必要があります)。
grantedDevices.push(selectedDevice)
updateGrantedDevices(grantedDevices)
}
callback(selectedDevice?.deviceId)
})
})

イベント: 'usb-device-added'

戻り値:

navigator.usb.requestDevice が呼ばれた後や、select-usb-device から呼ばれるコールバックが利用可能なる前に新しいデバイスが利用可能になると、select-usb-device が発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、新しく追加されたデバイスで UI を更新するために使用することを意図しています。

イベント: 'usb-device-removed'

戻り値:

navigator.usb.requestDevice が呼ばれたときや、select-usb-device のコールバックが呼ばれる前にデバイスが取り除かれた場合に、select-usb-device が発生した後に発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、指定されたデバイスを取り除いて UI を更新するために使用することを意図しています。

イベント: 'usb-device-revoked'

戻り値:

  • event Event
  • details Object
    • device USBDevice[]
    • origin string (任意) - デバイスが失効したオリジンです。

USBDevice.forget() が呼ばれた後に発生します。 このイベントは、setDevicePermissionHandler が使用されたときに権限の永続ストレージの維持に利用できます。

インスタンスメソッド

Session のインスタンスでは、以下のメソッドが利用できます。

ses.getCacheSize()

戻り値 Promise<Integer> - バイト単位の、session の現在のキャッシュサイズ。

ses.clearCache()

戻り値 Promise<void> - キャッシュクリア操作が完了すると実行されます。

セッションの HTTP キャッシュをクリアします。

ses.clearStorageData([options])

  • options Object (任意)
    • origin string (任意) - window.location.origin の表記の scheme://host:port に従わなければいけません。
    • storages string[] (任意) - 消去するストレージの種別です。cookiesfilesystemindexdblocalstorageshadercachewebsqlserviceworkerscachestorage を含められます。 指定しない場合は、全種類のストレージをクリアします。
    • quotas string[] (任意) - 消去するクォータの種類。temporary, syncable を含められます。 指定しない場合は、全てのクオータをクリアします。

戻り値 Promise<void> - ストレージデータがクリアされると実行されます。

ses.flushStorageData()

未書き込みの DOM ストレージのデータをディスクに書き込みます。

ses.setProxy(config)

  • config Object
    • mode string (任意) - そのプロキシのモード。 directauto_detectpac_scriptfixed_serverssystem のうちの一つであるべきです。 指定しない場合は、他の指定オプションに基づいて自動決定されます。
      • direct direct モードでは、すべての接続はプロキシを介さずに直接作成されます。
      • auto_detect auto_detect モードでは、プロキシの設定は http://wpad/wpad.dat でダウンロードできる PAC スクリプトによって決定されます。
      • pac_script pac_script モードでは、プロキシの設定は pacScript で指定された URL から取得される PAC スクリプトによって決定されます。 これは pacScript が指定されている場合のデフォルトモードです。
      • fixed_servers fixed_servers モードでは、プロキシの設定を proxyRules で指定します。 これは proxyRules が指定されている場合のデフォルトモードです。
      • system system モードでは、プロキシ構成をオペレーティングシステムから取得します。 system モードはプロキシ構成を設定しない場合とは異なりますのでご注意ください。 後者の場合、プロキシ設定に影響を与えるコマンドラインオプションがない場合にのみ、 Electron はシステム設定にフォールバックします。
    • pacScript string (任意) - PAC ファイルに関連付けられた URL。
    • proxyRules string (任意) - 使用するプロキシを示すルール。
    • proxyBypassRules string (任意) - プロキシ設定をバイパスする URL を示すルール。

戻り値 Promise<void> - プロキシ設定処理が完了すると実行されます。

プロキシ設定を設定します。

mode を指定せずに pacScriptproxyRules をどちらも一緒に指定した場合、proxyRules は オプションは無視され pacScript の設定が適用されます。

以前のプロキシでプールされたソケットが将来のリクエストで再利用されるのを防ぐには、現在フライト中の接続を閉じるために ses.closeAllConnections が必要でしょう。

proxyRules は以下のルールに従う必要があります。

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

以下がその例です。

  • http=foopy:80;ftp=foopy2 - http:// URL には HTTP プロキシ foopy:80 を、ftp:// URL には HTTP プロキシ foopy2:80 を使用する。
  • foopy:80 - すべての URL に foopy:80 HTTP プロキシを使用する。
  • foopy:80,bar,direct:// - すべての URL に foopy:80 HTTP プロキシを使用する。 foopy:80 が使用できない場合は bar にフェイルオーバーし、その後はプロキシを使用しません。
  • socks4://foopy - すべての URL に SOCKS 4 プロキシ foopy:1080 を使用する。
  • http=foopy,socks5://bar.com - HTTP の URL には HTTP プロキシ foopy を使用し、foopy が使用できない場合は SOCKS 5 プロキシ bar.com にフェイルオーバーします。
  • http=foopy,socks5://bar.com - HTTP の URL には HTTP プロキシ foopy を使用し、foopy が使用できない場合はプロキシを使用しません。
  • http=foopy;socks=foopy2 - HTTP の URL には HTTP プロキシ foopy を、ほかの URLには socks4://foopy2 を使用します。

proxyBypassRules は以下に説明されているコンマ区切りのルールのリストです。

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

    HOSTNAME_PATTERN パターンに一致するすべてのホスト名のマッチ。

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

  • "." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]

    特定のドメインサフィックスのマッチ。

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

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

    IP アドレスリテラルである URL のマッチ。

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

  • IP_LITERAL "/" PREFIX_LENGTH_IN_BITS

    指定された範囲内の IP リテラルに一致する URL のマッチ。 IP の範囲は CIDR 表記で指定します。

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

  • <local>

    ローカルアドレスのマッチ。 <local> の意味は、ホストが "127.0.0.1"、"::1"、"localhost" のいずれかに一致するかどうかです。

ses.resolveProxy(url)

  • url URL

戻り値 Promise<string> - url のプロキシ情報で実行されます。

ses.forceReloadProxyConfig()

戻り値 Promise<void> - プロキシサービスのすべての内部状態がリセットされたときに解決します。すでに利用可能な場合は最新のプロキシ設定が再適用されます。 プロキシモードが pac_script の場合、再び pacScript から PAC スクリプトが取得されます。

ses.setDownloadPath(path)

  • path string - ダウンロード場所。

ダウンロードの保存ディレクトリを設定します。 デフォルトでは、ダウンロードディレクトリは各アプリフォルダの下の ダウンロード (Downloads) になります。

ses.enableNetworkEmulation(options)

  • options Object
    • offline boolean (任意) - ネットワークの停止をエミュレートするかどうか。 省略値は false です。
    • latency Double (任意) - RTT ミリ秒。 省略値は 0 で、このときレイテンシのスロットルは無効化されます。
    • downloadThroughput Double (任意) - 下りレート Bps。 省略値は 0 で、このときダウンロードのスロットルは無効化されます。
    • uploadThroughput Double (任意) - 上りレート Bps。 省略値は 0 で、このときアップロードのスロットルは無効化されます。

session の指定された構成でネットワークをエミュレートします。

// 50kbps のスループットと 500ms の待ち時間で GPRS 接続をエミュレートする。
window.webContents.session.enableNetworkEmulation({
latency: 500,
downloadThroughput: 6400,
uploadThroughput: 6400
})

// ネットワークの停止をエミュレートする。
window.webContents.session.enableNetworkEmulation({ offline: true })

ses.preconnect(options)

  • options Object
    • url string - 事前接続する URL。 ソケットの開通に関係しているのはオリジンのみです。
    • numSockets number (任意) - 事前接続するソケット数。 1 から 6 にしてください。 省略値は 1 です。

指定された数のソケットをオリジンに事前接続します。

ses.closeAllConnections()

戻り値 Promise<void> - すべての接続が閉じられた時に解決されます。

注: 現在フライト中のすべてのリクエストが終了/失敗します。

ses.disableNetworkEmulation()

session に対して既にアクティブなネットワークエミュレーションを無効にします。 元のネットワーク構成にリセットします。

ses.setCertificateVerifyProc(proc)

  • proc Function | null
    • request Object
      • hostname string
      • certificate Certificate
      • validatedCertificate Certificate
      • isIssuedByKnownRoot boolean - Chromium がルート CA を標準ルートとして認識している場合は true です。 そうでない場合は、ローカルにインストールされた MITM プロキシ (企業のプロキシなど) のルートによってこの証明書が生成されている可能性があります。 verificationResultOK でない場合、信頼しないでください。
      • verificationResult string - 証明書が信頼されている場合は OK に、さもなくば CERT_REVOKED のようなエラーになります。
      • errorCode Integer - エラーコード。
    • callback Function
      • verificationResult Integer - こちら の証明書エラーコードのうち一つの値を取ります。 証明書エラーコードの他に、以下の特殊コードを取ることがあります。
        • 0 - 成功を示し、証明書の透明性の検証を無効にします。
        • -2 - 失敗を示します。
        • -3 - Chromium からの認証結果を使用します。

session の証明書検証プロセスを設定し、サーバー証明書の検証が要求されるたびにprocproc(request, callback) で呼びます。 callback(0) を呼ぶと証明書を承認し、callback(-2) を呼ぶとそれを拒否します。

setCertificateVerifyProc(null) を呼び出すと、デフォルトの証明書検証プロシージャに戻ります。

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

注意: このプロシージャの結果は、ネットワークサービスによってキャッシュされます。

ses.setPermissionRequestHandler(handler)

  • handler Function | null
    • webContents WebContents - 権限を要求している WebContents。 リクエストがサブフレームからのものである場合、リクエストのオリジンを確認するためには requestingUrl を使用する必要があることに注意してください。
    • permission string - 要求されたパーミッションのタイプ。
      • clipboard-read - クリップボードからの読み取りアクセスを要求する。
      • clipboard-sanitized-write - クリップボードへの書き込みアクセスを要求します。
      • media - カメラ、マイク、スピーカーなどのメディアデバイスへのアクセスを要求する。
      • display-capture - 画面キャプチャへのアクセスをリクエストします。
      • mediaKeySystem - DRM で保護されたコンテンツへのアクセスを要求します。
      • geolocation - ユーザーの現在地へのアクセスを要求する。
      • notifications - 通知の作成とユーザーのシステムトレイに表示する機能を要求します。
      • midi - webmidi API で MIDI アクセスを要求します。
      • midiSysex - webmidi API でシステム専用メッセージの使用を要求する。
      • pointerLock - 入力方法としてマウスの動きを直接解釈するよう要求する。 詳細はこちら をクリックしてください。 これらのリクエストは、常にメインフレームから送信されているように見えます。
      • fullscreen - アプリがフルスクリーンモードになるよう要求する。
      • openExternal - 外部アプリケーションでリンクを開くように要求する。
      • window-management - getScreenDetails API を使用して画面をエミュレートするアクセスをリクエストします。
      • unknown - 認識されない認可リクエスト
    • callback Function
      • permissionGranted boolean - 権限の許可か拒否.
    • details Object - このプロパティの一部は、特定の権限タイプでのみ使用できます。
      • externalURL string (任意) - openExternal リクエストの URL。
      • securityOrigin string (任意) - media のリクエストでのセキュリティオリジン。
      • mediaTypes string[] (任意) - 要求されている、複数のメディアアクセスのタイプ。要素は videoaudio にできます
      • requestingUrl string - リクエストしているフレームが読み込んだ最後の URL
      • isMainFrame boolean - リクエストしたフレームがメインフレームかどうか

session の、権限の要求に応答するために使用できるハンドラを設定します。 callback(true) を呼ぶと権限が許可され callback(false) を呼ぶと拒否されます。 ハンドラをクリアするには、setPermissionRequestHandler(null) を呼びます。 注意として、完全な認可処理にするには setPermissionCheckHandler も実装しなければなりません。 ほとんどのウェブ API は権限の確認を行い、確認が拒否されている場合は認可のリクエストを行います。

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

callback(true)
})

ses.setPermissionCheckHandler(handler)

  • handler Function<boolean> | null
    • webContents (WebContents | null) - 権限を確認している WebContents リクエストがサブフレームからのものである場合、リクエストのオリジンを確認するためには requestingUrl を使用する必要があることに注意してください。 すべてのクロスオリジンサブフレームによる権限の確認はハンドラの webContents に null が渡されますが、notifications の確認のような、ある特定の権限の確認では常に null が渡されます。 embeddingOriginrequestingOrigin を使用して、所有しているフレームと要求しているフレームがそれぞれどのオリジンにあるかを判断する必要があります。
    • permission string - 権限確認の種別。 有効な値は midiSysex, notifications, geolocation, media, mediaKeySystem, midi, pointerLock, fullscreen, openExternal, hid, serial, usb のいずれかです。
    • requestingOrigin string - 権限チェックのオリジン URL
    • details Object - このプロパティの一部は、特定の権限タイプでのみ使用できます。
      • embeddingOrigin string (任意) - 権限の確認をしたフレームのオリジン。 権限の確認を行うクロスオリジンのサブフレームでのみ設定されます。
      • securityOrigin string (任意) - media の確認でのセキュリティオリジン。
      • mediaType string (任意) - 要求されたメディアアクセスの型で、videoaudiounknown になります。
      • requestingUrl string (任意) - リクエストしているフレームが読み込んだ最後の URL. 権限の確認を行うクロスオリジンのサブフレームでは提供されません。
      • isMainFrame boolean - リクエストしたフレームがメインフレームかどうか

session の、権限のチェックに応答するために使用できるハンドラを設定します。 trueを返すと権限を許可し、false を返すとそれを拒否します。 注意として、完全な認可処理にするには setPermissionRequestHandler も実装しなければなりません。 ほとんどのウェブ API は権限の確認を行い、確認が拒否されている場合は認可のリクエストを行います。 ハンドラをクリアするには、 setPermissionCheckHandler(null) を呼びます。

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

return false // 拒否
})

ses.setDisplayMediaRequestHandler(handler)

  • handler Function | null
    • request Object
      • frame WebFrameMain - メディアへのアクセスをリクエストしているフレームです。
      • securityOrigin String - リクエストしているページのオリジンです。
      • videoRequested Boolean - ウェブコンテンツが映像ストリームをリクエストしていると true です。
      • audioRequested Boolean - ウェブコンテンツが音声ストリームをリクエストしていると true です。
      • userGesture Boolean - リクエストがトリガされたときにユーザージェスチャが有効だったかどうかです。
    • callback Function
      • streamsオブジェクト
        • video Object | WebFrameMain (任意)
          • id String - 認可されたストリームの ID です。 これは大抵 DesktopCapturerSource オブジェクトに由来するものです。
          • name String - 認可されたストリームの名前です。 これは大抵 DesktopCapturerSource オブジェクトに由来するものです。
        • audio String | WebFrameMain (任意) - 文字列が指定される場合は、loopbackloopbackWithMute のどちらかです。 ループバックデバイスを指定すると、システムオーディオをキャプチャできます。これは現在 Windows でのみサポートされています。 WebFrameMain が指定されている場合はそのフレームからの音声をキャプチャします。
        • enableLocalEcho Boolean (任意) - audioWebFrameMain 型で、このフラグが true に設定されている場合、オーディオのローカル再生は消音されません (つまり、MediaRecorderWebFrameMain を録音する際にこのフラグを true に設定すると、録音中でもスピーカーへ音声が流れるようになります)。 省略値は false です。

このハンドラは、navigator.mediaDevices.getDisplayMedia API を通じてウェブコンテンツがディスプレイメディアへのアクセスを要求したときに呼び出されます。 desktopCapturer API を使用して、どのストリームへのアクセスを認可するのか選択してください。

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

session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
desktopCapturer.getSources({ types: ['screen'] }).then((sources) => {
// 最初に見つけた画面へのアクセスを認可します。
callback({ video: sources[0] })
})
})

WebFrameMain オブジェクトを映像または音声ストリームとして渡すと、そのフレームからの映像または音声をキャプチャします。

const { session } = require('electron')

session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
// タブに自身のキャプチャを許可します。
callback({ video: request.frame })
})

関数の代わりに null を渡すとハンドラはデフォルトの状態にリセットされます。

ses.setDevicePermissionHandler(handler)

  • handler Function<boolean> | null
    • details Object
      • deviceType string - 許可が求められているデバイスのタイプで、hidserial または usb になります。
      • origin string - デバイス権限チェックのオリジン URL。
      • device HIDDevice | SerialPort - 許可を求められているデバイス。

デバイスの権限チェックの応答に使用できるハンドラを session に設定します。 true を返すとデバイスに権限を許可し、false を返すとそれを拒否します。 ハンドラを消去するには setDevicePermissionHandler(null) と呼び出します。 このハンドラは、最初にデバイスへの許可の呼び出しを (navigator.hid.requestDevice などを介して) せずに、デバイスへのデフォルト権限を提供するために利用できます。 このハンドラが定義されていない場合、(navigator.hid.requestDevice などを介した) デバイスの選択において付与された権限をデフォルトのデバイス権限として使用します。 更に、Electron の既定の動作では付与されたデバイス権限をメモリに保持します。 より長期間の保存が必要な場合、開発者は付与されたデバイスのパーミッションを保存し (select-hid-device イベントを処理するときなど)、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') {
// ここにロジックを追加して、HID の選択を許可すべきかどうかを判断してください。
return true
} else if (permission === 'serial') {
// ここにロジックを追加して、シリアルポートの選択を許可すべきかどうかを判断してください。
} else if (permission === 'usb') {
// ここにロジックを追加して、USB デバイスの選択を許可すべきかどうかを判断してください。
}
return false
})

// 任意ですが、以前に永続化されたデバイスを永続化ストアから取得します。
const grantedDevices = fetchGrantedDevices()

win.webContents.session.setDevicePermissionHandler((details) => {
if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
if (details.device.vendorId === 123 && details.device.productId === 345) {
// この種類のデバイスを常に許可します (これにより最初の `navigator.hid.requestDevice` の呼び出しをスキップできます)。
return true
}

// 過去に許可されたデバイスの一覧を検索します
return grantedDevices.some((grantedDevice) => {
return grantedDevice.vendorId === details.device.vendorId &&
grantedDevice.productId === details.device.productId &&
grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
})
} else if (details.deviceType === 'serial') {
if (details.device.vendorId === 123 && details.device.productId === 345) {
// この種類のデバイスを常に許可します (これにより最初の `navigator.hid.requestDevice` の呼び出しをスキップできます)。
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
    • details Object
      • deviceId string
      • pairingKind string - リクエストしているペアリングの確認の種類です。 以下の値のいずれかです。
        • confirm このプロンプトはその Bluetooth デバイスをペアリングするかどうか確認するものです。
        • confirmPin このプロンプトは指定された PIN がデバイス上に表示された PIN と一致するかどうか確認するものです。
        • providePin このプロンプトはデバイスに PIN の提供を要求するものです。
      • frame WebFrameMain
      • pin string (任意) - pairingKindconfirmPin のとき、検証する PIN の値です。
    • callback Function
      • response Object
        • confirmed boolean - ダイアログがキャンセルされたならば、false が渡されます。 pairingKindconfirmconfirmPin であれば、この値はペアリングが承認されたことを示します。 pairingKindprovidePin の場合は、提供されているならばこの値は true になります。
        • pin string | null (任意) - pairingKindprovidePin のとき、この値は Bluetooth デバイスに必要な PIN になります。

Bluetooth のペアリング要求に応答するハンドラを設定します。 このハンドラにより、開発者はペアリングの前に追加の検証を必要とするデバイスを扱えます。 ハンドラが定義されていない場合、Linux や Windows 上での追加検証が必要なペアリングは自動キャンセルされます。 macOS は自動的にペアリングを行うため、macOS ではハンドラは不要です。 ハンドラを消去するには、setBluetoothPairingHandler(null) と呼び出してください。


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

let bluetoothPinCallback = null

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

// レンダラーからの IPC メッセージをリッスンして、Bluetooth ペアリングのレスポンスを取得します。
ipcMain.on('bluetooth-pairing-response', (event, response) => {
bluetoothPinCallback(response)
})

mainWindow.webContents.session.setBluetoothPairingHandler((details, callback) => {
bluetoothPinCallback = callback
// IPC メッセージをレンダラーに送信し、ユーザーにペアリングの確認を促します。
// 注意として、この場合このメッセージを処理してユーザーに確認する
// ロジックがレンダラーに必要です。
mainWindow.webContents.send('bluetooth-pairing-request', details)
})

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

ses.clearHostResolverCache()

戻り値 Promise<void> - 操作が完了すると実行されます。

ホスト解決のキャッシュをクリアします。

ses.allowNTLMCredentialsForDomains(domains)

  • domains string - 統合認証が有効であるサーバーのカンマ区切りのリスト。

HTTP NTLM またはネゴシエート認証の資格情報を常に送信するかどうかを動的に設定します。

const { session } = require('electron')
// 統合認証において、 `example.com`、`foobar.com`、`baz` で終わる
// URL を考えます。
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')

// 統合認証に、すべての URL を考えます。
session.defaultSession.allowNTLMCredentialsForDomains('*')

ses.setUserAgent(userAgent[, acceptLanguages])

  • userAgent string
  • acceptLanguages string (任意)

このセッションの userAgentacceptLanguages をオーバーライドします。

acceptLanguages は、言語コードのカンマ区切りリスト (例: "en-US, fr, de, ko, zh-CN, ja") でなければなりません。

これは既存の WebContents には影響しません。それぞれの WebContentswebContents.setUserAgent を使用してセッション全体のユーザーエージェントをオーバーライドできます。

ses.isPersistent()

戻り値 boolean - このセッションが持続的なものであるかどうか。 BrowserWindow のデフォルトの webContents セッションは持続的です。 パーティションからセッションを作成する場合、persist: で始まるセッションは持続化され、他のセッションは一時的なものになります。

ses.getUserAgent()

戻り値 string - このセッションのユーザエージェント。

ses.setSSLConfig(config)

  • config Object
    • minVersion string (任意) - tls1tls1.1tls1.2tls1.3 のいずれかにできます。 これはリモートサーバーに接続する際に許可する最小の SSL バージョンです。 省略値は tls1 です。
    • maxVersion string (任意) - tls1.2tls1.3 にできます。 これはリモートサーバーに接続する際に許可する最大の SSL バージョンです。 省略値は tls1.3 です。
    • disabledCipherSuites Integer[] (任意) - ネット組み込みポリシーで無効化されたものに加えて、使用を禁止すべき暗号スートを明示したリスト。 0xAABB のようなリテラルの形式をサポートしています。ここで AA は cipher_suite[0] であり、BB は cipher_suite[1] です。これは RFC 2246 のセクション 7.4.1.2 で定義されています。 識別不可かつパース可能な暗号スートの形式であっても、エラーは返しません。 例: TLS_RSA_WITH_RC4_128_MD5 を無効にするには、0x0004 を指定し、TLS_ECDSA_WITH_RC4_128_SHA を無効にするには 0xC002 を指定します。 注意として、TLSv1.3 の暗号化方式はこの仕組みで無効にできません。

セッションの SSL 構成を設定します。 それ以降のネットワークリクエストではすべて新しい構成を使用します。 既存のネットワーク接続 (WebSocket 接続など) は終了しませんが、プール内の古いソケットは新しい接続に再利用されません。

ses.getBlobData(identifier)

  • identifier string - 有効な UUID。

戻り値 Promise<Buffer> - blob データで実行されます。

ses.downloadURL(url)

  • url string

url にあるリソースのダウンロードを初期化します。 この API は、will-download イベントでアクセスできる DownloadItem を生成します。

注意: これは webContents.downloadURL と異なり、ページのオリジンに関連するセキュリティチェックを実行しません。

ses.createInterruptedDownload(options)

  • options Object
    • path string - ダウンロードの絶対パス。
    • urlChain string[] - ダウンロードの完全な URL チェーン。
    • mimeType string (任意)
    • offset Integer - ダウンロードの範囲の始端。
    • length Integer - ダウンロードの長さ。
    • lastModified string (任意) - ヘッダの最終更新日の値。
    • eTag string (任意) - ヘッダの ETag の値。
    • startTime Double (任意) - ダウンロードが開始されたときの UNIX エポックからの秒数。

以前の Session からの、cancelled または interrupted なダウンロードの再開を許可します。 この API は、will-download イベントでアクセスできる DownloadItem を生成します。 DownloadItem はそれに関連付けられた WebContents を持たず、初期状態は interrupted です。 DownloadItemresume API を呼ぶことでのみ、ダウンロードが始まります。

ses.clearAuthCache()

戻り値 Promise<void> - session の HTTP 認証キャッシュがクリアされると実行されます。

ses.setPreloads(preloads)

  • preloads string[] - プリロードスクリプトへの絶対パスの配列

通常の preload スクリプトが実行される直前に、このセッションに関連するすべてのウェブコンテンツで実行されるスクリプトを追加します。

ses.getPreloads()

戻り値 string[] - 登録されているプリロードスクリプトへのパスの配列。

ses.setCodeCachePath(path)

  • path String - レンダラーが v8 で生成された JS のコードキャッシュを格納する絶対パス。

このセッションで生成された JS の コードキャッシュ を保存するディレクトリを設定します。 このディレクトリは、呼び出し以前にユーザーが作成しておく必要はありません。ランタイムは、存在しない場合には作成し、そうでない場合は既存のディレクトリを使用します。 ディレクトリを作成できない場合、コードキャッシュは使用されず、コードキャッシュに関連するすべての操作はランタイム内でエラーを出さずに失敗します。 デフォルトでは、それぞれのユーザーデータフォルダー配下の Code Cache というディレクトリです。

ses.clearCodeCaches(options)

  • options Object
    • urls String[] (任意) - 生成されたコードキャッシュのうち削除する必要があるもののリソースに対応する URL の配列。 このリストが空の場合、キャッシュディレクトリのすべてのエントリが削除されます。

戻り値 Promise<void> - コードキャッシュの消去操作が完了すると解決されます。

ses.setSpellCheckerEnabled(enable)

  • enable boolean

組み込みスペルチェッカーを有効にするかどうかを設定します。

ses.isSpellCheckerEnabled()

戻り値 boolean - 組み込みスペルチェッカーが有効化されているかどうか。

ses.setSpellCheckerLanguages(languages)

  • languages string[] - スペルチェッカーを有効にする言語コードの配列。

組み込みスペルチェッカーは、ユーザーが入力している言語を自動的に検出しません。 スペルチェッカーが単語を正しくチェックするには、言語コードの配列でこの API を呼び出す必要があります。 ses.availableSpellCheckerLanguages プロパティで、サポートしている言語コードのリストを取得できます。

注: macOS では、OS のスペルチェッカーが使用されて言語が自動的に検出されます。 この API は、macOS では何もしません。

ses.getSpellCheckerLanguages()

戻り値 string[] - スペルチェッカーが有効になっている言語コードの配列。 このリストが空の場合、スペルチェッカーは en-US の使用へフォールバックします。 この設定が空のリストである場合、Electron は起動時に既定で現在の OS ロケールをこの設定に追加しようとします。 この設定は再起動後も持続します。

注意: macOS では、OS のスペルチェッカーが使用されて独自の言語リストを返します。 macOS の場合、この API は OS の設定言語を返します。

ses.setSpellCheckerDictionaryDownloadURL(url)

  • url string - Electron が hunspell 辞書をダウンロードする基底 URL。

デフォルトでは、Electron は Chromium CDN から hunspell 辞書をダウンロードします。 この動作をオーバーライドする場合は、この API を使用して、独自ホスト版の hunspell 辞書を辞書ダウンローダーが指すようにすることができます。 ホストに必要なファイルが入っている、各リリースの hunspell_dictionaries.zip ファイルをこちらで公開しています。

ファイルサーバーは 大文字小文字を区別してはいけません。 できない場合、各ファイルを 2 回アップロードする必要があります。1 回目はその ZIP ファイルの大文字小文字のままで、2 回目はファイル名をすべて小文字にしてアップロードしてください。

hunspell_dictionaries.ziphttps://example.com/dictionaries/language-code.bdic に存在して利用できる場合、ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/') を呼び出すことになります。 末尾のスラッシュに注意してください。 辞書への URL は、${url}${filename} の形式になります。

注: macOS では、OS のスペルチェッカーが使用されるため辞書ファイルをダウンロードしません。 この API は、macOS では何もしません。

ses.listWordsInSpellCheckerDictionary()

戻り値 Promise<string[]> - アプリのカスタム辞書の全単語の配列。 ディスクから完全な辞書が読み込まれたときに解決されます。

ses.addWordToSpellCheckerDictionary(word)

  • word string - 辞書に追加したい単語

戻り値 boolean - 単語がカスタム辞書に正常に書き込まれたかどうか。 この API は、持続的でない (一時的な) セッションでは動作しません。

注意: macOS と Windows 10 では、この単語は OS カスタム辞書にも書き込まれます

ses.removeWordFromSpellCheckerDictionary(word)

  • word string - 辞書から削除したい単語

戻り値 boolean - 単語がカスタム辞書から正常に削除されたかどうか。 この API は、持続的でない (一時的な) セッションでは動作しません。

注釈: macOS と Windows 10 では、この単語は OS カスタム辞書からも削除されます

ses.loadExtension(path[, options])

  • path string - 解凍されていない Chrome 拡張機能を含んだディレクトリへのパス
  • options Object (任意)
    • allowFileAccess boolean - 拡張機能が file:// プロトコルでローカルファイルを読み込んで file:// ページにコンテンツスクリプトを注入することを許可するかどうか。 これは、例えば file:// URL でデベロッパー ツール拡張機能を読み込むために必要です。 省略値は、false です。

戻り値 Promise<Extension> - 拡張機能が読み込まれたときに解決されます。

このメソッドは、拡張機能を読み込めなかった場合に例外を発生させます。 拡張機能のインストール時に警告が発生した場合 (Electron が未サポートの API を拡張機能が要求した場合など) は、コンソールにログが記録されます。

注意として、Electron は Chrome 拡張機能の API のすべてをサポートしていません。 サポート内容の詳細は サポートしている拡張機能 API をご参照ください。

注意として、以前のバージョンの Electron では、読み込まれた拡張機能は以降のアプリケーション実行のために記憶されます。 現在はそうなっていません。拡張機能を読み込みたい場合は、アプリを起動するたびに loadExtension を呼び出す必要があります。

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

app.on('ready', async () => {
await session.defaultSession.loadExtension(
path.join(__dirname, 'react-devtools'),
// allowFileAccess は、file:// URL でのデベロッパー ツール拡張機能の読み込みに必要です。
{ allowFileAccess: true }
)
// 注意として、React デベロッパー ツール拡張機能を使用するにはそのコピーを
// ダウンロードして解凍する必要があります。
})

この API は、パッケージした (.crx) 拡張機能の読み込みをサポートしていません。

注意: この API は app モジュールの ready イベントが発生する前には呼び出せません。

注: インメモリ (一時的な) セッションでの拡張機能読み込みはサポートされておらず、エラーが送出されます。

ses.removeExtension(extensionId)

  • extensionId string - 削除する拡張機能の ID

拡張機能を取り除きます。

注意: この API は app モジュールの ready イベントが発生する前には呼び出せません。

ses.getExtension(extensionId)

  • extensionId string - 取得する拡張機能の ID

戻り値 Extension | null - 指定した ID である読み込まれた拡張機能。

注意: この API は app モジュールの ready イベントが発生する前には呼び出せません。

ses.getAllExtensions()

戻り値 Extension[] - 読み込まれた拡張機能のリスト。

注意: この API は app モジュールの ready イベントが発生する前には呼び出せません。

ses.getStoragePath()

戻り値 string | null - このセッションのデータが保存されている、ディスク上のファイルシステムの絶対パスです。 インメモリセッションの場合、これは null を返します。

インスタンスプロパティ

Session のインスタンスには以下のプロパティがあります。

ses.availableSpellCheckerLanguages 読み出し専用

この string[] 配列は利用可能な既知のすべてのスペルチェッカー言語で構成されます。 この配列にない言語コードを setSpellCheckerLanguages API に提供すると、エラーが発生します。

ses.spellCheckerEnabled

boolean 型で、組み込みスペルチェッカーが有効かどうかを示します。

ses.storagePath 読み出し専用

string | null 型で、このセッションのデータが保存されているディスクのファイルシステムの絶対パスを示します。 インメモリセッションの場合、これは null を返します。

ses.cookies 読み出し専用

このセッションの Cookie オブジェクト。

ses.serviceWorkers 読み出し専用

このセッションの ServiceWorkers オブジェクト。

ses.webRequest 読み出し専用

このセッションの WebRequest オブジェクト。

ses.protocol 読み出し専用

このセッションの Protocol オブジェクト。

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 読み出し専用

このセッションの NetLog オブジェクト。

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

app.whenReady().then(async () => {
const netLog = session.fromPartition('some-partition').netLog
netLog.startLogging('/path/to/net-log')
// ネットワークイベントの後
const path = await netLog.stopLogging()
console.log('Net-logs written to', path)
})