CookieStoreManager — Schnittstelle · JavaScript-Referenz

Signatur

interface CookieStoreManager

Beschreibung

CookieStoreManager gehört zur Cookie Store API. Man erzeugt die Schnittstelle nicht selbst, sondern greift über ServiceWorkerRegistration.cookies darauf zu. Im Service Worker ist das self.registration.cookies, auf einer Seite zum Beispiel (await navigator.serviceWorker.ready).cookies.

In einem Fenster-Kontext meldet cookieStore.addEventListener("change", …) Änderungen, solange die Seite geöffnet ist. Ein Service Worker läuft aber nicht dauerhaft. Deshalb muss er im Voraus festlegen, welche Cookies ihn interessieren. Mit diesen Abonnements weckt der Browser den Worker bei einer passenden Änderung auf und löst das Event cookiechange auf dem ServiceWorkerGlobalScope aus. Das Event ist ein ExtendableCookieChangeEvent und enthält die Listen changed und deleted.

Die Schnittstelle hat drei Methoden:

subscribe(subscriptions) – legt Abonnements an. Rückgabewert: Promise<undefined>.
getSubscriptions() – liefert die aktuellen Abonnements als Promise<Array<{name, url}>>.
unsubscribe(subscriptions) – entfernt Abonnements. Rückgabewert: Promise<undefined>.

Typische Einsatzfälle: Caches leeren oder Push-Abonnements aufräumen, wenn ein Sitzungs-Cookie gelöscht wird (Abmeldung). Oder Offline-Daten synchronisieren, wenn sich ein Einstellungs-Cookie ändert.

Parameter

Name	Typ	Default	Beschreibung
$subscriptions Pflicht	Array<{ name?: string, url?: string }>		Wird an `subscribe()` und `unsubscribe()` übergeben: eine Liste von Abonnement-Objekten. `name` ist der Cookie-Name. Fehlt er, gilt das Abonnement für alle Cookies der URL. `url` muss im Geltungsbereich (Scope) der Service-Worker-Registrierung liegen und ist standardmäßig der Scope selbst.

Rückgabewert

Typ

CookieStoreManager

Beschreibung

Wird über ServiceWorkerRegistration.cookies abgerufen. Alle Methoden arbeiten asynchron und geben ein Promise zurück.

Beispiele

Im Service Worker ein Sitzungs-Cookie abonnieren

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

Aktive Abonnements: [{ name: "session_id", url: "https://example.com/" }]

Auf cookiechange reagieren: bei Abmeldung Cache leeren

// sw.js
self.addEventListener('cookiechange', (event) => {
  for (const cookie of event.deleted) {
    if (cookie.name === 'session_id') {
      // Nutzer hat sich abgemeldet: private Daten entfernen
      event.waitUntil(caches.delete('user-data'));
      console.log('Sitzung beendet, Cache gelöscht');
    }
  }
  for (const cookie of event.changed) {
    console.log(`Cookie geändert: ${cookie.name}=${cookie.value}`);
  }
});

Sitzung beendet, Cache gelöscht

Von der Seite aus Abonnements prüfen und kündigen

// main.js (Fenster-Kontext)
const registration = await navigator.serviceWorker.ready;

if ('cookies' in registration) {
  const subs = await registration.cookies.getSubscriptions();
  console.log(`${subs.length} Abonnement(s) vorhanden`);

  // Alle Abonnements wieder entfernen
  await registration.cookies.unsubscribe(subs);
  console.log('Verbleibend:', (await registration.cookies.getSubscriptions()).length);
} else {
  console.log('CookieStoreManager wird nicht unterstützt');
}

1 Abonnement(s) vorhanden Verbleibend: 0

// Wichtig · Fallstricke

Browserunterstützung: Vollständig unterstützt nur in Chromium-basierten Browsern (ab Version 87). Firefox und Safari unterstützen die Cookie Store API bisher gar nicht oder nur teilweise, etwa cookieStore ohne Service-Worker-Abonnements. Deshalb vor der Nutzung immer mit 'cookies' in registration prüfen, ob die Schnittstelle vorhanden ist.
Nur in einem sicheren Kontext (HTTPS oder localhost) verfügbar.
Die url eines Abonnements muss im Scope der Registrierung liegen, sonst wird das Promise mit einem TypeError abgewiesen.
Abonnements hängen an der Registrierung. Sie bleiben über Neustarts des Workers hinweg bestehen und verschwinden erst mit unregister(). Mehrfaches subscribe() mit denselben Werten erzeugt keine Duplikate.
Cookies mit dem Attribut HttpOnly sind für die Cookie Store API unsichtbar. Für sie gibt es keine Events, und ihre Werte lassen sich nicht auslesen.
Arbeiten im cookiechange-Handler mit event.waitUntil() absichern, sonst kann der Browser den Worker vorzeitig beenden.

Siehe auch

CookieStore ContactsManager StorageManager BatteryManager CacheStorage