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 de cookies, déclarez l'autorisation "cookies" dans votre ainsi que les autorisations d'hôte 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, par exemple, que si le site A est intégré à l'aide d'un iFrame sur le site B, et du site C, les versions intégrées d'un cookie partitionné provenant de A peuvent avoir des valeurs différentes pour B et C.

Par défaut, toutes les méthodes d'API fonctionnent sur des cookies non partitionnés. La 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 Stockage et cookies

Exemples

Vous trouverez un exemple simple d'utilisation de l'API pour les cookies dans la examples/api/cookies. Pour découvrir d'autres exemples et obtenir de l'aide 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" ou "example.com").

  • expirationDate

    numéro facultatif

    Date d'expiration du cookie, exprimée en nombre de secondes depuis l'epoch UNIX. Non fournie 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 que les scripts côté client ne peuvent pas accéder au cookie).

  • nom

    chaîne

    Nom du cookie.

  • partitionKey

    CookiePartitionKey facultatif

    Chrome 119 ou version ultérieure

    Clé de partitionnement pour la lecture ou la modification des cookies à l'aide de l'attribut partitionné.

  • chemin d'accès

    chaîne

    Chemin du cookie.

  • sameSite

    SameSiteStatus

    Chrome (version 51 ou ultérieure)

    L'é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 date d'expiration.

  • storeId

    chaîne

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

  • valeur

    chaîne

    Valeur du cookie.

CookieDetails

Chrome (version 88 ou ultérieure)

Informations permettant d'identifier le cookie.

Propriétés

  • nom

    chaîne

    Nom du cookie auquel accéder.

  • partitionKey

    CookiePartitionKey facultatif

    Chrome 119 et versions ultérieures

    Clé de partitionnement pour la lecture ou la modification des cookies à l'aide de 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 sera utilisé.

  • url

    chaîne

    URL à laquelle le cookie à 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

  • hasCrossSiteAncestor

    Booléen facultatif

    En attente

    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 intersites d'accéder aux cookies définis par ce site dans un contexte intersites.

  • 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

Chrome (version 44 ou 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", "cause" est défini sur "explicite". 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é automatiquement supprimé en raison d'un "ensemble" appelé cela l'a remplacé, « car » est "écrasement". Planifiez votre réponse en conséquence.

Énumération

SameSiteStatus

Chrome (version 51 ou ultérieure)

"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

Méthodes

get()

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

Récupère des informations sur un seul cookie. S'il existe plusieurs cookies du même nom pour l'URL donnée, celui dont le chemin 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

  • détails

    CookieDetails

  • rappel

    function 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 | indéfini>

    Chrome (version 88 ou ultérieure)

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getAll()

Promise 
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 sont triés, ceux dont le chemin est le plus long en premier. Si plusieurs cookies ont la même longueur de chemin, ceux ayant la date de création la plus ancienne sont prioritaires. Cette méthode récupère uniquement les cookies des domaines pour lesquels l'extension dispose d'autorisations d'hôte.

Paramètres

  • détails

    objet

    Informations pour filtrer les cookies en cours de récupération.

    • 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 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 sont 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 (version 88 ou ultérieure)

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getAllCookieStores()

Promise 
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

      CookieStore[]

      Tous les magasins de cookies existants.

Renvoie

  • Promise<CookieStore[]>

    Chrome (version 88 ou ultérieure)

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

remove()

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

Supprime un cookie par son nom.

Paramètres

  • détails

    CookieDetails

  • rappel

    function facultatif

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

    (details?: object) => void

    • détails

      objet facultatif

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

      • nom

        chaîne

        Nom du cookie qui a été supprimé.

      • partitionKey

        CookiePartitionKey facultatif

        Chrome 119 ou version ultérieure

        Clé de partitionnement pour la lecture ou la modification des cookies à l'aide de l'attribut partitionné.

      • storeId

        chaîne

        Identifiant du magasin de cookies où le cookie a été supprimé.

      • url

        chaîne

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

Renvoie

  • Promise<object | indéfini>

    Chrome 88 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

set()

Promise 
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 la définition du cookie.

    • 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 nombre de secondes écoulées 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. Ce champ est vide par défaut en cas d'omission.

    • partitionKey

      CookiePartitionKey facultatif

      Chrome 119 et versions ultérieures

      Clé de partitionnement pour la lecture ou la modification des cookies à l'aide de l'attribut partitionné.

    • chemin d'accès

      chaîne facultatif

      Chemin du cookie. La valeur par défaut correspond à la partie 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 "unspecified" (non spécifié). Dans ce cas, 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 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

      chaîne facultatif

      Valeur du cookie. Ce champ est vide par défaut en cas d'omission.

  • rappel

    function facultatif

    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. 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 (version 88 ou ultérieure)

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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é. 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, générant ainsi une seconde notification avec "cause". "explicite".

Paramètres

  • rappel

    fonction

    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 défini ou supprimé.

      • supprimé

        booléen

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