browser.cookies

Beschrijving

Gebruik de chrome.cookies API om cookies op te vragen en aan te passen en om een melding te krijgen als ze worden gewijzigd.

Rechten

cookies

Als je de cookies-API wilt gebruiken, definieer je het recht "cookies" in je manifest, samen met hostrechten voor hosts waarvan je de cookies wilt openen. Voorbeeld:

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

Partitionering

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 bijvoorbeeld dat als site A is ingesloten met een iframe in site B en site C, de ingesloten versies van een gepartitioneerde cookie van A verschillende waarden kunnen hebben op B en C.

Standaard werken alle API-methoden met niet-gepartitioneerde cookies. Je kunt de property partitionKey gebruiken om dit gedrag te overschrijven.

Ga naar Opslag en cookies voor meer informatie over de algemene impact van partitionering voor extensies.

Voorbeelden

Je vindt een eenvoudig voorbeeld van het gebruik van de cookies-API in de directory examples/api/cookies. Ga naar Samples voor andere voorbeelden en hulp bij het bekijken van de broncode.

Typen

Vertegenwoordigt informatie over een HTTP-cookie.

Eigenschappen

  • domein

    tekenreeks

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

  • expirationDate

    number optioneel

    De vervaldatum van de cookie als het aantal seconden sinds het Unix-tijdvak. Niet verstrekt voor sessiecookies.

  • hostOnly

    booleaans

    Waar als de cookie een host-only cookie is (dat wil zeggen dat de host van een verzoek exact moet overeenkomen met het domein van de cookie).

  • httpOnly

    booleaans

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

  • name

    tekenreeks

    De naam van de cookie.

  • partitionKey

    CookiePartitionKey optioneel

    Chrome 119+ browser.* sinds Chrome 148

    De partitiesleutel voor het lezen of aanpassen van cookies met het kenmerk Partitioned.

  • pad

    tekenreeks

    Het pad van de cookie.

  • sameSite

    SameSiteStatus

    Chrome 51+ browser.* sinds Chrome 148

    De SameSite-status van de cookie (dat wil zeggen of de cookie wordt gestuurd met cross-site-verzoeken).

  • veilig

    booleaans

    Waar als de cookie is gemarkeerd als Beveiligd (dat wil zeggen dat het bereik is beperkt tot beveiligde kanalen, meestal HTTPS).

  • sessie

    booleaans

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

  • storeId

    tekenreeks

    De ID van de cookieopslag die deze cookie bevat, zoals aangegeven in getAllCookieStores().

  • waarde

    tekenreeks

    De waarde van de cookie.

CookieDetails

Chrome 88+ browser.* sinds Chrome 148

Informatie om de cookie te identificeren.

Eigenschappen

  • name

    tekenreeks

    De naam van de cookie die moet worden geopend.

  • partitionKey

    CookiePartitionKey optioneel

    Chrome 119+ browser.* sinds Chrome 148

    De partitiesleutel voor het lezen of aanpassen van cookies met het kenmerk Partitioned.

  • storeId

    tekenreeks optioneel

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

  • url

    tekenreeks

    De URL waaraan de cookie is gekoppeld. Dit argument kan een volledige URL zijn. In dat geval worden alle gegevens na het URL-pad (bijvoorbeeld de querytekenreeks) genegeerd. Als de hostrechten voor deze URL niet zijn gespecificeerd in het manifestbestand, mislukt de API-aanroep.

CookiePartitionKey

Chrome 119+ browser.* sinds Chrome 148

Vertegenwoordigt de partitiesleutel van een gepartitioneerde cookie.

Eigenschappen

  • hasCrossSiteAncestor

    booleaans optioneel

    Chrome 130+ browser.* sinds Chrome 148

    Geeft aan of de cookie is ingesteld in een cross-site context. Dit voorkomt dat een site op het hoogste niveau die is ingesloten in een context van meerdere sites, 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 cookieopslag in de browser. Een incognitovenster gebruikt bijvoorbeeld een andere cookieopslag dan een venster dat niet in de incognitomodus is.

Eigenschappen

  • id

    tekenreeks

    De unieke ID voor de cookie-opslag.

  • tabIds

    number[]

    ID's van alle browsertabbladen die deze cookieopslag delen.

FrameDetails

Chrome 132+ browser.* sinds Chrome 148

Gegevens om het frame te identificeren.

Eigenschappen

  • documentId

    tekenreeks optioneel

    De unieke ID van het document. Als de frameId en/of tabId worden verstrekt, worden ze gevalideerd om overeen te komen met het document dat is gevonden met de verstrekte document-ID.

  • frameId

    number optioneel

    De unieke ID voor het frame binnen het tabblad.

  • tabId

    number optioneel

    De unieke ID van het tabblad met het frame.

OnChangedCause

Chrome 44+ browser.* sinds Chrome 148

De onderliggende reden voor de wijziging van de cookie. Als een cookie is ingevoegd of verwijderd via een expliciete aanroep van chrome.cookies.remove, is de oorzaak expliciet. Als een cookie automatisch is verwijderd omdat deze is verlopen, is de oorzaak 'verlopen'. Als een cookie is verwijderd omdat deze is overschreven met een al verlopen vervaldatum, wordt de oorzaak ingesteld op expired_overwrite. Als een cookie automatisch is verwijderd vanwege garbage collection, is de oorzaak 'evicted'. Als een cookie automatisch is verwijderd vanwege een set-aanroep die de cookie heeft overschreven, is de oorzaak overwrite. Plan je reactie dienovereenkomstig.

Enum

"evicted"

expired

explicit

expired_overwrite

"overwrite"

SameSiteStatus

Chrome 51+ browser.* sinds Chrome 148

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

Enum

"no_restriction"

"lax"

"strict"

"unspecified"

Methoden

get()

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

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

Parameters

Retourzendingen

  • Promise<Cookie | undefined>

    Chrome 88+ browser.* sinds Chrome 148

getAll()

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

Hiermee worden alle cookies uit één cookieopslag opgehaald die overeenkomen met de ingevoerde informatie. De geretourneerde cookies worden gesorteerd, met de cookies met het langste pad bovenaan. Als meerdere cookies dezelfde padlengte hebben, komen de cookies met de vroegste aanmaaktijd eerst. Deze methode haalt alleen cookies op voor domeinen waarvoor de extensie hostrechten heeft.

Parameters

  • details

    object

    Informatie om de cookies te filteren die worden opgehaald.

    • domein

      tekenreeks optioneel

      Beperkt de opgehaalde cookies tot cookies waarvan de domeinen overeenkomen met of subdomeinen zijn van dit domein.

    • name

      tekenreeks optioneel

      Filtert de cookies op naam.

    • partitionKey

      CookiePartitionKey optioneel

      Chrome 119+ browser.* sinds Chrome 148

      De partitiesleutel voor het lezen of aanpassen van cookies met het kenmerk Partitioned.

    • pad

      tekenreeks optioneel

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

    • veilig

      booleaans optioneel

      Filtert de cookies op de property Secure.

    • sessie

      booleaans optioneel

      Filtert sessiecookies versus persistente cookies.

    • storeId

      tekenreeks optioneel

      De cookie-opslag waaruit cookies moeten worden opgehaald. Als je 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.

Retourzendingen

  • Promise<Cookie[]>

    Chrome 88+ browser.* sinds Chrome 148

getAllCookieStores()

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

Toont alle bestaande cookie-opslaglocaties.

Retourzendingen

  • Promise<CookieStore[]>

    Chrome 88+ browser.* sinds Chrome 148

getPartitionKey()

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

De partitiesleutel voor het aangegeven frame.

Parameters

Retourzendingen

  • Promise<object>

remove()

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

Verwijdert een cookie op naam.

Parameters

Retourzendingen

  • Promise<object | undefined>

    Chrome 88+ browser.* sinds Chrome 148

set()

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

Stelt een cookie met de ingevoerde cookiegegevens in. Kan gelijkwaardige cookies overschrijven als deze bestaan.

Parameters

  • details

    object

    Informatie over de cookie die wordt ingesteld.

    • domein

      tekenreeks optioneel

      Het domein van de cookie. Als je dit weglaat, wordt de cookie een host-only cookie.

    • expirationDate

      number optioneel

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

    • httpOnly

      booleaans optioneel

      Of de cookie moet worden gemarkeerd als HttpOnly. De standaard is onwaar.

    • name

      tekenreeks optioneel

      De naam van de cookie. Standaard leeg als dit wordt weggelaten.

    • partitionKey

      CookiePartitionKey optioneel

      Chrome 119+ browser.* sinds Chrome 148

      De partitiesleutel voor het lezen of aanpassen van cookies met het kenmerk Partitioned.

    • pad

      tekenreeks optioneel

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

    • sameSite

      SameSiteStatus optioneel

      Chrome 51+ browser.* sinds Chrome 148

      De SameSite-status van de cookie. De standaardwaarde is 'unspecified'. Als de parameter wordt weggelaten, wordt de cookie ingesteld zonder een SameSite-kenmerk op te geven.

    • veilig

      booleaans optioneel

      Of de cookie moet worden gemarkeerd als Beveiligd. De standaard is onwaar.

    • storeId

      tekenreeks optioneel

      De ID van de cookieopslag waarin de cookie moet worden ingesteld. De cookie wordt standaard ingesteld in de cookieopslag van de huidige uitvoeringscontext.

    • url

      tekenreeks

      De aanvraag-URI die moet worden gekoppeld aan de instelling van de cookie. Deze waarde kan van invloed zijn op de standaard domein- en padwaarden van de gemaakte cookie. Als de hostrechten voor deze URL niet zijn gespecificeerd in het manifestbestand, mislukt de API-aanroep.

    • waarde

      tekenreeks optioneel

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

Retourzendingen

  • Promise<Cookie | undefined>

    Chrome 88+ browser.* sinds Chrome 148

Evenementen

onChanged

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

Wordt geactiveerd als een cookie wordt ingesteld of verwijderd. In een speciaal geval wordt het updaten van de eigenschappen van een cookie geïmplementeerd als een proces in 2 stappen: de cookie die moet worden geüpdatet, wordt eerst helemaal verwijderd, waardoor een melding wordt gegenereerd met de oorzaak 'overschrijven' . Daarna wordt een nieuwe cookie geschreven met de geüpdatete waarden, waardoor een 2e melding wordt gegenereerd met de oorzaak 'explicit'.

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

    (changeInfo: object) => void

    • changeInfo

      object

      • veroorzaken

        OnChangedCause

        De onderliggende reden voor de wijziging van de cookie.

      • koekje

        Cookie

        Informatie over de cookie die is ingesteld of verwijderd.

      • verwijderd

        booleaans

        True als een cookie is verwijderd.