Beschrijving
Gebruik de chrome.cookies API om cookies op te vragen en te wijzigen, en om een melding te ontvangen wanneer ze veranderen.
Toestemmingen
cookiesManifest
Om de cookies-API te gebruiken, moet u de "cookies"-toestemming in uw manifest declareren, samen met hosttoestemmingen voor alle hosts waarvan u de cookies wilt benaderen. Bijvoorbeeld:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
Indeling
Partitioned cookies stellen een website in staat om aan te geven dat bepaalde cookies gekoppeld moeten worden aan de oorsprong van het frame op het hoogste niveau. Dit betekent dat als website A via een iframe is ingesloten in website B en website C, een partitioned cookie in elk van beide een andere waarde kan hebben.
chrome.cookies ondersteunt geen partitionering, wat betekent dat alle methoden cookies lezen en schrijven vanuit alle partities. De methode cookies.set() slaat cookies op in de standaardpartitie.
Zie Opslag en cookies voor meer informatie over de algemene impact van partitionering voor extensies.
Voorbeelden
Een eenvoudig voorbeeld van het gebruik van de cookies-API vindt u in de map examples/api/cookies . Voor andere voorbeelden en hulp bij het bekijken van de broncode, zie Voorbeelden .
Soorten
Cookie
Geeft informatie weer over een HTTP-cookie.
Eigenschappen
- domein
snaar
Het domein van de cookie (bijv. "www.google.com", "example.com").
- vervaldatum
nummer optioneel
De vervaldatum van de cookie wordt weergegeven als het aantal seconden sinds de UNIX-epoch. Niet beschikbaar voor sessiecookies.
- hostOnly
booleaans
Dit is waar als de cookie een host-only cookie is (d.w.z. de host van een verzoek moet exact overeenkomen met het domein van de cookie).
- httpOnly
booleaans
Retourneert 'true' als de cookie is gemarkeerd als HttpOnly (d.w.z. dat de cookie niet toegankelijk is voor client-side scripts).
- naam
snaar
De naam van de cookie.
- partitiesleutel
CookiePartitionKey optioneel
Chrome 119+De partitiesleutel voor het lezen of wijzigen van cookies met het attribuut 'Partitioned'.
- pad
snaar
Het pad van de cookie.
- dezelfde siteChrome 51+
De status van de cookie ten aanzien van dezelfde site (d.w.z. of de cookie wordt meegestuurd met verzoeken van andere sites).
- zeker
booleaans
Dit is waar als de cookie is gemarkeerd als 'Beveiligd' (d.w.z. dat het bereik ervan beperkt is tot beveiligde kanalen, meestal HTTPS).
- sessie
booleaans
Dit is waar als het een sessiecookie betreft, in tegenstelling tot een permanente cookie met een vervaldatum.
- winkel-ID
snaar
De ID van de cookiestore die deze cookie bevat, zoals opgegeven in getAllCookieStores().
- waarde
snaar
De waarde van de cookie.
CookieDetails
Gegevens ter identificatie van de cookie.
Eigenschappen
- naam
snaar
De naam van de cookie waartoe toegang moet worden verkregen.
- partitiesleutel
CookiePartitionKey optioneel
Chrome 119+De partitiesleutel voor het lezen of wijzigen van cookies met het attribuut 'Partitioned'.
- winkel-ID
string optioneel
De ID van de cookieopslag waarin naar de cookie moet worden gezocht. Standaard wordt de cookieopslag van de huidige uitvoeringscontext gebruikt.
- URL
snaar
De URL waaraan de cookie voor toegang is gekoppeld. Dit argument kan een volledige URL zijn; in dat geval worden alle gegevens na het URL-pad (bijvoorbeeld de queryreeks) genegeerd. Als de hostrechten voor deze URL niet in het manifestbestand zijn gespecificeerd, mislukt de API-aanroep.
CookiePartitionKey
Vertegenwoordigt de partitiesleutel van een gepartitioneerde cookie.
Eigenschappen
- heeftCrossSiteAncestor
boolean optioneel
Chrome 130+Geeft aan of de cookie is ingesteld in een context die meerdere sites omvat. Dit voorkomt dat een site op het hoogste niveau, ingebed in een context die meerdere sites omvat, toegang krijgt tot cookies die door de site op het hoogste niveau in een context die slechts één site omvat, zijn ingesteld.
- topLevelSite
string optioneel
De website op het hoogste niveau waar de gepartitioneerde cookie beschikbaar is.
CookieStore
Dit vertegenwoordigt een cookieopslag in de browser. Een incognito-venster gebruikt bijvoorbeeld een aparte cookieopslag ten opzichte van een niet-incognito-venster.
Eigenschappen
- id
snaar
De unieke identificatiecode voor de cookieopslag.
- tabIds
nummer[]
Identificaties van alle browsertabbladen die deze cookieopslag delen.
FrameDetails
Details ter identificatie van het frame.
Eigenschappen
- documentId
string optioneel
De unieke identificatiecode voor het document. Indien frameId en/of tabId worden opgegeven, worden deze gecontroleerd om te zien of ze overeenkomen met het document dat is gevonden op basis van de opgegeven document-ID.
- frameId
nummer optioneel
De unieke identificatiecode voor het frame binnen het tabblad.
- tabId
nummer optioneel
De unieke identificatiecode voor het tabblad dat het frame bevat.
OnChangedCause
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 "cause" "explicit". Als een cookie automatisch is verwijderd vanwege het verlopen van de vervaldatum, is "cause" "expired". Als een cookie is verwijderd omdat deze is overschreven met een reeds verlopen vervaldatum, is "cause" ingesteld op "expired_overwrite". Als een cookie automatisch is verwijderd door garbage collection, is "cause" "evicted". Als een cookie automatisch is verwijderd door een "set"-aanroep die deze heeft overschreven, is "cause" "overwrite". Stem uw reactie hierop af.
Enum
"uitgezet" "verlopen" "expliciet" "verlopen_overschrijven" "overschrijven"
SameSiteStatus
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()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
): Promise<Cookie | undefined>
Haalt informatie op over één specifieke cookie. Als er meer dan één cookie met dezelfde naam bestaat voor de opgegeven URL, wordt de cookie met het langste pad geretourneerd. Bij cookies met hetzelfde pad wordt de cookie met de vroegste aanmaaktijd geretourneerd.
Parameters
Retourneert
Belofte< Cookie | niet gedefinieerd>
Chrome 88+Promises worden alleen ondersteund voor Manifest V3 en later; voor andere platforms moeten callbacks worden gebruikt.
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
): Promise<Cookie[]>
Haalt alle cookies op uit één cookieopslag die overeenkomen met de opgegeven informatie. De geretourneerde cookies worden gesorteerd, waarbij de cookies met het langste pad eerst komen. 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
voorwerp
Information to filter the cookies being retrieved.
- domein
string optioneel
Beperkt de opgehaalde cookies tot die waarvan het domein overeenkomt met of een subdomein is van dit domein.
- naam
string optioneel
Filtert de cookies op naam.
- partitiesleutel
CookiePartitionKey optioneel
Chrome 119+De partitiesleutel voor het lezen of wijzigen van cookies met het attribuut 'Partitioned'.
- pad
string optioneel
Beperkt de opgehaalde cookies tot die waarvan het pad exact overeenkomt met deze tekenreeks.
- zeker
boolean optioneel
Filtert de cookies op basis van hun 'Beveiligd'-eigenschap.
- sessie
boolean optioneel
Filtert sessiecookies uit elkaar en onderscheidt ze van permanente cookies.
- winkel-ID
string optioneel
De cookieopslag waaruit cookies moeten worden opgehaald. Indien deze wordt weggelaten, wordt de cookieopslag van de huidige uitvoeringscontext gebruikt.
- URL
string optioneel
Beperkt de opgehaalde cookies tot die welke overeenkomen met de opgegeven URL.
- terugbelverzoek
functie optioneel
De
callbackparameter ziet er als volgt uit:(cookies: Cookie[]) => void
- cookies
Cookie []
Alle bestaande, nog geldige cookies die overeenkomen met de opgegeven cookie-informatie.
Retourneert
Belofte< Cookie []>
Chrome 88+Promises worden alleen ondersteund voor Manifest V3 en later; voor andere platforms moeten callbacks worden gebruikt.
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
): Promise<CookieStore[]>
Geeft een overzicht van alle bestaande cookie-opslagplaatsen.
Parameters
- terugbelverzoek
functie optioneel
The
callbackparameter looks like:(cookieStores: CookieStore[]) => void
- cookieStores
CookieStore []
Alle bestaande cookiewinkels.
Retourneert
Promise< CookieStore []>
Chrome 88+Promises worden alleen ondersteund voor Manifest V3 en later; voor andere platforms moeten callbacks worden gebruikt.
getPartitionKey()
chrome.cookies.getPartitionKey(
details: FrameDetails,
callback?: function,
): Promise<object>
De partitiesleutel voor het aangegeven frame.
Parameters
- details
- terugbelverzoek
functie optioneel
De
callbackparameter ziet er als volgt uit:(details: object) => void
- details
voorwerp
Bevat details over de opgehaalde partitiesleutel.
- partitiesleutel
De partitiesleutel voor het lezen of wijzigen van cookies met het attribuut 'Partitioned'.
Retourneert
Promise<object>
Promises worden alleen ondersteund voor Manifest V3 en later; voor andere platforms moeten callbacks worden gebruikt.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
): Promise<object | undefined>
Verwijdert een cookie op naam.
Parameters
- details
- terugbelverzoek
functie optioneel
De
callbackparameter ziet er als volgt uit:(details?: object) => void
- details
object optioneel
Bevat details over de verwijderde cookie. Als de verwijdering om welke reden dan ook mislukt, wordt de belofte afgewezen.
- naam
snaar
De naam van de verwijderde cookie.
- partitiesleutel
CookiePartitionKey optional
Chrome 119+De partitiesleutel voor het lezen of wijzigen van cookies met het attribuut 'Partitioned'.
- winkel-ID
snaar
De ID van de cookiestore waaruit de cookie is verwijderd.
- URL
snaar
De URL die hoort bij de verwijderde cookie.
Retourneert
Promise<object | undefined>
Chrome 88+Promises worden alleen ondersteund voor Manifest V3 en later; voor andere platforms moeten callbacks worden gebruikt.
set()
chrome.cookies.set(
details: object,
callback?: function,
): Promise<Cookie | undefined>
Stelt een cookie in met de opgegeven cookiegegevens; bestaande, gelijkwaardige cookies kunnen worden overschreven.
Parameters
- details
voorwerp
Details over de geplaatste cookie.
- domein
string optioneel
Het domein van de cookie. Indien weggelaten, wordt de cookie een host-only cookie.
- vervaldatum
nummer optioneel
De vervaldatum van de cookie wordt weergegeven als het aantal seconden sinds de UNIX-epoch. Indien deze datum wordt weggelaten, wordt de cookie een sessiecookie.
- httpOnly
boolean optioneel
Of de cookie als HttpOnly moet worden gemarkeerd. Standaard is dit false.
- naam
string optioneel
De naam van de cookie. Standaard leeg als deze wordt weggelaten.
- partitiesleutel
CookiePartitionKey optioneel
Chrome 119+De partitiesleutel voor het lezen of wijzigen van cookies met het attribuut 'Partitioned'.
- pad
string optioneel
Het pad van de cookie. Standaard is dit het padgedeelte van de URL-parameter.
- dezelfde site
SameSiteStatus optioneel
Chrome 51+De SameSite-status van de cookie. Standaard is deze "niet gespecificeerd", d.w.z. als deze wordt weggelaten, wordt de cookie ingesteld zonder een SameSite-attribuut te specificeren.
- zeker
boolean optioneel
Of de cookie als 'Beveiligd' moet worden gemarkeerd. Standaard is dit 'false'.
- winkel-ID
string optioneel
De ID van de cookieopslag waarin de cookie moet worden geplaatst. Standaard wordt de cookie geplaatst in de cookieopslag van de huidige uitvoeringscontext.
- URL
snaar
De request-URI die gekoppeld moet worden aan het instellen van de cookie. Deze waarde kan van invloed zijn op de standaarddomein- en padwaarden van de aangemaakte cookie. Als de hostrechten voor deze URL niet in het manifestbestand zijn gespecificeerd, mislukt de API-aanroep.
- waarde
string optioneel
De waarde van de cookie. Standaard leeg als deze wordt weggelaten.
- terugbelverzoek
functie optioneel
De
callbackparameter ziet er als volgt uit:(cookie?: Cookie) => void
- koekje
Cookie optioneel
Bevat details over de ingestelde cookie. Als het instellen om welke reden dan ook mislukt, wordt de promise afgewezen.
Retourneert
Belofte< Cookie | niet gedefinieerd>
Chrome 88+Promises worden alleen ondersteund voor Manifest V3 en later; voor andere platforms moeten callbacks worden gebruikt.
Evenementen
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
Deze gebeurtenis wordt geactiveerd wanneer een cookie wordt ingesteld of verwijderd. Let op: het bijwerken van de eigenschappen van een cookie gebeurt in twee stappen: eerst wordt de bij te werken cookie volledig verwijderd, wat een melding genereert met de "oorzaak" "overschrijven". Vervolgens wordt een nieuwe cookie met de bijgewerkte waarden aangemaakt, wat een tweede melding genereert met de "oorzaak" "expliciet".
Parameters
- terugbelverzoek
functie
De
callbackparameter ziet er als volgt uit:(changeInfo: object) => void
- changeInfo
voorwerp
- oorzaak
De onderliggende reden voor de wijziging van de cookie.
- koekje
Informatie over de cookie die is ingesteld of verwijderd.
- VERWIJDERD
booleaans
Dit is waar als een cookie is verwijderd.