chrome.cookies

Beschreibung

Verwenden Sie die chrome.cookies API, um Cookies abzufragen und zu ändern und um über Änderungen benachrichtigt zu werden.

Berechtigungen

cookies

Um die Cookies API zu verwenden, deklarieren Sie die Berechtigung "cookies" im Manifest zusammen mit den 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 angeben, dass bestimmte Cookies mit dem Ursprung des Frames der obersten Ebene verknüpft werden sollen. Wenn also Website A mit einem iFrame in Website B und Website C eingebettet ist, können die eingebetteten Versionen eines partitionierten Cookies aus A unterschiedliche Werte für B und C haben.

Standardmäßig werden nicht partitionierte Cookies von allen API-Methoden verwendet. Mit dem Attribut partitionKey kann dieses Verhalten überschrieben werden.

Details zu den allgemeinen Auswirkungen der Partitionierung auf 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 zum Anzeigen 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.com“)

  • expirationDate

    Nummer optional

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

  • hostOnly

    boolean

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

  • httpOnly

    boolean

    Dieser Wert ist „True“, wenn das Cookie als „HttpOnly“ gekennzeichnet ist, d.h., dass clientseitige Scripts nicht auf das Cookie zugreifen können.

  • name

    String

    Der Name des Cookies.

  • partitionKey

    CookiePartitionKey optional

    Chrome 119 und höher

    Der Partitionsschlü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 Same-Site-Status des Cookies (d.h., ob das Cookie mit websiteübergreifenden Anfragen gesendet wird).

  • sicher

    boolean

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

  • session

    boolean

    „True“, wenn das Cookie ein Sitzungscookie im Gegensatz zu einem dauerhaften Cookie mit Ablaufdatum ist.

  • storeId

    String

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

  • value

    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 Partitionsschlü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 wird. Standardmäßig wird der Cookiespeicher des aktuellen Ausführungskontexts verwendet.

  • url

    String

    Die URL, der das Cookie für den Zugriff zugeordnet ist. Dieses Argument kann eine vollständige URL sein. In diesem Fall werden alle Daten nach dem URL-Pfad (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 Partitionsschlüssel eines partitionierten Cookies dar.

Attribute

  • topLevelSite

    String optional

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

CookieStore

Stellt einen Cookie-Speicher im Browser dar. Ein Inkognitomodus-Fenster verwendet beispielsweise einen anderen Cookie-Speicher als ein Nicht-Inkognito-Fenster.

Attribute

  • id

    String

    Die eindeutige Kennung für den Cookiespeicher.

  • tabIds

    Nummer[]

    IDs aller Browsertabs, die diesen Cookie-Speicher gemeinsam nutzen.

OnChangedCause

Chrome 44 und höher

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

Enum

"expired_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“, „lax“ auf „SameSite=Lax“ und „strict“ auf „SameSite=Strict“ gesetzt ist. „nicht angegeben“ entspricht einem Cookie, das ohne das SameSite-Attribut gesetzt wurde.

Enum

"no_restriction"

Methoden

get()

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

Ruft Informationen über ein einzelnes Cookie ab. Wenn für die angegebene URL mehr als ein Cookie mit demselben Namen vorhanden ist, 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.

Parameters

  • Details

    CookieDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (cookie?: Cookie)=>void

    • Keks

      Cookie optional

      Enthält Details zum Cookie. Wenn kein solches Cookie gefunden wurde, ist dieser Parameter null.

Rückgaben

  • Promise<Cookie|nicht definiert>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getAll()

Versprechen 
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 sortiert werden. Wenn mehrere Cookies dieselbe Pfadlänge haben, werden die Cookies mit dem frühesten Erstellungszeitpunkt zuerst angezeigt. Mit dieser Methode werden nur Cookies für Domains abgerufen, für die die Erweiterung Hostberechtigungen hat.

Parameters

  • Details

    Objekt

    Informationen zum Filtern der abgerufenen Cookies

    • Domain

      String optional

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

    • name

      String optional

      Filtert die Cookies nach Namen.

    • partitionKey

      CookiePartitionKey optional

      Chrome 119 und höher

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

    • Pfad

      String optional

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

    • sicher

      Boolescher Wert optional

      Filtert die Cookies nach ihrer Secure-Property.

    • session

      Boolescher Wert optional

      Filtert sitzungsspezifische vs. persistente Cookies heraus.

    • storeId

      String optional

      Der Cookiespeicher, aus dem Cookies abgerufen werden sollen. Wenn keine Angabe gemacht wird, wird der Cookiespeicher des aktuellen Ausführungskontexts verwendet.

    • url

      String optional

      Beschränkt die abgerufenen Cookies auf die Cookies, 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 den angegebenen Cookie-Informationen entsprechen.

Rückgaben

  • Promise<Cookie[]>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getAllCookieStores()

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

Listet alle vorhandenen Cookie-Speicher auf.

Parameters

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

      Alle vorhandenen Cookie-Speicher.

Rückgaben

  • Promise<CookieStore[]>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

remove()

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

Löscht ein Cookie anhand seines Namens.

Parameters

  • Details

    CookieDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (details?: object)=>void

    • Details

      Objekt optional

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

      • name

        String

        Der Name des Cookies, das entfernt wurde.

      • partitionKey

        CookiePartitionKey optional

        Chrome 119 und höher

        Der Partitionsschlü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 mit dem entfernten Cookie verknüpfte URL.

Rückgaben

  • Promise<object|undefined>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

set()

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

Setzt ein Cookie mit den angegebenen Cookie-Daten; vorhandene Cookies können überschrieben werden.

Parameters

  • Details

    Objekt

    Details zum gesetzten Cookie

    • Domain

      String optional

      Die Domain des Cookies. Wird er nicht angegeben, wird das Cookie zu einem Nur-Host-Cookie.

    • expirationDate

      Nummer optional

      Das Ablaufdatum des Cookies in Sekunden seit der UNIX-Epoche. Wird er nicht angegeben, wird das Cookie zu einem Sitzungscookie.

    • httpOnly

      Boolescher Wert optional

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

    • name

      String optional

      Der Name des Cookies. Ist standardmäßig leer, wenn keine Angabe gemacht wird.

    • partitionKey

      CookiePartitionKey optional

      Chrome 119 und höher

      Der Partitionsschlüssel zum Lesen oder Ändern von Cookies mit dem Attribut „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 „unspecific“. Das heißt, wenn das Cookie nicht angegeben wird, wird das Cookie ohne Angabe eines SameSite-Attributs festgelegt.

    • sicher

      Boolescher Wert optional

      Gibt an, 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 Cookie-Speicher des aktuellen Ausführungskontexts gespeichert.

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

    • value

      String optional

      Der Wert des Cookies. Ist standardmäßig leer, wenn keine Angabe gemacht wird.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (cookie?: Cookie)=>void

    • Keks

      Cookie optional

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

Rückgaben

  • Promise<Cookie|nicht definiert>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

Veranstaltungen

onChanged

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

Wird ausgelöst, wenn ein Cookie gesetzt oder entfernt wird Beachten Sie als Sonderfall, dass das Aktualisieren der Eigenschaften eines Cookies in einem zweistufigen Prozess implementiert wird: Das zu aktualisierende Cookie wird zuerst vollständig entfernt, woraufhin eine Benachrichtigung mit dem Hinweis „überschreiben“ angezeigt wird. Danach wird ein neues Cookie mit den aktualisierten Werten geschrieben und eine zweite Benachrichtigung mit „cause“ (explizit) generiert.

Parameters

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (changeInfo: object)=>void

    • changeInfo

      Objekt

      • Der zugrunde liegende 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.