CookieStore: change — Ereignis · JavaScript-Referenz

Signatur

cookieStore.addEventListener("change", handler)

Beschreibung

Das change-Ereignis wird am globalen cookieStore-Objekt (window.cookieStore) ausgelöst, wenn sich ein Cookie ändert, das für das aktuelle Dokument sichtbar ist. Dabei ist egal, ob die Änderung über die Cookie Store API, über document.cookie oder über einen Set-Cookie-Header einer HTTP-Antwort passiert ist.

Der Handler bekommt ein CookieChangeEvent. Dessen Eigenschaft changed ist ein Array mit neu gesetzten oder geänderten Cookies, deleted ein Array mit gelöschten Cookies. Jeder Eintrag ist ein Objekt mit Feldern wie name, value, domain, path, expires, secure, sameSite und partitioned. Bei gelöschten Cookies sind in der Regel nur name (und eventuell weitere Metadaten) gesetzt, value fehlt.

Nützlich ist das Ereignis, um den Anmeldestatus über mehrere Tabs abzugleichen, auf abgelaufene Sitzungs-Cookies zu reagieren oder Einwilligungs-Cookies zu beobachten. Früher musste man dafür document.cookie regelmäßig abfragen. Registrieren kann man den Handler mit cookieStore.addEventListener("change", handler) oder über die Eigenschaft cookieStore.onchange.

In Service Workern gibt es dieses Ereignis nicht. Dort nutzt man stattdessen das cookiechange-Ereignis am ServiceWorkerGlobalScope, zusammen mit registration.cookies.subscribe().

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"change"`.
$handler Pflicht	(event: CookieChangeEvent) => void		Callback, das ein `CookieChangeEvent` mit den Arrays `changed` und `deleted` erhält.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal` (zum Entfernen über einen `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein CookieChangeEvent.

Beispiele

Änderungen mit addEventListener protokollieren

const onCookieChange = (event) => {
  for (const cookie of event.changed) {
    console.log(`Gesetzt: ${cookie.name} = ${cookie.value}`);
  }
  for (const cookie of event.deleted) {
    console.log(`Gelöscht: ${cookie.name}`);
  }
};

cookieStore.addEventListener("change", onCookieChange);

// Änderung auslösen
await cookieStore.set("theme", "dark");
await cookieStore.delete("theme");

Gesetzt: theme = dark Gelöscht: theme

Abmeldung in allen Tabs erkennen (onchange-Eigenschaft)

cookieStore.onchange = ({ deleted }) => {
  const loggedOut = deleted.some((c) => c.name === "session_id");
  if (loggedOut) {
    console.log("Sitzung beendet – Weiterleitung zum Login");
    location.assign("/login");
  }
};

Sitzung beendet – Weiterleitung zum Login

Listener mit removeEventListener bzw. AbortController entfernen

const controller = new AbortController();

const handler = (event) => {
  const consent = event.changed.find((c) => c.name === "consent");
  if (consent) {
    console.log("Einwilligung aktualisiert:", consent.value);
    controller.abort(); // danach nicht mehr lauschen
  }
};

cookieStore.addEventListener("change", handler, { signal: controller.signal });

await cookieStore.set({ name: "consent", value: "analytics", expires: Date.now() + 864e5 });

// Alternativ klassisch:
// cookieStore.removeEventListener("change", handler);

Einwilligung aktualisiert: analytics

Funktionsprüfung mit Rückfall auf Polling

if ("cookieStore" in window) {
  cookieStore.addEventListener("change", (e) => console.log("Änderung:", e.changed, e.deleted));
} else {
  let last = document.cookie;
  setInterval(() => {
    if (document.cookie !== last) {
      last = document.cookie;
      console.log("Cookies geändert (Polling)");
    }
  }, 1000);
}

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser unterstützen die API seit Version 87. Safari (ab 18.4) und Firefox (ab 140) kamen deutlich später dazu. Vorher immer mit "cookieStore" in window prüfen.
Nur sichere Kontexte: cookieStore gibt es nur über HTTPS bzw. localhost.
HttpOnly-Cookies sind für JavaScript unsichtbar. Für sie wird kein change-Ereignis ausgelöst.
Ein abgelaufenes Cookie erscheint in deleted. Wird ein Cookie mit einem Ablaufdatum in der Vergangenheit gesetzt, zählt das ebenfalls als Löschung.
Das Ereignis kommt asynchron. Es ist nicht garantiert, dass es sofort nach await cookieStore.set() ausgelöst wird. Mehrere Änderungen können auch in einem Ereignis zusammengefasst werden.
Es gibt das Ereignis nur im Fenster-Kontext. In Service Workern stattdessen cookiechange in Verbindung mit CookieStoreManager.subscribe() verwenden.
Sicherheit: Cookie-Werte stammen möglicherweise vom Server oder aus fremden Subdomains. Sie nicht ungeprüft in innerHTML einsetzen (XSS-Gefahr).

Siehe auch

CookieStore CookieChangeEvent CookieStore.prototype.set() CookieStore.prototype.delete() CookieStore.prototype.get() ServiceWorkerGlobalScope: cookiechange Document.cookie EventTarget.addEventListener()