W3cubDocs

/Web APIs

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.

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.

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

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
Launch_Handler_API 102 102 No No 88 No 102 102 No 70 No 19.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Launch_Handler_API