Skip to Content
Platform.Ontology

Launch Handler

Controls how an installed app reopens when a link is clicked.

Works without askingHome screen and system linksWindowWeb browsersWhile you use it

In one line

Can choose whether links reopen your installed app in its existing window or a new one

Controls how an installed app reopens when a link is clicked.

Picks reuse of the existing window or a new one.

What it can and can't do

What the user does: You click a link that opens in your installed web app

It can

  • Reuse the app's open window when you click a link
  • Open a new window instead
  • Pass the link to the app that is already running

It cannot

  • Work for a site that is not installed
  • Open links outside the app on its own
  • Work in Firefox or Safari
  • Change how other apps open

How it differs between platforms: Chrome, Edge and Samsung Internet only. Firefox, Safari and iPhone do not support it.

Browser support

BrowserStatusFirst versionReleasedNote
ChromeSupported1102023-02-07None
EdgeSupported1102023-02-09None
FirefoxNot supportedNot availableNot listedNone
SafariNot supportedNot availableNot listedNone
Safari on iPhoneNot supportedNot availableNot listedNone
Chrome on AndroidSupported1102023-02-07None
Samsung InternetSupported21.02023-05-19None

How a site asks for it

APImanifest launch_handler {client_mode}
Browser compat keysmanifests.webapp.launch_handler
How access is grantedinstall
What the user seesNone
Needs a secure context (HTTPS)Yes
Needs a user gestureNo
How long it lastsPer origin
How to take it backSite settings
Inside an iframeSame as top level; cross-origin iframes need a permissions policy where listed

Typical flow

  1. Call the API
  2. Browser applies its access rules
  3. Page receives the result

Data you get

What comes back: Controls how an installed app reopens when a link is clicked.
Shape: object
How often: on demand

FieldTypeUnitRangePrecision
client_modeenumNoneauto, navigate-new, navigate-existing, focus-existingNot listed

Technical limits

  • Installed PWA only

The story

What it is

An installed web app picks whether a clicked link reuses its open window or opens a new one.

For you

You click a link to your app, and it opens in the window you already have, instead of a pile of new windows. It feels tidy and like a normal desktop app.

For makers

Makers choose between single window and many windows for a better flow. A chat app can jump to the right thread in the open window. It is a polish feature for installed web apps.

Where you see it

TypeExampleApps
messagingA chat app takes you to the right conversation in the window you already have open.Slack
musicA web music player plays the clicked track in the existing player, not a second one.None named
productivityA web mail app opens a new message in the main window when you click a mail link.Gmail
gamesA web game launcher reuses its window when you click a game invite link.None named
videoA web video call app takes your meeting link to the call window you already have.Google Meet
creativeA web design app opens a shared file link in its existing window as a new tab.Figma
enterpriseA company portal opens a link to a ticket in the same app window to keep staff focused.None named

Risks

  • Only installed apps
  • Can surprise users

What the platform says

Good uses and abuse

Legitimate uses

  • Single window apps

Known abuse

  • None

Scores

ScoreValueMeaning
Sensitivity1 of 5How revealing the data is
Utility2 of 5How useful it is to honest apps
Friction1 of 5How much the user has to do
Fingerprint bitsNot ratedRough identifying entropy, when known

History

  • 2023-02, Chrome 110: Launch Handler ships

Sources

How well checked: Checked against real behavior.

On this page