PeriodicSyncManager — Schnittstelle · JavaScript-Referenz

Signatur

interface PeriodicSyncManager

Beschreibung

Das Interface PeriodicSyncManager gehört zur Web Periodic Background Synchronization API. Eine Web-App kann damit den Browser bitten, ihren Service Worker in regelmäßigen Abständen zu wecken, damit er z. B. neue Artikel, Wetterdaten oder Nachrichten vorab in den Cache lädt. Öffnet der Nutzer die App später, sind die Inhalte schon aktuell. Das funktioniert auch dann, wenn gerade kein Tab der App offen ist.

Man erzeugt das Objekt nicht selbst. Man erreicht es über die Eigenschaft ServiceWorkerRegistration.periodicSync, also z. B. (await navigator.serviceWorker.ready).periodicSync. Es bietet drei Methoden:

register(tag, { minInterval }): Registriert eine periodische Synchronisation unter einem eindeutigen Namen (Tag). minInterval ist der gewünschte Mindestabstand in Millisekunden. Rückgabewert: Promise<undefined>.
getTags(): Liefert ein Promise<string[]> mit allen registrierten Tags.
unregister(tag): Entfernt die Registrierung zu einem Tag. Rückgabewert: Promise<undefined>.

Die eigentliche Arbeit erledigt der Service Worker im Ereignis periodicsync (ein PeriodicSyncEvent mit der Eigenschaft tag). Mit event.waitUntil() hält man den Worker am Leben, bis das Promise erfüllt ist. Wann und wie oft das Ereignis tatsächlich ausgelöst wird, entscheidet allein der Browser. Er berücksichtigt dabei Netzwerk, Akkustand und wie intensiv der Nutzer die Seite verwendet (Site Engagement). minInterval ist daher nur ein Wunsch und keine Zusage.

Parameter

Name	Typ	Default	Beschreibung
$tag Pflicht	string		Eindeutiger Name der Synchronisation. Wird bei `register()` und `unregister()` übergeben und kommt im Service Worker als `event.tag` an.
$options.minInterval	number	0	Nur bei `register()`: gewünschter Mindestabstand zwischen zwei Synchronisationen in Millisekunden. Der Browser kann deutlich größere Abstände wählen.

Beispiele

Zugriff auf den Manager und Registrierung mit Berechtigungsprüfung

// Seite (main.js): Service Worker muss bereits registriert sein
const registerContentSync = 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 ist evtl. nicht installiert');
    return;
  }

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

registerContentSync();

Periodische Synchronisation registriert

Ereignis periodicsync im Service Worker verarbeiten

// sw.js
const refreshNews = 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') {
    // Worker aktiv halten, bis der Cache aktualisiert ist
    event.waitUntil(refreshNews());
  }
});

Registrierte Tags auflisten und eine Synchronisation abmelden

const disableNewsSync = async () => {
  const registration = await navigator.serviceWorker.ready;
  if (!('periodicSync' in registration)) return;

  const tags = await registration.periodicSync.getTags();
  console.log('Aktive Tags:', tags);

  if (tags.includes('news-update')) {
    await registration.periodicSync.unregister('news-update');
    console.log('news-update abgemeldet');
  }
};

// z. B. wenn der Nutzer in den Einstellungen die Offline-Aktualisierung abschaltet
document.querySelector('#offline-toggle')?.addEventListener('change', (e) => {
  if (!e.target.checked) disableNewsSync();
});

Aktive Tags: ["news-update"] news-update abgemeldet

// Wichtig · Fallstricke

Browserunterstützung: Die API ist experimentell und nur in Chromium-Browsern verfügbar (Chrome, Edge, Opera ab Version 80). Firefox und Safari unterstützen sie nicht. Prüfen Sie deshalb immer mit 'periodicSync' in registration, ob sie vorhanden ist, und bieten Sie eine Alternative an, z. B. eine Aktualisierung beim Öffnen der App.
Voraussetzungen: Die API funktioniert nur in einem sicheren Kontext (HTTPS), mit aktivem Service Worker und in Chrome praktisch nur bei installierten PWAs. Ohne Berechtigung periodic-background-sync lehnt register() das Promise mit einer NotAllowedError ab.
Kein fester Zeitplan: minInterval ist nur eine Untergrenze. Der Browser legt die tatsächliche Häufigkeit anhand des Site Engagement fest, oft nur ungefähr einmal täglich oder noch seltener. Ohne Netzwerk wird gar nicht synchronisiert. Für zeitkritische Logik ist die API deshalb ungeeignet.
Laufzeit begrenzt: Der Browser beendet lange Aufgaben in periodicsync. Halten Sie die Arbeit kurz und sichern Sie sie mit event.waitUntil() ab.
Nicht verwechseln: Die einmalige Background Sync API (SyncManager, Ereignis sync) ist dafür da, fehlgeschlagene Aktionen nachzuholen, sobald wieder eine Verbindung besteht. PeriodicSyncManager ist für wiederkehrende Aktualisierungen gedacht.
Datenschutz: Regelmäßige Hintergrundanfragen können verraten, wann und wo ein Gerät online ist. Browser schränken die API deshalb stark ein. Setzen Sie sie sparsam ein und lassen Sie Nutzer sie abschalten.

Siehe auch

Permissions.query() PeriodicSyncEvent SyncManager PeriodicWave PreferenceManager