chrome.cookies

Description

Utilisez l'API chrome.cookies pour interroger et modifier les cookies, et pour être averti lorsqu'ils changent.

Autorisations

cookies

Pour utiliser l'API cookies, déclarez l'autorisation "cookies" dans votre fichier manifeste, ainsi que les autorisations d'hôte pour tous les hôtes dont vous souhaitez accéder aux cookies. 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 mis en correspondance avec l'origine du frame de premier niveau. Par exemple, si le site A est intégré à l'aide d'un iframe sur les sites B et C, les versions intégrées d'un cookie partitionné provenant d'A peuvent avoir des valeurs différentes sur les sites B et C.

Par défaut, toutes les méthodes d'API fonctionnent sur des cookies non partitionnés. La propriété partitionKey peut être utilisée pour remplacer ce comportement.

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 cookies dans le répertoire examples/api/cookies. Pour obtenir d'autres exemples et de l'aide pour afficher le code source, consultez la section Exemples.

Types

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

    number 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érieure

    Clé de partition pour lire ou modifier les cookies avec l'attribut "Partitionné".

  • chemin d'accès

    chaîne

    Chemin d'accès du cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 ou version ultérieure

    État de la valeur "SameSite" du cookie (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

Chrome 88 ou version ultérieure

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 ou version ultérieure

    Clé 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, auquel cas toutes les données qui suivent le chemin d'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

Chrome 119 ou version ultérieure

Représente la clé de partition d'un cookie partitionné.

Propriétés

  • hasCrossSiteAncestor

    booléen facultatif

    Chrome 130 ou version ultérieure

    Indique 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 sur 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 espace de stockage 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

    number[]

    Identifiants de tous les onglets du navigateur qui partagent ce magasin de cookies.

FrameDetails

En attente

Informations permettant d'identifier le frame.

Propriétés

  • documentId

    chaîne facultatif

    Identifiant unique du document. Si frameId et/ou tabId sont fournis, ils seront validés pour correspondre au document trouvé à l'aide de l'ID de document fourni.

  • frameId

    number facultatif

    Identifiant unique du frame dans l'onglet.

  • tabId

    number facultatif

    Identifiant unique de l'onglet contenant le frame.

OnChangedCause

Chrome 44 ou version ultérieure

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é supprimé automatiquement en raison de son expiration, la valeur de "cause" sera "expired". Si un cookie a été supprimé en raison d'une date d'expiration déjà passée, la valeur "cause" est définie sur "expired_overwrite". Si un cookie a été supprimé automatiquement en raison de la collecte des déchets, la valeur "cause" sera "evicted". 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"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 ou version ultérieure

État "SameSite" d'un cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). "no_restriction" correspond à un cookie défini avec "SameSite=None", "lax" à "SameSite=Lax" et "strict" à "SameSite=Strict". "non spécifié" correspond à un cookie défini sans l'attribut SameSite.

Énumération

"no_restriction"

"lax"

"strict"

"unspecified"

Méthodes

get()

Promesse 
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 ayant la même longueur de chemin d'accès, le cookie ayant la date de création la plus ancienne est renvoyé.

Paramètres

  • détails

    CookieDetails

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (cookie?: Cookie) => void

    • biscuit

      Cookie facultatif

      Contient des informations sur le cookie. Ce paramètre est nul si aucun cookie de ce type n'a été trouvé.

Renvoie

  • Promise<Cookie | undefined>

    Chrome 88 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

getAll()

Promesse 
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 ou version ultérieure

      Clé de partition pour lire ou modifier les cookies avec 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é "Sécurisé".

    • 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 cet élément n'est pas spécifié, le magasin de cookies du contexte d'exécution actuel sera utilisé.

    • url

      chaîne facultatif

      Limite les cookies récupérés à ceux qui correspondent à l'URL donnée.

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (cookies: Cookie[]) => void

    • cookies

      Cookie[]

      Tous les cookies existants et non expirés qui correspondent aux informations de cookie données.

Renvoie

  • Promise<Cookie[]>

    Chrome 88 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

getAllCookieStores()

Promesse 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

Répertorie tous les magasins de cookies existants.

Paramètres

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      Toutes les boutiques de cookies existantes.

Renvoie

  • Promise<CookieStore[]>

    Chrome 88 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

getPartitionKey()

Promesse en attente
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

Clé de partition pour le frame indiqué.

Paramètres

  • détails

    FrameDetails

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      Contient des informations sur la clé de partition récupérée.

      • partitionKey

        CookiePartitionKey

        Clé de partition pour lire ou modifier les cookies avec l'attribut "Partitionné".

Renvoie

  • Promise<object>

    Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

remove()

Promesse 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

Supprime un cookie par nom.

Paramètres

  • détails

    CookieDetails

  • rappel

    fonction 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érieure

        Clé 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 supprimé.

Renvoie

  • Promise<object | undefined>

    Chrome 88 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

set()

Promesse 
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. Si elle est omise, le cookie devient un cookie réservé à l'hôte.

    • expirationDate

      number facultatif

      Date d'expiration du cookie, exprimée en secondes depuis l'epoch UNIX. Si cet argument est omis, le cookie devient un cookie de session.

    • httpOnly

      booléen facultatif

      Indique si le cookie doit être marqué comme 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érieure

      Clé 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 51 ou version ultérieure

      État SameSite du cookie. La valeur par défaut est "unspecified". 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

      ID du magasin de cookies dans lequel définir le cookie. Par défaut, le cookie est défini dans le magasin de cookies du contexte d'exécution actuel.

    • url

      chaîne

      URI de requête à associer au paramètre 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 échoue.

    • 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ètre a échoué pour une raison quelconque, il sera défini sur "null" et runtime.lastError sera défini.

Renvoie

  • Promise<Cookie | undefined>

    Chrome 88 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

É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 est implémentée en deux étapes: le cookie à mettre à jour est d'abord supprimé entièrement, ce qui génère une notification avec la valeur "overwrite" pour la propriété "cause" . 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

      • Raison sous-jacente du changement du cookie.

      • biscuit

        Cookie

        Informations sur le cookie défini ou supprimé.

      • supprimé

        booléen

        "True" si un cookie a été supprimé.