Control how your app is launched

The Launch Handler API is part of the capabilities project and is
currently in development. This post will be updated as the implementation progresses.

What is the Launch Handler API? #
There are many ways to launch a Progressive Web App. Probably t…


This content originally appeared on web.dev and was authored by Thomas Steiner

What is the Launch Handler API? #

There are many ways to launch a Progressive Web App. Probably the most common is via the icon on the home screen or the app drawer of the device. But when you think about it, there are many other ways a launch can happen:

There are even more ways, but you get the idea. Given the manifold possibilities for launching PWAs, what has been missing is a way to let apps customize their launch behavior across all types of app launch triggers. The launch_handler manifest member together with the window.launchQueue interface enables PWAs to do just that.

Suggested use cases for the Launch Handler API #

Examples of sites that may use this API include:

  • Apps that prefer to only have a single instance of themselves open at any time, with new navigations focusing the existing instance. Examples include apps like music players or games, where it generally makes sense to only have one instance of the app open at any time.
  • Apps that enable multi-document management, but within their own single instance, for example, an HTML-implemented tab strip, floating sub-windows, or apps using tabbed application mode.

Current status #

Step Status
1. Create explainer Complete
2. Create initial draft of specification Not started
3. Gather feedback & iterate on design In progress
4. Origin trial Started
5. Launch Not started

How to use the Launch Handler API #

Enabling via about://flags #

To experiment with the Launch Handler API locally, without an origin trial token, enable the #enable-desktop-pwas-launch-handler flag in about://flags.

Enabling support during the origin trial phase #

Starting in Chromium 98, the Launch Handler API will be available as an origin trial in Chromium. The origin trial is expected to end in Chromium 102 (June 15, 2022).

Origin trials allow you to try new features and give feedback on their usability, practicality, and effectiveness to the web standards community. For more information, see the Origin Trials Guide for Web Developers. To sign up for this or another origin trial, visit the registration page.

Register for the origin trial #

  1. Request a token for your origin.
  2. Add the token to your pages. There are two ways to do that:
    • Add an origin-trial <meta> tag to the head of each page. For example, this may look something like:
      <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
    • If you can configure your server, you can also add the token using an Origin-Trial HTTP header. The resulting response header should look something like:
      Origin-Trial: TOKEN_GOES_HERE

Feature detection #

To check if the Launch Handler API is supported, use:

if ('launchQueue' in window && 'targetURL' in LaunchParams.prototype) {
  // The Launch Handler API is supported.
}

The launch_handler manifest member #

To declaratively specify the launch behavior of your app, add the launch_handler manifest member to your manifest. It has two sub-fields, route_to and navigate_existing_client. The former lets you control whether a new or an existing client should be launched, and the latter how and if this client should be navigated. The Web App Manifest excerpt below shows a file with exemplary values that would always route all launches to a new client.

{
  "launch_handler": {
    "route_to": "new-client",
    "navigate_existing_client": "always"
  }
}

If unspecified, launch_handler defaults to {"route_to": "auto", "navigate_existing_client": "always"}. The allowed values for the sub-fields are as follows:

  • route_to:

    • new-client: A new browsing context is created in a web app window to load the launch's target URL.
    • existing-client: An existing browsing context is used, specifically the one most recently used. How the launch is handled within that browsing context depends on navigate_existing_client.
    • auto: The behavior is up to the user agent to decide what works best for the platform. For example, mobile devices only support single clients and would use existing-client, while desktop devices support multiple windows and would use new-client to avoid data loss.

  • navigate_existing_client:

    • always: Existing browsing contexts chosen for launch will navigate the browsing context to the launch's target URL.
    • never: Existing browsing contexts chosen for launch will not be navigated and instead have targetURL in the enqueued LaunchParams set to the launch's target URL.

Both route_to and navigate_existing_client also accept a list (array) of values, where the first valid value will be used. This is to allow new values to be added to the spec without breaking backwards compatibility with existing implementations.

For example, if the hypothetical value "matching-url-client" were added, sites would specify "route_to": ["matching-url-client", "existing-client"] to continue to control the behavior of older browsers that did not support "matching-url-client".

The window.launchQueue interface #

If the app has declared that it wants to handle launches in an existing client (by specifying "route_to": "existing-client"), it can imperatively do something with incoming launch URLs. This is where the launchQueue comes into play. To access launch target URLs, a site needs to specify a consumer for the window.launchQueue object, which is then passed the target URL via the launchParams.targetURL field. Launches are queued until they are handled by the specified consumer, which is invoked exactly once for each launch. In this manner, every launch is handled, regardless of when the consumer was specified. The code snippet below shows a fictive audio player PWA that extracts a song ID from a target URL that it is potentially passed on launch.

launchQueue.setConsumer((launchParams) => {
  const songID = extractSongId(launchParams.targetURL);
  if (songID) {
    playSong(songID);
  }
});

Demo #

You can see a demo of the Launch Handler API in action in the PWA Launch Handler Demo. Be sure to check out the source code of the application to see how it uses the Launch Handler API.

  1. Install the Musicr 2.0 app on a Chrome OS device.
  2. Send yourself a link in a chat application of the form https://launch-handler.glitch.me?track=https://example.com/music.mp3. (You can customize https://example.com/music.mp3 for any URL pointing to an audio file, for example, https://launch-handler.glitch.me?track=https://cdn.glitch.me/3e952c9c-4d6d-4de4-9873-23cf976b422e%2Ffile_example_MP3_700KB.mp3?v=1638795977190).
  3. Click the link in your chat app and notice how Musicr 2.0 opens and plays the track.
  4. Click the link in your chat app again and notice that you will not get a second instance of Musicr 2.0.
Musicr 2.0 web application launched and playing music it handled from the launch params.

Security and permissions #

The Chromium team designed and implemented the Launch Handler API using the core principles defined in Controlling Access to Powerful Web Platform Features, including user control, transparency, and ergonomics.

Feedback #

The Chromium team wants to hear about your experiences with the Launch Handler API.

Tell us about the API design #

Is there something about the API that does not work like you expected? Or are there missing methods or properties that you need to implement your idea? Have a question or comment on the security model? File a spec issue on the corresponding GitHub repo, or add your thoughts to an existing issue.

Report a problem with the implementation #

Did you find a bug with Chromium's implementation? Or is the implementation different from the spec? File a bug at new.crbug.com. Be sure to include as much detail as you can, simple instructions for reproducing, and enter Blink>AppManifest in the Components box. Glitch works great for sharing quick and easy repros.

Show support for the API #

Are you planning to use the Launch Handler API? Your public support helps the Chromium team prioritize features and shows other browser vendors how critical it is to support them.

Send a tweet to @ChromiumDev using the hashtag #LaunchHandler and let us know where and how you are using it.

Helpful links #

Acknowledgements #

Hero image by SpaceX on Unsplash.


This content originally appeared on web.dev and was authored by Thomas Steiner


Print Share Comment Cite Upload Translate Updates
APA

Thomas Steiner | Sciencx (2021-12-14T00:00:00+00:00) Control how your app is launched. Retrieved from https://www.scien.cx/2021/12/14/control-how-your-app-is-launched/

MLA
" » Control how your app is launched." Thomas Steiner | Sciencx - Tuesday December 14, 2021, https://www.scien.cx/2021/12/14/control-how-your-app-is-launched/
HARVARD
Thomas Steiner | Sciencx Tuesday December 14, 2021 » Control how your app is launched., viewed ,<https://www.scien.cx/2021/12/14/control-how-your-app-is-launched/>
VANCOUVER
Thomas Steiner | Sciencx - » Control how your app is launched. [Internet]. [Accessed ]. Available from: https://www.scien.cx/2021/12/14/control-how-your-app-is-launched/
CHICAGO
" » Control how your app is launched." Thomas Steiner | Sciencx - Accessed . https://www.scien.cx/2021/12/14/control-how-your-app-is-launched/
IEEE
" » Control how your app is launched." Thomas Steiner | Sciencx [Online]. Available: https://www.scien.cx/2021/12/14/control-how-your-app-is-launched/. [Accessed: ]
rf:citation
» Control how your app is launched | Thomas Steiner | Sciencx | https://www.scien.cx/2021/12/14/control-how-your-app-is-launched/ |

Please log in to upload a file.



There are no updates yet.
Click the Upload button above to add an update.

You must be logged in to translate posts. Please log in or register.

Related Posts