session
The session
module can be used to create new Session
objects.
You can also access the session
of existing pages by using the session
property of webContents
which is a property of
BrowserWindow
.
const BrowserWindow = require('electron').BrowserWindow;
var win = new BrowserWindow({ width: 800, height: 600 });
win.loadURL("http://github.com");
var ses = win.webContents.session;
Methods
The session
module has the following methods:
session.fromPartition(partition)
partition
String
Returns a new Session
instance from partition
string.
If partition
starts with persist:
, the page will use a persistent session
available to all pages in the app with the same partition
. if there is no
persist:
prefix, the page will use an in-memory session. If the partition
is
empty then default session of the app will be returned.
Properties
The session
module has the following properties:
session.defaultSession
Returns the default session object of the app.
Class: Session
You can create a Session
object in the session
module:
const session = require('electron').session;
var ses = session.fromPartition('persist:name');
Instance Events
The following events are available on instances of Session
:
Event: 'will-download'
event
Eventitem
DownloadItemwebContents
WebContents
Emitted when Electron is about to download item
in webContents
.
Calling event.preventDefault()
will cancel the download.
session.defaultSession.on('will-download', function(event, item, webContents) {
event.preventDefault();
require('request')(item.getURL(), function(data) {
require('fs').writeFileSync('/somewhere', data);
});
});
Instance Methods
The following methods are available on instances of Session
:
ses.cookies
The cookies
gives you ability to query and modify cookies. For example:
// Query all cookies.
session.defaultSession.cookies.get({}, function(error, cookies) {
console.log(cookies);
});
// Query all cookies associated with a specific url.
session.defaultSession.cookies.get({ url : "http://www.github.com" }, function(error, cookies) {
console.log(cookies);
});
// Set a cookie with the given cookie data;
// may overwrite equivalent cookies if they exist.
var cookie = { url : "http://www.github.com", name : "dummy_name", value : "dummy" };
session.defaultSession.cookies.set(cookie, function(error) {
if (error)
console.error(error);
});
ses.cookies.get(filter, callback)
filter
Objecturl
String optional - Retrieves cookies which are associated withurl
. Empty implies retrieving cookies of all urls.name
String optional - Filters cookies by name.domain
String optional - Retrieves cookies whose domains match or are subdomains ofdomains
path
String optional - Retrieves cookies whose path matchespath
.secure
Boolean optional - Filters cookies by their Secure property.session
Boolean optional - Filters out session or persistent cookies.
callback
Function
Sends a request to get all cookies matching details
, callback
will be called
with callback(error, cookies)
on complete.
cookies
is an Array of cookie
objects.
cookie
Objectname
String - The name of the cookie.value
String - The value of the cookie.domain
String - The domain of the cookie.hostOnly
String - Whether the cookie is a host-only cookie.path
String - The path of the cookie.secure
Boolean - Whether the cookie is marked as secure.httpOnly
Boolean - Whether the cookie is marked as HTTP only.session
Boolean - Whether the cookie is a session cookie or a persistent cookie with an expiration date.expirationDate
Double optional - The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.
ses.cookies.set(details, callback)
details
Objecturl
String - Retrieves cookies which are associated withurl
name
String - The name of the cookie. Empty by default if omitted.value
String - The value of the cookie. Empty by default if omitted.domain
String - The domain of the cookie. Empty by default if omitted.path
String - The path of the cookie. Empty by default if omitted.secure
Boolean - Whether the cookie should be marked as Secure. Defaults to false.session
Boolean - Whether the cookie should be marked as HttpOnly. Defaults to false.expirationDate
Double - The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie.
callback
Function
Sets the cookie with details
, callback
will be called with callback(error)
on complete.
ses.cookies.remove(url, name, callback)
url
String - The URL associated with the cookie.name
String - The name of cookie to remove.callback
Function
Removes the cookies matching url
and name
, callback
will called with
callback()
on complete.
ses.clearCache(callback)
callback
Function - Called when operation is done
Clears the session’s HTTP cache.
ses.clearStorageData([options, ]callback)
options
Object (optional)origin
String - Should followwindow.location.origin
’s representationscheme://host:port
.storages
Array - The types of storages to clear, can contain:appcache
,cookies
,filesystem
,indexdb
,local storage
,shadercache
,websql
,serviceworkers
quotas
Array - The types of quotas to clear, can contain:temporary
,persistent
,syncable
.
callback
Function - Called when operation is done.
Clears the data of web storages.
ses.setProxy(config, callback)
config
Stringcallback
Function - Called when operation is done.
If config
is a PAC url, it is used directly otherwise
config
is parsed based on the following rules indicating which
proxies to use for the session.
config = scheme-proxies[";"<scheme-proxies>]
scheme-proxies = [<url-scheme>"="]<proxy-uri-list>
url-scheme = "http" | "https" | "ftp" | "socks"
proxy-uri-list = <proxy-uri>[","<proxy-uri-list>]
proxy-uri = [<proxy-scheme>"://"]<proxy-host>[":"<proxy-port>]
For example:
"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.
ses.resolveProxy(url, callback)
url
URLcallback
Function
Resolves the proxy information for url
. The callback
will be called with
callback(proxy)
when the request is performed.
ses.setDownloadPath(path)
path
String - The download location
Sets download saving directory. By default, the download directory will be the
Downloads
under the respective app folder.
ses.enableNetworkEmulation(options)
options
Objectoffline
Boolean - Whether to emulate network outage.latency
Double - RTT in msdownloadThroughput
Double - Download rate in BpsuploadThroughput
Double - Upload rate in Bps
Emulates network with the given configuration for the session
.
// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
window.webContents.session.enableNetworkEmulation({
latency: 500,
downloadThroughput: 6400,
uploadThroughput: 6400
});
// To emulate a network outage.
window.webContents.session.enableNetworkEmulation({offline: true});
ses.disableNetworkEmulation()
Disables any network emulation already active for the session
. Resets to
the original network configuration.
ses.setCertificateVerifyProc(proc)
proc
Function
Sets the certificate verify proc for session
, the proc
will be called with
proc(hostname, certificate, callback)
whenever a server certificate
verification is requested. Calling callback(true)
accepts the certificate,
calling callback(false)
rejects it.
Calling setCertificateVerifyProc(null)
will revert back to default certificate
verify proc.
myWindow.webContents.session.setCertificateVerifyProc(function(hostname, cert, callback) {
if (hostname == 'github.com')
callback(true);
else
callback(false);
});
ses.webRequest
The webRequest
API set allows to intercept and modify contents of a request at
various stages of its lifetime.
Each API accepts an optional filter
and a listener
, the listener
will be
called with listener(details)
when the API's event has happened, the details
is an object that describes the request. Passing null
as listener
will
unsubscribe from the event.
The filter
is an object that has an urls
property, which is an Array of URL
patterns that will be used to filter out the requests that do not match the URL
patterns. If the filter
is omitted then all requests will be matched.
For certain events the listener
is passed with a callback
, which should be
called with an response
object when listener
has done its work.
// Modify the user agent for all requests to the following urls.
var filter = {
urls: ["https://*.github.com/*", "*://electron.github.io"]
};
session.defaultSession.webRequest.onBeforeSendHeaders(filter, function(details, callback) {
details.requestHeaders['User-Agent'] = "MyAgent";
callback({cancel: false, requestHeaders: details.requestHeaders});
});
ses.webRequest.onBeforeRequest([filter, ]listener)
filter
Objectlistener
Function
The listener
will be called with listener(details, callback)
when a request
is about to occur.
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
Double
The callback
has to be called with an response
object:
response
Objectcancel
Boolean optionalredirectURL
String optional - The original request is prevented from being sent or completed, and is instead redirected to the given URL.
ses.webRequest.onBeforeSendHeaders([filter, ]listener)
filter
Objectlistener
Function
The listener
will be called with listener(details, callback)
before sending
an HTTP request, once the request headers are available. This may occur after a
TCP connection is made to the server, but before any http data is sent.
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoublerequestHeaders
Object
The callback
has to be called with an response
object:
response
Objectcancel
Boolean optionalrequestHeaders
Object optional - When provided, request will be made with these headers.
ses.webRequest.onSendHeaders([filter, ]listener)
filter
Objectlistener
Function
The listener
will be called with listener(details)
just before a request is
going to be sent to the server, modifications of previous onBeforeSendHeaders
response are visible by the time this listener is fired.
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoublerequestHeaders
Object
ses.webRequest.onHeadersReceived([filter,] listener)
filter
Objectlistener
Function
The listener
will be called with listener(details, callback)
when HTTP
response headers of a request have been received.
details
Objectid
Stringurl
Stringmethod
StringresourceType
Stringtimestamp
DoublestatusLine
StringstatusCode
IntegerresponseHeaders
Object
The callback
has to be called with an response
object:
response
Objectcancel
BooleanresponseHeaders
Object optional - When provided, the server is assumed to have responded with these headers.
ses.webRequest.onResponseStarted([filter, ]listener)
filter
Objectlistener
Function
The listener
will be called with listener(details)
when first byte of the
response body is received. For HTTP requests, this means that the status line
and response headers are available.
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleresponseHeaders
ObjectfromCache
Boolean - Indicates whether the response was fetched from disk cache.statusCode
IntegerstatusLine
String
ses.webRequest.onBeforeRedirect([filter, ]listener)
filter
Objectlistener
Function
The listener
will be called with listener(details)
when a server initiated
redirect is about to occur.
details
Objectid
Stringurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleredirectURL
StringstatusCode
Integerip
String optional - The server IP address that the request was actually sent to.fromCache
BooleanresponseHeaders
Object
ses.webRequest.onCompleted([filter, ]listener)
filter
Objectlistener
Function
The listener
will be called with listener(details)
when a request is
completed.
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleresponseHeaders
ObjectfromCache
BooleanstatusCode
IntegerstatusLine
String
ses.webRequest.onErrorOccurred([filter, ]listener)
filter
Objectlistener
Function
The listener
will be called with listener(details)
when an error occurs.
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoublefromCache
Booleanerror
String - The error description.