Background Fetch API
====================

Limited availability
--------------------

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **Background Fetch API** provides a method for managing downloads that may take a significant amount of time such as movies, audio files, and software.

Concepts and Usage
------------------

When a web application requires the user to download large files, this often presents a problem in that the user needs to stay connected to the page for the download to complete. If they lose connectivity, close the tab or navigate away from the page the download stops.

The Background Synchronization API provides a way for service workers to defer processing until a user is connected; however it can't be used for long running tasks such as downloading a large file. Background Sync requires that the service worker stays alive until the fetch is completed, and to conserve battery life and to prevent unwanted tasks happening in the background the browser will at some point terminate the task.

The Background Fetch API solves this problem. It creates a way for a web developer to tell the browser to perform some fetches in the background, for example when the user clicks a button to download a video file. The browser then performs the fetches in a user-visible way, displaying progress to the user and giving them a method to cancel the download. Once the download is complete the browser then opens the service worker, at which point your application can do something with the response if required.

The Background Fetch API will enable the fetch to happen if the user starts the process while offline. Once they are connected it will begin. If the user goes off line, the process pauses until the user is on again.

Interfaces
----------

`BackgroundFetchManager` 
Experimental

A map where the keys are background fetch IDs and the values are `BackgroundFetchRegistration` objects.

`BackgroundFetchRegistration` 
Experimental

Represents a Background Fetch.

`BackgroundFetchRecord` 
Experimental

Represents an individual fetch request and response.

`BackgroundFetchEvent` 
Experimental

The event type for the `backgroundfetchabort` and `backgroundfetchclick` event

`BackgroundFetchUpdateUIEvent` 
Experimental

The event type for the `backgroundfetchsuccess` and `backgroundfetchfail` event

### Extensions to other interfaces

`ServiceWorkerRegistration.backgroundFetch` Read only  
Experimental

Returns a reference to a `BackgroundFetchManager` object, which manages background fetch operations.

`backgroundfetchabort` event 
Experimental

Fired when a background fetch operation has been canceled by the user or the app.

`backgroundfetchclick` event 
Experimental

Fired when the user has clicked on the UI for a background fetch operation.

`backgroundfetchfail` event 
Experimental

Fired when at least one of the requests in a background fetch operation has failed.

`backgroundfetchsuccess` event 
Experimental

Fired when all of the requests in a background fetch operation have succeeded.

Examples
--------

Before using Background Fetch, check for browser support.


```js
if (!("BackgroundFetchManager" in self)) {
  // Provide fallback downloading.
}
```


 Using Background Fetch requires a registered service worker. Then call `backgroundFetch.fetch()` to perform a fetch. This
 returns a promise that resolves with a `BackgroundFetchRegistration`.

A background fetch may fetch a number of files. In our example the fetch requests an MP3 and a JPEG. This enables a package of files that the user sees as one item (for example a podcast and artwork) to be downloaded at once.


```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,
    },
  );
});
```


You can find a demo application which implements Background Fetch here.

Specifications
--------------

| Specification |
| --- |
| Background Fetch  |

Browser compatibility
---------------------

### api.BackgroundFetchManager

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

### api.BackgroundFetchRegistration

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

### api.BackgroundFetchRecord

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

See also
--------

* Introducing Background Fetch
* Background Fetch - HTTP 203