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 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. -
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, whereasnavigate-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 insidesetConsumer()
is passed aLaunchParams
object instance. LaunchQueue
-
When a progressive web app (PWA) is launched with a
launch_handler
client_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 the
LaunchQueue
class, which allows custom launch navigation handling to be implemented in a progressive web app (PWA), with the handling context signified by thelaunch_handler
manifest fieldclient_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