ServiceWorkerRegistration — Schnittstelle · JavaScript-Referenz

Signatur

interface ServiceWorkerRegistration extends EventTarget

Beschreibung

Ein ServiceWorkerRegistration-Objekt entsteht, wenn eine Seite mit navigator.serviceWorker.register() einen Service Worker anmeldet. Es verbindet ein Service-Worker-Skript mit einem Scope (URL-Präfix) und verwaltet die Lebenszyklus-Zustände des Workers über die Eigenschaften installing, waiting und active.

Wichtige Eigenschaften und Methoden:

scope – der URL-Bereich, den der Service Worker kontrolliert.
installing, waiting, active – die jeweiligen ServiceWorker-Instanzen oder null.
updateViaCache – steuert, ob der HTTP-Cache beim Update-Check verwendet wird ("imports", "all", "none").
navigationPreload – liefert einen NavigationPreloadManager.
pushManager – Zugang zur Push API (PushManager).
update() – prüft manuell auf eine neue Version des Worker-Skripts.
unregister() – hebt die Registrierung auf.
showNotification() / getNotifications() – zeigt bzw. liest System-Benachrichtigungen.
Event updatefound – feuert, sobald ein neuer Worker installiert wird (onupdatefound).

Man verwendet das Interface typischerweise, um Updates zu erkennen und dem Nutzer „Neue Version verfügbar“ anzuzeigen, um Push-Abonnements anzulegen oder um Benachrichtigungen aus dem Hauptthread bzw. dem Worker (self.registration) heraus anzuzeigen.

Rückgabewert

Typ

ServiceWorkerRegistration

Beschreibung

Wird nicht direkt konstruiert, sondern von navigator.serviceWorker.register(), navigator.serviceWorker.ready, getRegistration() bzw. getRegistrations() als Promise-Wert geliefert.

Beispiele

Service Worker registrieren und Registrierung inspizieren

const registerSW = async () => {
  if (!('serviceWorker' in navigator)) return;
  try {
    const registration = await navigator.serviceWorker.register('/sw.js', { scope: '/' });
    console.log('Scope:', registration.scope);
    const state = registration.installing ? 'installing'
      : registration.waiting ? 'waiting'
      : registration.active ? 'active' : 'unbekannt';
    console.log('Zustand:', state);
  } catch (err) {
    console.error('Registrierung fehlgeschlagen:', err);
  }
};

registerSW();

Scope: https://example.com/ Zustand: installing

Neue Version erkennen (updatefound) und aktivieren

const registration = await navigator.serviceWorker.register('/sw.js');

registration.addEventListener('updatefound', () => {
  const newWorker = registration.installing;
  newWorker.addEventListener('statechange', () => {
    // Installiert + bereits ein Controller vorhanden = echtes Update
    if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
      if (confirm('Neue Version verfügbar. Jetzt neu laden?')) {
        newWorker.postMessage({ type: 'SKIP_WAITING' });
      }
    }
  });
});

navigator.serviceWorker.addEventListener('controllerchange', () => location.reload());

// Zusätzlich stündlich manuell nach Updates suchen
setInterval(() => registration.update(), 60 * 60 * 1000);

Benachrichtigung über die Registrierung anzeigen

const notify = async () => {
  const permission = await Notification.requestPermission();
  if (permission !== 'granted') return;

  const registration = await navigator.serviceWorker.ready;
  await registration.showNotification('Bestellung versendet', {
    body: 'Ihr Paket ist unterwegs.',
    icon: '/icons/paket.png',
    tag: 'bestellung-4711'
  });

  const list = await registration.getNotifications({ tag: 'bestellung-4711' });
  console.log('Offene Benachrichtigungen:', list.length);
};

notify();

Offene Benachrichtigungen: 1

Alle Registrierungen entfernen (z. B. beim Debuggen)

const registrations = await navigator.serviceWorker.getRegistrations();
const results = await Promise.all(registrations.map((reg) => reg.unregister()));
console.log(`${results.filter(Boolean).length} Service Worker abgemeldet`);

1 Service Worker abgemeldet

// Wichtig · Fallstricke

Sicherer Kontext: Service Worker funktionieren nur über HTTPS (Ausnahme: localhost). In privaten Fenstern mancher Browser (z. B. Firefox) ist navigator.serviceWorker ggf. nicht verfügbar – immer per Feature-Detection prüfen.
Scope-Beschränkung: Der Scope darf standardmäßig nicht oberhalb des Skript-Pfads liegen. Für einen breiteren Scope muss der Server den Header Service-Worker-Allowed senden.
Wartender Worker: Ein neuer Worker bleibt in waiting, bis alle kontrollierten Tabs geschlossen sind – außer der Worker ruft self.skipWaiting() auf. Unbedachtes skipWaiting() kann laufende Seiten mit inkompatiblen Cache-Ständen versorgen.
unregister() wirkt erst, wenn keine Clients mehr kontrolliert werden; bestehende Caches (CacheStorage) werden nicht automatisch gelöscht.
showNotification() erfordert eine erteilte Benachrichtigungsberechtigung und wirft sonst einen TypeError. Auf iOS/Safari sind Push und Benachrichtigungen erst ab 16.4 und nur für zum Home-Bildschirm hinzugefügte Web-Apps verfügbar.
Die Eigenschaften sync, periodicSync, backgroundFetch und index sind nicht standardübergreifend verfügbar (meist nur Chromium).

Siehe auch

ServiceWorkerContainer ServiceWorkerGlobalScope ServiceWorker ScreenOrientation BackgroundFetchRegistration