Signatur
Beschreibung
Die Eigenschaft backgroundFetch eines ServiceWorkerRegistration-Objekts gibt eine Referenz auf den zugehörigen BackgroundFetchManager zurück. Über diesen Manager startet man mit fetch() einen Hintergrundabruf, holt mit get() einen laufenden Abruf anhand seiner ID oder listet mit getIds() alle aktiven Abrufe auf.
Die Background Fetch API ist für große oder lange Downloads gedacht, etwa Filme, Podcasts, Offline-Pakete oder Spiel-Assets. Der Browser führt den Abruf auch dann weiter, wenn der Nutzer die Seite schließt oder der Service Worker beendet wird. Der Fortschritt wird dem Nutzer in der Regel über die Download-UI des Browsers angezeigt. Ist der Abruf fertig, wird im Service Worker das Ereignis backgroundfetchsuccess bzw. backgroundfetchfail ausgelöst, in dem man die Antworten z. B. im Cache ablegen kann.
Die Eigenschaft steht sowohl im Fenster-Kontext (über navigator.serviceWorker.ready) als auch im Service Worker selbst (über self.registration.backgroundFetch) zur Verfügung. Sie ist nur in sicheren Kontexten (HTTPS) verfügbar und setzt einen aktiven Service Worker voraus.
Rückgabewert
BackgroundFetchManager-Objekt der Registrierung mit den Methoden fetch(id, requests, options), get(id) und getIds(). In Browsern ohne Unterstützung ist die Eigenschaft undefined.Beispiele
Unterstützung prüfen und Hintergrund-Download starten
const downloadEpisode = async () => {
const registration = await navigator.serviceWorker.ready;
if (!('backgroundFetch' in registration)) {
console.log('Background Fetch nicht unterstützt – normaler fetch() als Fallback');
return;
}
const bgFetch = await registration.backgroundFetch.fetch(
'podcast-folge-42',
['/audio/folge-42.mp3', '/img/folge-42-cover.jpg'],
{
title: 'Podcast Folge 42',
icons: [{ sizes: '192x192', src: '/img/icon-192.png', type: 'image/png' }],
downloadTotal: 60 * 1024 * 1024 // erwartete Größe in Bytes
}
);
console.log(`Abruf gestartet: ${bgFetch.id}`);
};
downloadEpisode();Fortschritt eines laufenden Abrufs verfolgen
const trackProgress = async (id) => {
const registration = await navigator.serviceWorker.ready;
const bgFetch = await registration.backgroundFetch.get(id);
if (!bgFetch) {
console.log('Kein laufender Abruf mit dieser ID');
return;
}
bgFetch.addEventListener('progress', () => {
if (!bgFetch.downloadTotal) return;
const percent = Math.round((bgFetch.downloaded / bgFetch.downloadTotal) * 100);
console.log(`Fortschritt: ${percent} %`);
});
};
trackProgress('podcast-folge-42');Alle aktiven Abrufe auflisten und abbrechen
const cancelAll = async () => {
const registration = await navigator.serviceWorker.ready;
const ids = await registration.backgroundFetch.getIds();
console.log('Aktive Abrufe:', ids);
for (const id of ids) {
const bgFetch = await registration.backgroundFetch.get(id);
await bgFetch?.abort();
}
};
cancelAll();Im Service Worker: Ergebnisse cachen
// sw.js
self.addEventListener('backgroundfetchsuccess', (event) => {
const bgFetch = event.registration;
event.waitUntil((async () => {
const cache = await caches.open('downloads');
const records = await bgFetch.matchAll();
await Promise.all(records.map(async (record) => {
const response = await record.responseReady;
await cache.put(record.request, response);
}));
await event.updateUI({ title: 'Download abgeschlossen' });
})());
});
// Zugriff im Service Worker selbst
console.log(self.registration.backgroundFetch);// Wichtig · Fallstricke
- Experimentell und eingeschränkt unterstützt: Die API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen sie nicht. Prüfe daher immer mit
'backgroundFetch' in registrationund plane einen Fallback mit normalemfetch()ein. - Nur in sicheren Kontexten (HTTPS bzw.
localhost) und mit aktivem Service Worker verfügbar. Deshalb vor dem Zugriff am bestennavigator.serviceWorker.readyabwarten. - Die ID in
fetch()muss eindeutig sein. Ist unter derselben ID schon ein Abruf aktiv, wird das Promise mit einemTypeErrorabgelehnt. - Wird
downloadTotalangegeben und überschritten, bricht der Browser den Abruf ab. Die Angabe sollte also realistisch sein oder weggelassen werden. - Je nach Browser kann eine Berechtigung nötig sein oder der Abruf blockiert werden, etwa wenn der Nutzer Hintergrund-Downloads deaktiviert hat.
- Antworten stehen erst in den Service-Worker-Ereignissen (
backgroundfetchsuccess,backgroundfetchfail,backgroundfetchabort,backgroundfetchclick) zuverlässig bereit. Sie sollten dort in die Cache API übernommen werden, weil der Browser sie danach freigeben kann.