Launch Handler API
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:
{
"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 LaunchParams.targetURL property of the LaunchParams object passed into the 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 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 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, <code>navigate-existing</code> might make more sense on mobile, where single app instances are commonplace, whereas <code>navigate-new</code> 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 LaunchQueue.setConsumer's callback function to provide custom handling of the LaunchParams.targetURL
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
POSTmethod. This allows custom file handling to be implemented.
Interfaces
- LaunchParams
- : Used when implementing custom launch navigation handling in a PWA. When LaunchQueue.setConsumer is invoked to set up the launch navigation handling functionality, the callback function inside
setConsumer()is passed aLaunchParamsobject instance.
- : Used when implementing custom launch navigation handling in a PWA. When LaunchQueue.setConsumer is invoked to set up the launch navigation handling functionality, the callback function inside
- LaunchQueue
- : When a progressive web app (PWA) is launched with a
launch_handlerclient_modevalue offocus-existing,navigate-new, ornavigate-existing,LaunchQueueprovides 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 LaunchQueue.setConsumer callback function.
- : When a progressive web app (PWA) is launched with a
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_handlermanifest fieldclient_modevalue.
- : 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
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 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
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
