PeriodicSyncEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface PeriodicSyncEvent extends ExtendableEvent

Beschreibung

Die Schnittstelle PeriodicSyncEvent gehört zur Web Periodic Background Synchronization API. Ein solches Ereignis wird im ServiceWorkerGlobalScope als periodicsync-Event ausgelöst, wenn der Browser entscheidet, dass eine zuvor über registration.periodicSync.register() angemeldete periodische Synchronisierung fällig ist – und das Gerät online ist.

Typische Anwendungsfälle sind das Vorladen von Inhalten, damit sie beim nächsten Öffnen der App sofort (auch offline) verfügbar sind: aktuelle Nachrichten, Wetterdaten, Podcast-Episoden-Listen oder Kurswechsel. Der Service Worker ruft Daten per fetch() ab und legt sie in der Cache API oder IndexedDB ab.

Da PeriodicSyncEvent von ExtendableEvent erbt, steht event.waitUntil(promise) zur Verfügung. Damit hält man den Service Worker am Leben, bis die asynchrone Arbeit abgeschlossen ist. Die einzige eigene Eigenschaft ist tag (schreibgeschützt, string): Sie enthält den Namen, unter dem die Synchronisierung registriert wurde, und erlaubt die Unterscheidung mehrerer Aufgaben.

Wichtig: Das angegebene minInterval ist nur eine Untergrenze. Wie oft das Event tatsächlich feuert, bestimmt der Browser anhand von Faktoren wie Nutzungsintensität der Seite (Site-Engagement), Akkustand und Netzwerktyp.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Konstruktor-Parameter: Name des Ereignisses, in der Praxis immer `"periodicsync"`.
$options Pflicht	{ tag: string }		Konstruktor-Parameter: Objekt mit der Pflichteigenschaft `tag` – dem Bezeichner der periodischen Synchronisierung. Erbt zusätzlich die Optionen von `ExtendableEvent`/`Event` (`bubbles`, `cancelable`, `composed`).

Rückgabewert

Typ

PeriodicSyncEvent

Beschreibung

Der Konstruktor new PeriodicSyncEvent(type, options) liefert ein neues Ereignisobjekt. In der Praxis erzeugt der Browser die Instanz selbst und übergibt sie an den periodicsync-Handler.

Beispiele

Periodische Synchronisierung auf der Seite registrieren

// main.js – im Fenster-Kontext
const registerNewsSync = async () => {
  const registration = await navigator.serviceWorker.ready;

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

  const status = await navigator.permissions.query({
    name: 'periodic-background-sync',
  });

  if (status.state !== 'granted') {
    console.log('Keine Berechtigung – App installiert?');
    return;
  }

  // Höchstens einmal pro 12 Stunden
  await registration.periodicSync.register('news-update', {
    minInterval: 12 * 60 * 60 * 1000,
  });
  console.log('Sync "news-update" registriert');
};

registerNewsSync();

Sync "news-update" registriert

periodicsync im Service Worker behandeln (addEventListener)

// 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);
  }
};

self.addEventListener('periodicsync', (event) => {
  console.log('Periodischer Sync:', event.tag);

  if (event.tag === 'news-update') {
    // Service Worker bis zum Abschluss am Leben halten
    event.waitUntil(updateNews());
  }
});

Periodischer Sync: news-update

Alternative: onperiodicsync-Property und Abmelden

// sw.js – Handler über die on-Property
self.onperiodicsync = (event) => {
  if (event.tag === 'weather') {
    event.waitUntil(
      fetch('/api/weather')
        .then((res) => res.json())
        .then((data) => console.log('Wetter aktualisiert:', data.city))
    );
  }
};

// main.js – registrierte Tags anzeigen und einen entfernen
const cleanUp = async () => {
  const registration = await navigator.serviceWorker.ready;
  const tags = await registration.periodicSync.getTags();
  console.log('Aktive Tags:', tags);
  if (tags.includes('weather')) {
    await registration.periodicSync.unregister('weather');
  }
};
cleanUp();

Aktive Tags: ["weather"]

Ereignis manuell erzeugen (z. B. für Tests)

// Nur in Browsern mit Unterstützung, im Service-Worker-Kontext
const testEvent = new PeriodicSyncEvent('periodicsync', { tag: 'news-update' });
console.log(testEvent.type, testEvent.tag);
console.log(testEvent instanceof ExtendableEvent);

periodicsync news-update true

// Wichtig · Fallstricke

Kompatibilität: Experimentell und nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet) verfügbar. Firefox und Safari unterstützen die API nicht – immer per 'periodicSync' in registration prüfen und eine Alternative (z. B. Aktualisierung beim Start der App) vorsehen.
Voraussetzungen: Sicherer Kontext (HTTPS), aktiver Service Worker und in Chrome in der Regel eine installierte PWA. Ohne Installation bleibt die Berechtigung periodic-background-sync meist auf denied.
Keine Zeitgarantie: minInterval ist nur ein Mindestabstand. Der Browser kann das Event seltener oder gar nicht auslösen (geringes Site-Engagement, Energiesparmodus, getaktete Verbindung). Nicht für zeitkritische Aufgaben oder Benachrichtigungen verwenden – dafür ist die Push API gedacht.
waitUntil nicht vergessen: Ohne event.waitUntil() kann der Service Worker beendet werden, bevor fetch() oder Cache-Schreibvorgänge abgeschlossen sind. Lang laufende Aufgaben können vom Browser trotzdem abgebrochen werden.
Nicht verwechseln mit SyncEvent (einmalige Background Sync API), das nach Wiederherstellung der Verbindung genau einmal feuert.
Zum Testen bieten die Chrome DevTools unter Application → Periodic Background Sync eine Möglichkeit, das Event manuell auszulösen.

Siehe auch

Cache PeriodicSyncManager PeriodicWave ProgressEvent SyncEvent