Signatur
Beschreibung
Die Eigenschaft sync einer ServiceWorkerRegistration liefert das zugehörige SyncManager-Objekt. Es gehört zur Background Synchronization API. Damit verschiebst du Arbeit wie das Absenden eines Formulars oder einer Chat-Nachricht so lange, bis der Nutzer wieder eine stabile Netzwerkverbindung hat. Das klappt auch dann, wenn die Seite inzwischen geschlossen wurde.
Der typische Ablauf sieht so aus: Die Seite speichert die ausstehenden Daten, zum Beispiel in IndexedDB. Danach registriert sie mit registration.sync.register(tag) eine Synchronisation unter einem eindeutigen Namen (Tag). Sobald der Browser Konnektivität feststellt, löst er im Service Worker das Ereignis sync aus. Dort überträgt der Worker die Daten. Wenn das von event.waitUntil() übergebene Promise abgelehnt wird, versucht der Browser es später erneut.
Die Eigenschaft steht sowohl im Fenster-Kontext (über navigator.serviceWorker.ready) als auch im Service Worker selbst (über self.registration.sync) zur Verfügung. Mit getTags() fragst du ab, welche Synchronisationen noch ausstehen.
Rückgabewert
SyncManager-Objekt der Registrierung mit den Methoden register(tag) und getTags(). In Browsern ohne Unterstützung ist die Eigenschaft undefined.Beispiele
Hintergrundsynchronisation mit Feature-Erkennung registrieren
// Im Fenster-Kontext (z. B. main.js)
const registriereSync = async () => {
if (!('serviceWorker' in navigator)) return;
const registration = await navigator.serviceWorker.ready;
if ('sync' in registration) {
try {
await registration.sync.register('nachrichten-senden');
console.log('Sync registriert');
} catch (err) {
console.error('Sync-Registrierung fehlgeschlagen:', err);
}
} else {
console.log('Background Sync nicht verfügbar – sofort senden');
}
};
registriereSync();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(`HTTP ${res.status}`); // löst einen erneuten Versuch aus
}
};
self.addEventListener('sync', (event) => {
if (event.tag === 'nachrichten-senden') {
event.waitUntil(sendeAusstehendeNachrichten());
}
});Ausstehende Sync-Tags abfragen
const zeigeAusstehendeSyncs = async () => {
const registration = await navigator.serviceWorker.ready;
if (!registration.sync) return;
const tags = await registration.sync.getTags();
console.log('Ausstehend:', tags);
};
zeigeAusstehendeSyncs();// Wichtig · Fallstricke
- Browser-Kompatibilität: Nur Chromium-basierte Browser unterstützen die Eigenschaft. Firefox und Safari kennen sie nicht. Prüfe sie deshalb immer mit
'sync' in registrationund sieh eine Ausweichlösung vor, etwa das sofortige Senden oder einen erneuten Versuch beim nächsten Seitenaufruf. - Die API funktioniert nur in einem sicheren Kontext (HTTPS oder
localhost) und nur mit einem aktiven Service Worker. Warte deshalb aufnavigator.serviceWorker.ready, bevor duregister()aufrufst. - Wenn du denselben Tag mehrfach registrierst, wird er zu einer ausstehenden Synchronisation zusammengefasst. Brauchst du getrennte Aufgaben, verwende eindeutige Tags.
- Der Browser begrenzt die Zahl der Wiederholungsversuche (in Chrome etwa drei) und die Laufzeit des Ereignisses. Du hast keinen Einfluss darauf, wann synchronisiert wird. Für wiederkehrende Aufgaben ist
ServiceWorkerRegistration.periodicSyncgedacht. - Sync hat keinen eigenen Datenspeicher. Speichere die zu sendenden Daten selbst, zum Beispiel in IndexedDB, denn im
sync-Ereignis hast du keinen Zugriff auf den Zustand der Seite. - In den Chrome-DevTools kannst du unter Application → Service Workers ein
sync-Ereignis manuell auslösen, um es zu testen.