browser.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 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é 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 remplacer 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 Cookies dans le répertoire examples/api/cookies. Pour obtenir d'autres exemples et de l'aide pour afficher le code source, consultez 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 nombre de secondes depuis l'epoch UNIX. Non fourni pour les cookies de session.

  • hostOnly

    booléen

    "True" si le cookie est un cookie d'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 et versions ultérieures browser.* depuis Chrome 148

    Clé de partitionnement pour lire ou modifier les cookies avec l'attribut Partitioned.

  • chemin d'accès

    chaîne

    Chemin d'accès du cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 et versions ultérieures browser.* depuis Chrome 148

    État 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 qu'il est fourni dans getAllCookieStores().

  • valeur

    chaîne

    Valeur du cookie.

CookieDetails

Chrome 88+ browser.* depuis Chrome 148

Détails 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 browser.* depuis Chrome 148

    Clé de partitionnement pour lire ou modifier les cookies avec l'attribut Partitioned.

  • storeId

    chaîne facultatif

    ID du cookie store 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 auquel accéder est associé. Cet argument peut être une URL complète, auquel cas toutes les données suivant 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 browser.* depuis Chrome 148

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

Propriétés

  • hasCrossSiteAncestor

    boolean facultatif

    Chrome 130+ browser.* depuis Chrome 148

    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 SameSite.

  • 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 de navigation privée utilise un espace de stockage de cookies distinct de celui d'une fenêtre de navigation standard.

Propriétés

  • id

    chaîne

    Identifiant unique du cookie store.

  • tabIds

    number[]

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

FrameDetails

Chrome 132+ browser.* depuis Chrome 148

Détails permettant d'identifier le frame.

Propriétés

  • documentId

    chaîne facultatif

    Identifiant unique du document. Si les paramètres frameId et/ou tabId sont fournis, ils seront validés pour correspondre au document trouvé par 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+ browser.* depuis Chrome 148

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 de "cause" sera "explicit". Si un cookie a été automatiquement supprimé en raison de son expiration, "cause" sera "expired". Si un cookie a été supprimé, car il a été écrasé par une date d'expiration déjà expirée, "cause" sera défini sur "expired_overwrite". Si un cookie a été automatiquement supprimé en raison d'un nettoyage de la mémoire, la valeur de "cause" sera "evicted". Si un cookie a été automatiquement supprimé 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 et versions ultérieures browser.* depuis Chrome 148

É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 cookie défini sans l'attribut SameSite.

Énumération

"no_restriction"

"lax"

"strict"

"unspecified"

Méthodes

get()

browser.cookies.get(
  details: CookieDetails,
): Promise<Cookie | undefined>

Récupère des informations sur un seul cookie. Si plusieurs cookies portent le même nom pour l'URL donnée, celui dont le chemin d'accès est le plus long sera renvoyé. Pour les cookies ayant la même longueur de chemin, celui dont l'heure de création est la plus ancienne est renvoyé.

Paramètres

Renvoie

  • Promise<Cookie | undefined>

    Chrome 88+ browser.* depuis Chrome 148

getAll()

browser.cookies.getAll(
  details: object,
): Promise<Cookie[]>

Récupère tous les cookies d'un même magasin de cookies qui correspondent aux informations données. Les cookies renvoyés seront triés, ceux dont le chemin est le plus long apparaissant en premier. Si plusieurs cookies ont la même longueur de chemin, ceux dont l'heure de création est la plus ancienne seront placés en premier. Cette méthode ne récupère que les cookies des domaines pour lesquels l'extension dispose d'autorisations d'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 à celui-ci ou en sont des sous-domaines.

    • nom

      chaîne facultatif

      Filtre les cookies par nom.

    • partitionKey

      CookiePartitionKey facultatif

      Chrome 119 et versions ultérieures browser.* depuis Chrome 148

      Clé de partitionnement pour lire ou modifier les cookies avec l'attribut Partitioned.

    • 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é

      boolean facultatif

      Filtre les cookies en fonction de leur propriété "Secure".

    • session

      boolean facultatif

      Filtre les cookies de session par rapport aux cookies persistants.

    • storeId

      chaîne facultatif

      Le cookie store à partir duquel récupérer les cookies. En cas d'omission, le cookie store 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.

Renvoie

  • Promise<Cookie[]>

    Chrome 88+ browser.* depuis Chrome 148

getAllCookieStores()

browser.cookies.getAllCookieStores(): Promise<CookieStore[]>

Répertorie tous les magasins de cookies existants.

Renvoie

  • &CookieStore[]>

    Chrome 88+ browser.* depuis Chrome 148

getPartitionKey()

Chrome 132+ browser.* depuis Chrome 148 
browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

Clé de partition de l'image indiquée.

Paramètres

Renvoie

  • Promise<object>

remove()

browser.cookies.remove(
  details: CookieDetails,
): Promise<object | undefined>

Supprime un cookie par son nom.

Paramètres

Renvoie

  • Promise<object | undefined>

    Chrome 88+ browser.* depuis Chrome 148

set()

browser.cookies.set(
  details: object,
): Promise<Cookie | undefined>

Définit un cookie avec les données de cookie fournies. Peut écraser les cookies équivalents s'ils existent.

Paramètres

  • détails

    objet

    Détails sur le cookie en cours de définition.

    • domaine

      chaîne facultatif

      Domaine du cookie. S'il est omis, le cookie devient un cookie réservé à l'hôte.

    • expirationDate

      number facultatif

      Date d'expiration du cookie, exprimée en nombre de secondes depuis l'epoch UNIX. En cas d'omission, le cookie devient un cookie de session.

    • httpOnly

      boolean facultatif

      Indique si le cookie doit être marqué comme HttpOnly. Valeur par défaut : "false".

    • nom

      chaîne facultatif

      Nom du cookie. Vide par défaut si omis.

    • partitionKey

      CookiePartitionKey facultatif

      Chrome 119 et versions ultérieures browser.* depuis Chrome 148

      Clé de partitionnement pour lire ou modifier les cookies avec l'attribut Partitioned.

    • chemin d'accès

      chaîne facultatif

      Chemin d'accès du cookie. La valeur par défaut est la partie du chemin d'accès du paramètre d'URL.

    • sameSite

      SameSiteStatus facultatif

      Chrome 51 et versions ultérieures browser.* depuis Chrome 148

      État SameSite du cookie. La valeur par défaut est "unspecified". Autrement dit, si elle est omise, le cookie est défini sans spécifier d'attribut SameSite.

    • sécurisé

      boolean 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 la requête à associer au paramètre du cookie. Cette valeur peut affecter les valeurs par défaut du domaine et du chemin d'accès 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. Vide par défaut si omis.

Renvoie

  • Promise<Cookie | undefined>

    Chrome 88+ browser.* depuis Chrome 148

Événements

onChanged

browser.cookies.onChanged.addListener(
  callback: function,
)

Déclenché lorsqu'un cookie est défini ou supprimé. Dans un cas particulier, 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é, ce qui génère une notification avec la cause "overwrite" . 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

  • callback

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

      • supprimé

        booléen

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