BackgroundFetchRegistration

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

Note: This feature is available in Web Workers.

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.

EventTarget BackgroundFetchRegistration

Instance properties

Also inherits properties from its parent, EventTarget.

BackgroundFetchRegistration.id Read only Experimental

A string containing the background fetch's ID.

BackgroundFetchRegistration.uploadTotal Read only Experimental

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

BackgroundFetchRegistration.uploaded Read only Experimental

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

BackgroundFetchRegistration.downloadTotal Read only Experimental

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.downloaded Read only Experimental

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

BackgroundFetchRegistration.result Read only Experimental

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

BackgroundFetchRegistration.failureReason Read only Experimental

A string with a value that indicates a reason for a background fetch failure. Can be one of the following values: "", "aborted", "bad-status", "fetch-error", "quota-exceeded", "download-total-exceeded".

BackgroundFetchRegistration.recordsAvailable Read only Experimental

A boolean indicating whether the recordsAvailable flag is set.

Instance methods

Also inherits methods from its parent, EventTarget.

BackgroundFetchRegistration.abort() Experimental

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

BackgroundFetchRegistration.match() Experimental

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

BackgroundFetchRegistration.matchAll() Experimental

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

Events

Also inherits events from its parent, EventTarget.

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

progress Experimental

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

Examples

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

js
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".

js
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.

js
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);
});

Specifications

Specification
Background Fetch
# background-fetch-registration

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
BackgroundFetchRegistration
Experimental
abort
Experimental
downloadTotal
Experimental
downloaded
Experimental
failureReason
Experimental
id
Experimental
match
Experimental
matchAll
Experimental
progress event
Experimental
recordsAvailable
Experimental
result
Experimental
uploadTotal
Experimental
uploaded
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.