CookieStoreManager.subscribe() — Methode · JavaScript-Referenz

Signatur

CookieStoreManager.prototype.subscribe(subscriptions)

Beschreibung

subscribe() ist Teil der Cookie Store API. Die Methode wird über ServiceWorkerRegistration.cookies aufgerufen, also über ein CookieStoreManager-Objekt, und legt fest, welche Cookies der Service Worker beobachtet. Ändert sich ein passendes Cookie oder wird es gelöscht, bekommt der Service Worker ein cookiechange-Ereignis vom Typ ExtendableCookieChangeEvent, und zwar auch dann, wenn gerade keine Seite geöffnet ist.

Anders als im Fenster-Kontext, wo man mit cookieStore.addEventListener("change", …) einfach mithört, muss ein Service Worker vorher genau angeben, welche Cookies ihn interessieren. Jede Anmeldung besteht aus einem Cookie-Namen (name) und einer URL (url). Die URL muss im Geltungsbereich (scope) der Registrierung liegen.

Typische Einsätze sind: Sitzungs- oder Anmelde-Cookies überwachen und bei einer Abmeldung den Cache leeren, Einstellungen synchronisieren oder Push-Abos anpassen. Am besten meldet man sich im install- oder activate-Ereignis des Service Workers an. Die Anmeldungen bleiben mit der Registrierung erhalten, bis sie mit unsubscribe() entfernt werden.

Parameter

Name	Typ	Default	Beschreibung
$subscriptions Pflicht	Array<{ name?: string, url?: string }>		Liste von Anmelde-Objekten. `name`: Name des Cookies, das beobachtet werden soll. `url`: URL, für die das Cookie gelten muss. Ohne Angabe wird der `scope` der Registrierung verwendet. Die URL muss innerhalb des `scope` liegen.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das ohne Wert erfüllt wird, sobald die Anmeldung gespeichert ist. Es wird mit einem TypeError abgelehnt, wenn eine URL nicht zum scope der Registrierung passt.

Beispiele

Anmeldung im Service Worker beim Aktivieren

// sw.js
self.addEventListener("activate", (event) => {
  event.waitUntil(
    self.registration.cookies.subscribe([
      { name: "session_id", url: "/" },
      { name: "theme" } // url = scope der Registrierung
    ])
  );
});

self.addEventListener("cookiechange", (event) => {
  for (const cookie of event.changed) {
    console.log("Geändert:", cookie.name, cookie.value);
  }
  for (const cookie of event.deleted) {
    console.log("Gelöscht:", cookie.name);
  }
});

Geändert: theme dark Gelöscht: session_id

Bei Abmeldung (Cookie gelöscht) den Cache leeren

// sw.js
self.addEventListener("install", (event) => {
  event.waitUntil(
    self.registration.cookies.subscribe([{ name: "session_id" }])
  );
});

self.addEventListener("cookiechange", (event) => {
  const loggedOut = event.deleted.some((c) => c.name === "session_id");
  if (loggedOut) {
    event.waitUntil(
      caches.keys().then((keys) =>
        Promise.all(keys.map((key) => caches.delete(key)))
      )
    );
  }
});

Anmeldung von der Seite aus mit Funktionsprüfung

// main.js (Fenster-Kontext)
const subscribeCookies = async () => {
  if (!("serviceWorker" in navigator)) return;
  const registration = await navigator.serviceWorker.ready;

  if (!registration.cookies) {
    console.warn("CookieStoreManager wird nicht unterstützt.");
    return;
  }

  try {
    await registration.cookies.subscribe([{ name: "cart", url: "/shop/" }]);
    const subs = await registration.cookies.getSubscriptions();
    console.log(subs);
  } catch (err) {
    console.error("Anmeldung fehlgeschlagen:", err);
  }
};

subscribeCookies();

[{ name: "cart", url: "https://example.com/shop/" }]

// Wichtig · Fallstricke

Kompatibilität: Vollständig nur in Chromium-Browsern (Chrome/Edge ab 87). Andere Browser setzen die Cookie Store API teils nur im Fenster-Kontext um. Vor dem Aufruf mit if (registration.cookies) prüfen, ob die Funktion vorhanden ist.
Funktioniert nur in einem sicheren Kontext (HTTPS oder localhost).
Eine url außerhalb des scope der Registrierung führt zu einem TypeError. Relative URLs werden gegen die Adresse des Service-Worker-Skripts aufgelöst.
HttpOnly-Cookies lösen zwar Ereignisse aus, ihr Wert ist aber je nach Browser nicht lesbar. Sicherheitsrelevante Entscheidungen deshalb nicht nur auf dem Cookie-Wert aufbauen.
Wenn man sich mehrmals mit derselben Kombination aus Name und URL anmeldet, entsteht kein Duplikat. Die Anmeldungen bleiben erhalten, bis man unsubscribe() aufruft oder die Registrierung entfernt wird.
Den Aufruf in event.waitUntil() einpacken, damit der Service Worker nicht beendet wird, bevor die Anmeldung gespeichert ist.

Siehe auch

CookieStoreManager CookieStoreManager.unsubscribe() CookieStoreManager.getSubscriptions() ExtendableCookieChangeEvent CookieStore ServiceWorkerRegistration