ExtendableCookieChangeEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface ExtendableCookieChangeEvent extends ExtendableEvent

Beschreibung

ExtendableCookieChangeEvent gehört zur Cookie Store API. Das Ereignisobjekt wird dem cookiechange-Ereignis im ServiceWorkerGlobalScope übergeben, sobald sich Cookies ändern, die der Service Worker vorher über registration.cookies.subscribe() abonniert hat. Im Fenster-Kontext heißt das Gegenstück CookieChangeEvent und wird von cookieStore ausgelöst.

Weil die Schnittstelle von ExtendableEvent erbt, steht event.waitUntil() zur Verfügung. So kann der Service Worker asynchrone Arbeit erledigen, zum Beispiel Caches leeren, offene Tabs benachrichtigen oder eine Sitzung mit dem Server abgleichen, ohne dass der Browser ihn vorher beendet.

Wichtige Eigenschaften (nur lesbar):

changed: Array von CookieListItem-Objekten (name, value, domain, path, expires, secure, sameSite, partitioned) mit neu gesetzten oder geänderten Cookies.
deleted: Array von CookieListItem-Objekten mit gelöschten oder abgelaufenen Cookies. Verlässlich ist hier vor allem name.

Typische Einsatzfälle sind das Erkennen von Logout und Login, das Invalidieren von benutzerspezifischen Cache-Einträgen und das Synchronisieren des Anmeldestatus über alle geöffneten Tabs, ohne ständig nachzufragen (Polling).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, in der Praxis immer `"cookiechange"`. Nur relevant beim manuellen Aufruf von `new ExtendableCookieChangeEvent()`.
$options	{ changed?: CookieListItem[], deleted?: CookieListItem[] }	{ changed: [], deleted: [] }	Optionales Initialisierungsobjekt für den Konstruktor mit den Listen `changed` und `deleted`. Dazu kommen die Optionen von `ExtendableEvent`/`Event`.

Rückgabewert

Typ

ExtendableCookieChangeEvent

Beschreibung

Ein Ereignisobjekt mit den nur lesbaren Arrays changed und deleted sowie der geerbten Methode waitUntil().

Beispiele

Cookie-Änderungen im Service Worker abonnieren

// sw.js
self.addEventListener('activate', (event) => {
  event.waitUntil((async () => {
    await self.registration.cookies.subscribe([
      { name: 'session_id', url: '/' },
      { name: 'theme', url: '/' }
    ]);
    const subs = await self.registration.cookies.getSubscriptions();
    console.log('Aktive Abos:', subs.map((s) => s.name));
  })());
});

Aktive Abos: ["session_id", "theme"]

Logout erkennen, Cache leeren und Tabs informieren

// sw.js
const handleCookieChange = (event) => {
  event.waitUntil((async () => {
    const loggedOut = event.deleted.some((c) => c.name === 'session_id');
    const loggedIn = event.changed.some((c) => c.name === 'session_id');

    if (loggedOut) {
      await caches.delete('user-data');
    }

    const clients = await self.clients.matchAll({ type: 'window' });
    for (const client of clients) {
      client.postMessage({
        type: 'auth-status',
        loggedIn: loggedIn && !loggedOut
      });
    }
    console.log('Geändert:', event.changed.map((c) => c.name));
    console.log('Gelöscht:', event.deleted.map((c) => c.name));
  })());
};

self.addEventListener('cookiechange', handleCookieChange);

Geändert: [] Gelöscht: ["session_id"]

on-Property verwenden und Listener wieder entfernen

// sw.js
const logChange = (event) => {
  for (const { name, value, expires } of event.changed) {
    console.log(`${name} = ${value} (läuft ab: ${expires ? new Date(expires).toISOString() : 'Sitzung'})`);
  }
};

// Variante 1: on-Property
self.oncookiechange = logChange;

// Variante 2: addEventListener / removeEventListener
self.addEventListener('cookiechange', logChange);
self.removeEventListener('cookiechange', logChange);

// Abo komplett beenden
self.addEventListener('message', (e) => {
  if (e.data === 'stop-cookie-watch') {
    e.waitUntil(self.registration.cookies.unsubscribe([{ name: 'theme', url: '/' }]));
  }
});

theme = dark (läuft ab: Sitzung)

Ereignis manuell erzeugen (z. B. für Tests)

// sw.js – nur im Service-Worker-Kontext verfügbar
const testEvent = new ExtendableCookieChangeEvent('cookiechange', {
  changed: [{ name: 'theme', value: 'dark' }],
  deleted: [{ name: 'session_id' }]
});

console.log(testEvent.type, testEvent.changed[0].value, testEvent.deleted.length);

cookiechange dark 1

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-basierte Browser (ab Chrome/Edge 87) unterstützen Cookie-Änderungsereignisse im Service Worker. Firefox und Safari bieten sie bisher nicht an, deshalb vorher prüfen, etwa mit 'cookies' in self.registration oder 'ExtendableCookieChangeEvent' in self.
Nur mit Abonnement: Das Ereignis wird nur für Cookies ausgelöst, die zuvor per registration.cookies.subscribe() abonniert wurden. Die angegebene url muss im Geltungsbereich (scope) des Service Workers liegen, sonst wird das Promise abgelehnt.
Sicherer Kontext: Nur über HTTPS bzw. localhost verfügbar.
HttpOnly-Cookies sind für die Cookie Store API unsichtbar. Für sie gibt es keine Einträge in changed/deleted.
Ein Überschreiben oder Ablaufen kann gebündelt gemeldet werden. Beide Arrays auswerten und nicht davon ausgehen, dass immer nur ein Cookie enthalten ist.
Asynchrone Arbeit immer in event.waitUntil() einschließen, sonst kann der Browser den Service Worker vorzeitig beenden.
Sicherheit: Cookie-Werte (z. B. Sitzungs-IDs) nicht ungefiltert per postMessage an Clients weitergeben. Besser nur den Status übermitteln.

Siehe auch

ExtendableMessageEvent CookieChangeEvent ExtendableEvent RTCDTMFToneChangeEvent IDBVersionChangeEvent