Launch Handler
Controls how an installed app reopens when a link is clicked.
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
| Browser | Status | First version | Released | Note |
|---|---|---|---|---|
| Chrome | Supported | 110 | 2023-02-07 | None |
| Edge | Supported | 110 | 2023-02-09 | None |
| Firefox | Not supported | Not available | Not listed | None |
| Safari | Not supported | Not available | Not listed | None |
| Safari on iPhone | Not supported | Not available | Not listed | None |
| Chrome on Android | Supported | 110 | 2023-02-07 | None |
| Samsung Internet | Supported | 21.0 | 2023-05-19 | None |
How a site asks for it
| API | manifest launch_handler {client_mode} |
| Browser compat keys | manifests.webapp.launch_handler |
| How access is granted | install |
| What the user sees | None |
| Needs a secure context (HTTPS) | Yes |
| Needs a user gesture | No |
| How long it lasts | Per origin |
| How to take it back | Site settings |
| Inside an iframe | Same as top level; cross-origin iframes need a permissions policy where listed |
Typical flow
- Call the API
- Browser applies its access rules
- 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
| Field | Type | Unit | Range | Precision |
|---|---|---|---|---|
client_mode | enum | None | auto, navigate-new, navigate-existing, focus-existing | Not 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
| Type | Example | Apps |
|---|---|---|
| messaging | A chat app takes you to the right conversation in the window you already have open. | Slack |
| music | A web music player plays the clicked track in the existing player, not a second one. | None named |
| productivity | A web mail app opens a new message in the main window when you click a mail link. | Gmail |
| games | A web game launcher reuses its window when you click a game invite link. | None named |
| video | A web video call app takes your meeting link to the call window you already have. | Google Meet |
| creative | A web design app opens a shared file link in its existing window as a new tab. | Figma |
| enterprise | A 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
- MDN Web Docs: launch_handler. A setting that tells an installed web app how to open when launched, such as reusing an existing window.
Good uses and abuse
Legitimate uses
- Single window apps
Known abuse
- None
Scores
| Score | Value | Meaning |
|---|---|---|
| Sensitivity | 1 of 5 | How revealing the data is |
| Utility | 2 of 5 | How useful it is to honest apps |
| Friction | 1 of 5 | How much the user has to do |
| Fingerprint bits | Not rated | Rough identifying entropy, when known |
History
- 2023-02, Chrome 110: Launch Handler ships
Sources
How well checked: Checked against real behavior.