BackgroundFetchRegistration.failureReason — Eigenschaft · JavaScript-Referenz

Signatur

BackgroundFetchRegistration.failureReason

Beschreibung

Die Eigenschaft failureReason eines BackgroundFetchRegistration-Objekts zeigt an, warum ein Hintergrund-Abruf nicht erfolgreich abgeschlossen wurde. Die Background Fetch API ist für große Downloads gedacht, etwa Podcasts, Videos oder Offline-Pakete. Solche Downloads führt der Browser auch dann weiter, wenn die Seite oder der Service Worker geschlossen wurde.

Mögliche Werte:

"": Kein Fehler, der Abruf läuft noch oder war erfolgreich.
"aborted": Der Abruf wurde abgebrochen, durch den Nutzer oder per abort().
"bad-status": Mindestens eine Antwort hatte einen Status, der nicht ok ist, z. B. 404 oder 500.
"fetch-error": Mindestens ein Abruf ist aus einem anderen Grund fehlgeschlagen, z. B. CORS, Netzwerkfehler oder ungültige Anfrage.
"quota-exceeded": Der verfügbare Speicherplatz (Storage-Quota) wurde während des Abrufs überschritten.
"download-total-exceeded": Die übertragene Datenmenge war größer als der Wert von downloadTotal, der beim Start angegeben wurde.

Typischerweise liest man die Eigenschaft im Service Worker im Handler für das Event backgroundfetchfail aus, oder auf der Seite im progress-Event der Registrierung, sobald result den Wert "failure" hat. So kann man dem Nutzer eine passende Meldung zeigen oder einen neuen Versuch anbieten.

Rückgabewert

Typ

Beschreibung

Ein String mit dem Fehlergrund. Er ist leer (""), wenn kein Fehler aufgetreten ist.

Beispiele

Fehlergrund im Service Worker auswerten

// sw.js
self.addEventListener('backgroundfetchfail', (event) => {
  const reg = event.registration;
  console.log(`Abruf ${reg.id} fehlgeschlagen: ${reg.failureReason}`);

  event.waitUntil(
    self.registration.showNotification('Download fehlgeschlagen', {
      body: `Grund: ${reg.failureReason}`
    })
  );
});

Abruf podcast-42 fehlgeschlagen: bad-status

Fehlergründe in verständliche Meldungen übersetzen

const meldungen = {
  'aborted': 'Der Download wurde abgebrochen.',
  'bad-status': 'Der Server hat eine Datei nicht geliefert.',
  'fetch-error': 'Netzwerk- oder CORS-Fehler beim Download.',
  'quota-exceeded': 'Nicht genug Speicherplatz auf dem Gerät.',
  'download-total-exceeded': 'Die Datei ist größer als angekündigt.'
};

const beschreibeFehler = (registration) =>
  meldungen[registration.failureReason] ?? 'Kein Fehler.';

// Beispiel mit einem simulierten Objekt:
console.log(beschreibeFehler({ failureReason: 'quota-exceeded' }));

Nicht genug Speicherplatz auf dem Gerät.

Fortschritt auf der Seite überwachen und Fehler erkennen

const starteDownload = async () => {
  if (!('BackgroundFetchManager' in self)) {
    console.warn('Background Fetch wird nicht unterstützt.');
    return;
  }
  const swReg = await navigator.serviceWorker.ready;
  const bgFetch = await swReg.backgroundFetch.fetch(
    'film-1',
    ['/media/film-1.mp4'],
    { title: 'Film herunterladen', downloadTotal: 250 * 1024 * 1024 }
  );

  bgFetch.addEventListener('progress', () => {
    if (bgFetch.result === 'failure') {
      console.error('Fehlgeschlagen:', bgFetch.failureReason);
    } else if (bgFetch.result === 'success') {
      console.log('Download abgeschlossen.');
    }
  });
};

starteDownload();

Fehlgeschlagen: download-total-exceeded

// Wichtig · Fallstricke

Experimentell: Die Background Fetch API gibt es derzeit nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Prüfe die Unterstützung vorher, z. B. mit 'BackgroundFetchManager' in self.
Die API funktioniert nur in einem sicheren Kontext (HTTPS) und setzt einen aktiven Service Worker voraus.
failureReason ist nur zusammen mit result aussagekräftig. Solange result leer ist, läuft der Abruf noch, und failureReason ist ebenfalls "".
Bei "bad-status" und "fetch-error" erfährst du nicht, welche Anfrage fehlgeschlagen ist. Das findest du mit matchAll() und den einzelnen BackgroundFetchRecord-Einträgen heraus.
Gib downloadTotal realistisch an, sonst bricht der Browser den Abruf mit "download-total-exceeded" ab.

Siehe auch

BackgroundFetchRegistration.recordsAvailable BackgroundFetchRegistration.result BackgroundFetchRegistration.uploaded BackgroundFetchRegistration.downloaded BackgroundFetchRegistration.id