Manifest member in Manifest
protocol_handlers manifest member
Published Updated
The protocol_handlers manifest member registers an installed web app with the operating system as a handler for URL schemes. Its value is an array of { protocol, url } objects. After registration, clicking a web+note:// or mailto: link in any application opens the web app at the url,
with %s replaced by the full link.
Chrome 96 and Edge 96 implement the member for desktop installs on Windows and macOS as well as Linux
(BCD manifests.webapp.protocol_handlers). Chrome on Android and Samsung Internet do not read it. Neither do Firefox 157 or
Safari 27. The runtime API navigator.registerProtocolHandler() covers a
different case: it registers the current site as a handler, and the browser may ask
the user to confirm it; the manifest member registers at install time and integrates with the OS.
Member
Section titled “Member”| Property | Value |
|---|---|
| Type | array of objects. Each object has two required strings: protocol, a scheme name without the colon, and url, an HTTPS URL inside the manifest scope that contains the literal token %s. A relative url resolves against the manifest URL. |
| Default | an empty array; nothing is registered. |
| Example value | [{ "protocol": "web+note", "url": "/open?note=%s" }]. |
protocol must be either a custom scheme beginning with web+ followed by lowercase ASCII
letters, or one of the schemes the HTML Standard safelists: bitcoin, ftp, ftps, geo,
im, irc, ircs, magnet, mailto, matrix, mms, news, nntp, openpgp4fpr, sftp,
sip, sms, smsto, ssh, tel, urn, webcal, wtai, and xmpp. Anything else, such
as note or ms-word, is skipped.
Chromium’s parser drops malformed entries and keeps the rest of the array:
protocol_handlers entry ignored, required property 'protocol' is invalid. and
protocol_handlers entry ignored, required property 'url' is invalid. name the missing field,
and a url without the token produces The url provided ('/open?note=') does not contain '%s'. The spec also skips an entry whose url falls outside scope and a second entry whose
normalized url duplicates an earlier one.
Registration is per install: Chrome writes the handler into the OS when the app is installed and removes it on uninstall. The first time a link with the scheme launches the app, Chrome shows a confirmation dialog naming the app before navigating, and the OS may ask the user to pick a default when more than one application claims the scheme.
Examples
Section titled “Examples”The manifest side is a few lines; the handler page has to cope with a value that may be absent, encoded, or not the scheme it expected.
Registering a custom web+ scheme for a notes app
Section titled “Registering a custom web+ scheme for a notes app”A notes app claims web+note so that web+note://2026-10-03 links in email and chat open the
matching entry. The url sits under the app’s scope and carries %s as a query value, which
keeps the rest of the path static.
{ "name": "Notebook", "start_url": "/", "scope": "/", "display": "standalone", "protocol_handlers": [ { "protocol": "web+note", "url": "/open?note=%s" } ]}Only one handler per scheme is registered; listing the same protocol twice with different
URLs keeps the first entry.
Decoding the substituted link on the handler page
Section titled “Decoding the substituted link on the handler page”The browser replaces %s with the entire link, so the page receives web+note://2026-10-03,
not 2026-10-03, with characters such as # percent-encoded. Read the raw query value and
decode it yourself: URLSearchParams turns + into a space and would corrupt web+note. The fallback branch
renders the ordinary page when the value is missing or carries another scheme, which is what a
direct visit to /open looks like.
const raw = location.search.match(/[?&]note=([^&]*)/)?.[1];let link = null;try { link = raw ? decodeURIComponent(raw) : null;} catch { link = null; // malformed percent-encoding: treat as no link}
if (link?.startsWith('web+note://')) { openNote(link.slice('web+note://'.length)); // "2026-10-03"} else { showNoteList(); // direct visit, or a scheme this page does not handle}Replace the query with history.replaceState() after reading it so a reload or a bookmark does
not re-run the handler.
Falling back to the runtime API where the manifest is ignored
Section titled “Falling back to the runtime API where the manifest is ignored”On browsers without the manifest member, navigator.registerProtocolHandler() registers the
same scheme as a handler for the current site, and the browser may ask the user to confirm. Calling it from a button click is a reasonable pattern. Feature-detect
both and expose a button for the runtime path.
export function offerProtocolRegistration(button) { const installed = matchMedia('(display-mode: standalone)').matches; if (installed) return; // Chrome/Edge desktop: the manifest already registered web+note if (typeof navigator.registerProtocolHandler !== 'function') return; // Safari: no path button.hidden = false; button.addEventListener('click', () => { navigator.registerProtocolHandler('web+note', `${location.origin}/open?note=%s`); });}Firefox 157 accepts the runtime registration for web+ schemes.
See also
Section titled “See also”- Manifest protocol_handlers: registering a PWA for custom URL schemes
- scope manifest member
- launch_handler manifest member
- Manifest Incubations: protocol_handlers member (wicg.github.io)
- Handle protocols in PWAs (learn.microsoft.com)
- Navigator: registerProtocolHandler() method (developer.mozilla.org)
Specifications
| Specification | Status |
|---|---|
| Manifest Protocol Handlers | W3C |
| Manifest Incubations: protocol_handlers member | WICG draft |
| HTML Standard: safelisted schemes | WHATWG living standard |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Desktop)# | Yes | 96 | high | source | — |
| Chrome (Android)# | No | — | high | source | 1 |
| Edge (Desktop)# | Yes | 96 | high | source | 2 |
| Firefox (Desktop)# | No | — | high | source | 3 |
| Firefox (Android)# | No | — | high | source | 45 |
| Safari (macOS)# | No | — | high | source | 6 |
| Safari (iOS)# | No | — | high | source | 78 |
| Samsung Internet# | No | — | high | source | 910 |
| WebView (Android)# | No | — | high | source | 1112 |
- No Chrome Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Chrome.
- No Firefox support is recorded in browser-compat-data.
- No Firefox for Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Firefox.
- No Safari support is recorded in browser-compat-data.
- No Safari on iOS support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Safari.
- No Samsung Internet support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Chrome Android.
- No WebView Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Chrome Android.