Signatur
Beschreibung
Die Eigenschaft tag eines SyncEvent gibt den Namen zurück, unter dem eine Hintergrund-Synchronisation registriert wurde. Die Registrierung erfolgt im Seitenkontext oder im Service Worker mit registration.sync.register('mein-tag'). Sobald der Browser wieder eine Netzwerkverbindung erkennt, löst er im Service Worker das Ereignis sync aus. Über event.tag erkennt man dort, welche Aufgabe gerade ausgeführt werden soll.
Braucht eine Anwendung mehrere Arten von Hintergrundaufgaben, etwa „ausstehende Nachrichten senden“ und „Formulardaten hochladen“, dann bekommt jede Aufgabe ein eigenes Tag. Der sync-Handler verzweigt anhand von event.tag in die passende Logik. Wird dasselbe Tag mehrmals registriert, solange noch eine Synchronisation aussteht, fasst der Browser diese Registrierungen zu einer einzigen zusammen. Tags eignen sich deshalb gut, um doppelte Aufträge zu vermeiden.
Die Eigenschaft ist schreibgeschützt. Ihr Wert ist genau die Zeichenkette, die an register() übergeben wurde. Sie wird in der Regel zusammen mit event.waitUntil() genutzt, damit der Service Worker aktiv bleibt, bis die Arbeit erledigt ist.
Rückgabewert
SyncManager.register(tag) vergebene Bezeichner der Synchronisations-Aufgabe.Beispiele
Sync registrieren und im Service Worker nach Tag verzweigen
// main.js – Seitenkontext
const registriereSync = async () => {
const reg = await navigator.serviceWorker.ready;
if ('sync' in reg) {
await reg.sync.register('nachrichten-senden');
console.log('Sync registriert');
}
};
registriereSync();
// sw.js – Service Worker
self.addEventListener('sync', (event) => {
console.log('Sync-Tag:', event.tag);
if (event.tag === 'nachrichten-senden') {
event.waitUntil(sendeAusstehendeNachrichten());
}
});
const sendeAusstehendeNachrichten = async () => {
// z. B. Daten aus IndexedDB lesen und per fetch senden
await fetch('/api/nachrichten', { method: 'POST', body: '[]' });
};Mehrere Aufgaben über eine Zuordnungstabelle abarbeiten
// sw.js
const aufgaben = {
'formular-upload': () => fetch('/api/formular', { method: 'POST' }),
'statistik-senden': () => fetch('/api/statistik', { method: 'POST' }),
};
self.addEventListener('sync', (event) => {
const aufgabe = aufgaben[event.tag];
if (!aufgabe) {
console.warn(`Unbekanntes Sync-Tag: ${event.tag}`);
return;
}
event.waitUntil(aufgabe());
});Tags mit ID für einzelne Datensätze und letzter Versuch
// Seitenkontext: eindeutiges Tag pro Entwurf
const reg = await navigator.serviceWorker.ready;
await reg.sync.register(`entwurf-${42}`);
// sw.js
self.addEventListener('sync', (event) => {
if (event.tag.startsWith('entwurf-')) {
const id = event.tag.slice('entwurf-'.length);
console.log(`Entwurf ${id}, letzter Versuch: ${event.lastChance}`);
event.waitUntil(fetch(`/api/entwuerfe/${id}`, { method: 'PUT' }));
}
});// Wichtig · Fallstricke
- Browser-Kompatibilität: Die Background Sync API gibt es nur in Chromium-basierten Browsern. Firefox und Safari unterstützen sie nicht. Prüfe deshalb vorher mit
'sync' in registrationund sieh eine Ausweichlösung vor, etwa ein Senden beim nächsten Seitenaufruf oder beim Ereignisonline. SyncEventsteht nur im Service-Worker-Kontext zur Verfügung. Außerdem ist ein sicherer Kontext (HTTPS) nötig.- Die Eigenschaft ist schreibgeschützt. Eine Zuweisung an
event.tagwird ohne Fehlermeldung ignoriert; im Strict Mode löst sie einenTypeErroraus. - Mehrere Registrierungen mit demselben Tag werden zu einer zusammengefasst. Wer pro Datensatz eine eigene Synchronisation braucht, sollte eindeutige Tags verwenden, z. B. mit angehängter ID.
- Ohne
event.waitUntil()kann der Browser den Service Worker vorzeitig beenden. Wird das übergebene Promise abgelehnt, versucht der Browser die Synchronisation später erneut, aber nur begrenzt oft. Ob es der letzte Versuch ist, zeigtevent.lastChance. - Speichere keine vertraulichen Daten im Tag. Lege stattdessen nur einen Schlüssel ab und halte die eigentlichen Daten in IndexedDB.