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.
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, initially0
. 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, or0
. BackgroundFetchRegistration.downloaded
Read only Experimental-
A
number
containing the size in bytes that has been downloaded, initially0
. 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 therecordsAvailable
flag is set.
Instance methods
Also inherits methods from its parent, EventTarget
.
BackgroundFetchRegistration.abort()
Experimental-
Aborts the background fetch. Returns a
Promise
that resolves withtrue
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 ofBackgroundFetchRecord
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
orfailureReason
.
Examples
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);
});
Specifications
Specification |
---|
Background Fetch # background-fetch-registration |
Browser compatibility
BCD tables only load in the browser