Launch Handler API
==================

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

The **Launch Handler API** allows developers to control how a progressive web app (PWA) is launched — for example if it uses an existing window or creates a new one, and how the app's target launch URL is handled.

Concepts and usage
------------------

You can specify launch behavior for your app by adding the `launch_handler` field to your web app manifest file. This has one sub-field, `client_mode`, which contains a string value specifying how the app should be launched and navigated to. For example:


```json
"launch\_handler": {
    "client\_mode": "focus-existing"
}
```


If not specified, the default `client_mode` value is `auto`. Available values are:

`focus-existing`

The most recently interacted with browsing context in a web app window is chosen to handle the launch. This will populate the target launch URL in the `targetURL` property of the `LaunchParams` object passed into the `window.launchQueue.setConsumer()`'s callback function. As you'll see below, this allows you to set custom launch handing functionality for your app.

`navigate-existing`

The most recently interacted with browsing context in a web app window is navigated to the target launch URL. The target URL is still made available via `window.launchQueue.setConsumer()` to allow additional custom launch navigation handling to be implemented.

`navigate-new`

A new browsing context is created in a web app window to load the target launch URL. The target URL is still made available via `window.launchQueue.setConsumer()` to allow additional custom launch navigation handling to be implemented.

`auto`

The user agent decides what works best for the platform. For example, `navigate-existing` might make more sense on mobile, where single app instances are commonplace, whereas `navigate-new` might make more sense in a desktop context. This is the default value used if provided values are invalid.

When `focus-existing` is used, you can include code inside the `window.launchQueue.setConsumer()`'s callback function to provide custom handling of the `targetURL`


```js
window.launchQueue.setConsumer((launchParams) => {
  // Do something with launchParams.targetURL
});
```


**Note:** `LaunchParams` also has a `LaunchParams.files` property, which returns a read-only array of `FileSystemHandle` objects representing any files passed along with the launch navigation via the `POST` method. This allows custom file handling to be implemented.

Interfaces
----------

`LaunchParams`

Used when implementing custom launch navigation handling in a PWA. When `window.launchQueue.setConsumer()` is invoked to set up the launch navigation handling functionality, the callback function inside `setConsumer()` is passed a `LaunchParams` object instance.

`LaunchQueue`

When a progressive web app (PWA) is launched with a `launch_handler` `client_mode` value of `focus-existing`, `navigate-new`, or `navigate-existing`, `LaunchQueue` provides access to functionality that allows custom launch navigation handling to be implemented in the PWA. This functionality is controlled by the properties of the `LaunchParams` object passed into the `setConsumer()` callback function.

Extensions to other interfaces
------------------------------

`window.launchQueue`

Provides access to the `LaunchQueue` class, which allows custom launch navigation handling to be implemented in a progressive web app (PWA), with the handling context signified by the `launch_handler` manifest field `client_mode` value.

Examples
--------


```js
if ("launchQueue" in window) {
  window.launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      const params = new URL(launchParams.targetURL).searchParams;

      // Assuming a music player app that gets a track passed to it to be played
      const track = params.get("track");
      if (track) {
        audio.src = track;
        title.textContent = new URL(track).pathname.substr(1);
        audio.play();
      }
    }
  });
}
```


This code is included in the PWA, and executed when the app loads, upon launch. The `window.launchQueue.setConsumer()`'s callback function extracts the search param out of the `LaunchParams.targetURL` and, if it finds a `track` param, uses it to populate an `<audio>` element's `src` and play the audio track that this points to.

See the Musicr 2.0 demo app for full working code.

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

| Specification |
| --- |
| Web App Launch Handler API # launchqueue-interface |

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

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

See also
--------

* Launch Handler API: Control how your app is launched
* Musicr 2.0 demo app