Control how your app is launched.


![Thomas Steiner](https://web.dev/images/authors/thomassteiner.jpg) Thomas Steiner [GitHub](https://github.com/tomayac) [LinkedIn](https://www.linkedin.com/in/thomassteinerlinkedin) [Mastodon](https://toot.cafe/@tomayac) [Bluesky](https://bsky.app/profile/tomayac.com) [Homepage](https://blog.tomayac.com/)

<br />

The Launch Handler API lets you control how your app is launched, for example, whether it uses an
existing or a new window and whether the chosen window is navigated to the launch URL. As with
the File Handing API, this also enqueues a `LaunchParams` object in the launched page's `window.launchQueue`.

## Current status

| Step | Status |
|---|---|
| 1. Create explainer | [Complete](https://github.com/WICG/sw-launch/blob/main/launch_handler.md) |
| 2. Create initial draft of specification | [Complete](https://wicg.github.io/web-app-launch/) |
| 3. Gather feedback \& iterate on design | Complete |
| 4. Origin trial. | Complete |
| 5. **Launch** | **Complete** |

## Use the Launch Handler API

### Browser support


### Interfaces

The Launch Handler API defines two new interfaces.

`LaunchParams` : An object containing the `targetURL` to be handled by the consumer.
`LaunchQueue` : Queues launches until they are handled by the specified consumer.

#### The `launch_handler` manifest member

To declaratively specify the launch behavior of your app, add the `launch_handler` manifest member
to your manifest. It has one sub-field called `client_mode`. It lets you control whether a new or an
existing client should be launched and if this client should be navigated. The following example
shows a file with exemplary values that would always route all launches to a new
client.

```json
{
  "launch_handler": {
    "client_mode": "navigate-new"
  }
}
```

If unspecified, `launch_handler` defaults to `{"client_mode": "auto"}`. The allowed values for the
sub-fields are:

- `client_mode`:
  - `navigate-new`: A new browsing context is created in a web app window to load the launch's target URL.
  - `navigate-existing`: The most recently interacted with browsing context in a web app window is navigated to the launch's target URL.
  - `focus-existing`: The most recently interacted with browsing context in a web app window is chosen to handle the launch. A new `LaunchParams` object with its `targetURL` set to the launch URL will be enqueued in the document's `window.launchQueue`.
  - `auto`: The behavior is up to the user agent to decide what works best for the platform. For example, mobile devices only support single clients and would use `existing-client`, while desktop devices support multiple windows and would use `navigate-new` to avoid data loss.

The `client_mode` property also accepts a list (array) of values, where the first valid value will be
used. This is to allow new values to be added to the spec without breaking backwards compatibility
with existing implementations.

For example, if the hypothetical value `"focus-matching-url"` were added, sites would specify
`"client_mode": ["focus-matching-url", "navigate-existing"]` to continue to control the
behavior of older browsers that did not support `"focus-matching-url"`.

#### Use window.launchQueue

In the following code, the function `extractSongID()` extracts a `songID` from the URL
passed on launch. This is used to play a song in a music player PWA.

```javascript
if ('launchQueue' in window) {
  launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      const songID = extractSongId(launchParams.targetURL);
      if (songID) {
        playSong(songID);
      }
    }
  });
}
```

## Demo

You can see a demo of the Launch Handler API in action in the
[PWA Launch Handler Demo](https://mdn.github.io/dom-examples/launch-handler/). Be sure to check out the
[source code](https://github.com/mdn/dom-examples/tree/main/launch-handler) of the application to see how it uses the
Launch Handler API.

1. Install the *Musicr 2.0* app.
2. Send yourself a link in a chat application of the form `https://mdn.github.io/dom-examples/launch-handler/?track=https://example.com/music.mp3`. (You can customize `https://example.com/music.mp3` for any URL pointing to an audio file, for example, `https://mdn.github.io/dom-examples/launch-handler/?track=https://huggingface.co/spaces/VIDraft/PHI4-Multimodal/resolve/main/examples/harvard.wav`).
3. Click the link in your chat app and notice how *Musicr 2.0* opens and plays the track.
4. Click the link in your chat app again and notice that you won't get a second instance of *Musicr 2.0*.

## Feedback

The Chromium team wants to hear about your experiences with the Launch Handler API.

### Tell us about the API design

Is there something about the API that does not work like you expected? Or are there missing methods
or properties that you need to implement your idea? Have a question or comment on the security
model? File a spec issue on the corresponding [GitHub repo](https://github.com/WICG/sw-launch/issues), or add your thoughts to an
existing issue.

### Report a problem with the implementation

Did you find a bug with Chromium's implementation? Or is the implementation different from the spec?
File a bug at [new.crbug.com](https://new.crbug.com). Be sure to include as much detail as you can,
instructions for reproducing, and enter `Blink>AppManifest` in the **Components** box.

### Show support for the API

Are you planning to use the Launch Handler API? Your public support helps the Chromium team
prioritize features and shows other browser vendors how critical it is to support them.

Send a tweet to [@ChromiumDev](https://twitter.com/ChromiumDev) using the hashtag
[`#LaunchHandler`](https://twitter.com/search?q=%23LaunchHandler&src=recent_search_click&f=live) and
let us know where and how you are using it.

## Helpful links

- [Public explainer](https://github.com/WICG/sw-launch/blob/main/launch_handler.md)
- [Draft spec](https://wicg.github.io/web-app-launch/)
- [Launch Handler API Demo](https://mdn.github.io/dom-examples/launch-handler/) \| [Launch Handler API Demo source](https://github.com/mdn/dom-examples/tree/main/launch-handler)
- [Chromium tracking bug](https://bugs.chromium.org/p/chromium/issues/detail?id=1231886)
- [ChromeStatus.com entry](https://www.chromestatus.com/feature/5722383233056768)
- Blink Component: [`Blink>AppManifest`](https://bugs.chromium.org/p/chromium/issues/list?q=component:Blink%3EAppManifest)
- [TAG Review](https://github.com/w3ctag/design-reviews/issues/683)
- [Intent to Prototype](https://groups.google.com/a/chromium.org/g/blink-dev/c/8tNe2jrJ78A)