BackgroundFetchRegistration

The BackgroundFetchRegistration interface of the Background Fetch API represents an individual background fetch.

A BackgroundFetchRegistration instance is returned by the BackgroundFetchManager.fetch() or BackgroundFetchManager.get() methods, and therefore there has no constructor.

The following properties are available synchronously, as convenience properties copied from those in the BackgroundFetchRegistration instance.

BackgroundFetchRegistration.idRead only

A string containing the background fetch's ID.

BackgroundFetchRegistration.uploadTotalRead only

A number containing the total number of bytes to be uploaded.

BackgroundFetchRegistration.uploadedRead only

A number containing the size in bytes successfully sent, initially 0.

BackgroundFetchRegistration.downloadTotalRead only

A number containing the total size in bytes of this download. This is the value set when the background fetch was registered, or 0.

BackgroundFetchRegistration.downloadedRead only

A number containing the size in bytes that has been downloaded, initially 0.

BackgroundFetchRegistration.resultRead only

Returns an empty string initially, on completion either the string "success" or "failure".

BackgroundFetchRegistration.failureReasonRead only

One of the following strings:

""

The background fetch has not completed, or was successful.

"aborted"

The operation was cancelled by the user, or abort() was called.

"bad-status"

A response had a not-ok status (a status outside the range 200-299).

"fetch-error"

A fetch failed for other reasons, for example CORS, or a network failure.

"quota-exceeded"

Storage quota was reached during the operation.

"download-total-exceeded"

The provided downloadTotal was exceeded. This value was set when the background fetch was registered.

BackgroundFetchRegistration.recordsAvailableRead only

A boolean indicating whether the recordsAvailable flag is set.

BackgroundFetchRegistration.abort()

Aborts the background fetch. Returns a Promise that resolves with true if the fetch was successfully aborted.

BackgroundFetchRegistration.match()

Returns a single BackgroundFetchRecord object which is the first match for the arguments.

BackgroundFetchRegistration.matchAll()

Returns a Promise that resolves with an array of BackgroundFetchRecord objects containing requests and responses.

Listen to these events using addEventListener() or by assigning an event listener to the oneventname property of this interface.

progress

Fired when there is a change to any of the following properties: uploaded, downloaded, result or failureReason.

The following code creates a BackGroundFetchRegistration as bgFetch, with an id of "my-fetch".

navigator.serviceWorker.ready.then(async (swReg) => {
  const bgFetch = await swReg.backgroundFetch.fetch('my-fetch', ['/ep-5.mp3', 'ep-5-artwork.jpg'], {
    title: 'Episode 5: Interesting things.',
    icons: [{
      sizes: '300x300',
      src: '/ep-5-icon.png',
      type: 'image/png',
    }],
    downloadTotal: 60 * 1024 * 1024,
  });
});

Logging the id to the console returns "my-fetch".

console.log(bgFetch.id); // "my-fetch"

The match() method can be used to find a particular BackgroundFetchRecord from those that are part of the registration.

bgFetch.match('/ep-5.mp3').then(async (record) => {
  if (!record) {
    console.log('No record found');
    return;
  }

  console.log(`Here's the request`, record.request);
  const response = await record.responseReady;
  console.log(`And here's the response`, response);
});