SyncManager.register() — Methode · JavaScript-Referenz

Signatur

SyncManager.prototype.register(tag)

Beschreibung

register() gehört zur Background Synchronization API. Du erreichst die Methode über ServiceWorkerRegistration.sync. Mit ihr meldest du eine einmalige Synchronisation unter einem frei wählbaren Tag an. Ist das Gerät online, feuert der Browser das sync-Ereignis im Service Worker sofort. Andernfalls wartet er, bis wieder eine Verbindung besteht – auch dann, wenn der Nutzer die Seite inzwischen geschlossen hat.

Typisch ist der Einsatz in Offline-fähigen Web-Apps (PWAs): Formulareingaben, Chatnachrichten oder Änderungen werden zunächst lokal gespeichert, meist in IndexedDB. Anschließend registrierst du eine Synchronisation. Der Service Worker liest die ausstehenden Daten im sync-Handler und sendet sie an den Server. Gibt der Handler über event.waitUntil() ein abgelehntes Promise zurück, versucht der Browser es später erneut (mit Backoff). event.lastChance zeigt an, ob es der letzte Versuch ist.

Die Tags sind eindeutig: Registrierst du einen Tag, der bereits aussteht, fasst der Browser beide Registrierungen zusammen. So vermeidest du doppelte Synchronisationen. Welche Tags noch ausstehen, fragst du mit SyncManager.getTags() ab.

Aufrufen kannst du die Methode sowohl im Fensterkontext als auch im Service Worker selbst. Voraussetzung ist immer ein aktiver Service Worker. Deshalb wartest du im Fenster am besten auf navigator.serviceWorker.ready.

Parameter

Name	Typ	Default	Beschreibung
$tag Pflicht	string		Frei wählbarer Bezeichner für diese Synchronisation, z. B. `"sync-nachrichten"`. Er steht im Service Worker als `event.tag` zur Verfügung. Registrierst du denselben Tag mehrfach, bleibt es bei einer einzigen ausstehenden Synchronisation.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das ohne Wert erfüllt wird, sobald die Registrierung angelegt ist. Es wird mit einer DOMException abgelehnt, wenn kein aktiver Service Worker existiert (InvalidStateError) oder der Nutzer bzw. Browser Hintergrund-Synchronisation nicht erlaubt (NotAllowedError).

Beispiele

Synchronisation im Fensterkontext registrieren

const registriereSync = async () => {
  if (!('serviceWorker' in navigator) || !('SyncManager' in window)) {
    console.log('Background Sync nicht unterstützt – sende direkt.');
    return false;
  }
  const registration = await navigator.serviceWorker.ready;
  try {
    await registration.sync.register('sync-nachrichten');
    console.log('Sync registriert');
    return true;
  } catch (err) {
    console.error('Sync-Registrierung fehlgeschlagen:', err.name);
    return false;
  }
};

registriereSync();

Sync registriert

sync-Ereignis im Service Worker verarbeiten (sw.js)

// sw.js
// holeAusstehendeNachrichten() und entferneNachricht() sind eigene IndexedDB-Hilfsfunktionen
self.addEventListener('sync', (event) => {
  if (event.tag === 'sync-nachrichten') {
    event.waitUntil(sendeAusstehendeNachrichten());
  }
});

const sendeAusstehendeNachrichten = async () => {
  const nachrichten = await holeAusstehendeNachrichten();
  for (const msg of nachrichten) {
    const res = await fetch('/api/nachrichten', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(msg)
    });
    // Wirft bei Fehler -> Browser wiederholt den Sync später
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    await entferneNachricht(msg.id);
  }
};

Offline-Formular: speichern, registrieren, Fallback

// speichereInIndexedDB() und sendeDirekt() sind eigene Hilfsfunktionen
const form = document.querySelector('#kommentar-form');

form.addEventListener('submit', async (e) => {
  e.preventDefault();
  const daten = { id: crypto.randomUUID(), text: form.text.value };
  await speichereInIndexedDB(daten);

  const reg = await navigator.serviceWorker.ready;
  if ('sync' in reg) {
    await reg.sync.register('sync-kommentare');
    const tags = await reg.sync.getTags();
    console.log('Ausstehend:', tags);
  } else {
    await sendeDirekt(daten); // Fallback ohne Background Sync
  }
});

Ausstehend: ["sync-kommentare"]

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur Chromium-basierte Browser unterstützen die Methode. Firefox und Safari kennen SyncManager nicht. Prüfe die Unterstützung daher immer vorab ('SyncManager' in window bzw. 'sync' in registration) und sieh einen direkten Versand als Fallback vor.
Die Methode funktioniert nur in einem sicheren Kontext (HTTPS oder localhost) und nur mit einem aktiven Service Worker. Ohne aktiven Worker wird das Promise mit InvalidStateError abgelehnt.
Das Promise wird bereits erfüllt, wenn die Registrierung angelegt ist. Es sagt also nichts darüber aus, ob die Synchronisation später erfolgreich war.
Der Browser entscheidet selbst, wann er synchronisiert und wie oft er es erneut versucht; in Chrome sind es meist drei Versuche. Zu lange laufende sync-Handler können abgebrochen werden. Deshalb solltest du nicht auf feste Zeitpunkte vertrauen.
Die Nutzdaten übergibst du nicht an register(). Speichere sie selbst, etwa in IndexedDB, und lies sie im Service Worker wieder aus.
Für wiederkehrende Synchronisation gibt es die separate Periodic Background Sync API (registration.periodicSync), die ebenfalls kaum verbreitet ist.

Siehe auch

SyncManager.getTags() PushManager.register() PushManager.unregister() PeriodicSyncManager.register() LockManager.request()