BackgroundFetchRegistration
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
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
The following properties are available synchronously, as convenience properties copied from those in the BackgroundFetchRegistration
instance.
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-
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.recordsAvailable
Read only Experimental-
A
boolean
indicating whether therecordsAvailable
flag is set.
Instance methods
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
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"
.
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
BCD tables only load in the browser