Definition

protocol_handlers (manifest field)

Short definition

protocol_handlers is a manifest array such as [{"protocol": "web+music", "url": "/play?track=%s"}] that registers the installed app as a handler for a URL scheme. Clicking a web+music: link anywhere in the OS, after the user confirms a one-time permission prompt, opens the app at the given URL with %s replaced by the encoded link.

Reviewed July 25, 2026

Custom schemes must be prefixed with "web+" (or be one of a short allow-list of existing schemes like mailto and tel) for security reasons — arbitrary protocol names like "myapp" are rejected by the spec.

Registration only takes effect after install; a site running as a normal open tab cannot claim a protocol handler, which keeps the feature from being abused by untrusted pages the user has merely visited.

The %s placeholder in the target URL is mandatory and is substituted with the percent-encoded value of the full activating URL, so the handler page must parse it back out with the URL/URLSearchParams API.

Browser support is currently limited to Chromium-based browsers; Safari and Firefox do not implement protocol_handlers as of this writing, per the MDN compatibility table at https://developer.mozilla.org/en-US/docs/Web/Manifest/protocol_handlers.

Related terms

Web App Manifest

A Web App Manifest is a JSON file (usually manifest.webmanifest) that declares your app's name, icons, start URL, theme colour and display mode. The browser reads it to render the install prompt and the home-screen icon.

share_target (manifest field)

share_target is a manifest object, for example {"action": "/share", "method": "POST", "enctype": "multipart/form-data", "params": {"title": "title", "text": "text", "url": "url", "files": [{"name": "media", "accept": ["image/*"]}]}}, that adds the installed PWA as a destination in the operating system's native share sheet.

shortcuts (manifest field)

shortcuts is a manifest array of up to (practically) four entries, each with name, url and optional icons, that appear when a user long-presses the installed app icon on Android or right-clicks it on Windows/ChromeOS. Example: {"name": "New order", "url": "/orders/new", "icons": [{"src": "/shortcut-new.png", "sizes": "96x96"}]}.

install event (service worker)

The install event fires on the ServiceWorkerGlobalScope the first time a browser registers a new or updated service worker script. Handlers typically call event.waitUntil(caches.open(...).then(cache => cache.addAll([...]))) to pre-cache the app shell before the worker is allowed to move to the "installed" state.

activate event (service worker)

The activate event fires after a service worker moves from "installed" to "activating", typically once the old worker's clients have all closed or skipWaiting() was called. Handlers commonly use it to clean up outdated Cache Storage entries left behind by earlier versions of the app shell.

fetch event (service worker)

The fetch event fires in the service worker for every navigation, script, image or XHR request originating from a page it controls. Calling event.respondWith(promise) lets the worker substitute its own Response, most commonly by checking the Cache Storage API first and falling back to fetch() from the network.