AppOrWeb-to-WebApp Communication: Custom Scheme Handlers

I’ve previously written about Web-to-App communication via Application Protocols. App Protocols allow web content to invoke a native application outside of the browser.

WebApp advocates (like me!) want to continue to close the native/browser gaps that prevent web applications from becoming full-fledged replacements for native apps. To that end, I’ve recently spent some time looking at how the web platform allows JavaScript registration of a protocol handler, where the handling “app” is a same-origin web page.

Currently supported by Firefox and Chromium-based browsers (on platforms other than Android), the function navigator.registerProtocolHandler(scheme, url_template, description) enables a website to become a handler for a URL scheme.

Real-World Usage

The canonical use-case for this is web based email clients like Gmail. Gmail would like to be able to be the user’s handler for mailto links. When the user clicks a mailto link, the content of the link should be sent to a handler page on mail.google.com which responds accordingly (e.g. by creating a new email to the specified addressee).

https://mail.google.com/mail/u/0/?extsrc=mailto&url=mailto:u@example.com

The registerProtocolHandler API isn’t limited to the mailto scheme, however. It presently supports a short list of allowed schemes¹, and any scheme named web+{one-or-more-lowercaseASCII}.

User Experience

I’ve built a page containing a number of test cases here. When you push the button to register a protocol handler, you receive a permission prompt from Chrome/Edge or Firefox:

To avoid annoying users, if the user declines Chrome’s prompt, the site is blocked from re-requesting permission to handle the protocol. A user must manually visit the settings page to unblock permission.

User-Activation Requirements

If a page attempts to call registerProtocolHandler() on load or before the user has interacted with the page (a so-called “gesture”), then Chromium-based browsers will not pop the permission prompt. Instead, an overlapping-diamonds icon is shown at the right-hand side of the address bar, with the text “This page wants to install a service handler.” Here’s what this looks like on Gmail:

Settings

Within Chrome, you can view your currently registered handlers (and sites blocked from asking to become the registered handler) by visiting chrome://settings/content/handlers.

Operating System Integration

One particularly interesting aspect of allowing web-based registration of protocol handlers is that it is desirable for the rest of the operating system outside of the browser to respect those protocol handler associations.

For example, clicking a mailto link in some other application should launch the browser to the web-based handler if registered. However, having the browser change system state in this manner is complicated, especially on modern versions of Windows whereby various protections have been put in place to try to prevent “hijacking” of file type and protocol handler associations.

Edge and Chrome will only attempt to become the systemwide handler for a protocol when running a channel that offers to become the default browser (e.g. Stable). On such a channel, if the browser wasn’t already the handler for the protocol, after the user clicks “Allow” on the Chrome permission bubble, a Windows UAC dialog is shown:

If the user accepts by clicking “Yes”, the RegisterChromeForProtocol function silently updates the registry:

PWAs as Handlers

There is significant interest in allowing Progressive Web Applications to register as handlers for URL schemes.

Other Things I’ve Learned

• Chrome, Edge, and Firefox disallow registration of protocol handlers in Private/Incognito/InPrivate modes; the call fails silently.
• With my patch landed, Chrome, Edge, and Firefox disallow registration of protocol handlers from non-secure contexts (e.g. HTTP). Due to the same-origin requirement for the handler URL, this effectively prevents the use of a non-secure page as a handler.
• An upcoming patch proposes blocking registration from cross-origin subframes.
• Chromium-based browsers enable IT admins to set default scheme-to-web mappings using Group Policy.
• Chromium-based browsers do not (as of v93) offer a Group Policy to disallow protocol handler registration; an end-user setting inside about://settings does allow an individual user to turn off the prompts.
• Chromium versions prior to v81 failed to enforce specified limits on web+ protocol names. Firefox and Chromium v81+ do enforce the limits.
• Firefox does not support targeting a RPH registered protocol as the target of a form POST request; it silently drops the POST body.
• Firefox does not implement the unregisterProtocolHandler API. Users must manually unregister protocol handlers using the browser UI.
• On Windows at least, neither Firefox Stable nor Firefox Nightly seems to try to become the systemwide handler for a scheme.
• If you have a custom scheme link in a subframe, you probably want to add a target=_blank attribute on it. Otherwise, the web app you’ve configured as the protocol handler might load within that subframe and get blocked due to privacy settings or X-Frame-Options directives. 

-Eric

¹ The permitted schemes as of February 2023 are:

kProtocolSafelist[] = { 
  "bitcoin",
  "cabal",
  "dat",
  "did",
  "doi",
  "dweb",
  "ethereum",
  "geo",
  "hyper",
  "im",
  "ipfs",
  "ipns",
  "irc",
  "ircs",
  "magnet",
  "mailto", 
  "matrix", 
  "mms",  
  "news", 
  "nntp", 
  "openpgp4fpr",
  "sip",    
  "sms",   
  "smsto", 
  "ssb",
  "ssh", 
  "tel", 
  "urn",
  "webcal",
  "wtai", 
  "xmpp"
};