Launch Handler API

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:

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

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

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

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.slice(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

See also

• Launch Handler API: Control how your app is launched