Navigator: registerProtocolHandler() method

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

The Navigator method registerProtocolHandler() lets websites 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

js
registerProtocolHandler(scheme, url)

Parameters

scheme

A string containing the permitted scheme for the protocol that 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 use the https scheme. Older browsers also supported http.

Return value

None (undefined).

Exceptions

SecurityError DOMException

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 DOMException

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
  • ftp
  • ftps
  • geo
  • im
  • irc
  • ircs
  • magnet
  • mailto
  • matrix
  • mms
  • news
  • nntp
  • openpgp4fpr
  • sftp
  • sip
  • sms
  • smsto
  • ssh
  • tel
  • urn
  • webcal
  • wtai
  • xmpp

Examples

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

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

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
HTML Standard
# custom-handlers

Browser compatibility

Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
registerProtocolHandler
scheme parameter supports bitcoin
scheme parameter supports cabal
ExperimentalNon-standard
scheme parameter supports dat
ExperimentalNon-standard
scheme parameter supports did
ExperimentalNon-standard
scheme parameter supports dweb
ExperimentalNon-standard
scheme parameter supports etherium
ExperimentalNon-standard
scheme parameter supports ftp
Experimental
scheme parameter supports ftps
Experimental
scheme parameter supports geo
scheme parameter supports hyper
ExperimentalNon-standard
scheme parameter supports im
scheme parameter supports ipfs
ExperimentalNon-standard
scheme parameter supports ipns
ExperimentalNon-standard
scheme parameter supports irc
scheme parameter supports ircs
scheme parameter supports magnet
scheme parameter supports mailto
scheme parameter supports matrix
scheme parameter supports mms
scheme parameter supports news
scheme parameter supports nntp
scheme parameter supports openpgp4fpr
scheme parameter supports sftp
Experimental
scheme parameter supports sip
scheme parameter supports sms
scheme parameter supports smsto
scheme parameter supports ssb
ExperimentalNon-standard
scheme parameter supports ssh
scheme parameter supports tel
scheme parameter supports urn
scheme parameter supports webcal
scheme parameter supports wtai
scheme parameter supports xmpp
Secure context required

See also