Getting started with Protocol Handlers for your web app

Beginning with Microsoft Edge 96, web apps can now use Protocol Handlers in Microsoft Edge. This is a powerful feature that allows your installed web application (or PWA) to handle pre-set or custom protocols. Installed web applications can now register with the operating system as protocol handlers and launch when a specific protocol is invoked. Let’s dive into the feature to understand how developers can take advantage of it.

Typical use cases

Probably the most common protocol that we interact with is the http protocol. When we click on a link that uses this protocol, the system knows to open the web browser and navigate to the address that is specified. Another typical protocol is mailto which allows users to click on email addresses and open the default e-mail client. There are other pre-defined protocols but we can see how this concept of “URL protocol” is useful, since it tells the system about an identifier and how to access the identifier. Protocol handlers allow your web application to participate as the app in these use cases.

Benefits

By having the ability to register as protocol handlers, your web app has better integration with the operating system, and can be set to open specific protocols. It can even be set as a default handler, so if for example, the web app you are building is an email client, you can give your users the option for it to be the default application for creating new e-mails.

Additionally, you can create custom schemes that your web app can handle by registering protocols that are prefixed with web+. This is useful if you require to handle a URL for which the set of safelisted schemes doesn’t fit the bill.

Protocol handlers could be used for web app communication where one app directly invokes another and passes data via custom protocol links.

How-to

To register your installed web application as a protocol handler, you must use the protocol_handlers field in the manifest file. If the protocol_handlers field is present in the manifest, then during installation the web app will be registered as a protocol handler for the protocols specified in the collection.

This field receives a collection of protocol and url pairs. The protocol specifies which scheme to register and the url tells the user agent which resource will process the URI.

Example

As an example we will look at the PWinter PWA. This is an installable web application that allows the user to create custom PWA logos by selecting 3 colors. The application defines the custom web+pwinter:// protocol handler in its manifest file.

"protocol_handlers": [
      {
        "protocol": "web+pwinter",
        "url": "index.html?colors=%s"
      }
    ]

With this in place and the web app installed on a desktop OS, you can now click on web+pwinter:// links on a website like web+pwinter://3D3D3D-5A0FC8-3D3D3D. This link represents the 3 colors that will be used by the installed web app for each letter. Note the value of the url key must also have a %s substring that will be replaced by the actual resource in the link.

When clicking the link, the browser asks for permission to open the application, and then prompts you to confirm that you want to handle the protocol and the app you’d like to use for it. If you give permission, then the selected application opens with the specified content.

Feature Support

Protocol Handlers are supported in Windows, Linux and Mac, and are shipping in Microsoft Edge 96.  We have contributed this work to the Chromium open-source project and the feature is now available in other Chromium based browsers too!

Related feature

This feature is similar to the JS method navigator.registerProtocolHandler(). It actually uses the same underlying steps, with the main difference being that registerProtocolHandler() is the JavaScript way of registering a website to handle protocols, while the protocol_handlers field in the manifest is the equivalent for installed web applications. On top of this, developers can specify multiple protocols without having to make repeated calls to the same method.

You can learn more about Protocol Handlers with our documentation and the manifest specification.

Protocol handling brings a powerful way to communicate between applications. Let us know how you are using or plan to use the feature, and any feedback you might have that can help us improve on the functionality. You can do so in the feedback tool in Microsoft Edge, or by pressing Alt+Shift+I.

– Diego Gonzalez, Program Manager, Microsoft Edge