PeriodicSyncManager.register() — Methode · JavaScript-Referenz

Signatur

PeriodicSyncManager.prototype.register(tag, options)

Beschreibung

Mit register() bittet eine Web-App über ihre Service-Worker-Registrierung (registration.periodicSync) den Browser, in regelmäßigen Abständen ein periodicsync-Ereignis im Service Worker auszulösen. So lassen sich Inhalte wie Nachrichten, Artikel oder Konfigurationen im Hintergrund aktualisieren. Die Daten sind dann schon aktuell, wenn der Nutzer die App das nächste Mal öffnet, auch wenn er offline ist.

Das Tag ist ein frei wählbarer Name für die Registrierung. Registriert man dasselbe Tag noch einmal, entsteht keine zweite Registrierung, sondern die Optionen der bestehenden werden ersetzt. Über options.minInterval gibt man an, wie viele Millisekunden mindestens zwischen zwei Synchronisierungen liegen sollen. Das ist nur ein Mindestwert: Wann und wie oft tatsächlich synchronisiert wird, entscheidet der Browser selbst. Dabei berücksichtigt er zum Beispiel den Site-Engagement-Score, die Netzwerkverbindung (etwa nur im bekannten WLAN) und den Akkustand.

Die API funktioniert nur, wenn die Seite als installierte PWA läuft und die Berechtigung periodic-background-sync erteilt ist. Prüfe deshalb vor dem Aufruf mit navigator.permissions.query() die Berechtigung und mit 'periodicSync' in registration, ob die Funktion überhaupt vorhanden ist.

Parameter

Name	Typ	Default	Beschreibung
$tag Pflicht	string		Name der Synchronisierung, z. B. `'news-update'`. Im Service Worker steht er als `event.tag` zur Verfügung. Dasselbe Tag noch einmal zu registrieren, aktualisiert die bestehende Registrierung.
$options	object	{}	Objekt mit Optionen für die Registrierung.
$options.minInterval	number	0	Gewünschter Mindestabstand zwischen zwei Synchronisierungen in Millisekunden. Der Browser kann ihn verlängern (Chrome: höchstens etwa einmal alle 12 Stunden).

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Promise, das ohne Wert erfüllt wird, sobald die Registrierung gespeichert ist. Es wird mit einer DOMException abgelehnt, zum Beispiel NotAllowedError bei fehlender Berechtigung oder InvalidStateError, wenn kein aktiver Service Worker vorhanden ist.

Beispiele

Periodische Synchronisierung sicher registrieren

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

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

  // Berechtigung prüfen
  const status = await navigator.permissions.query({
    name: 'periodic-background-sync',
  });
  if (status.state !== 'granted') {
    console.log('Keine Berechtigung – ist die App installiert?');
    return;
  }

  try {
    await registration.periodicSync.register('news-update', {
      minInterval: 24 * 60 * 60 * 1000, // höchstens einmal pro Tag
    });
    console.log('Periodische Synchronisierung registriert.');
  } catch (err) {
    console.error('Registrierung fehlgeschlagen:', err.name, err.message);
  }
};

registerNewsSync();

Periodische Synchronisierung registriert.

Ereignis im Service Worker verarbeiten (sw.js)

// sw.js
const updateNewsCache = async () => {
  const cache = await caches.open('news-v1');
  const response = await fetch('/api/news/latest');
  if (response.ok) {
    await cache.put('/api/news/latest', response);
  }
};

self.addEventListener('periodicsync', (event) => {
  if (event.tag === 'news-update') {
    // waitUntil hält den Service Worker aktiv, bis der Cache aktualisiert ist
    event.waitUntil(updateNewsCache());
  }
});

Doppelte Registrierung vermeiden und wieder abmelden

const toggleSync = async (enabled) => {
  const registration = await navigator.serviceWorker.ready;
  const tags = await registration.periodicSync.getTags();

  if (enabled && !tags.includes('news-update')) {
    await registration.periodicSync.register('news-update', {
      minInterval: 12 * 60 * 60 * 1000,
    });
  } else if (!enabled && tags.includes('news-update')) {
    await registration.periodicSync.unregister('news-update');
  }

  console.log('Aktive Tags:', await registration.periodicSync.getTags());
};

toggleSync(true);

Aktive Tags: ["news-update"]

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Funktion ist experimentell und nur in Chromium-Browsern verfügbar (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen sie nicht. Plane deshalb immer einen Ersatzweg ein, z. B. die Aktualisierung beim Öffnen der App.
Nur für installierte PWAs: In einem normalen Browser-Tab wird die Berechtigung meist nicht erteilt, und register() schlägt mit NotAllowedError fehl.
Keine Zeitgarantie: minInterval ist nur ein Mindestwert. Je nach Nutzung der Seite kann der Browser seltener oder gar nicht synchronisieren. Für zeitkritische Aufgaben ist die API nicht geeignet, dafür eignen sich eher Push-Nachrichten.
Sicherer Kontext: Die API funktioniert nur über HTTPS (oder localhost) und braucht einen aktiven Service Worker. Deshalb wartet man vorher auf navigator.serviceWorker.ready.
Die Synchronisierung läuft nur, wenn das Gerät online ist, und oft nur über ein Netzwerk, mit dem es schon einmal verbunden war. Der Code im Service Worker sollte kurz dauern, weil der Browser lang laufende Aufgaben abbrechen kann.

Siehe auch

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