SyncManager — Schnittstelle · JavaScript-Referenz

Signatur

interface SyncManager

Beschreibung

SyncManager ist der zentrale Einstiegspunkt der Background Synchronization API. Eine Instanz erzeugt man nicht selbst, sondern bekommt sie über ServiceWorkerRegistration.sync. Damit kann eine Web-App Aufgaben aufschieben, bis wieder eine stabile Netzwerkverbindung besteht. Ein typisches Beispiel ist eine Nachricht, die ein Nutzer offline abschickt: Sie wird zuerst in IndexedDB gespeichert und erst gesendet, wenn das Gerät wieder online ist.

Die Schnittstelle hat zwei Methoden:

register(tag) legt eine Sync-Registrierung mit einem frei gewählten Bezeichner (Tag) an und gibt ein Promise<undefined> zurück.
getTags() liefert ein Promise<string[]> mit allen Tags, die derzeit registriert sind und noch ausstehen.

Sobald der Browser eine Verbindung erkennt, löst er im Service Worker das Ereignis sync aus (SyncEvent). Dort liest man über event.tag den Tag aus und übergibt mit event.waitUntil() ein Promise, das die eigentliche Arbeit erledigt. Wird dieses Promise abgelehnt, versucht der Browser den Sync später erneut, mit wachsendem Abstand zwischen den Versuchen. Das funktioniert auch dann, wenn die Seite schon geschlossen ist.

Registriert man einen Tag, der bereits aussteht, entsteht keine zweite Registrierung. Mehrfaches Registrieren desselben Tags fasst der Browser also zusammen. Für wiederkehrende Synchronisationen gibt es die eigene Periodic Background Sync API (PeriodicSyncManager).

Parameter

Name	Typ	Default	Beschreibung
$tag Pflicht	string		Gilt nur für `register()`: ein frei wählbarer Bezeichner für die Sync-Registrierung, der im Service Worker als `SyncEvent.tag` ankommt.

Rückgabewert

Typ

Promise<undefined> | Promise<string[]>

Beschreibung

register() gibt ein Promise<undefined> zurück, das nach erfolgreicher Registrierung erfüllt wird. getTags() gibt ein Promise<string[]> mit allen ausstehenden Tags zurück.

Beispiele

Sync-Registrierung auf der Seite anlegen

// Auf der Seite (Hauptthread)
const sendeSpaeter = async () => {
  if (!('serviceWorker' in navigator) || !('SyncManager' in window)) {
    console.log('Background Sync nicht unterstützt – sofort senden');
    return;
  }
  const registration = await navigator.serviceWorker.ready;
  try {
    await registration.sync.register('nachrichten-senden');
    console.log('Sync registriert');
  } catch (err) {
    console.error('Registrierung fehlgeschlagen:', err);
  }
};

sendeSpaeter();

Sync registriert

sync-Ereignis im Service Worker verarbeiten

// sw.js
const sendeAusstehendeNachrichten = async () => {
  // In der Praxis: Nachrichten aus IndexedDB lesen
  const nachrichten = [{ text: 'Hallo' }];
  for (const n of nachrichten) {
    const res = await fetch('/api/nachrichten', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(n)
    });
    if (!res.ok) throw new Error('Server-Fehler ' + res.status);
  }
};

self.addEventListener('sync', (event) => {
  if (event.tag === 'nachrichten-senden') {
    // Abgelehntes Promise => Browser versucht es später erneut
    event.waitUntil(sendeAusstehendeNachrichten());
  }
});

Ausstehende Registrierungen mit getTags() auflisten

const zeigeAusstehendeSyncs = async () => {
  const registration = await navigator.serviceWorker.ready;
  const tags = await registration.sync.getTags();
  console.log('Ausstehend:', tags);
  if (tags.includes('nachrichten-senden')) {
    console.log('Nachrichten werden gesendet, sobald Sie wieder online sind.');
  }
};

zeigeAusstehendeSyncs();

Ausstehend: ['nachrichten-senden'] Nachrichten werden gesendet, sobald Sie wieder online sind.

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-Browser (Chrome, Edge, Opera, Samsung Internet) unterstützen die API. Firefox und Safari haben sie nicht. Prüfen Sie deshalb immer mit 'SyncManager' in window und sehen Sie einen Ausweg vor, zum Beispiel sofort senden oder beim nächsten Seitenaufruf erneut versuchen.
Sicherer Kontext: Die API steht nur über HTTPS (oder localhost) zur Verfügung, und es muss ein aktiver Service Worker registriert sein. Ohne aktiven Worker wird register() mit einem InvalidStateError abgelehnt.
Daten nicht im Tag ablegen: Der Tag ist nur ein Bezeichner. Die eigentlichen Nutzdaten gehören in IndexedDB, denn der Service Worker kann jederzeit beendet werden.
Wiederholungen sind begrenzt: Nach mehreren Fehlversuchen gibt der Browser auf; in Chrome sind es nach aktuellem Stand drei Versuche. Über SyncEvent.lastChance lässt sich der letzte Versuch erkennen. Die Laufzeit des Ereignisses ist ebenfalls beschränkt, in Chrome etwa auf einige Minuten.
Berechtigungen: Nutzer oder Richtlinien können Background Sync deaktivieren. In Chrome hängt das an der Website-Einstellung „Hintergrundsynchronisierung“. Ist sie deaktiviert, schlägt register() mit NotAllowedError fehl.

Siehe auch

LockManager PushManager PaymentManager ContactsManager StorageManager