chrome.cookies
Description: |
Use the chrome.cookies API to query and modify cookies, and to be notified when they change.
|
Availability: |
Since Chrome 29.
|
Permissions: |
"cookies"
host permissions |
Manifest
To use the cookies API, you must declare the "cookies" permission in your manifest, along with host permissions for any hosts whose cookies you want to access. For example:
{ "name": "My extension", ... "permissions": [ "cookies", "*://*.google.com" ], ... }
Examples
You can find a simple example of using the cookies API in the examples/api/cookies directory. For other examples and for help in viewing the source code, see Samples.
Summary
Types | |
---|---|
SameSiteStatus | |
Cookie | |
CookieStore | |
OnChangedCause | |
Methods | |
get −
chrome.cookies.get(object details, function callback)
| |
getAll −
chrome.cookies.getAll(object details, function callback)
| |
set −
chrome.cookies.set(object details, function callback)
| |
remove −
chrome.cookies.remove(object details, function callback)
| |
getAllCookieStores −
chrome.cookies.getAllCookieStores(function callback)
| |
Events | |
onChanged |
Types
SameSiteStatus
Enum |
---|
"no_restriction" ,
"lax" ,
or "strict"
|
Cookie
properties | ||
---|---|---|
string | name |
The name of the cookie. |
string | value |
The value of the cookie. |
string | domain |
The domain of the cookie (e.g. "www.google.com", "example.com"). |
boolean | hostOnly |
True if the cookie is a host-only cookie (i.e. a request's host must exactly match the domain of the cookie). |
string | path |
The path of the cookie. |
boolean | secure |
True if the cookie is marked as Secure (i.e. its scope is limited to secure channels, typically HTTPS). |
boolean | httpOnly |
True if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts). |
SameSiteStatus | sameSite |
Since Chrome 51. The cookie's same-site status (i.e. whether the cookie is sent with cross-site requests). |
boolean | session |
True if the cookie is a session cookie, as opposed to a persistent cookie with an expiration date. |
double | (optional) expirationDate |
The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies. |
string | storeId |
The ID of the cookie store containing this cookie, as provided in getAllCookieStores(). |
CookieStore
properties | ||
---|---|---|
string | id |
The unique identifier for the cookie store. |
array of integer | tabIds |
Identifiers of all the browser tabs that share this cookie store. |
OnChangedCause
Enum |
---|
"evicted" ,
"expired" ,
"explicit" ,
"expired_overwrite" ,
or "overwrite"
|
Methods
get
chrome.cookies.get(object details, function callback)
Retrieves information about a single cookie. If more than one cookie of the same name exists for the given URL, the one with the longest path will be returned. For cookies with the same path length, the cookie with the earliest creation time will be returned.
Parameters | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
object | details |
Details to identify the cookie being retrieved.
|
|||||||||
function | callback |
The callback parameter should be a function that looks like this: function( Cookie cookie) {...};
|
getAll
chrome.cookies.getAll(object details, function callback)
Retrieves all cookies from a single cookie store that match the given information. The cookies returned will be sorted, with those with the longest path first. If multiple cookies have the same path length, those with the earliest creation time will be first.
Parameters | |||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | details |
Information to filter the cookies being retrieved.
|
|||||||||||||||||||||
function | callback |
The callback parameter should be a function that looks like this: function(array of Cookie cookies) {...};
|
set
chrome.cookies.set(object details, function callback)
Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist.
Parameters | ||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | details |
Details about the cookie being set.
|
||||||||||||||||||||||||||||||
function | (optional) callback |
If you specify the callback parameter, it should be a function that looks like this: function( Cookie cookie) {...};
|
remove
chrome.cookies.remove(object details, function callback)
Deletes a cookie by name.
Parameters | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | details |
Information to identify the cookie to remove.
|
||||||||||||
function | (optional) callback |
If you specify the callback parameter, it should be a function that looks like this: function(object details) {...};
|
getAllCookieStores
chrome.cookies.getAllCookieStores(function callback)
Lists all existing cookie stores.
Parameters | |||||
---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(array of CookieStore cookieStores) {...};
|
Events
onChanged
Fired when a cookie is set or removed. As a special case, note that updating a cookie's properties is implemented as a two step process: the cookie to be updated is first removed entirely, generating a notification with "cause" of "overwrite" . Afterwards, a new cookie is written with the updated values, generating a second notification with "cause" "explicit".
addListener
chrome.cookies.onChanged.addListener(function callback)
Parameters | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object changeInfo) {...};
|