chroom.cookies

Beschrijving

Gebruik de chrome.cookies API om cookies op te vragen en te wijzigen, en om een ​​melding te krijgen wanneer ze veranderen.

Machtigingen

cookies

Om de cookies-API te gebruiken, geeft u de toestemming voor "cookies" in uw manifest aan, samen met de hostrechten voor alle hosts waarvan u toegang wilt krijgen tot de cookies. Bijvoorbeeld:

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}

Partitioneren

Met gepartitioneerde cookies kan een site aangeven dat bepaalde cookies moeten worden gekoppeld aan de oorsprong van het frame op het hoogste niveau. Dit betekent dat als site A bijvoorbeeld is ingesloten met behulp van een iframe in site B en site C, de ingebedde versies van een gepartitioneerde cookie van A verschillende waarden kunnen hebben op B en C.

Standaard werken alle API-methoden met niet-gepartitioneerde cookies. De eigenschap partitionKey kan worden gebruikt om dit gedrag te overschrijven.

Voor details over de algemene impact van het partitioneren van extensies, zie Opslag en cookies .

Voorbeelden

Een eenvoudig voorbeeld van het gebruik van de cookies-API vindt u in de map example/api/cookies . Zie Voorbeelden voor andere voorbeelden en voor hulp bij het bekijken van de broncode.

Soorten

Vertegenwoordigt informatie over een HTTP-cookie.

Eigenschappen

  • domein

    snaar

    Het domein van de cookie (bijvoorbeeld "www.google.com", "example.com").

  • vervaldatum

    nummer optioneel

    De vervaldatum van de cookie als het aantal seconden sinds het UNIX-tijdperk. Niet voorzien voor sessiecookies.

  • alleen host

    Booleaans

    Waar als de cookie een cookie is die alleen voor de host geldt (dat wil zeggen dat de host van een verzoek exact moet overeenkomen met het domein van de cookie).

  • httpAlleen

    Booleaans

    Waar als de cookie is gemarkeerd als HttpOnly (dat wil zeggen dat de cookie niet toegankelijk is voor scripts aan de clientzijde).

  • naam

    snaar

    De naam van het koekje.

  • partitiesleutel

    CookiePartitionKey optioneel

    Chroom 119+

    De partitiesleutel voor het lezen of wijzigen van cookies met het gepartitioneerde kenmerk.

  • pad

    snaar

    Het pad van het koekje.

  • Chroom 51+

    De status van de cookie op dezelfde site (dat wil zeggen of de cookie wordt verzonden met cross-site verzoeken).

  • zeker

    Booleaans

    Waar als de cookie als Veilig is gemarkeerd (dat wil zeggen dat de reikwijdte ervan beperkt is tot beveiligde kanalen, doorgaans HTTPS).

  • sessie

    Booleaans

    Waar als de cookie een sessiecookie is, in tegenstelling tot een permanente cookie met een vervaldatum.

  • winkelId

    snaar

    De ID van de cookiewinkel die deze cookie bevat, zoals opgegeven in getAllCookieStores().

  • waarde

    snaar

    De waarde van het cookie.

CookieDetails

Chroom 88+

Details om de cookie te identificeren.

Eigenschappen

  • naam

    snaar

    De naam van de cookie waartoe toegang moet worden verkregen.

  • partitiesleutel

    CookiePartitionKey optioneel

    Chroom 119+

    De partitiesleutel voor het lezen of wijzigen van cookies met het gepartitioneerde kenmerk.

  • winkelId

    tekenreeks optioneel

    De ID van de cookiewinkel waarin naar de cookie moet worden gezocht. Standaard wordt de cookieopslag van de huidige uitvoeringscontext gebruikt.

  • URL

    snaar

    De URL waarmee de cookie waartoe toegang moet worden verkregen, is gekoppeld. Dit argument kan een volledige URL zijn, in welk geval alle gegevens die het URL-pad volgen (bijvoorbeeld de queryreeks) eenvoudigweg worden genegeerd. Als er geen hostmachtigingen voor deze URL zijn opgegeven in het manifestbestand, mislukt de API-aanroep.

CookiePartitionKey

Chroom 119+

Vertegenwoordigt de partitiesleutel van een gepartitioneerde cookie.

Eigenschappen

  • heeftCrossSiteAncestor

    Booleaans optioneel

    In behandeling

    Geeft aan of de cookie is ingesteld in een cross-cross-site context. Dit voorkomt dat een site op het hoogste niveau die is ingebed in een cross-site context toegang krijgt tot cookies die zijn ingesteld door de site op het hoogste niveau in een context van dezelfde site.

  • topLevelSite

    tekenreeks optioneel

    De site op het hoogste niveau waarin de gepartitioneerde cookie beschikbaar is.

CookieStore

Vertegenwoordigt een cookie-opslag in de browser. Een venster in de incognitomodus gebruikt bijvoorbeeld een aparte cookieopslag dan een niet-incognitovenster.

Eigenschappen

  • Identiteitskaart

    snaar

    De unieke identificatie voor de cookiewinkel.

  • tabbladID's

    nummer[]

    Identificatiegegevens van alle browsertabbladen die deze cookieopslag delen.

OnChangedCause

Chroom 44+

De onderliggende reden achter de wijziging van de cookie. Als een cookie is geplaatst of verwijderd via een expliciete aanroep van "chrome.cookies.remove", zal "oorzaak" "expliciet" zijn. Als een cookie vanwege de vervaldatum automatisch is verwijderd, wordt ‘oorzaak’ ‘verlopen’. Als een cookie is verwijderd omdat deze is overschreven met een reeds verlopen vervaldatum, wordt 'oorzaak' ingesteld op 'expired_overwrite'. Als een cookie automatisch werd verwijderd vanwege het verzamelen van afval, wordt "oorzaak" "uitgezet". Als een cookie automatisch werd verwijderd vanwege een "set"-aanroep die de cookie overschreef, zal "oorzaak" "overschrijven" zijn. Plan uw reactie dienovereenkomstig.

Enum

"uitgezet"

"verlopen"

"expliciet"

"verlopen_overschrijven"

"overschrijven"

SameSiteStatus

Chroom 51+

De 'SameSite'-status van een cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' komt overeen met een cookie die is ingesteld met 'SameSite=None', 'lax' met 'SameSite=Lax' en 'strict' met 'SameSite=Strict'. 'unspecified' komt overeen met een cookie die is ingesteld zonder het SameSite-attribuut.

Enum

"geen_beperking"

"laks"

"streng"

"niet gespecificeerd"

Methoden

get()

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

Haalt informatie op over een enkele cookie. Als er meer dan één cookie met dezelfde naam bestaat voor de opgegeven URL, wordt degene met het langste pad geretourneerd. Voor cookies met dezelfde padlengte wordt de cookie met de vroegste aanmaaktijd geretourneerd.

Parameters

  • details

    Cookiedetails

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (cookie?: Cookie) => void

    • koekje

      Koekje optioneel

      Bevat details over de cookie. Deze parameter is nul als een dergelijke cookie niet is gevonden.

Retouren

  • Beloof < Koekje | ongedefinieerd>

    Chroom 88+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

getAll()

Belofte
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

Haalt alle cookies op uit één enkele cookie-opslag die overeenkomen met de opgegeven informatie. De geretourneerde cookies worden gesorteerd, waarbij de cookies met het langste pad bovenaan staan. Als meerdere cookies dezelfde padlengte hebben, zullen degenen met de vroegste aanmaaktijd de eerste zijn. Deze methode haalt alleen cookies op voor domeinen waarvoor de extensie hostrechten heeft.

Parameters

  • details

    voorwerp

    Informatie om de cookies te filteren die worden opgehaald.

    • domein

      tekenreeks optioneel

      Beperkt de opgehaalde cookies tot degenen waarvan de domeinen overeenkomen of subdomeinen hiervan zijn.

    • naam

      tekenreeks optioneel

      Filtert de cookies op naam.

    • partitiesleutel

      CookiePartitionKey optioneel

      Chroom 119+

      De partitiesleutel voor het lezen of wijzigen van cookies met het gepartitioneerde kenmerk.

    • pad

      tekenreeks optioneel

      Beperkt de opgehaalde cookies tot degenen waarvan het pad exact overeenkomt met deze tekenreeks.

    • zeker

      Booleaans optioneel

      Filtert de cookies op basis van hun Secure-eigenschap.

    • sessie

      Booleaans optioneel

      Filtert sessie- en permanente cookies uit.

    • winkelId

      tekenreeks optioneel

      De cookiewinkel waaruit cookies kunnen worden opgehaald. Als u dit weglaat, wordt de cookieopslag van de huidige uitvoeringscontext gebruikt.

    • URL

      tekenreeks optioneel

      Beperkt de opgehaalde cookies tot de cookies die overeenkomen met de opgegeven URL.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (cookies: Cookie[]) => void

    • koekjes

      Koekje []

      Alle bestaande, niet-verlopen cookies die overeenkomen met de opgegeven cookie-informatie.

Retouren

  • Beloof < Cookie []>

    Chroom 88+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

getAllCookieStores()

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

Geeft een overzicht van alle bestaande cookiewinkels.

Parameters

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (cookieStores: CookieStore[]) => void

    • cookieWinkels

      CookieStore []

      Alle bestaande cookiewinkels.

Retouren

  • Beloof het< CookieStore []>

    Chroom 88+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

remove()

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

Verwijdert een cookie op naam.

Parameters

  • details

    Cookiedetails

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (details?: object) => void

    • details

      object optioneel

      Bevat details over de cookie die is verwijderd. Als het verwijderen om welke reden dan ook mislukt, is dit "null" en wordt runtime.lastError ingesteld.

      • naam

        snaar

        De naam van de cookie die is verwijderd.

      • partitiesleutel

        CookiePartitionKey optioneel

        Chroom 119+

        De partitiesleutel voor het lezen of wijzigen van cookies met het gepartitioneerde kenmerk.

      • winkelId

        snaar

        De ID van de cookiewinkel waaruit de cookie is verwijderd.

      • URL

        snaar

        De URL die is gekoppeld aan de cookie die is verwijderd.

Retouren

  • Belofte<object | ongedefinieerd>

    Chroom 88+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

set()

Belofte
chrome.cookies.set(
  details: object,
  callback?: function,
)

Stelt een cookie in met de opgegeven cookiegegevens; kan gelijkwaardige cookies overschrijven als deze bestaan.

Parameters

  • details

    voorwerp

    Details over de cookie die wordt geplaatst.

    • domein

      tekenreeks optioneel

      Het domein van de cookie. Als u dit weglaat, wordt de cookie een cookie die alleen voor de host beschikbaar is.

    • vervaldatum

      nummer optioneel

      De vervaldatum van de cookie als het aantal seconden sinds het UNIX-tijdperk. Als u dit weglaat, wordt de cookie een sessiecookie.

    • httpAlleen

      Booleaans optioneel

      Of de cookie gemarkeerd moet worden als HttpOnly. Standaard ingesteld op false.

    • naam

      tekenreeks optioneel

      De naam van het koekje. Standaard leeg als dit wordt weggelaten.

    • partitiesleutel

      CookiePartitionKey optioneel

      Chroom 119+

      De partitiesleutel voor het lezen of wijzigen van cookies met het gepartitioneerde kenmerk.

    • pad

      tekenreeks optioneel

      Het pad van het koekje. Standaard ingesteld op het padgedeelte van de URL-parameter.

    • zelfdeSite

      SameSiteStatus optioneel

      Chroom 51+

      De status van de cookie op dezelfde site. Standaard ingesteld op "niet gespecificeerd", dwz als dit wordt weggelaten, wordt de cookie ingesteld zonder een SameSite-attribuut op te geven.

    • zeker

      Booleaans optioneel

      Of de cookie als veilig moet worden gemarkeerd. Standaard ingesteld op false.

    • winkelId

      tekenreeks optioneel

      De ID van de cookiewinkel waarin de cookie moet worden geplaatst. Standaard wordt de cookie ingesteld in de cookieopslag van de huidige uitvoeringscontext.

    • URL

      snaar

      De verzoek-URI die moet worden gekoppeld aan de instelling van de cookie. Deze waarde kan van invloed zijn op de standaarddomein- en padwaarden van de gemaakte cookie. Als er geen hostmachtigingen voor deze URL zijn opgegeven in het manifestbestand, mislukt de API-aanroep.

    • waarde

      tekenreeks optioneel

      De waarde van het cookie. Standaard leeg als dit wordt weggelaten.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (cookie?: Cookie) => void

    • koekje

      Koekje optioneel

      Bevat details over de cookie die is ingesteld. Als de instelling om welke reden dan ook mislukt, is dit 'null' en wordt runtime.lastError ingesteld.

Retouren

  • Beloof < Koekje | ongedefinieerd>

    Chroom 88+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

Evenementen

onChanged

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

Wordt geactiveerd wanneer een cookie wordt geplaatst of verwijderd. Houd er in een speciaal geval rekening mee dat het bijwerken van de eigenschappen van een cookie wordt geïmplementeerd als een proces van twee stappen: de cookie die moet worden bijgewerkt, wordt eerst volledig verwijderd, waardoor een melding wordt gegenereerd met de "oorzaak" van "overschrijven" . Daarna wordt een nieuwe cookie geschreven met de bijgewerkte waarden, waardoor een tweede melding wordt gegenereerd met "oorzaak" "expliciet".

Parameters

  • terugbellen

    functie

    De callback parameter ziet er als volgt uit: 

    (changeInfo: object) => void

    • wijzigInfo

      voorwerp

      • De onderliggende reden achter de wijziging van de cookie.

      • koekje

        Koekje

        Informatie over de cookie die is geplaatst of verwijderd.

      • VERWIJDERD

        Booleaans

        Waar als een cookie is verwijderd.