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.

EventTarget

BackgroundFetchRegistrationInstance 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, 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

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 the `recordsAvailable` flag is set.

Instance methods
----------------

`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
------

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.