Launch Handler API

Limited availability

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

Experimental:This is anexperimental technology
Check theBrowser compatibility table carefully before using this in production.

TheLaunch Handler API allows developers to control how aprogressive 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 thelaunch_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 defaultclient_mode value isauto. 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 thetargetURL property of theLaunchParams object passed into thewindow.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 viawindow.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 viawindow.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, whereasnavigate-new might make more sense in a desktop context. This is the default value used if provided values are invalid.

Whenfocus-existing is used, you can include code inside thewindow.launchQueue.setConsumer()'s callback function to provide custom handling of thetargetURL

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

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

Interfaces

LaunchParams: Used when implementing custom launch navigation handling in a PWA. Whenwindow.launchQueue.setConsumer() is invoked to set up the launch navigation handling functionality, the callback function insidesetConsumer() is passed aLaunchParams object instance.
LaunchQueue: When aprogressive web app (PWA) is launched with alaunch_handlerclient_mode value offocus-existing,navigate-new, ornavigate-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 theLaunchParams object passed into thesetConsumer() callback function.

Extensions to other interfaces

window.launchQueue: Provides access to theLaunchQueue class, which allows custom launch navigation handling to be implemented in aprogressive web app (PWA), with the handling context signified by thelaunch_handler manifest fieldclient_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. Thewindow.launchQueue.setConsumer()'s callback function extracts the search param out of theLaunchParams.targetURL and, if it finds atrack param, uses it to populate an<audio> element'ssrc and play the audio track that this points to.

See theMusicr 2.0 demo app for full working code.