chrome.cookies

Beschreibung

Verwenden Sie die chrome.cookies API, um Cookies abzufragen und zu ändern und sich bei Änderungen benachrichtigen zu lassen.

Berechtigungen

cookies

Deklarieren Sie zur Verwendung der Cookies API die Berechtigung "cookies" in Ihrem zusammen mit den Hostberechtigungen für alle Hosts, deren Cookies Sie um darauf zuzugreifen. Beispiel:

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

Partitionierung

Mithilfe von partitionierten Cookies kann eine Website kennzeichnen, dass bestimmte Cookies mit dem Ursprung des Frames auf oberster Ebene. Das heißt, wenn Website A beispielsweise mit einem iFrame auf Website B eingebettet wird, und Website C können die eingebetteten Versionen eines partitionierten Cookies von A auf B und C unterschiedliche Werte haben.

Standardmäßig werden alle API-Methoden mit nicht partitionierten Cookies verarbeitet. Die partitionKey-Property kann dieses Verhalten überschrieben werden.

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

Beispiele

Ein einfaches Beispiel für die Verwendung der Cookies API finden Sie in der examples/api/cookies. Weitere Beispiele und Hilfe bei der Anzeige Den Quellcode finden Sie unter Beispiele.

Typen

Informationen zu einem HTTP-Cookie.

Attribute

  • Domain

    String

    Die Domain des Cookies (z. B. „www.google.com“ oder „beispiel.com“)

  • expirationDate

    Zahl optional

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

  • hostOnly

    boolean

    „True“, wenn das Cookie ein reines Host-Cookie ist (d.h., der Host einer Anfrage muss genau mit der Domain des Cookies übereinstimmen).

  • httpOnly

    boolean

    "True", wenn das Cookie als HttpOnly gekennzeichnet ist, d.h. wenn clientseitige Skripts nicht auf das Cookie zugreifen können.

  • Name

    String

    Der Name des Cookies.

  • partitionKey

    CookiePartitionKey optional

    Chrome 119 oder höher

    Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mithilfe des Attributs "Partitioned"

  • Pfad

    String

    Der Pfad des Cookies.

  • sameSite

    SameSiteStatus

    Chrome 51 und höher

    Der Status des Cookies auf derselben Website (d.h., ob das Cookie mit websiteübergreifenden Anfragen gesendet wird).

  • sicher

    boolean

    „True“, wenn das Cookie als sicher markiert ist (d.h. sein Umfang auf sichere Kanäle beschränkt ist, in der Regel HTTPS).

  • Sitzung

    boolean

    "True", wenn das Cookie ein Sitzungscookie ist, im Gegensatz zu einem dauerhaften 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 (ab Version 88)

Details zur Identifizierung des Cookies.

Attribute

  • Name

    String

    Der Name des Cookies, auf das zugegriffen werden soll.

  • partitionKey

    CookiePartitionKey optional

    Chrome 119 oder höher

    Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mithilfe des Attributs "Partitioned"

  • storeId

    String optional

    Die ID des Cookiespeichers, 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 aufgerufene Cookie 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 oder höher

Stellt den Partitionierungsschlüssel eines partitionierten Cookies dar.

Attribute

  • hasCrossSiteAncestor

    Boolescher Wert optional

    Ausstehend

    Gibt an, ob das Cookie in einem websiteübergreifenden Kontext gesetzt wurde. Dadurch wird verhindert, dass eine Website der obersten Ebene, die in einen websiteübergreifenden Kontext eingebettet ist, auf Cookies zugreift, die von der Top-Level-Website im selben Kontext gesetzt wurden.

  • topLevelSite

    String optional

    Die Website der obersten Ebene, auf der das partitionierte Cookie verfügbar ist.

CookieStore

Ein Cookie-Speicher im Browser. Bei einem Inkognito-Modus-Fenster wird beispielsweise ein anderer Cookie-Speicher als ein Nicht-Inkognito-Fenster verwendet.

Attribute

  • id

    String

    Die eindeutige Kennung für den Cookie-Speicher.

  • tabIds

    Zahl[]

    IDs aller Browsertabs, die denselben Cookie-Speicher nutzen.

OnChangedCause

Chrome (ab Version 44)

Der Grund für die Änderung des Cookies. Wenn ein Cookie durch einen expliziten Aufruf von „chrome.cookies.remove“ eingefügt oder durch einen expliziten Aufruf von „chrome.cookies.remove“ entfernt wurde, „cause“ sind „explizit“. „Ursache“, wenn ein Cookie nach Ablauf automatisch entfernt wurde ist „abgelaufen“. Wenn ein Cookie entfernt wurde, weil es mit einem abgelaufenen Ablaufdatum überschrieben wurde: wird auf „expired_overwrite“ festgelegt. „Ursache“, wenn ein Cookie aufgrund der automatischen Speicherbereinigung automatisch entfernt wurde werden „entfernt“. Ob ein Cookie aufgrund eines „set“-Vorgangs automatisch entfernt wurde die es überschrieben hat, „cause“. wird überschrieben. Planen Sie Ihre Antwort entsprechend.

Enum

SameSiteStatus

Chrome 51 oder höher

„SameSite“ eines Cookies (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' [no_restriction] entspricht einer Cookie-Gruppe mit 'SameSite=None', 'lax' in 'SameSite=Lax' und 'strict' in 'SameSite=Strict'. 'nicht angegeben' entspricht einem Cookie, das ohne das SameSite-Attribut gesetzt wurde.

Enum

Methoden

get()

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

Ruft Informationen zu einem einzelnen Cookie ab. Falls mehrere Cookies mit demselben Namen für die angegebene URL vorhanden sind, wird das Cookie mit dem längsten Pfad zurückgegeben. Bei Cookies mit derselben Pfadlänge wird das Cookie mit dem frühesten Erstellungszeitpunkt 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 solches Cookie gefunden wurde.

Gibt Folgendes zurück:

  • Promise<Cookie | nicht definiert>

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getAll()

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

Ruft alle Cookies aus einem einzelnen Cookie-Speicher ab, die mit den angegebenen Informationen übereinstimmen. Die zurückgegebenen Cookies werden sortiert, wobei die Cookies mit dem längsten Pfad zuerst aufgeführt werden. Falls mehrere Cookies die gleiche Pfadlänge haben, werden die Cookies mit dem frühesten Erstellungszeitpunkt zuerst aufgeführt. Mit dieser Methode werden nur Cookies für Domains abgerufen, für die die Erweiterung Hostberechtigungen hat.

Parameter

  • Details

    Objekt

    Informationen zum Filtern der abgerufenen Cookies.

    • Domain

      String optional

      Die abgerufenen Cookies werden auf diejenigen beschränkt, deren Domains mit dieser übereinstimmen oder Subdomains davon sind.

    • Name

      String optional

      Filtert die Cookies nach Name.

    • partitionKey

      CookiePartitionKey optional

      Chrome 119 oder höher

      Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mithilfe des Attributs "Partitioned"

    • Pfad

      String optional

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

    • sicher

      Boolescher Wert optional

      Die Cookies werden nach ihrer Secure-Property gefiltert.

    • Sitzung

      Boolescher Wert optional

      Filtert Sitzungs- und dauerhafte Cookies heraus.

    • storeId

      String optional

      Der Cookie-Speicher, aus dem Cookies abgerufen werden sollen. Wenn nichts angegeben ist, wird der Cookiespeicher 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

      Kekse[]

      Alle vorhandenen, nicht abgelaufenen Cookies, die mit den angegebenen Cookie-Informationen übereinstimmen.

Gibt Folgendes zurück:

  • Promise<Cookie[]>

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getAllCookieStores()

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

Listet alle vorhandenen Cookie-Speicher auf.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      Alle vorhandenen Cookie-Speicher.

Gibt Folgendes zurück:

  • Promise<CookieStore[]>

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

remove()

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

Löscht ein Cookie nach Name.

Parameter

  • Details

    CookieDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (details?: object) => void

    • Details

      Objekt (optional)

      Enthält Details zum entfernten Cookie. Wenn das Entfernen aus irgendeinem Grund fehlgeschlagen ist, lautet der Wert „null“ und runtime.lastError wird festgelegt.

      • Name

        String

        Der Name des Cookies, das entfernt wurde.

      • partitionKey

        CookiePartitionKey optional

        Chrome 119 oder höher

        Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mithilfe des Attributs "Partitioned"

      • storeId

        String

        Die ID des Cookiespeichers, aus dem das Cookie entfernt wurde.

      • URL

        String

        Die URL, die dem entfernten Cookie zugeordnet ist

Gibt Folgendes zurück:

  • Promise<object | nicht definiert>

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

set()

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

Setzt ein Cookie mit den angegebenen Cookie-Daten. kann äquivalente Cookies überschreiben, sofern sie vorhanden sind.

Parameter

  • Details

    Objekt

    Details zum Cookie, das gesetzt wird.

    • Domain

      String optional

      Die Domain des Cookies. Wenn keine Angabe gemacht wird, wird das Cookie zu einem reinen Host-Cookie.

    • expirationDate

      Zahl optional

      Das Ablaufdatum des Cookies in Sekunden seit der UNIX-Epoche. Wenn keine Angabe gemacht wird, wird das Cookie zu einem Sitzungscookie.

    • httpOnly

      Boolescher Wert optional

      Legt fest, 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 oder höher

      Der Partitionierungsschlüssel zum Lesen oder Ändern von Cookies mithilfe des Attributs "Partitioned"

    • Pfad

      String optional

      Der Pfad des Cookies. Die Standardeinstellung ist der Pfadteil des URL-Parameters.

    • sameSite

      SameSiteStatus optional

      Chrome 51 und höher

      Der SameSite-Status des Cookies. Die Standardeinstellung ist „nicht spezifiziert“. Wird kein Wert angegeben, wird das Cookie ohne Angabe eines SameSite-Attributs gesetzt.

    • sicher

      Boolescher Wert optional

      Legt fest, ob das Cookie als sicher markiert werden soll. Die Standardeinstellung ist "false".

    • storeId

      String optional

      Die ID des Cookiespeichers, in dem das Cookie gespeichert werden soll. Standardmäßig wird das Cookie im Cookiespeicher des aktuellen Ausführungskontexts platziert.

    • URL

      String

      Der Anfrage-URI, der mit der Einstellung des Cookies verknüpft werden soll. Dieser Wert kann sich auf die Standarddomain- und -pfadwerte 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, lautet der Wert „null“ und runtime.lastError wird festgelegt.

Gibt Folgendes zurück:

  • Promise<Cookie | nicht definiert>

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

Ereignisse

onChanged

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

Wird ausgelöst, wenn ein Cookie gesetzt oder entfernt wird In einem 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 der Information „Ursache“ generiert wird. von "überschreiben" . Danach wird ein neues Cookie mit den aktualisierten Werten geschrieben, das eine zweite Benachrichtigung mit „cause“ generiert. „explizit“.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (changeInfo: object) => void

    • changeInfo

      Objekt

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

      • Keks

        Kekse

        Informationen zum Cookie, das gesetzt oder entfernt wurde.

      • entfernt

        boolean

        „True“, wenn ein Cookie entfernt wurde.