ServiceWorkerContainer.getRegistration() — Methode · JavaScript-Referenz

Signatur

ServiceWorkerContainer.prototype.getRegistration(clientURL)

Beschreibung

Mit navigator.serviceWorker.getRegistration() fragen Sie ab, ob für eine bestimmte URL schon ein Service Worker registriert ist. Der Browser vergleicht die übergebene Client-URL mit den Scopes aller Registrierungen desselben Ursprungs. Er gibt die Registrierung mit dem längsten passenden Scope zurück, also die spezifischste Übereinstimmung.

Das ist nützlich, wenn Sie nicht bei jedem Seitenaufruf erneut register() aufrufen wollen. Typische Fälle sind: prüfen, ob die App schon „offline-fähig“ ist, gezielt nach Updates suchen (registration.update()), Push-Abonnements über registration.pushManager verwalten oder einen Service Worker wieder entfernen (registration.unregister()).

Ohne Argument wird die URL des aktuellen Dokuments verwendet. Relative URLs werden gegen die Basis-URL des Dokuments aufgelöst. Die Methode legt keine Registrierung an. Wenn nichts passt, wird das Promise mit undefined erfüllt und nicht abgelehnt.

Parameter

Name	Typ	Default	Beschreibung
$clientURL	string \| URL	URL des aktuellen Dokuments	Die URL, für die eine passende Registrierung gesucht wird. Sie muss denselben Ursprung wie das aufrufende Dokument haben. Relative Angaben werden gegen die Basis-URL des Dokuments aufgelöst.

Rückgabewert

Typ

Promise<ServiceWorkerRegistration | undefined>

Beschreibung

Ein Promise, das mit der passenden ServiceWorkerRegistration erfüllt wird oder mit undefined, wenn keine Registrierung zur URL passt. Das Promise wird mit einem SecurityError abgelehnt, wenn die URL einen fremden Ursprung hat.

Beispiele

Prüfen, ob die aktuelle Seite schon von einem Service Worker kontrolliert wird

const checkRegistration = async () => {
  if (!('serviceWorker' in navigator)) {
    console.log('Service Worker werden nicht unterstützt.');
    return;
  }

  const registration = await navigator.serviceWorker.getRegistration();

  if (registration) {
    console.log('Registriert mit Scope:', registration.scope);
  } else {
    console.log('Keine Registrierung gefunden – registriere jetzt …');
    await navigator.serviceWorker.register('/sw.js');
  }
};

checkRegistration();

Registriert mit Scope: https://example.com/

Registrierung für einen bestimmten Unterpfad abfragen und aktualisieren

const updateAppWorker = async () => {
  // Passende Registrierung für den Bereich /app/ suchen
  const registration = await navigator.serviceWorker.getRegistration('/app/');

  if (!registration) {
    console.warn('Für /app/ ist kein Service Worker registriert.');
    return;
  }

  await registration.update();
  console.log('Update-Prüfung ausgeführt für', registration.scope);
};

updateAppWorker();

Update-Prüfung ausgeführt für https://example.com/app/

Service Worker beim Abmelden entfernen

const removeServiceWorker = async () => {
  const registration = await navigator.serviceWorker.getRegistration();
  if (!registration) return false;

  const success = await registration.unregister();
  console.log(success ? 'Service Worker entfernt.' : 'Entfernen fehlgeschlagen.');
  return success;
};

document.querySelector('#logout')?.addEventListener('click', removeServiceWorker);

Service Worker entfernt.

Fremde Ursprünge führen zu einem Fehler

try {
  await navigator.serviceWorker.getRegistration('https://andere-domain.example/');
} catch (err) {
  console.error(err.name);
}

SecurityError

// Wichtig · Fallstricke

Sicherer Kontext nötig: navigator.serviceWorker gibt es nur unter HTTPS oder localhost. In privaten Fenstern mancher Browser, etwa bei Firefox mit bestimmten Einstellungen, ist die Eigenschaft undefined. Prüfen Sie daher vorher mit 'serviceWorker' in navigator, ob die API verfügbar ist.
undefined statt Fehler: Gibt es keine passende Registrierung, wird das Promise normal erfüllt. Prüfen Sie den Rückgabewert also mit if (registration), nicht mit catch.
Scope-Abgleich über Präfixe: Gesucht wird die Registrierung, deren Scope das längste Präfix der Client-URL ist. getRegistration('/app/page') findet also eine Registrierung mit Scope /app/. Umgekehrt findet getRegistration('/') keine Registrierung, die nur für /app/ gilt.
Registriert heißt nicht aktiv: Eine vorhandene Registrierung bedeutet nicht, dass die Seite schon kontrolliert wird. Prüfen Sie dafür registration.active oder navigator.serviceWorker.controller. Wenn Sie auf einen aktiven Worker warten wollen, verwenden Sie navigator.serviceWorker.ready.
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt (Chrome 40+, Firefox 44+, Safari 11.1+, Edge 17+). Den Internet Explorer gibt es nicht mehr, dort fehlt die API ganz.

Siehe auch

ServiceWorkerContainer.getRegistrations() ServiceWorkerContainer.register() ServiceWorkerContainer.startMessages() ServiceWorkerRegistration.getNotifications() ServiceWorkerRegistration.unregister()