PeriodicSyncManager.unregister() — Methode · JavaScript-Referenz

Signatur

PeriodicSyncManager.prototype.unregister(tag)

Beschreibung

Die Methode unregister() des Interfaces PeriodicSyncManager gehört zur Periodic Background Synchronization API. Sie meldet eine vorher mit register() angelegte periodische Synchronisation ab, die über ihren eindeutigen Tag gefunden wird. Danach löst der Browser für diesen Tag keine periodicsync-Events mehr im Service Worker aus.

Erreichbar ist der Manager über ServiceWorkerRegistration.periodicSync, also sowohl aus dem Fensterkontext (über navigator.serviceWorker.ready) als auch direkt im Service Worker über self.registration.periodicSync.

Typische Einsatzfälle sind: der Nutzer schaltet in den Einstellungen die automatische Aktualisierung von Inhalten ab, er meldet sich ab, oder eine bestimmte Synchronisation soll durch eine mit anderem Intervall ersetzt werden. Es ist kein Fehler, einen Tag abzumelden, der gar nicht registriert ist. Das Promise wird trotzdem erfüllt.

Parameter

Name	Typ	Default	Beschreibung
$tag Pflicht	string		Der eindeutige Bezeichner der periodischen Synchronisation, der vorher an `register(tag, options)` übergeben wurde.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Registrierung entfernt ist. Wenn kein aktiver Service Worker vorhanden ist, wird es abgelehnt (z. B. mit einer InvalidStateError-DOMException).

Beispiele

Periodische Synchronisation aus der Seite abmelden

const stopNewsSync = async () => {
  const registration = await navigator.serviceWorker.ready;

  // Unterstützung prüfen, da die API experimentell ist
  if (!('periodicSync' in registration)) {
    console.log('Periodic Background Sync wird nicht unterstützt.');
    return;
  }

  await registration.periodicSync.unregister('news-update');
  console.log('Synchronisation "news-update" abgemeldet.');
};

stopNewsSync().catch(console.error);

Synchronisation "news-update" abgemeldet.

Nur abmelden, wenn der Tag tatsächlich registriert ist

const unregisterIfPresent = async (tag) => {
  const { periodicSync } = await navigator.serviceWorker.ready;
  const tags = await periodicSync.getTags();

  if (tags.includes(tag)) {
    await periodicSync.unregister(tag);
    console.log(`"${tag}" entfernt.`);
  } else {
    console.log(`"${tag}" war nicht registriert.`);
  }
  console.log('Verbleibend:', await periodicSync.getTags());
};

unregisterIfPresent('content-sync');

"content-sync" entfernt. Verbleibend: []

Einstellungs-Schalter: Auto-Update ein- und ausschalten

const toggle = document.querySelector('#auto-update');

toggle.addEventListener('change', async () => {
  const { periodicSync } = await navigator.serviceWorker.ready;

  try {
    if (toggle.checked) {
      await periodicSync.register('articles', {
        minInterval: 12 * 60 * 60 * 1000 // 12 Stunden
      });
    } else {
      await periodicSync.unregister('articles');
    }
    console.log('Auto-Update:', toggle.checked ? 'an' : 'aus');
  } catch (err) {
    console.error('Sync-Einstellung fehlgeschlagen:', err.name);
  }
});

Auto-Update: aus

Abmeldung direkt im Service Worker

// sw.js
self.addEventListener('message', (event) => {
  if (event.data?.type === 'LOGOUT') {
    event.waitUntil(
      self.registration.periodicSync.unregister('user-inbox')
    );
  }
});

// Wichtig · Fallstricke

Experimentell und eingeschränkt verfügbar: Nur Chromium-basierte Browser unterstützen die API. Firefox und Safari haben sie nicht. Prüfe deshalb immer vorher mit 'periodicSync' in registration.
Die API gibt es nur in sicheren Kontexten (HTTPS oder localhost) und nur mit einem aktiven Service Worker.
Einen Tag abzumelden, der nicht existiert, löst keinen Fehler aus. Ob die Abmeldung etwas bewirkt hat, lässt sich mit getTags() prüfen.
Die Abmeldung bricht ein periodicsync-Event nicht ab, das gerade läuft. Sie verhindert nur künftige Auslösungen.
Für die Registrierung ist in Chrome die Berechtigung periodic-background-sync nötig (in der Regel nur bei installierten PWAs). unregister() braucht selbst keine Berechtigung. Wird die Berechtigung entzogen, entfernt der Browser die Registrierungen unter Umständen automatisch.
Die Abmeldung über ServiceWorkerRegistration.unregister() entfernt auch alle periodischen Synchronisationen dieser Registrierung.

Siehe auch

PeriodicSyncManager.getTags() PeriodicSyncManager.register() PushManager.unregister() SyncManager.register() PushManager.register()