session
ブラウザーセッション、クッキー、キャッシュ、プロキシの設定などを管理します。
プロセス: Main
session
モジュールは、新しい session
オブジェクトを作成するのに使用できます。
WebContents
の session
プロパティ、または 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
戻り値 Session
- partition
文字列からの Session のインスタンス。 同じ partition
を持つ既存の session
が存在する場合は、それが返されます。 それ以外の場合は、options
で新しい session
インスタンスが作成されます。
partition
が persist:
始まりの場合、ページはアプリの全ページで利用可能な永続的なセッションを同じ partition
で使用します。 persist:
プレフィックスがない場合、ページは、インメモリセッションを使用します。 partition
が空の場合は、アプリのデフォルトのセッションが返されます。
options
で Session
を作成するには、以前に 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'
戻り値:
event
Eventitem
DownloadItemwebContents
WebContents
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'
戻り値:
event
Eventextension
Extension
拡張機能が読み込まれた後に発生します。 これは、拡張機能が "有効な" 拡張機能のセットに追加されるたびに発生します。 これは以下のものが含まれます。
Session.loadExtension
から拡張機能が読み込まれるとき。- 拡張機能が再読み込みされるとき。
- クラッシュによって。
- 拡張機能が要求したことで (
chrome.runtime.reload()
)。
イベント: 'extension-unloaded'
戻り値:
event
Eventextension
Extension
拡張機能が取り除かれた後に発生します。 これは Session.removeExtension
が呼ばれたときに発生します。
イベント: 'extension-ready'
戻り値:
event
Eventextension
Extension
拡張機能が読み込まれ、必要なブラウザの状態がすべて初期化され、拡張機能のバックグラウンドページの開始をサポートするようになった後に発生します。
イベント: 'preconnect'
戻り値:
event
EventpreconnectUrl
string - レンダラーによって事前接続に要求されている URL。allowCredentials
boolean - レンダラーが接続に資格情報を含めることを要求している場合は true です (詳細については、仕様 を参照してください)。
一般的に リソースヒント が原因で、レンダリングプロセスが URL への事前接続を要求したときに生成されます。
イベント: 'spellcheck-dictionary-initialized'
戻り値:
event
EventlanguageCode
string - 辞書ファイルの言語コード
hunspell 辞書ファイルの初期化に成功したときに発生します。 これはファイルをダウンロードした後に発生します。
イベント: 'spellcheck-dictionary-download-begin'
戻り値:
event
EventlanguageCode
string - 辞書ファイルの言語コード
hunspell 辞書ファイルのダウンロードが始まったときに発生します
イベント: 'spellcheck-dictionary-download-success'
戻り値:
event
EventlanguageCode
string - 辞書ファイルの言語コード
hunspell 辞書ファイルのダウンロードに成功したときに発生します
イベント: 'spellcheck-dictionary-download-failure'
戻り値:
event
EventlanguageCode
string - 辞書ファイルの言語コード
hunspell 辞書ファイルのダウンロードが失敗したときに発生します。 失敗の詳細は、netlog を収集してダウンロードリクエストを調べる必要があります。
イベント: 'select-hid-device'
戻り値:
event
Eventdetails
ObjectdeviceList
HIDDevice[]frame
WebFrameMain
callback
FunctiondeviceId
string | null (任意)
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'
戻り値:
event
Eventdetails
Objectdevice
HIDDevice[]frame
WebFrameMain
navigator.hid.requestDevice
が呼ばれた後や、select-hid-device
から呼ばれるコールバックが利用可能なる前に新しいデバイスが利用可能になると、select-hid-device
が発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、新しく追加されたデバイスで UI を更新するために使用することを意図しています。
イベント: 'hid-device-removed'
戻り値:
event
Eventdetails
Objectdevice
HIDDevice[]frame
WebFrameMain
navigator.hid.requestDevice
が呼ばれたときや、select-hid-device
のコールバックが呼ばれる前にデバイスが取り除かれた場合に、select-hid-device
が発生した後に発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、指定されたデバイスを取り除いて UI を更新するために使用することを意図しています。
イベント: 'hid-device-revoked'
戻り値:
event
Eventdetails
Objectdevice
HIDDevice[]origin
string (任意) - デバイスが失効したオリジンです。
HIDDevice.forget()
が呼ばれた後に発生します。 このイベントは、setDevicePermissionHandler
が使用されたときに権限の永続ストレージの維持に利用できます。
イベント: 'select-serial-port'
戻り値:
event
EventportList
SerialPort[]webContents
WebContentscallback
FunctionportId
string
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'
戻り値:
event
Eventport
SerialPortwebContents
WebContents
navigator.serial.requestPort
が呼ばれた後や、select-serial-port
から呼ばれるコールバックが利用可能なる前に新しいシリアルポートが利用可能になると、select-serial-port
が発生します。 このイベントは、UI でユーザーにポートの選択を求め、新しく追加されたポートで UI を更新するために使用することを意図しています。
イベント: 'serial-port-removed'
戻り値:
event
Eventport
SerialPortwebContents
WebContents
navigator.serial.requestPort
が呼ばれたときや、select-serial-port
のコールバックが呼ばれる前にシリアルポートが取り除かれた場合に、select-serial-port
が発生した後に発生します。 このイベントは、UI でユーザーにポートの選択を求め、指定されたポートを取り除いて UI を更新するために使用することを意図しています。
イベント: 'serial-port-revoked'
戻り値:
event
Eventdetails
Objectport
SerialPortframe
WebFrameMainorigin
string - デバイスが失効したオリジンです。
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'
戻り値:
event
Eventdetails
ObjectdeviceList
USBDevice[]frame
WebFrameMain
callback
FunctiondeviceId
string (任意)
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'
戻り値:
event
Eventdetails
Objectdevice
USBDeviceframe
WebFrameMain
navigator.usb.requestDevice
が呼ばれた後や、select-usb-device
から呼ばれるコールバックが利用可能なる前に新しいデバイスが利用可能になると、select-usb-device
が発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、新しく追加されたデバイスで UI を更新するために使用することを意図しています。
イベント: 'usb-device-removed'
戻り値:
event
Eventdetails
Objectdevice
USBDeviceframe
WebFrameMain
navigator.usb.requestDevice
が呼ばれたときや、select-usb-device
のコールバックが呼ばれる前にデバイスが取り除かれた場合に、select-usb-device
が発生した後に発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、指定されたデバイスを取り除いて UI を更新するために使用することを意図しています。
イベント: 'usb-device-revoked'
戻り値:
event
Eventdetails
Objectdevice
USBDevice[]origin
string (任意) - デバイスが失効したオリジンです。
USBDevice.forget()
が呼ばれた後に発生します。 このイベントは、setDevicePermissionHandler
が使用されたときに権限の永続ストレージの維持に利用できます。
インスタンスメソッド
Session
のインスタンスでは、以下のメソッドが利用できます。
ses.getCacheSize()
戻り値 Promise<Integer>
- バイト単位の、session の現在のキャッシュサイズ。
ses.clearCache()
戻り値 Promise<void>
- キャッシュクリア操作が完了すると実行されます。
セッションの HTTP キャッシュをクリアします。
ses.clearStorageData([options])
戻り値 Promise<void>
- ストレージデータがクリアされると実行されます。
ses.flushStorageData()
未書き込みの DOM ストレージのデータをディスクに書き込みます。
ses.setProxy(config)
config
Objectmode
string (任意) - そのプロキシのモード。direct
、auto_detect
、pac_script
、fixed_servers
、system
のうちの一つであるべきです。 指定しない場合は、他の指定オプションに基づいて自動決定されます。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
を指定せずに pacScript
とproxyRules
をどちらも一緒に指定した場合、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)
session
の指定された構成でネットワークをエミュレートします。
// 50kbps のスループットと 500ms の待ち時間で GPRS 接続をエミュレートする。
window.webContents.session.enableNetworkEmulation({
latency: 500,
downloadThroughput: 6400,
uploadThroughput: 6400
})
// ネットワークの停止をエミュレートする。
window.webContents.session.enableNetworkEmulation({ offline: true })
ses.preconnect(options)
指定された数のソケットをオリジンに事前接続します。
ses.closeAllConnections()
戻り値 Promise<void>
- すべての接続が閉じられた時に解決されます。
注: 現在フライト中のすべてのリクエストが終了/失敗します。
ses.disableNetworkEmulation()
session
に対して既にアクティブなネットワークエミュレーションを無効にします。 元のネットワーク構成にリセットします。
ses.setCertificateVerifyProc(proc)
proc
Function | nullrequest
Objecthostname
stringcertificate
CertificatevalidatedCertificate
CertificateisIssuedByKnownRoot
boolean - Chromium がルート CA を標準ルートとして認識している場合はtrue
です。 そうでない場合は、ローカルにインストールされた MITM プロキシ (企業のプロキシなど) のルートによってこの証明書が生成されている可能性があります。verificationResult
がOK
でない場合、信頼しないでください。verificationResult
string - 証明書が信頼されている場合はOK
に、さもなくばCERT_REVOKED
のようなエラーになります。errorCode
Integer - エラーコード。
callback
FunctionverificationResult
Integer - こちら の証明書エラーコードのうち一つの値を取ります。 証明書エラーコードの他に、以下の特殊コードを取ることがあります。0
- 成功を示し、証明書の透明性の検証を無効にします。-2
- 失敗を示します。-3
- Chromium からの認証結果を使用します。
session
の証明書検証プロセスを設定し、サーバー証明書の検証が要求されるたびにproc
を proc(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 | nullwebContents
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
FunctionpermissionGranted
boolean - 権限の許可か拒否.
details
Object - このプロパティの一部は、特定の権限タイプでのみ使用できます。externalURL
string (任意) -openExternal
リクエストの URL。securityOrigin
string (任意) -media
のリクエストでのセキュリティオリジン。mediaTypes
string[] (任意) - 要求されている、複数のメディアアクセスのタイプ。要素はvideo
かaudio
にできますrequestingUrl
string - リクエストしているフレームが読み込んだ最後の URLisMainFrame
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> | nullwebContents
(WebContents | null) - 権限を確認している WebContents リクエストがサブフレームからのものである場合、リクエストのオリジンを確認するためにはrequestingUrl
を使用する必要があることに注意してください。 すべてのクロスオリジンサブフレームによる権限の確認はハンドラの webContents にnull
が渡されますが、notifications
の確認のような、ある特定の権限の確認では常にnull
が渡されます。embeddingOrigin
とrequestingOrigin
を使用して、所有しているフレームと要求しているフレームがそれぞれどのオリジンにあるかを判断する必要があります。permission
string - 権限確認の種別。 有効な値はmidiSysex
,notifications
,geolocation
,media
,mediaKeySystem
,midi
,pointerLock
,fullscreen
,openExternal
,hid
,serial
,usb
のいずれかです。requestingOrigin
string - 権限チェックのオリジン URLdetails
Object - このプロパティの一部は、特定の権限タイプでのみ使用できます。embeddingOrigin
string (任意) - 権限の確認をしたフレームのオリジン。 権限の確認を行うクロスオリジンのサブフレームでのみ設定されます。securityOrigin
string (任意) -media
の確認でのセキュリティオリジン。mediaType
string (任意) - 要求されたメディアアクセスの型で、video
、audio
かunknown
になります。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 | nullrequest
Objectframe
WebFrameMain - メディアへのアクセスをリクエストしているフレームです。securityOrigin
String - リクエストしているページのオリジンです。videoRequested
Boolean - ウェブコンテンツが映像ストリームをリクエストしていると true です。audioRequested
Boolean - ウェブコンテンツが音声ストリームをリクエストしていると true です。userGesture
Boolean - リクエストがトリガされたときにユーザージェスチャが有効だったかどうかです。
callback
Functionstreams
オブジェクトvideo
Object | WebFrameMain (任意)id
String - 認可されたストリームの ID です。 これは大抵 DesktopCapturerSource オブジェクトに由来するものです。name
String - 認可されたストリームの名前です。 これは大抵 DesktopCapturerSource オブジェクトに由来するものです。
audio
String | WebFrameMain (任意) - 文字列が指定される場合は、loopback
かloopbackWithMute
のどちらかです。 ループバックデバイスを指定すると、システムオーディオをキャプチャできます。これは現在 Windows でのみサポートされています。 WebFrameMain が指定されている場合はそのフレームからの音声をキャプチャします。enableLocalEcho
Boolean (任意) -audio
が WebFrameMain 型で、このフラグがtrue
に設定されている場合、オーディオのローカル再生は消音されません (つまり、MediaRecorder
でWebFrameMain
を録音する際にこのフラグを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> | nulldetails
ObjectdeviceType
string - 許可が求められているデバイスのタイプで、hid
、serial
または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 | nulldetails
ObjectdeviceId
stringpairingKind
string - リクエストしているペアリングの確認の種類です。 以下の値のいずれかです。confirm
このプロンプトはその Bluetooth デバイスをペアリングするかどうか確認するものです。confirmPin
このプロンプトは指定された PIN がデバイス上に表示された PIN と一致するかどうか確認するものです。providePin
このプロンプトはデバイスに PIN の提供を要求するものです。
frame
WebFrameMainpin
string (任意) -pairingKind
がconfirmPin
のとき、検証する PIN の値です。
callback
Functionresponse
Objectconfirmed
boolean - ダイアログがキャンセルされたならば、false
が渡されます。pairingKind
がconfirm
やconfirmPin
であれば、この値はペアリングが承認されたことを示します。pairingKind
がprovidePin
の場合は、提供されているならばこの値はtrue
になります。pin
string | null (任意) -pairingKind
がprovidePin
のとき、この値は 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
stringacceptLanguages
string (任意)
このセッションの userAgent
と acceptLanguages
をオーバーライドします。
acceptLanguages
は、言語コードのカンマ区切りリスト (例: "en-US, fr, de, ko, zh-CN, ja"
) でなければなりません。
これは既存の WebContents
には影響しません。それぞれの WebContents
は webContents.setUserAgent
を使用してセッション全体のユーザーエージェントをオーバーライドできます。
ses.isPersistent()
戻り値 boolean
- このセッションが持続的なものであるかどうか。 BrowserWindow
のデフォルトの webContents
セッションは持続的です。 パーティションからセッションを作成する場合、persist:
で始まるセッションは持続化され、他のセッションは一時的なものになります。
ses.getUserAgent()
戻り値 string
- このセッションのユーザエージェント。
ses.setSSLConfig(config)
config
ObjectminVersion
string (任意) -tls1
、tls1.1
、tls1.2
、tls1.3
のいずれかにできます。 これはリモートサーバーに接続する際に許可する最小の SSL バージョンです。 省略値はtls1
です。maxVersion
string (任意) -tls1.2
かtls1.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)
以前の Session
からの、cancelled
または interrupted
なダウンロードの再開を許可します。 この API は、will-download イベントでアクセスできる DownloadItem を生成します。 DownloadItem はそれに関連付けられた WebContents
を持たず、初期状態は interrupted
です。 DownloadItem の resume
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)
戻り値 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.zip
が https://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 拡張機能を含んだディレクトリへのパス
戻り値 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)
})