* docs: document modernization initiative more clearly
6.4 KiB
Class: Cookies
Query and modify a session's cookies.
Process: Main
Instances of the Cookies
class are accessed by using cookies
property of
a Session
.
For example:
const { session } = require('electron')
// Query all cookies.
session.defaultSession.cookies.get({})
.then((cookies) => {
console.log(cookies)
}).catch((error) => {
console.log(error)
})
// Query all cookies associated with a specific url.
session.defaultSession.cookies.get({ url: 'http://www.github.com' })
.then((cookies) => {
console.log(cookies)
}).catch((error) => {
console.log(error)
})
// Set a cookie with the given cookie data;
// may overwrite equivalent cookies if they exist.
const cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }
session.defaultSession.cookies.set(cookie)
.then(() => {
// success
}, (error) => {
console.error(error)
})
Instance Events
The following events are available on instances of Cookies
:
Event: 'changed'
event
Eventcookie
Cookie - The cookie that was changed.cause
String - The cause of the change with one of the following values:explicit
- The cookie was changed directly by a consumer's action.overwrite
- The cookie was automatically removed due to an insert operation that overwrote it.expired
- The cookie was automatically removed as it expired.evicted
- The cookie was automatically evicted during garbage collection.expired-overwrite
- The cookie was overwritten with an already-expired expiration date.
removed
Boolean -true
if the cookie was removed,false
otherwise.
Emitted when a cookie is changed because it was added, edited, removed, or expired.
Instance Methods
The following methods are available on instances of Cookies
:
cookies.get(filter)
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.
Returns Promise<Cookie[]>
- A promise which resolves an array of cookie objects.
Sends a request to get all cookies matching filter
, and resolves a promise with
the response.
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
Functionerror
Errorcookies
Cookie[] - an array of cookie objects.
Sends a request to get all cookies matching filter
, callback
will be called
with callback(error, cookies)
on complete.
cookies.set(details)
details
Objecturl
String - The url to associate the cookie with.name
String (optional) - The name of the cookie. Empty by default if omitted.value
String (optional) - The value of the cookie. Empty by default if omitted.domain
String (optional) - The domain of the cookie. Empty by default if omitted.path
String (optional) - The path of the cookie. Empty by default if omitted.secure
Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to false.httpOnly
Boolean (optional) - Whether the cookie should be marked as HTTP only. Defaults to false.expirationDate
Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted then the cookie becomes a session cookie and will not be retained between sessions.
Returns Promise<void>
- A promise which resolves when the cookie has been set
Sets a cookie with details
.
cookies.set(details, callback)
details
Objecturl
String - The url to associate the cookie with.name
String (optional) - The name of the cookie. Empty by default if omitted.value
String (optional) - The value of the cookie. Empty by default if omitted.domain
String (optional) - The domain of the cookie. Empty by default if omitted.path
String (optional) - The path of the cookie. Empty by default if omitted.secure
Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to false.httpOnly
Boolean (optional) - Whether the cookie should be marked as HTTP only. Defaults to false.expirationDate
Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted then the cookie becomes a session cookie and will not be retained between sessions.
callback
Functionerror
Error
Sets a cookie with details
, callback
will be called with callback(error)
on complete.
cookies.remove(url, name)
url
String - The URL associated with the cookie.name
String - The name of cookie to remove.
Returns Promise<void>
- A promise which resolves when the cookie has been removed
Removes the cookies matching url
and name
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.
cookies.flushStore()
Returns Promise<void>
- A promise which resolves when the cookie store has been flushed
Writes any unwritten cookies data to disk.
cookies.flushStore(callback)
callback
Function
Writes any unwritten cookies data to disk.