Enables extensions to get and set cookies, and be notified when they change.
To use this API, you need to include the "cookies" API permission in your manifest.json file, as well as host permissions for the sites whose cookies you need to access. See cookie Permissions.
In order to use this API, an add-on must specify the "cookies" API permission in its manifest, along with host permissions for any sites for which it wishes to access cookies. The add-on may read or write any cookies which could be read or written by a URL matching the host permissions. For example:
http://*.example.com/
An add-on with this host permission may:
www.example.com
, with any path.www.example.com
, with any path.It may not:
www.example.com
.http://www.example.com/
An add-on with this host permission may:
www.example.com
, with any path..example.com
, with any path.www.example.com
with any path..example.com
with any path.It may not:
foo.example.com
.foo.www.example.com
.*://*.example.com/
An add-on with this host permission may:
www.example.com
with any path.Third-party cookies are cookies that are set by a website other than the one you are currently on. For example:
When first-party isolation is on, cookies are further qualified by the domain of the original page the user visited (essentially, the domain shown to the user in the URL bar, also known as the "first party domain"). This means it's not possible for a tracker to correlate its cookie from bbc.com with its cookie from cnn.com, so the tracker can't track a single user across both sites.
First-party isolation can be enabled directly by the user by adjusting the browser's configuration, and can be set by extensions using the firstPartyIsolate
setting in the privacy
API. Note that first-party isolation is enabled by default in Tor Browser.
In the cookies
API, the first party domain is represented using the firstPartyDomain
attribute. All cookies set while first-party isolation is on will have this attribute set to the domain of the original page. In the example above, this would be "bbc.com" for one cookie and "cnn.com" for the other. All cookies set by websites while first-party isolation is off will have this property set to an empty string.
The cookies.get()
, cookies.getAll()
, cookies.set()
and cookies.remove()
APIs all accept a firstPartyDomain
option.
When first-party isolation is on, you must provide this option or the API call will fail and return a rejected promise. For get()
, set()
, and remove()
you must pass a string value. For getAll()
, you may also pass null
here, and this will get all cookies, whether or not they have a non-empty value for firstPartyDomain
.
When first-party isolation is off, the firstPartyDomain
parameter is optional and defaults to an empty string. A non-empty string can be used to retrieve or modify first-party isolation cookies. Likewise, passing null
as firstPartyDomain
to getAll()
will return all cookies.
cookies.Cookie
cookies.CookieStore
cookies.OnChangedCause
cookies.SameSiteStatus
cookies.get()
cookies.getAll()
cookies.set()
cookies.remove()
cookies.getAllCookieStores()
cookies.onChanged
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
Cookie |
Yes |
14 |
45 |
? |
Yes |
14 |
? |
? |
48 |
? |
? |
? |
CookieStore |
Yes |
14 |
45 |
? |
Yes |
14 |
? |
? |
48 |
? |
? |
? |
OnChangedCause |
Yes |
79 |
45 |
? |
Yes |
No |
? |
? |
48 |
? |
? |
? |
get |
Yes |
14 |
45
Provides access to cookies from private browsing mode and container tabs since version 52.
|
? |
Yes |
14
HTTPOnly cookies are not retrieved.
|
? |
? |
48 |
? |
? |
? |
getAll |
Yes |
14
If no URL is provided, cookies are retrieved only for URLs in currently opened tabs. In Chrome, this gets all cookies on a user's machine.
|
45
Before version 52, the 'tabIds' list was empty and only cookies from the default cookie store were returned. From version 52 onwards, this has been fixed and the result includes cookies from private browsing mode and container tabs.
|
? |
Yes |
14
["Only the cookies in the default cookie store are retrieved.", "HTTPOnly cookies are not retrieved."]
|
? |
? |
48 |
? |
? |
? |
getAllCookieStores |
Yes |
14
Always returns the same default cookie store with ID 0. All cookies belong to this store.
|
45
Before version 52, only the default cookie store was visible. From version 52 onwards, the cookie stores for private browsing mode and container tabs are also readable.
|
? |
Yes |
14
Always returns the same default cookie store with ID 0.
|
? |
? |
48 |
? |
? |
? |
onChanged |
Yes |
79 |
45 |
? |
Yes |
No |
? |
? |
48 |
? |
? |
? |
remove |
Yes |
14 |
45
Before version 56, this function did not remove cookies from private browsing mode. From version 56 onwards this is fixed.
|
? |
Yes |
14 |
? |
? |
48
Before version 56, this function did not remove cookies from private browsing mode. From version 56 onwards this is fixed.
|
? |
? |
? |
sameSiteStatus |
Yes |
79 |
63 |
? |
No |
14
Only supports explicit.
|
? |
? |
63 |
? |
? |
? |
set |
Yes |
14 |
45
Before version 56, this function did not modify cookies in private browsing mode. From version 56 onwards this is fixed.
|
? |
Yes |
14 |
? |
? |
48
Before version 56, this function did not modify cookies in private browsing mode. From version 56 onwards this is fixed.
|
? |
? |
? |
Note: This API is based on Chromium's chrome.cookies
API. This documentation is derived from cookies.json
in the Chromium code.
© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies