Description
Utilisez l'API chrome.cookies
pour interroger et modifier les cookies, et pour être averti lorsqu'ils changent.
Autorisations
cookies
Fichier manifeste
Pour utiliser l'API pour les cookies, vous devez déclarer les "cookies" autorisation dans votre ainsi que les autorisations d'hôtes pour tous les hôtes dont vous souhaitez pour y accéder. Exemple :
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
Partitionnement
Les cookies partitionnés permettent à un site de marquer que certains cookies doivent être associés l'origine du cadre de premier niveau. Cela signifie que si le site A est intégré à l'aide d'un iFrame sur le site B, et sur le site C, un cookie partitionné peut avoir une valeur différente dans chacun.
chrome.cookies
n'est pas compatible avec le partitionnement, ce qui signifie que toutes les méthodes
lisent et écrivent des cookies
à partir de toutes les partitions. La méthode cookies.set()
stocke les cookies dans la partition par défaut.
Pour en savoir plus sur l'impact général du partitionnement pour les extensions, consultez la section Stockage et cookies.
Exemples
Vous trouverez un exemple simple d'utilisation de l'API pour les cookies dans la examples/api/cookies. Pour obtenir d'autres exemples et de l'aide pour afficher le code source, consultez la section Exemples.
Types
Cookie
Représente des informations sur un cookie HTTP.
Propriétés
-
domaine
chaîne
Domaine du cookie (par exemple, "www.google.com", "example.com").
-
expirationDate
numéro facultatif
Date d'expiration du cookie, exprimée en secondes depuis l'epoch UNIX. Non fourni pour les cookies de session.
-
hostOnly
booléen
"True" si le cookie est un cookie hôte uniquement (c'est-à-dire que l'hôte d'une requête doit correspondre exactement au domaine du cookie).
-
httpOnly
booléen
"True" si le cookie est marqué comme HttpOnly (c'est-à-dire qu'il est inaccessible aux scripts côté client).
-
nom
chaîne
Nom du cookie.
-
partitionKey
CookiePartitionKey facultatif
Chrome 119 ou version ultérieureClé de partition pour lire ou modifier les cookies avec l'attribut "Partitionné".
-
chemin d'accès
chaîne
Chemin du cookie.
-
sameSiteChrome 51 ou version ultérieure
État du cookie sur un site identique (c'est-à-dire si le cookie est envoyé avec des requêtes intersites).
-
sécurisé
booléen
"True" si le cookie est marqué comme sécurisé (c'est-à-dire que son champ d'application est limité aux canaux sécurisés, généralement HTTPS).
-
session
booléen
"True" si le cookie est un cookie de session, par opposition à un cookie persistant avec une date d'expiration.
-
storeId
chaîne
ID du magasin de cookies contenant ce cookie, tel que fourni dans getAllCookieStores().
-
valeur
chaîne
Valeur du cookie.
CookieDetails
Informations permettant d'identifier le cookie.
Propriétés
-
nom
chaîne
Nom du cookie auquel vous souhaitez accéder.
-
partitionKey
CookiePartitionKey facultatif
Chrome 119 et versions ultérieuresClé de partition pour lire ou modifier les cookies avec l'attribut "Partitionné".
-
storeId
chaîne facultatif
ID du magasin de cookies dans lequel rechercher le cookie. Par défaut, le magasin de cookies du contexte d'exécution actuel est utilisé.
-
url
chaîne
URL à laquelle le cookie auquel vous souhaitez accéder est associé. Cet argument peut être une URL complète. Dans ce cas, toutes les données qui suivent le chemin de l'URL (par exemple, la chaîne de requête) sont simplement ignorées. Si les autorisations d'hôte pour cette URL ne sont pas spécifiées dans le fichier manifeste, l'appel d'API échoue.
CookiePartitionKey
Représente la clé de partition d'un cookie partitionné.
Propriétés
-
hasCrossSiteAncestor
booléen facultatif
Chrome 130 ou version ultérieureIndique si le cookie a été défini dans un contexte intersites. Cela empêche un site de premier niveau intégré dans un contexte intersite d'accéder aux cookies définis par le site de premier niveau dans un contexte de même site.
-
topLevelSite
chaîne facultatif
Site de premier niveau dans lequel le cookie partitionné est disponible.
CookieStore
Représente un magasin de cookies dans le navigateur. Par exemple, une fenêtre en mode navigation privée utilise un magasin de cookies distinct de celui d'une fenêtre non privée.
Propriétés
-
id
chaîne
Identifiant unique du magasin de cookies.
-
tabIds
numéro[]
Identifiants de tous les onglets de navigateur qui partagent ce magasin de cookies.
OnChangedCause
Raison sous-jacente du changement du cookie. Si un cookie a été inséré ou supprimé via un appel explicite à "chrome.cookies.remove", la valeur de "cause" sera "explicit". Si un cookie a été automatiquement supprimé en raison de son expiration, "provoquez" est "arrivé à expiration". Si un cookie a été supprimé après avoir été remplacé par une date d'expiration déjà expirée, "cause" est défini sur "expired_overwrite". Si un cookie a été automatiquement supprimé en raison de la récupération de mémoire, "cause" est "évincée". Si un cookie a été supprimé automatiquement en raison d'un appel "set" qui l'a écrasé, la valeur de "cause" sera "overwrite". Planifiez votre réponse en conséquence.
Énumération
"evicted"
"explicit"
SameSiteStatus
État "SameSite" d'un cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). "no_restriction" correspond à un ensemble de cookies défini sur "SameSite=None", "lax" à "SameSite=Lax" et "strict" sur "SameSite=Strict". 'non spécifié' correspond à un ensemble de cookies sans l'attribut SameSite.
Énumération
"no_restriction"
"lax"
"strict"
"unspecified"
Méthodes
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
Récupère des informations sur un seul cookie. Si plusieurs cookies du même nom existent pour l'URL donnée, celui dont le chemin d'accès est le plus long est renvoyé. Pour les cookies dont la longueur de chemin est identique, le cookie dont l'heure de création est la plus ancienne est renvoyé.
Paramètres
Renvoie
-
Promise<Cookie | indéfini>
Chrome 88 ou version ultérieureLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
Récupère tous les cookies d'un même magasin de cookies qui correspondent aux informations données. Les cookies renvoyés sont triés, les plus longs en premier. Si plusieurs cookies ont la même longueur de chemin d'accès, ceux dont la date de création est la plus ancienne sont affichés en premier. Cette méthode ne récupère les cookies que pour les domaines pour lesquels l'extension dispose d'autorisations d'accès à l'hôte.
Paramètres
-
détails
objet
Informations permettant de filtrer les cookies récupérés.
-
domaine
chaîne facultatif
Limite les cookies récupérés à ceux dont les domaines correspondent ou sont des sous-domaines de celui-ci.
-
nom
chaîne facultatif
Filtre les cookies par nom.
-
partitionKey
CookiePartitionKey facultatif
Chrome 119 et versions ultérieuresClé de partitionnement pour la lecture ou la modification des cookies à l'aide de l'attribut partitionné.
-
chemin d'accès
chaîne facultatif
Limite les cookies récupérés à ceux dont le chemin correspond exactement à cette chaîne.
-
sécurisé
Booléen facultatif
Filtre les cookies en fonction de leur propriété "Secure".
-
session
booléen facultatif
Filtre les cookies de session et les cookies persistants.
-
storeId
chaîne facultatif
Magasin de cookies à partir duquel les cookies doivent être récupérés. Si cette valeur est omise, le magasin de cookies du contexte d'exécution actuel est utilisé.
-
url
chaîne facultatif
Limite les cookies récupérés à ceux qui correspondent à l'URL donnée.
-
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:(cookies: Cookie[]) => void
-
cookies
Cookie[]
Tous les cookies existants n'ayant pas expiré qui correspondent aux informations du cookie données.
-
Renvoie
-
Promise<Cookie[]>
Chrome 88 ou version ultérieureLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
Liste tous les magasins de cookies existants.
Paramètres
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit :(cookieStores: CookieStore[]) => void
-
cookieStores
Tous les magasins de cookies existants.
-
Renvoie
-
Promise<CookieStore[]>
Chrome (version 88 ou ultérieure)Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
Supprime un cookie par son nom.
Paramètres
-
détails
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:(details?: object) => void
-
détails
objet facultatif
Contient des informations sur le cookie supprimé. Si la suppression a échoué pour une raison quelconque, la valeur est "null", et
runtime.lastError
est défini.-
nom
chaîne
Nom du cookie supprimé.
-
partitionKey
CookiePartitionKey facultatif
Chrome 119 ou version ultérieureClé de partition pour lire ou modifier les cookies avec l'attribut "Partitionné".
-
storeId
chaîne
ID du magasin de cookies à partir duquel le cookie a été supprimé.
-
url
chaîne
URL associée au cookie qui a été supprimé.
-
-
Renvoie
-
Promise<object | undefined>
Chrome 88 ou version ultérieureLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
set()
chrome.cookies.set(
details: object,
callback?: function,
)
Définit un cookie avec les données de cookie données. Peut écraser les cookies équivalents s'ils existent.
Paramètres
-
détails
objet
Informations sur le cookie défini.
-
domaine
chaîne facultatif
Domaine du cookie. S'il est omis, le cookie devient un cookie d'hôte uniquement.
-
expirationDate
numéro facultatif
Date d'expiration du cookie, exprimée en secondes depuis l'epoch UNIX. S'il est omis, le cookie devient un cookie de session.
-
httpOnly
booléen facultatif
Indique si le cookie doit être marqué en tant que HttpOnly. Valeur par défaut : "false".
-
nom
chaîne facultatif
Nom du cookie. La valeur est vide par défaut si elle est omise.
-
partitionKey
CookiePartitionKey facultatif
Chrome 119 ou version ultérieureClé de partition pour lire ou modifier les cookies avec l'attribut "Partitionné".
-
chemin d'accès
chaîne facultatif
Chemin d'accès du cookie. Valeur par défaut : partie du chemin d'accès du paramètre d'URL.
-
sameSite
SameSiteStatus facultatif
Chrome (version 51 ou ultérieure)État du cookie "SameSite" La valeur par défaut est "non spécifié". Autrement dit, si cet attribut est omis, le cookie est défini sans spécifier d'attribut SameSite.
-
sécurisé
Booléen facultatif
Indique si le cookie doit être marqué comme sécurisé. Valeur par défaut : "false".
-
storeId
chaîne facultatif
Identifiant du magasin de cookies dans lequel le cookie doit être défini. Par défaut, le cookie est défini dans le magasin de cookies du contexte d'exécution actuel.
-
url
chaîne
URI de la requête à associer au paramétrage du cookie. Cette valeur peut avoir une incidence sur les valeurs de domaine et de chemin d'accès par défaut du cookie créé. Si les autorisations d'hôte pour cette URL ne sont pas spécifiées dans le fichier manifeste, l'appel d'API échouera.
-
valeur
chaîne facultatif
Valeur du cookie. La valeur est vide par défaut si elle est omise.
-
-
rappel
fonction facultatif
Le paramètre
callback
se présente comme suit :(cookie?: Cookie) => void
-
biscuit
Cookie facultatif
Contient des informations sur le cookie défini. Si le paramétrage échoue pour une raison quelconque, la valeur sera "null" et
runtime.lastError
sera défini.
-
Renvoie
-
Promise<Cookie | indéfini>
Chrome 88 ou version ultérieureLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
Événements
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
Déclenché lorsqu'un cookie est défini ou supprimé. Notez que la mise à jour des propriétés d'un cookie s'effectue en deux étapes: le cookie à mettre à jour est d'abord entièrement supprimé, générant ainsi une notification avec "cause". de "écraser" pour en savoir plus. Ensuite, un nouveau cookie est écrit avec les valeurs mises à jour, ce qui génère une deuxième notification avec "cause" "explicit".
Paramètres
-
rappel
fonction
Le paramètre
callback
se présente comme suit :(changeInfo: object) => void
-
changeInfo
objet
-
cause
Raison sous-jacente du changement du cookie.
-
biscuit
Informations sur le cookie défini ou supprimé.
-
supprimé
booléen
"True" si un cookie a été supprimé.
-
-