Signatur
Beschreibung
Die schreibgeschützte Eigenschaft id eines BackgroundFetchRegistration-Objekts enthält die Kennung, die der Entwickler beim Aufruf von registration.backgroundFetch.fetch(id, requests, options) als ersten Parameter angegeben hat. Anhand dieser ID lässt sich ein Hintergrund-Download eindeutig wiedererkennen, auch nachdem die Seite geschlossen und später wieder geöffnet wurde.
Gebraucht wird die ID vor allem im Service Worker. Dort kommen Ereignisse wie backgroundfetchsuccess, backgroundfetchfail, backgroundfetchabort und backgroundfetchclick an, und über event.registration.id lässt sich feststellen, welcher Download abgeschlossen ist, z. B. um die Ergebnisse im passenden Cache abzulegen oder die richtige Seite zu öffnen.
Die ID ist nur innerhalb der Service-Worker-Registrierung eindeutig. Wird fetch() mit einer ID aufgerufen, zu der bereits ein aktiver Background Fetch läuft, wird das Promise mit einem TypeError abgelehnt. Mit BackgroundFetchManager.get(id) kann man eine laufende Registrierung über ihre ID wieder abrufen, getIds() liefert alle aktiven IDs.
Rückgabewert
Beispiele
Background Fetch starten und ID auslesen
// Im Seitenkontext (window)
const startDownload = async () => {
const swReg = await navigator.serviceWorker.ready;
if (!('backgroundFetch' in swReg)) {
console.warn('Background Fetch wird nicht unterstützt');
return;
}
const bgFetch = await swReg.backgroundFetch.fetch(
'podcast-folge-42',
['/media/folge-42.mp3', '/media/folge-42-cover.jpg'],
{ title: 'Podcast-Folge 42', downloadTotal: 60 * 1024 * 1024 }
);
console.log(`Download gestartet: ${bgFetch.id}`);
};
startDownload();Im Service Worker anhand der ID reagieren
// service-worker.js
self.addEventListener('backgroundfetchsuccess', (event) => {
const bgFetch = event.registration;
event.waitUntil((async () => {
// Eigener Cache pro Download-ID
const cache = await caches.open(`downloads-${bgFetch.id}`);
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: `Fertig: ${bgFetch.id}` });
})());
});Laufenden Download über seine ID wiederfinden
const zeigeLaufendeDownloads = async () => {
const swReg = await navigator.serviceWorker.ready;
const ids = await swReg.backgroundFetch.getIds();
for (const id of ids) {
const bgFetch = await swReg.backgroundFetch.get(id);
const prozent = bgFetch.downloadTotal
? Math.round((bgFetch.downloaded / bgFetch.downloadTotal) * 100)
: 0;
console.log(`${bgFetch.id}: ${prozent} %`);
}
};
zeigeLaufendeDownloads();// Wichtig · Fallstricke
- Experimentelle API: Background Fetch gibt es derzeit nur in Chromium-basierten Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer vorher mit
'backgroundFetch' in registration, ob die API verfügbar ist. - Die API funktioniert nur in einem sicheren Kontext (HTTPS) und setzt einen aktiven Service Worker voraus.
- Eindeutigkeit: Die ID muss unter den aktiven Background Fetches einer Service-Worker-Registrierung eindeutig sein. Ein zweiter
fetch()-Aufruf mit derselben ID wird mit einemTypeErrorabgelehnt. Nach Abschluss oder Abbruch kann die ID wieder verwendet werden. - Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wie
bgFetch.id = 'neu'wird im nicht strikten Modus stillschweigend ignoriert und löst im strikten Modus einenTypeErroraus. - Die ID kann in der Oberfläche des Browsers oder in Logs auftauchen. Verwende daher keine sensiblen Daten wie Tokens oder E-Mail-Adressen als ID.