ServiceWorkerGlobalScope: periodicsync — Ereignis · JavaScript-Referenz

Signatur

self.addEventListener("periodicsync", handler)

Beschreibung

Das Ereignis periodicsync gehört zur Web Periodic Background Synchronization API. Der Browser löst es im ServiceWorkerGlobalScope aus, damit eine installierte Web-App im Hintergrund regelmäßig Daten aktualisieren kann – zum Beispiel Nachrichten, Wetterdaten oder Podcast-Folgen vorab laden. So stehen beim nächsten Öffnen der App schon aktuelle Inhalte bereit, auch ohne Netzwerkverbindung.

Den Handler registriert man entweder mit self.addEventListener("periodicsync", handler) oder über die Eigenschaft self.onperiodicsync = handler. Der Handler bekommt ein PeriodicSyncEvent. Dessen Eigenschaft tag gibt an, welche Registrierung das Ereignis ausgelöst hat. Mit event.waitUntil(promise) hält man den Service Worker am Leben, bis die asynchrone Arbeit fertig ist.

Die Registrierung erfolgt auf der Seite über registration.periodicSync.register(tag, { minInterval }). minInterval ist nur eine Untergrenze. Wann das Ereignis tatsächlich kommt, entscheidet der Browser – abhängig vom Engagement-Wert der Seite, vom Netzwerk und vom Akkustand. Das Ereignis wird nur ausgelöst, wenn das Gerät online ist.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"periodicsync"`.
$handler Pflicht	(event: PeriodicSyncEvent) => void		Die Callback-Funktion. Sie erhält ein `PeriodicSyncEvent` mit der Eigenschaft `tag` (string) und der Methode `waitUntil(promise)` (geerbt von `ExtendableEvent`).
$options	boolean \| AddEventListenerOptions	false	Die üblichen Optionen von `addEventListener`, z. B. `{ once: true }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Promise, das an event.waitUntil() übergeben wird, legt fest, wie lange der Service Worker aktiv bleibt.

Beispiele

Periodische Synchronisierung auf der Seite registrieren

// main.js – im Seitenkontext
const registerNewsSync = async () => {
  const registration = await navigator.serviceWorker.ready;
  if (!('periodicSync' in registration)) {
    console.log('Periodic Sync wird nicht unterstützt');
    return;
  }
  const status = await navigator.permissions.query({ name: 'periodic-background-sync' });
  if (status.state !== 'granted') {
    console.log('Berechtigung fehlt:', status.state);
    return;
  }
  // Frühestens alle 12 Stunden
  await registration.periodicSync.register('news-update', {
    minInterval: 12 * 60 * 60 * 1000
  });
  console.log('Registriert:', await registration.periodicSync.getTags());
};

registerNewsSync();

Registriert: ["news-update"]

Ereignis im Service Worker mit addEventListener verarbeiten

// sw.js
const updateNews = 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.clone());
  }
};

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

Alternative: onperiodicsync-Eigenschaft und Abmelden

// sw.js
self.onperiodicsync = (event) => {
  console.log('periodicsync ausgelöst, Tag:', event.tag);
  event.waitUntil(
    fetch('/api/weather').then((res) => res.json()).then((data) =>
      caches.open('weather').then((cache) =>
        cache.put('/api/weather', new Response(JSON.stringify(data)))
      )
    )
  );
};

// main.js – Registrierung wieder entfernen
const stopSync = async () => {
  const registration = await navigator.serviceWorker.ready;
  await registration.periodicSync.unregister('news-update');
  console.log('Verbleibende Tags:', await registration.periodicSync.getTags());
};

periodicsync ausgelöst, Tag: news-update Verbleibende Tags: []

// Wichtig · Fallstricke

Browser-Unterstützung: Experimentell und nur in Chromium-Browsern (Chrome/Edge ab 80) verfügbar. Firefox und Safari unterstützen die API nicht. Prüfe deshalb vorher mit 'periodicSync' in registration, ob sie vorhanden ist.
Voraussetzungen: Sicherer Kontext (HTTPS), ein aktiver Service Worker und in der Regel eine installierte PWA. Die Berechtigung periodic-background-sync muss erteilt sein, sonst schlägt register() mit einem NotAllowedError fehl.
Keine festen Zeitpunkte: minInterval ist nur ein Mindestabstand. Der Browser kann das Ereignis deutlich seltener auslösen (je nach Nutzungsintensität der Seite, Energiesparmodus oder Datensparmodus) oder ganz aussetzen. Die API eignet sich nicht für zeitkritische Aufgaben.
Nur online: Ohne Netzwerkverbindung wird das Ereignis nicht ausgelöst. Für einmalige Aufgaben, die nachgeholt werden sollen, sobald wieder eine Verbindung besteht, ist das sync-Ereignis (Background Sync) gedacht.
Immer waitUntil() verwenden: Ohne diesen Aufruf kann der Browser den Service Worker beenden, bevor fetch oder Cache-Operationen fertig sind. Lang laufende Aufgaben können trotzdem vom Browser abgebrochen werden.
Seiten erkennen, dass Daten im Hintergrund abgerufen werden. Übertrage daher nur wenige Daten und nichts Sensibles, und biete Nutzern eine Möglichkeit an, die Synchronisierung per unregister() abzuschalten.

Siehe auch

ServiceWorkerGlobalScope PeriodicSyncManager PeriodicSyncEvent PeriodicSyncManager.prototype.register() ExtendableEvent.prototype.waitUntil() ServiceWorkerGlobalScope: sync Notification: show