2016-11-10 20:25:26 +00:00
## Class: Cookies
> Query and modify a session's cookies.
2021-06-15 20:50:31 +00:00
Process: [Main ](../glossary.md#main-process )< br />
_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
2016-11-10 20:25:26 +00:00
Instances of the `Cookies` class are accessed by using `cookies` property of
a `Session` .
For example:
2023-11-21 07:50:08 +00:00
```js
2018-09-13 16:10:51 +00:00
const { session } = require('electron')
2016-11-10 20:25:26 +00:00
// Query all cookies.
2019-01-25 18:11:35 +00:00
session.defaultSession.cookies.get({})
.then((cookies) => {
console.log(cookies)
}).catch((error) => {
console.log(error)
})
2016-11-10 20:25:26 +00:00
// Query all cookies associated with a specific url.
2023-08-10 09:55:52 +00:00
session.defaultSession.cookies.get({ url: 'https://www.github.com' })
2019-01-25 18:11:35 +00:00
.then((cookies) => {
console.log(cookies)
}).catch((error) => {
console.log(error)
})
2016-11-10 20:25:26 +00:00
// Set a cookie with the given cookie data;
// may overwrite equivalent cookies if they exist.
2023-08-10 09:55:52 +00:00
const cookie = { url: 'https://www.github.com', name: 'dummy_name', value: 'dummy' }
2019-01-25 18:11:35 +00:00
session.defaultSession.cookies.set(cookie)
.then(() => {
// success
}, (error) => {
console.error(error)
})
2016-11-10 20:25:26 +00:00
```
### Instance Events
The following events are available on instances of `Cookies` :
#### Event: 'changed'
2021-03-11 20:14:16 +00:00
Returns:
2016-11-10 20:25:26 +00:00
* `event` Event
2017-11-29 10:38:35 +00:00
* `cookie` [Cookie ](structures/cookie.md ) - The cookie that was changed.
2021-11-16 04:13:18 +00:00
* `cause` string - The cause of the change with one of the following values:
2016-11-10 20:25:26 +00:00
* `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.
2021-11-16 04:13:18 +00:00
* `removed` boolean - `true` if the cookie was removed, `false` otherwise.
2016-11-10 20:25:26 +00:00
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` :
2019-01-25 18:11:35 +00:00
#### `cookies.get(filter)`
* `filter` Object
2021-11-16 04:13:18 +00:00
* `url` string (optional) - Retrieves cookies which are associated with
2019-06-21 21:19:21 +00:00
`url` . Empty implies retrieving cookies of all URLs.
2021-11-16 04:13:18 +00:00
* `name` string (optional) - Filters cookies by name.
* `domain` string (optional) - Retrieves cookies whose domains match or are
2024-08-09 23:35:18 +00:00
subdomains of `domain` .
2021-11-16 04:13:18 +00:00
* `path` string (optional) - Retrieves cookies whose path matches `path` .
* `secure` boolean (optional) - Filters cookies by their Secure property.
* `session` boolean (optional) - Filters out session or persistent cookies.
2023-02-21 10:44:35 +00:00
* `httpOnly` boolean (optional) - Filters cookies by httpOnly.
2019-01-25 18:11:35 +00:00
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.set(details)`
* `details` Object
2021-11-16 04:13:18 +00:00
* `url` string - The URL to associate the cookie with. The promise will be rejected if the URL is invalid.
* `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; this will be normalized with a preceding dot so that it's also valid for subdomains. 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
2021-08-24 00:52:17 +00:00
false unless [Same Site=None ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite#samesitenone_requires_secure ) attribute is used.
2021-11-16 04:13:18 +00:00
* `httpOnly` boolean (optional) - Whether the cookie should be marked as HTTP only.
2019-01-25 18:11:35 +00:00
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.
2021-11-16 04:13:18 +00:00
* `sameSite` string (optional) - The [Same Site ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#SameSite_cookies ) policy to apply to this cookie. Can be `unspecified` , `no_restriction` , `lax` or `strict` . Default is `lax` .
2019-01-25 18:11:35 +00:00
Returns `Promise<void>` - A promise which resolves when the cookie has been set
Sets a cookie with `details` .
#### `cookies.remove(url, name)`
2021-11-16 04:13:18 +00:00
* `url` string - The URL associated with the cookie.
* `name` string - The name of cookie to remove.
2019-01-25 18:11:35 +00:00
Returns `Promise<void>` - A promise which resolves when the cookie has been removed
Removes the cookies matching `url` and `name`
#### `cookies.flushStore()`
Returns `Promise<void>` - A promise which resolves when the cookie store has been flushed
2023-09-18 20:51:46 +00:00
Writes any unwritten cookies data to disk
Cookies written by any method will not be written to disk immediately, but will be written every 30 seconds or 512 operations
Calling this method can cause the cookie to be written to disk immediately.