Navigator.registerProtocolHandler()

Secure context
This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The Navigator method registerProtocolHandler() lets web sites register their ability to open or handle particular URL schemes (aka protocols).

For example, this API lets webmail sites open mailto: URLs, or VoIP sites open tel: URLs.

Syntax

navigator.registerProtocolHandler(scheme, url, title);
Note: Recently updated to navigator.registerProtocolHandler(scheme, url), but no browsers currently support this version.

Parameters

scheme
A string containing the protocol the site wishes to handle. For example, you can register to handle SMS text message links by passing the "sms" scheme.
url
A string containing the URL of the handler. This URL must include %s, as a placeholder that will be replaced with the escaped URL to be handled.
Note: The handler URL must us the https scheme. Older browsers also supported http.
title
A human-readable title string for the handler. This will be displayed to the user, such as prompting “Allow this site to handle [scheme] links?” or listing registered handlers in the browser’s settings.
Note: The title has been removed from the spec due to spoofing concerns, but all current browsers still require it. It is recommended to always set the title, since browsers that support the updated spec most likely will be backwards-compatible and still accept the title (but not use it).

Exceptions

SecurityError
The user agent blocked the registration. This might happen if:
  • The registered scheme (protocol) is invalid, such as a scheme the browser handles itself (https:, about:, etc.)
  • The handler URL’s origin does not match the origin of the page calling this API.
  • The browser requires that this function is called from a secure context.
  • The browser requires that the handler's URL be over HTTPS.
SyntaxError
The %s placeholder is missing from the handler URL.

Permitted schemes

For security reasons, registerProtocolHandler() restricts which schemes can be registered.

A custom scheme may be registered as long as:

  • The custom scheme's name begins with web+
  • The custom scheme's name includes at least 1 letter after the web+ prefix
  • The custom scheme has only lowercase ASCII letters in its name.

For example, web+burger, as shown in the Example below.

Otherwise, the scheme must be one of the following:

  • bitcoin
  • geo
  • im
  • irc
  • ircs
  • magnet
  • mailto
  • mms
  • news
  • nntp
  • openpgp4fpr
  • sip
  • sms
  • smsto
  • ssh
  • tel
  • urn
  • webcal
  • wtai
  • xmpp

Example

If your site is burgers.example.com, you can register a protocol handler for it to handle web+burger: links, like so:

navigator.registerProtocolHandler("web+burger",
                                  "https://burgers.example.com/?burger=%s",
                                  "Burger handler");

This creates a handler that lets web+burger: links send the user to your site, inserting the accessed burger URL into the %s placeholder.

This script must be run from the same origin as the handler URL (so any page at https://burgers.example.com), and the handler URL must be http or https.

The user will be notified that your code asked to register the protocol handler, so that they can decide whether or not to allow it. See the screenshot below for an example on google.co.uk:

A browser notification reads “Add Burger handler (www.google.co.uk) as an application for burger links?”, and offers an “Add Application” button and a close to ignore the handler request.

Specifications

Specification Status Comment
HTML Living Standard
The definition of 'registerProtocolHandler()' in that specification.
Living Standard Living standard

Browser compatibility

DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
registerProtocolHandlerChrome Full support 13
Notes
Full support 13
Notes
Notes Allowed schemes include mailto, mms, nntp, rtsp, and webcal. Custom protocols must be prefixed with web+.
Notes From Chrome 77, the URL parameter only accepts http or https URLs.
Edge Full support ≤79
Notes
Full support ≤79
Notes
Notes Allowed schemes include mailto, mms, nntp, rtsp, and webcal. Custom protocols must be prefixed with web+.
Firefox Full support 3IE ? Opera Full support 11.6Safari ? WebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android ? Safari iOS No support NoSamsung Internet Android Full support Yes
Secure context requiredChrome Full support 80Edge Full support ≤79Firefox Full support 62IE ? Opera ? Safari ? WebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android ? Safari iOS No support NoSamsung Internet Android No support No

Legend

Full support
Full support
No support
No support
Compatibility unknown
Compatibility unknown
See implementation notes.
See implementation notes.

See also