SyncManager.getTags() — Methode · JavaScript-Referenz

Signatur

SyncManager.prototype.getTags()

Beschreibung

Die Methode getTags() des SyncManager-Interfaces liefert die Bezeichner (Tags) aller Hintergrund-Synchronisationen, die mit SyncManager.register() angemeldet wurden und noch ausstehen. Ein Tag ist ein frei wählbarer String wie "outbox-sync", über den der Service Worker später im sync-Event erkennt, welche Aufgabe er erledigen soll.

Man erreicht den SyncManager über ServiceWorkerRegistration.sync, also entweder im Fenster-Kontext über navigator.serviceWorker.ready oder direkt im Service Worker über self.registration.sync. Typische Einsatzfälle sind das Prüfen, ob eine Synchronisation bereits eingeplant ist (um doppelte Registrierungen oder überflüssige Hinweise in der Oberfläche zu vermeiden), Debugging sowie das Anzeigen eines Status wie „Wird gesendet, sobald Sie wieder online sind“.

Sobald ein sync-Event erfolgreich abgeschlossen wurde (das Promise aus event.waitUntil() wurde erfüllt), verschwindet das zugehörige Tag aus der Liste. Schlägt die Synchronisation fehl, bleibt es für einen erneuten Versuch registriert, bis der Browser nach mehreren Fehlversuchen aufgibt (dann ist event.lastChance im letzten Versuch true).

Rückgabewert

Typ

Promise<string[]>

Beschreibung

Ein Promise, das mit einem Array der registrierten Tag-Strings erfüllt wird. Sind keine Synchronisationen ausstehend, ist das Array leer ([]).

Beispiele

Alle ausstehenden Sync-Tags auflisten

const listSyncTags = async () => {
  if (!('serviceWorker' in navigator) || !('SyncManager' in window)) {
    console.log('Background Sync wird nicht unterstützt');
    return [];
  }
  const registration = await navigator.serviceWorker.ready;
  const tags = await registration.sync.getTags();
  console.log('Ausstehende Syncs:', tags);
  return tags;
};

listSyncTags();

Ausstehende Syncs: ["outbox-sync"]

Doppelte Registrierung vermeiden und Status anzeigen

const scheduleOutboxSync = async () => {
  const registration = await navigator.serviceWorker.ready;
  const tags = await registration.sync.getTags();

  if (tags.includes('outbox-sync')) {
    console.log('Synchronisation ist bereits eingeplant.');
    return;
  }

  try {
    await registration.sync.register('outbox-sync');
    console.log('Nachrichten werden gesendet, sobald eine Verbindung besteht.');
  } catch (err) {
    console.error('Sync-Registrierung fehlgeschlagen:', err);
  }
};

document.querySelector('#send')?.addEventListener('click', scheduleOutboxSync);

Nachrichten werden gesendet, sobald eine Verbindung besteht.

Tags im Service Worker prüfen

// service-worker.js
self.addEventListener('sync', (event) => {
  if (event.tag === 'outbox-sync') {
    event.waitUntil((async () => {
      const pending = await self.registration.sync.getTags();
      console.log('Noch registriert während der Ausführung:', pending);
      await fetch('/api/outbox/flush', { method: 'POST' });
    })());
  }
});

Noch registriert während der Ausführung: ["outbox-sync"]

// Wichtig · Fallstricke

Browser-Unterstützung: Die Background Synchronization API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen sie nicht. Vorher immer mit 'SyncManager' in window bzw. 'sync' in registration prüfen und auf eine andere Lösung zurückfallen (z. B. sofortiger Versand, sobald das online-Event feuert).
Nur in sicheren Kontexten (HTTPS oder localhost) und mit aktivem Service Worker verfügbar.
Die Tags sind eindeutig: Ein erneutes register() mit einem vorhandenen Tag erzeugt keinen zweiten Eintrag. getTags() liefert deshalb nie Duplikate.
Ein Tag, dessen sync-Event gerade läuft, kann noch in der Liste stehen. Das Ergebnis ist nur eine Momentaufnahme und kann schon kurz danach veraltet sein.
Ist Background Sync in den Website-Einstellungen blockiert, kann das Promise abgelehnt werden. Deshalb Fehler mit try/catch behandeln.
Für wiederkehrende Synchronisationen gibt es die eigenständige PeriodicSyncManager.getTags() (Periodic Background Sync). Deren Tags erscheinen hier nicht.

Siehe auch

MediaStream.getTracks() SyncManager.register() PeriodicSyncManager.getTags() LockManager.request() DataTransfer.getData()