browser.cookies

Beschreibung

Mit der chrome.cookies API können Sie Cookies abfragen und ändern und sich benachrichtigen lassen, wenn sie sich ändern.

Berechtigungen

cookies

Wenn Sie die Cookies API verwenden möchten, deklarieren Sie die Berechtigung "cookies" in Ihrem Manifest 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 dem Ursprung des Frames auf oberster Ebene zugeordnet werden sollen. Wenn Website A beispielsweise über einen iFrame in Website B und Website C eingebettet ist, können die eingebetteten Versionen eines partitionierten Cookies von A auf B und C unterschiedliche Werte haben.

Standardmäßig werden alle API-Methoden auf nicht partitionierte Cookies angewendet. Mit dem Attribut partitionKey kann dieses Verhalten überschrieben werden.

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 zum Aufrufen 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“, „beispiel.de“).

  • expirationDate

    number 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 Host-only-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. das Cookie ist für clientseitige Skripts nicht zugänglich).

  • name

    String

    Der Name des Cookies.

  • partitionKey

    CookiePartitionKey optional

    Chrome 119 und höher browser.* seit Chrome 148

    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 browser.* seit Chrome 148

    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 Kanäle beschränkt, normalerweise HTTPS).

  • Sitzung

    boolean

    „true“, wenn das Cookie ein Sitzungscookie ist, im Gegensatz zu einem persistenten 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 oder höher browser.* seit Chrome 148

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 browser.* seit Chrome 148

    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 werden soll. Standardmäßig wird der Cookie-Speicher des aktuellen Ausführungskontexts verwendet.

  • URL

    String

    Die URL, mit der das Cookie verknüpft ist, auf das zugegriffen werden soll. 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 browser.* seit Chrome 148

Stellt den Partitionsschlüssel eines partitionierten Cookies dar.

Attribute

  • hasCrossSiteAncestor

    Boolesch optional

    Chrome 130 und höher browser.* seit Chrome 148

    Gibt an, ob das Cookie in einem websiteübergreifenden Kontext gesetzt wurde. Dadurch wird verhindert, dass eine in einem websiteübergreifenden Kontext eingebettete Top-Level-Website auf Cookies zugreift, 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. In einem Inkognitofenster wird beispielsweise ein anderer Cookie-Speicher verwendet als in einem normalen Fenster.

Attribute

  • id

    String

    Die eindeutige Kennung für den Cookie-Speicher.

  • tabIds

    number[]

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

FrameDetails

Chrome 132 und höher browser.* seit Chrome 148

Details zur Identifizierung des Frames.

Attribute

  • documentId

    String optional

    Die eindeutige Kennung für das Dokument. Wenn die „frameId“ und/oder „tabId“ angegeben sind, werden sie mit dem Dokument abgeglichen, das über die angegebene Dokument-ID gefunden wurde.

  • frameId

    number optional

    Die eindeutige Kennung für den Frame innerhalb des Tabs.

  • tabId

    number optional

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

OnChangedCause

Chrome 44 und höher browser.* seit Chrome 148

Der Grund für die Änderung des Cookies. Wenn ein Cookie eingefügt oder über einen expliziten Aufruf von „chrome.cookies.remove“ entfernt wurde, ist „cause“ „explicit“. Wenn ein Cookie aufgrund des Ablaufs automatisch entfernt wurde, lautet die Ursache „expired“. 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 automatischen Speicherbereinigung automatisch entfernt wurde, lautet die Ursache „evicted“. Wenn ein Cookie aufgrund eines „set“-Aufrufs, der es überschrieben hat, automatisch entfernt wurde, ist „cause“ „overwrite“. Planen Sie Ihre Antwort entsprechend.

Enum

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 und höher browser.* seit Chrome 148

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 festgelegt wurde.

Enum

"no_restriction"

"lax"

"strict"

"unspecified"

Methoden

get()

browser.cookies.get(
  details: CookieDetails,
): 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

Ausgabe

  • Promise<Cookie | undefined>

    Chrome 88 oder höher browser.* seit Chrome 148

getAll()

browser.cookies.getAll(
  details: object,
): 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 aufgeführt werden. Wenn mehrere Cookies dieselbe Pfadlänge haben, werden die 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 abgerufenen Cookies.

    • Domain

      String optional

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

    • name

      String optional

      Filtert die Cookies nach Name.

    • partitionKey

      CookiePartitionKey optional

      Chrome 119 und höher browser.* seit Chrome 148

      Der Partitionsschlü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 „Secure“-Attribut.

    • Sitzung

      Boolesch optional

      Filtert Sitzungscookies und persistente 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.

Ausgabe

  • Promise<Cookie[]>

    Chrome 88 oder höher browser.* seit Chrome 148

getAllCookieStores()

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

Listet alle vorhandenen Cookie-Speicher auf.

Ausgabe

  • Promise<CookieStore[]>

    Chrome 88 oder höher browser.* seit Chrome 148

getPartitionKey()

Chrome 132 und höher browser.* seit Chrome 148 
browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

Der Partitionsschlüssel für den angegebenen Frame.

Parameter

Ausgabe

  • Promise<object>

remove()

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

Löscht ein Cookie anhand des Namens.

Parameter

Ausgabe

  • Promise<object | undefined>

    Chrome 88 oder höher browser.* seit Chrome 148

set()

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

Setzt ein Cookie mit den angegebenen Cookie-Daten. Möglicherweise werden vorhandene Cookies überschrieben.

Parameter

  • Details

    Objekt

    Details zum Cookie, das gesetzt wird.

    • Domain

      String optional

      Die Domain des Cookies. Wenn Sie das Feld weglassen, wird das Cookie zu einem Host-only-Cookie.

    • expirationDate

      number optional

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

    • httpOnly

      Boolesch optional

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

    • name

      String optional

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

    • partitionKey

      CookiePartitionKey optional

      Chrome 119 und höher browser.* seit Chrome 148

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

    • Pfad

      String optional

      Der Pfad des Cookies. Standardmäßig wird der Pfadteil des URL-Parameters verwendet.

    • sameSite

      SameSiteStatus optional

      Chrome 51 und höher browser.* seit Chrome 148

      Der SameSite-Status des Cookies. Der Standardwert ist „unspecified“. Wenn der Wert 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 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. Standardmäßig leer, wenn keine Angabe gemacht wird.

Ausgabe

  • Promise<Cookie | undefined>

    Chrome 88 oder höher browser.* seit Chrome 148

Ereignisse

onChanged

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

Wird ausgelöst, wenn ein Cookie gesetzt oder entfernt wird. Beachten Sie, dass das Aktualisieren der Eigenschaften eines Cookies in zwei Schritten erfolgt: Das zu aktualisierende Cookie wird zuerst vollständig entfernt, wodurch eine Benachrichtigung mit der „Ursache“ „Überschreiben“ generiert wird. Anschließend wird ein neues Cookie mit den aktualisierten Werten geschrieben, wodurch eine zweite Benachrichtigung mit „cause“ „explicit“ generiert wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (changeInfo: object) => void

    • changeInfo

      Objekt

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