chrome.cookies

Description

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

Autorisations

cookies

Pour utiliser l'API pour les 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 d'indiquer que certains cookies doivent être associés à l'origine du frame de premier niveau. Cela signifie que, par exemple, si le site A est intégré à l'aide d'un iFrame dans le site B et le site C, les versions intégrées d'un cookie partitionné issu de A peuvent avoir des valeurs différentes sur 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 ignorer 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 pour les cookies dans le répertoire examples/api/cookies. Pour obtenir d'autres exemples et de l'aide concernant l'affichage du code source, consultez la section Exemples.

Types

Représente les informations sur un cookie HTTP.

Propriétés

  • domaine

    chaîne

    Domaine du cookie (par exemple, "www.google.com" ou "example.com").

  • expirationDate

    numéro facultatif

    Date d'expiration du cookie exprimée en nombre de secondes depuis l'epoch UNIX. Non fourni pour les cookies de session.

  • hostOnly

    boolean

    "True" si le cookie est un cookie de l'hôte uniquement (c'est-à-dire que l'hôte d'une requête doit correspondre exactement au domaine du cookie).

  • httpOnly

    boolean

    "True" si le cookie est marqué comme HttpOnly (c'est-à-dire que les scripts côté client ne peuvent pas accéder au cookie).

  • name

    chaîne

    Nom du cookie.

  • partitionKey

    CookiePartitionKey facultatif

    Chrome 119 et versions ultérieures

    Clé de partition permettant de lire ou de modifier les cookies à l'aide de l'attribut partitionné.

  • chemin d'accès

    chaîne

    Chemin du cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 et versions ultérieures

    État du cookie sur le même site (c'est-à-dire si le cookie a été envoyé avec des requêtes intersites).

  • sécurisé

    boolean

    "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

    boolean

    "True" si le cookie est un cookie de session, et non un cookie persistant avec date d'expiration.

  • storeId

    chaîne

    Identifiant du magasin de cookies contenant ce cookie, tel que fourni dans getAllCookieStores().

  • valeur

    chaîne

    Valeur du cookie.

CookieDetails

Chrome 88 et versions ultérieures

Détails permettant d'identifier le cookie.

Propriétés

  • name

    chaîne

    Nom du cookie auquel accéder.

  • partitionKey

    CookiePartitionKey facultatif

    Chrome 119 et versions ultérieures

    Clé de partition permettant de lire ou de modifier les cookies à l'aide de l'attribut partitionné.

  • storeId

    string facultatif

    Identifiant du magasin de cookies dans lequel rechercher le cookie. Par défaut, le magasin de cookies du contexte d'exécution actuel sera utilisé.

  • url

    chaîne

    URL à laquelle le cookie permettant d'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 échouera.

CookiePartitionKey

Chrome 119 et versions ultérieures

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

Propriétés

  • topLevelSite

    string 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 de la fenêtre de navigation privée.

Propriétés

  • id

    chaîne

    Identifiant unique du magasin de cookies.

  • tabIds

    nombre[]

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

OnChangedCause

Chrome 44 ou version ultérieure

Raison sous-jacente de la modification du cookie. Si un cookie a été inséré ou supprimé via un appel explicite à "chrome.cookies.remove", la valeur "cause" sera "explicite". Si un cookie a été automatiquement supprimé en raison de l'expiration, la "cause" sera "arrivé à expiration". Si un cookie a été supprimé après avoir été remplacé par une date d'expiration déjà expirée, la valeur "cause" est définie sur "expired_overwrite". Si un cookie a été automatiquement supprimé en raison de la récupération de mémoire, la "cause" sera "expulsée". Si un cookie a été automatiquement supprimé en raison d'un appel "set" qui l'a remplacé, la valeur "cause" sera "écraser". Planifiez votre réponse en conséquence.

Enum

"expired"

"expired_overwrite"

SameSiteStatus

Chrome 51 et versions ultérieures

É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". "unspecified" correspond à un ensemble de cookies sans attribut SameSite.

Enum

"no_restriction"

"lax"

"unspecified"

Méthodes

get()

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

Récupère les informations sur un cookie unique. S'il existe plusieurs cookies du même nom pour l'URL donnée, celui dont le chemin d'accès est le plus long est renvoyé. Pour les cookies dont le chemin d'accès est identique, c'est le cookie dont la date de création est la plus ancienne qui est renvoyé.

Paramètres

  • détails

    CookieDetails

  • rappel

    fonction facultative

    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 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 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 est résolue 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 magasin de cookies unique qui correspondent aux informations données. Les cookies renvoyés seront triés, en commençant par ceux avec le chemin le plus long. Si plusieurs cookies ont la même longueur de chemin, ceux dont l'heure de création est la plus ancienne sont les premiers. Cette méthode ne récupère que les cookies des domaines sur lesquels l'extension dispose des autorisations d'hôte.

Paramètres

  • détails

    objet

    Informations permettant de filtrer les cookies récupérés.

    • domaine

      string facultatif

      Limite les cookies récupérés à ceux dont les domaines correspondent à celui-ci ou sont des sous-domaines.

    • name

      string facultatif

      Filtre les cookies par nom.

    • partitionKey

      CookiePartitionKey facultatif

      Chrome 119 et versions ultérieures

      Clé de partition permettant de lire ou de modifier les cookies à l'aide de l'attribut partitionné.

    • chemin d'accès

      string 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

      string facultatif

      Magasin de cookies à partir duquel les cookies sont récupérés. En cas d'omission, le magasin de cookies du contexte d'exécution actuel sera utilisé.

    • url

      string facultatif

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

  • rappel

    fonction facultative

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

    (cookies: Cookie[])=>void

    • cookies

      Cookie[]

      Tous les cookies existants et toujours en cours de validité qui correspondent aux informations des cookies donnés.

Renvoie

  • Promise<Cookie[]>

    Chrome 88 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 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 est résolue avec le même type que celui transmis au rappel.

getAllCookieStores()

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

Liste tous les magasins de cookies existants.

Paramètres

  • rappel

    fonction facultative

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

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

      Tous les magasins de cookies existants.

Renvoie

  • Promise<CookieStore[]>

    Chrome 88 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 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 est résolue avec le même type que celui transmis au rappel.

remove()

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

Supprime un cookie en fonction de son nom.

Paramètres

  • détails

    CookieDetails

  • rappel

    fonction facultative

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

    (details?: object)=>void

    • détails

      objet facultatif

      Contient des informations sur le cookie qui a été supprimé. Si la suppression échoue pour une raison quelconque, la valeur sera "null", et la valeur runtime.lastError sera définie.

      • name

        chaîne

        Nom du cookie qui a été supprimé.

      • partitionKey

        CookiePartitionKey facultatif

        Chrome 119 et versions ultérieures

        Clé de partition permettant de lire ou de modifier les cookies à l'aide de l'attribut partitionné.

      • storeId

        chaîne

        Identifiant du magasin de cookies dans lequel le cookie a été supprimé.

      • url

        chaîne

        URL associée au cookie qui a été supprimé.

Renvoie

  • Promise<object|undefined>

    Chrome 88 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 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 est résolue 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 fournies. Peut remplacer les cookies équivalents, s'ils existent.

Paramètres

  • détails

    objet

    Informations sur le cookie en cours de définition.

    • domaine

      string facultatif

      Domaine du cookie. S'il est omis, il devient un cookie de l'hôte uniquement.

    • expirationDate

      numéro facultatif

      Date d'expiration du cookie exprimée en nombre de secondes depuis l'epoch UNIX. S'il est omis, il 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".

    • name

      string facultatif

      Nom du cookie. Vide par défaut en cas d'omission.

    • partitionKey

      CookiePartitionKey facultatif

      Chrome 119 et versions ultérieures

      Clé de partition permettant de lire ou de modifier les cookies à l'aide de l'attribut partitionné.

    • chemin d'accès

      string facultatif

      Chemin du cookie. La valeur par défaut correspond à la partie chemin du paramètre d'URL.

    • sameSite

      SameSiteStatus facultatif

      Chrome 51 et versions ultérieures

      L'état du cookie sur le même site La valeur par défaut est "unspecified", c'est-à-dire que 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

      string facultatif

      Identifiant 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 la requête à associer au paramètre du cookie. Cette valeur peut affecter les valeurs de domaine et de chemin 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

      string facultatif

      Valeur du cookie. Vide par défaut en cas d'omission.

  • rappel

    fonction facultative

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

    (cookie?: Cookie)=>void

    • biscuit

      Cookie facultatif

      Contient des informations sur le cookie qui a été défini. En cas d'échec de la configuration pour une raison quelconque, la valeur sera "null", et runtime.lastError sera défini.

Renvoie

  • Promise<Cookie|undefined>

    Chrome 88 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 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 est résolue 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é. Il existe un cas particulier. Notez que la mise à jour des propriétés d'un cookie s'effectue via un processus en deux étapes: le cookie à mettre à jour est d'abord supprimé intégralement, générant une notification avec la "cause" du remplacement . Un nouveau cookie est ensuite écrit avec les valeurs mises à jour, ce qui génère une deuxième notification indiquant la "cause" "explicite".

Paramètres

  • rappel

    function

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

    (changeInfo: object)=>void

    • changeInfo

      objet

      • Raison sous-jacente de la modification du cookie.

      • biscuit

        Cookie

        Informations sur le cookie qui a été défini ou supprimé.

      • supprimé

        boolean

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