chrome.cookies

Beschreibung

Verwenden Sie die chrome.cookies API, um Cookies abzufragen und zu ändern und um benachrichtigt zu werden, wenn sie sich ändern.

Berechtigungen

cookies

Manifest

Wenn Sie die Cookies API verwenden möchten, müssen Sie die Berechtigung „cookies“ in Ihrem Manifest deklarieren, zusammen mit Hostberechtigungen für alle Hosts, auf deren Cookies Sie zugreifen möchten. Beispiel:

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

Partitionierung

Mit partitionierten Cookies kann eine Website festlegen, dass bestimmte Cookies anhand des Ursprungs des Frames auf oberster Ebene verschlüsselt werden sollen. Wenn Website A also mithilfe eines iFrames in Website B und Website C eingebettet ist, kann ein partitioniertes Cookie in jeder Website einen anderen Wert haben.

chrome.cookies unterstützt keine Partitionierung. Das bedeutet, dass alle Methoden Cookies aus allen Partitionen lesen und in alle Partitionen schreiben. Mit der Methode cookies.set() werden Cookies in der Standardpartition gespeichert.

Weitere Informationen zu den allgemeinen Auswirkungen der Partitionierung für Erweiterungen finden Sie unter Speicher und Cookies.

Beispiele

Ein einfaches Beispiel für die Verwendung der Cookies API finden Sie im Verzeichnis examples/api/cookies. Weitere Beispiele und Hilfe beim Ansehen des Quellcodes finden Sie unter Beispiele.

Typen

Stellt Informationen zu einem HTTP-Cookie dar.

Attribute

  • Domain

    String

    Die Domain des Cookies, z.B. „www.google.com“ oder „beispiel.de“.

  • expirationDate

    number optional

    Das Ablaufdatum des Cookies als Anzahl der Sekunden seit der UNIX-Epoche. Nicht für Sitzungscookies verfügbar.

  • hostOnly

    boolean

    „True“, wenn das Cookie ein Host-only-Cookie ist. Das bedeutet, dass der Host einer Anfrage genau mit der Domain des Cookies übereinstimmen muss.

  • httpOnly

    boolean

    „True“, wenn das Cookie als „HttpOnly“ markiert ist. Das bedeutet, dass das Cookie für clientseitige Skripts unzugänglich ist.

  • name

    String

    Der Name des Cookies.

  • partitionKey

    CookiePartitionKey optional

    Chrome 119 und höher

    Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mit dem Attribut „Partitioned“.

  • Pfad

    String

    Der Pfad des Cookies.

  • sameSite

    SameSiteStatus

    Chrome 51 und höher

    Der SameSite-Status des Cookies, d.h. ob das Cookie mit websiteübergreifenden Anfragen gesendet wird.

  • sicher

    boolean

    „True“, wenn das Cookie als „Secure“ gekennzeichnet ist, d.h., sein Bereich ist auf sichere Channels beschränkt, in der Regel HTTPS.

  • Sitzung

    boolean

    „True“, wenn das Cookie ein Sitzungs-Cookie ist und kein persistentes Cookie mit einem Ablaufdatum.

  • storeId

    String

    Die ID des Cookie-Speichers, der dieses Cookie enthält, wie in getAllCookieStores() angegeben.

  • Wert

    String

    Der Wert des Cookies.

CookieDetails

Chrome 88 und höher

Details zur Identifizierung des Cookies.

Attribute

  • name

    String

    Der Name des Cookies, auf das zugegriffen werden soll.

  • partitionKey

    CookiePartitionKey optional

    Chrome 119 und höher

    Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mit dem Attribut „Partitioned“.

  • storeId

    String optional

    Die ID des Cookie-Speichers, in dem nach dem Cookie gesucht werden soll. Standardmäßig wird der Cookie-Speicher des aktuellen Ausführungskontexts verwendet.

  • URL

    String

    Die URL, mit der das Cookie für den Zugriff verknüpft ist. Dieses Argument kann eine vollständige URL sein. In diesem Fall werden alle Daten, die auf den URL-Pfad folgen (z. B. der Abfragestring), einfach ignoriert. Wenn in der Manifestdatei keine Hostberechtigungen für diese URL angegeben sind, schlägt der API-Aufruf fehl.

CookiePartitionKey

Chrome 119 und höher

Stellt den Partitionierungsschlüssel eines partitionierten Cookies dar.

Attribute

  • hasCrossSiteAncestor

    Boolesch optional

    Chrome 130 und höher

    Gibt an, ob das Cookie in einem websiteübergreifenden Kontext gesetzt wurde. So wird verhindert, dass eine Top-Level-Website, die in einem websiteübergreifenden Kontext eingebettet ist, auf Cookies zugreifen kann, die von der Top-Level-Website in einem SameSite-Kontext gesetzt wurden.

  • topLevelSite

    String optional

    Die Top-Level-Website, auf der das partitionierte Cookie verfügbar ist.

CookieStore

Stellt einen Cookie-Speicher im Browser dar. Ein Inkognitomodusfenster verwendet beispielsweise einen separaten Cookie-Speicher als ein Fenster, das nicht im Inkognitomodus geöffnet ist.

Attribute

  • id

    String

    Die eindeutige Kennung für den Cookie-Speicher.

  • tabIds

    number[]

    Kennungen aller Browser-Tabs, die diesen Cookie-Speicher gemeinsam nutzen.

FrameDetails

Chrome 132 und höher

Details zur Identifizierung des Frames.

Attribute

  • documentId

    String optional

    Die eindeutige Kennung für das Dokument. Wenn die frameId und/oder tabId angegeben werden, werden sie validiert, um mit dem Dokument übereinzustimmen, das anhand der angegebenen Dokument-ID gefunden wurde.

  • frameId

    number optional

    Die eindeutige Kennung für den Frame auf dem Tab.

  • tabId

    number optional

    Die eindeutige Kennung für den Tab, der den Frame enthält.

OnChangedCause

Chrome 44 und höher

Der zugrunde liegende Grund für die Änderung des Cookies. Wenn ein Cookie über einen expliziten Aufruf von „chrome.cookies.remove“ eingefügt oder entfernt wurde, ist „cause“ „explicit“. Wenn ein Cookie aufgrund des Ablaufs automatisch entfernt wurde, ist „cause“ (Ursache) „expired“ (abgelaufen). Wenn ein Cookie entfernt wurde, weil es mit einem bereits abgelaufenen Ablaufdatum überschrieben wurde, wird „cause“ auf „expired_overwrite“ gesetzt. Wenn ein Cookie aufgrund der Garbage Collection automatisch entfernt wurde, ist „cause“ (Ursache) „evicted“ (entfernt). Wenn ein Cookie automatisch entfernt wurde, weil es durch einen „set“-Aufruf überschrieben wurde, ist „cause“ (Ursache) „overwrite“ (überschreiben). Planen Sie Ihre Antwort entsprechend.

Enum

"evicted"

„abgelaufen“

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 und höher

Der „SameSite“-Status eines Cookies (https://tools.ietf.org/html/draft-west-first-party-cookies). „no_restriction“ entspricht einem Cookie, das mit „SameSite=None“ festgelegt wurde, „lax“ entspricht „SameSite=Lax“ und „strict“ entspricht „SameSite=Strict“. „unspecified“ entspricht einem Cookie, das ohne das SameSite-Attribut gesetzt wurde.

Enum

"no_restriction"

"lax"

"strict"

"unspecified"

Methoden

get()

Promise 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
): Promise<Cookie | undefined>

Ruft Informationen zu einem einzelnen Cookie ab. Wenn für die angegebene URL mehrere Cookies mit demselben Namen vorhanden sind, wird das Cookie mit dem längsten Pfad zurückgegeben. Bei Cookies mit derselben Pfadlänge wird das Cookie mit der frühesten Erstellungszeit zurückgegeben.

Parameter

  • Details

    CookieDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (cookie?: Cookie) => void

    • Keks

      Cookie optional

      Enthält Details zum Cookie. Dieser Parameter ist „null“, wenn kein entsprechendes Cookie gefunden wurde.

Ausgabe

  • Promise<Cookie | undefined>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getAll()

Promise 
chrome.cookies.getAll(
  details: object,
  callback?: function,
): Promise<Cookie[]>

Ruft alle Cookies aus einem einzelnen Cookie-Speicher ab, die den angegebenen Informationen entsprechen. Die zurückgegebenen Cookies werden sortiert, wobei die mit dem längsten Pfad zuerst angezeigt werden. Wenn mehrere Cookies dieselbe Pfadlänge haben, werden diejenigen mit der frühesten Erstellungszeit zuerst angezeigt. Mit dieser Methode werden nur Cookies für Domains abgerufen, für die die Erweiterung Hostberechtigungen hat.

Parameter

  • Details

    Objekt

    Informationen zum Filtern der abzurufenden Cookies.

    • Domain

      String optional

      Beschränkt die abgerufenen Cookies auf diejenigen, deren Domains mit dieser übereinstimmen oder Subdomains davon sind.

    • name

      String optional

      Filtert die Cookies nach Name.

    • partitionKey

      CookiePartitionKey optional

      Chrome 119 und höher

      Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mit dem Attribut „Partitioned“.

    • Pfad

      String optional

      Beschränkt die abgerufenen Cookies auf diejenigen, deren Pfad genau mit diesem String übereinstimmt.

    • sicher

      Boolesch optional

      Filtert die Cookies nach ihrem Attribut „Secure“.

    • Sitzung

      Boolesch optional

      Filtert Sitzungscookies im Vergleich zu persistenten Cookies heraus.

    • storeId

      String optional

      Der Cookie-Speicher, aus dem Cookies abgerufen werden sollen. Wenn nichts angegeben ist, wird der Cookie-Speicher des aktuellen Ausführungskontexts verwendet.

    • URL

      String optional

      Beschränkt die abgerufenen Cookies auf diejenigen, die mit der angegebenen URL übereinstimmen.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (cookies: Cookie[]) => void

    • Cookies

      Cookie[]

      Alle vorhandenen, nicht abgelaufenen Cookies, die den angegebenen Cookie-Informationen entsprechen.

Ausgabe

  • Promise<Cookie[]>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getAllCookieStores()

Promise 
chrome.cookies.getAllCookieStores(
  callback?: function,
): Promise<CookieStore[]>

Alle vorhandenen Cookie-Speicher auflisten

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      Alle vorhandenen Cookie-Speicher.

Ausgabe

  • Promise<CookieStore[]>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getPartitionKey()

Promise Chrome 132 oder höher 
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

Der Partitionierungsschlüssel für den angegebenen Frame.

Parameter

  • Details

    FrameDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (details: object) => void

    • Details

      Objekt

      Enthält Details zum abgerufenen Partitionsschlüssel.

      • partitionKey

        CookiePartitionKey

        Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mit dem Attribut „Partitioned“.

Ausgabe

  • Promise<object>

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

remove()

Promise 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
): Promise<object | undefined>

Löscht ein Cookie anhand des Namens.

Parameter

  • Details

    CookieDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (details?: object) => void

    • Details

      object optional

      Enthält Details zum entfernten Cookie. Wenn die Entfernung aus irgendeinem Grund fehlgeschlagen ist, wird das Promise abgelehnt.

      • name

        String

        Der Name des entfernten Cookies.

      • partitionKey

        CookiePartitionKey optional

        Chrome 119 und höher

        Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mit dem Attribut „Partitioned“.

      • storeId

        String

        Die ID des Cookie-Speichers, aus dem das Cookie entfernt wurde.

      • URL

        String

        Die URL, die mit dem entfernten Cookie verknüpft ist.

Ausgabe

  • Promise<object | undefined>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

set()

Promise 
chrome.cookies.set(
  details: object,
  callback?: function,
): Promise<Cookie | undefined>

Setzt ein Cookie mit den angegebenen Cookie-Daten. Vorhandene entsprechende Cookies werden möglicherweise überschrieben.

Parameter

  • Details

    Objekt

    Details zum gesetzten Cookie.

    • Domain

      String optional

      Die Domain des Cookies. Wird diese Option nicht angegeben, wird das Cookie zu einem Host-only-Cookie.

    • expirationDate

      number optional

      Das Ablaufdatum des Cookies als Anzahl der Sekunden seit der UNIX-Epoche. Wenn es weggelassen wird, wird das Cookie zu einem Sitzungscookie.

    • httpOnly

      Boolesch optional

      Gibt an, ob das Cookie als „HttpOnly“ markiert werden soll. Die Standardeinstellung ist "false".

    • name

      String optional

      Der Name des Cookies. Wenn keine Angabe gemacht wird, ist das Feld standardmäßig leer.

    • partitionKey

      CookiePartitionKey optional

      Chrome 119 und höher

      Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mit dem Attribut „Partitioned“.

    • Pfad

      String optional

      Der Pfad des Cookies. Der Standardwert ist der Pfadteil des URL-Parameters.

    • sameSite

      SameSiteStatus optional

      Chrome 51 und höher

      Der SameSite-Status des Cookies. Der Standardwert ist „unspecified“. Wenn das Attribut also weggelassen wird, wird das Cookie ohne Angabe eines SameSite-Attributs gesetzt.

    • sicher

      Boolesch optional

      Gibt an, ob das Cookie als „Secure“ gekennzeichnet werden soll. Die Standardeinstellung ist "false".

    • storeId

      String optional

      Die ID des Cookie-Speichers, in dem das Cookie festgelegt werden soll. Standardmäßig wird das Cookie im Cookie-Speicher des aktuellen Ausführungskontexts festgelegt.

    • URL

      String

      Der Anfrage-URI, der mit der Festlegung des Cookies verknüpft werden soll. Dieser Wert kann sich auf die Standardwerte für Domain und Pfad des erstellten Cookies auswirken. Wenn in der Manifestdatei keine Hostberechtigungen für diese URL angegeben sind, schlägt der API-Aufruf fehl.

    • Wert

      String optional

      Der Wert des Cookies. Wenn keine Angabe gemacht wird, ist das Feld standardmäßig leer.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (cookie?: Cookie) => void

    • Keks

      Cookie optional

      Enthält Details zum gesetzten Cookie. Wenn die Einstellung aus irgendeinem Grund fehlgeschlagen ist, wird das Promise abgelehnt.

Ausgabe

  • Promise<Cookie | undefined>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

onChanged

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

Wird ausgelöst, wenn ein Cookie gesetzt oder entfernt wird. Als Sonderfall ist zu beachten, dass die Aktualisierung der Eigenschaften eines Cookies in zwei Schritten erfolgt: Das zu aktualisierende Cookie wird zuerst vollständig entfernt, wodurch eine Benachrichtigung mit dem „cause“-Wert „overwrite“ generiert wird. Anschließend wird ein neues Cookie mit den aktualisierten Werten geschrieben, wodurch eine zweite Benachrichtigung mit dem „Grund“ „explizit“ generiert wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (changeInfo: object) => void

    • changeInfo

      Objekt

      • Der zugrunde liegende Grund für die Änderung des Cookies.

      • Keks

        Cookie

        Informationen zum Cookie, das gesetzt oder entfernt wurde.

      • entfernt

        boolean

        „True“, wenn ein Cookie entfernt wurde.