Intent to Prototype: URL Protocol Handler Registration for PWAs

428 views
Skip to first unread message

Fabio Rocha

unread,
Feb 26, 2020, 6:07:51 PM2/26/20
to blink-dev

Contact emails

fabio...@microsoft.com / connor...@microsoft.com / samue...@microsoft.com

 

Explainer

https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/URLProtocolHandler/explainer.md

 

Design doc/Spec

https://docs.google.com/document/d/1NHlWLjAPZ-dyxcz3AoTWibeerDeHW7Vqrx6FmhB0XmE

 

Summary

This feature will allow web developers to register web applications as URL protocol handlers via a property in the web app manifest. The apps would open directly when a custom-scheme URL is visited.

 


Implementation-wise, we intend to build this feature by reusing registerProtocolHandler internally and modifying the protocol handler registry and shell integration classes to account for the existence of PWAs. The idea is to avoid code duplication and maintain the APIs aligned. (see explainer and design doc for more details)

 

Motivation

Developers often register native applications as protocol handlers to increase discoverability and usage. While web developers can currently register websites as protocol handlers via registerProtocolHandler(), it is desirable to have web apps be first-class citizens and also be able to be launched directly when a custom-scheme link is invoked.

 

Risks

Interoperability and Compatibility

No interoperability or compatibility risks have been identified. Manifest elements will be ignored if unsupported by the client.

 

 

Ergonomics

This feature will work similar to registerProtocolHandler, so there will have to be some work on educating developers on the difference between the two (i.e.: one registers websites as handlers, the other registers web applications as handlers).

This feature will have no impact on the browser's ability to maintain good performance.

 

Security

Registering a protocol handler represents an important state change in the user's operating environment, and we must work to ensure that it is not abused. The registerProtocolHandler API implements an allow list of schemes that may be registered; we should start with that same restriction and evaluate whether it meets the needs, but possibly adding a few schemes to the list. URLs may contain sensitive user data; because PWAs require a secure context (HTTPS), invocation of a protocol handler will take place in a secure context. However, PWAs that implement protocol handlers must still take care to avoid sending potentially sensitive URL data over insecure channels.


Activation

Feature is intended to be disabled by default behind a feature flag.


 

Debuggability

There is no additional work needed by DevTools for this feature. Trace Events will be added to aid in debugging via about://tracing.

 

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

No. We will rely on the implementation of registerProtocolHandler for this feature, and that API is only supported, currently, in some Desktop platforms (Windows / Mac / Linux). Our initial plan is to support those same platforms.

 

Link to entry on the feature dashboard

https://chromestatus.com/features/5151703944921088

 

Requesting approval to ship?

No

 

Matt Giuca

unread,
Feb 27, 2020, 2:02:12 AM2/27/20
to Fabio Rocha, blink-dev
Hi Fabio,

I think this is a good direction (note: I am not an API owner so I can't vote on this). I've been saying for a long time that if we designed registerProtocolHandler today, it would be a declarative app manifest field, rather than a procedural API you call from a document.

I'll give some quick feedback here. I would like to see this moved to a WICG repo so issues can be filed.

> The registerProtocolHandler API implements an allow list of schemes that may be registered; we should start with that same restriction and evaluate whether it meets the needs, but possibly adding a few schemes to the list.

That allow list is currently very restrictive; it has a handful of schemes and "web+"-prefixed schemes. It doesn't include some of your examples like "ms-word://", and I would not want to start adding lots of random proprietary app schemes to the list (in my view it's already silly that it has such specific schemes as "bitcoin://"). I would prefer to push towards opening it up to any scheme, other than specifically blocked ones (which was discussed here, over two years ago: https://github.com/whatwg/html/issues/3998).

Other than that, I think it's unnecessary to draw a distinction between websites and PWAs here (your explainer says that registerProtocolHandler is for registering sites, while protocol_handlers is for registering apps). That's helpful for users to think about ("I've registered this app as a handler"), but from a technical perspective, I don't think there should be a distinction. What is registered is the URL as a handler. If the URL is within scope of an installed PWA that is set to open in a window, then it should open in a PWA window (or go through the launch event, if we end up shipping that). If not, it should open a browser tab. Basically, opening a protocol handler should be the same thing as opening a target=_blank link to that URL. That way, we separate the layers: protocol_handlers is just an alternative mechanism to register a URL as a protocol handler, while the app layer deals with launching app windows. The only difference should be that your declarative protocol_handlers ties the lifetime to the installation of the app: it gets registered when the app is installed, and unregistered when the app is uninstalled.

Matt

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/31f282fc-8282-4518-b633-40c3c7dfdefa%40chromium.org.

Fabio Rocha

unread,
Feb 27, 2020, 5:04:17 PM2/27/20
to blink-dev
It turns out that great Word formatting doesn't translate into great Google Groups formatting. 
I'm re-sending the proposal below with the formatting from the google docs template to make things easier to read. Apologies for the duplication.

-

No.


Matt Giuca

unread,
Feb 27, 2020, 6:32:43 PM2/27/20
to Fabio Rocha, blink-dev
The formatting of the above email was perfectly fine. It would be best not to duplicate it to keep the conversation in one thread.

FYI just a clarification, when I said "(note: I am not an API owner so I can't vote on this)." --- you actually don't need any votes to proceed from here, so just ignore that bit :).

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.

Fabio Rocha

unread,
Mar 2, 2020, 7:55:23 PM3/2/20
to blink-dev, fabio...@microsoft.com, connor...@microsoft.com, samue...@microsoft.com

I'll give some quick feedback here. I would like to see this moved to a WICG repo so issues can be filed.

Thanks Matt, I created this discussion on WICG's discourse, for the explainer to be discussed by other members of the community. If you/Google are supportive, please say something in there so that it can be moved there.

That allow list is currently very restrictive; it has a handful of schemes and "web+"-prefixed schemes. It doesn't include some of your examples like "ms-word://", and I would not want to start adding lots of random proprietary app schemes to the list (in my view it's already silly that it has such specific schemes as "bitcoin://"). I would prefer to push towards opening it up to any scheme, other than specifically blocked ones (which was discussed here, over two years ago: https://github.com/whatwg/html/issues/3998).

I agree here (and I'm aware ms-word:// is not part of the current safelist). I will push for that conversation to move forward but it's somewhat orthogonal to the bulk of this work, so I'll vouch for us to keep that as a separate issue.

  That's helpful for users to think about ("I've registered this app as a handler"), but from a technical perspective, I don't think there should be a distinction. What is registered is the URL as a handler. If the URL is within scope of an installed PWA that is set to open in a window, then it should open in a PWA window (or go through the launch event, if we end up shipping that). If not, it should open a browser tab. 
 That way, we separate the layers: protocol_handlers is just an alternative mechanism to register a URL as a protocol handler, while the app layer deals with launching app windows. The only difference should be that your declarative protocol_handlers ties the lifetime to the installation of the app: it gets registered when the app is installed, and unregistered when the app is uninstalled.

Just to make sure we are on the same page here: (a) by users above you mean developers and (b) by scope you mean the scope member of a web app, correct?

Assuming we're on the same page. I don't think what you suggest would be sufficient. It would be a bit cleaner from a technical perspective, I agree, but I don't think it would yield the right experience for the end user. I suppose we need to let the underlying operating system know somehow about the existence of the PWA that's handling a scheme, otherwise disambiguation dialogs, for instance, would always show the user agent as the handler, and then the UA would decide if it should handle the protocol via an app or a tab? I think deciding at the app layer is a bit too late, unless I'm misunderstanding your proposal here. I think that's the fundamental difference between websites as handlers (yes, the browser is the actual handler and decides which site to open) and apps (that need to be registered to the OSes as such, for the best UX). Am I missing something?

Fabio 


On Wednesday, February 26, 2020 at 11:02:12 PM UTC-8, Matt Giuca wrote:
Hi Fabio,

I think this is a good direction (note: I am not an API owner so I can't vote on this). I've been saying for a long time that if we designed registerProtocolHandler today, it would be a declarative app manifest field, rather than a procedural API you call from a document.

I'll give some quick feedback here. I would like to see this moved to a WICG repo so issues can be filed.

> The registerProtocolHandler API implements an allow list of schemes that may be registered; we should start with that same restriction and evaluate whether it meets the needs, but possibly adding a few schemes to the list.

That allow list is currently very restrictive; it has a handful of schemes and "web+"-prefixed schemes. It doesn't include some of your examples like "ms-word://", and I would not want to start adding lots of random proprietary app schemes to the list (in my view it's already silly that it has such specific schemes as "bitcoin://"). I would prefer to push towards opening it up to any scheme, other than specifically blocked ones (which was discussed here, over two years ago: https://github.com/whatwg/html/issues/3998).

Other than that, I think it's unnecessary to draw a distinction between websites and PWAs here (your explainer says that registerProtocolHandler is for registering sites, while protocol_handlers is for registering apps). That's helpful for users to think about ("I've registered this app as a handler"), but from a technical perspective, I don't think there should be a distinction. What is registered is the URL as a handler. If the URL is within scope of an installed PWA that is set to open in a window, then it should open in a PWA window (or go through the launch event, if we end up shipping that). If not, it should open a browser tab. Basically, opening a protocol handler should be the same thing as opening a target=_blank link to that URL. That way, we separate the layers: protocol_handlers is just an alternative mechanism to register a URL as a protocol handler, while the app layer deals with launching app windows. The only difference should be that your declarative protocol_handlers ties the lifetime to the installation of the app: it gets registered when the app is installed, and unregistered when the app is uninstalled.

Matt

On Thu, 27 Feb 2020 at 10:07, 'Fabio Rocha' via blink-dev <blin...@chromium.org> wrote:
To unsubscribe from this group and stop receiving emails from it, send an email to blin...@chromium.org.

Yoav Weiss

unread,
Mar 6, 2020, 2:28:01 AM3/6/20
to Fabio Rocha, blink-dev, connor...@microsoft.com, samue...@microsoft.com
As a couple of process drive-by comments:
* Would be good to file for a TAG review early, to give them enough time to review and avoid it becoming an issue later on.
* Seems like there's enough multi-company support to adopt this as a WICG repo for further incubation. Feel free to ping me off list on that front.

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/b4aedc53-7348-4f8e-aeba-84e7aa23d1eb%40chromium.org.

Fabio Rocha

unread,
Mar 6, 2020, 1:26:20 PM3/6/20
to blink-dev, fabio...@microsoft.com, connor...@microsoft.com, samue...@microsoft.com
* Would be good to file for a TAG review early, to give them enough time to review and avoid it becoming an issue later on.

Thanks Yoav. We've filed for a TAG review yesterday and posted to this thread. Our microsoft.com posts are moderated... so you should see a message from my colleague about that any time now...

 * Seems like there's enough multi-company support to adopt this as a WICG repo for further incubation. Feel free to ping me off list on that front.

Thank you for the support! We'll follow-up shortly. 

Samuel Tang

unread,
Mar 8, 2020, 5:15:17 PM3/8/20
to blink-dev, fabio...@microsoft.com, connor...@microsoft.com, samue...@microsoft.com
Here's the link to the w3c tag review: https://github.com/w3ctag/design-reviews/issues/482

nightpool

unread,
Mar 8, 2020, 5:16:45 PM3/8/20
to blink-dev, fabio...@microsoft.com, connor...@microsoft.com, samue...@microsoft.com

On Monday, March 2, 2020 at 7:55:23 PM UTC-5, Fabio Rocha wrote:
I think that's the fundamental difference between websites as handlers (yes, the browser is the actual handler and decides which site to open) and apps (that need to be registered to the OSes as such, for the best UX). Am I missing something?

I responded to this with some more context on the WICG thread (https://discourse.wicg.io/t/proposal-url-protocol-handler-registration-for-pwas/4276) but from a web developer perspective, I strongly disagree with this. When a user clicks on a mailto link, they want to open it in "Gmail" or "Outlook", and it makes no difference to them whether these are websites, progressive web apps, or native apps. For navigation, users are best served by one dialog that specifically mentions the app. 

Now, one tricky part of this proposal and a complicating factor to what I just said above is that registerProtocolHandler supports more use-cases then just navigation—it also supports redirecting `fetch` and `iframe`. Here's a demo of a really unique UX that can be achieved by using registerProtocolHandler and iframes: https://github.com/sandhawke/in-page-social-demo, allowing for a seamless implementation of "follow" and "like" buttons on federated social websites. However, it's not clear to me how to handle multiple websites that both want to handle protocol requests of this type. I also don't know whether system platforms support custom protocol interactions more complicated then "navigate to", but I haven't heard of any. If they don't, then it seems like we would still need to build some sort of chooser into the app layer anyway, or allow this to be a weird gotcha mismatch between the two APIs.

Fabio Rocha

unread,
Mar 9, 2020, 8:25:21 PM3/9/20
to blink-dev, fabio...@microsoft.com, connor...@microsoft.com, samue...@microsoft.com

Thank you for the comments, nightpool.

I phrased it poorly, but I believe we are on the same page regarding the app-centric UX that PWA protocol handler registration should provide. A "mailto" link should allow the user to choose between Outlook and Gmail, not between Outlook and Edge (assuming the Gmail PWA is associated with an Edge profile). The idea behind this proposal is that PWAs, as first-class citizens, can interact with other apps at the OS level. It is important to note that these other apps may be web apps or native apps. This will only be possible if the OS is aware of PWA specific information at install time.

We’ve responded to your feedback on the WICG thread and asked Yoav for a repo there for us to track all this input as issues and discuss them individually (e.g.: other use cases of registerProtocolHandler, which might fall out of the scope of our proposal but it would be good to take into consideration).

Frédéric Wang

unread,
May 16, 2020, 6:43:48 AM5/16/20
to blin...@chromium.org
Hi,

Thanks for this proposal and for working on this!

I already provided feedback to you on various places, but just repeating
it here for the record. As previously said, this is just an intent to
prototype and you don't need any vote, but I think it's good to raise
concerns as early as possible. Basically, this is very similar to the
existing web platform API registerProtocolHandler() and I believe it
would be good to share as much logic/code as possible on this and ensure
consistency between various implementations. In particular:

(1) An alternative to extend the capacity of registerProtocolHandler()
instead of introducing new manifest keys is discarded in your explainer
[1]. However, it's still not clear to me whether there is a consensus in
Chromium about which approach is best (see also [2] for a similar
discussion regarding extension). I personally don't have strong opinion
on what the answer to the previous question is but I have the feeling
that the manifest approach needs special handling to work with the
runtime permission model (reported in [3]), is not flexible enough to
allow potential future "programmable" extension (e.g. [4] proposed by
the dweb community) and leads to more code to write and maintain (at
least manifest parsing).

(2) AFAIK WebKit is not interested in implementing custom handler but
Mozilla implements registerProtocolHandler() and WebExtensions's
protocol_handlers's API and have general bugs opened regarding PWA [5]
[6] [7]. You indicated "No public signals" for Firefox but I think it
would be good to get their opinion on this feature if possible, perhaps
by opening an issue at [8]. In particular I believe they could have the
same considerations regarding reusing/extending
registerProtocolHandler(). Or regarding your proposal for "Different
apps registering the same protocol" [9] that they already implement in
the case of registerProtocolHandler(). Have you obtained feedback from
Mozilla since you posted the initial intent email?

(3) We probably want to allow the same schemes as
registerProtocolHandler(). The "switch to blocklist" approach issue
mentioned by Matt [10] has been stuck for a while and I'm not very
optimistic that a consensus is going to happen anytime soon. So
extending the safelist seems a good short term approach and recent
discussions in WHATWG suggests that extending the safelist would need at
least some documentation at [11]. That's what have done so for other
community proposals and I'm happy to help here too if necessary.

[1]
https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/URLProtocolHandler/explainer.md#have-protocol_handlers-extend-registerprotocolhandler-with-additional-data
[2] https://bugs.chromium.org/p/chromium/issues/detail?id=64100#c23
[3]
https://github.com/MicrosoftEdge/MSEdgeExplainers/issues/230#issuecomment-623749833
[4] https://arewedistributedyet.com/programmable-custom-protocol-handlers
[5]
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/protocol_handlers
[6] https://bugzilla.mozilla.org/show_bug.cgi?id=1407202
[7] https://bugzilla.mozilla.org/show_bug.cgi?id=1212648
[8] https://github.com/mozilla/standards-positions
[9]
https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/URLProtocolHandler/explainer.md#different-apps-registering-the-same-protocol
[10] https://github.com/whatwg/html/issues/3998
[11] https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml

Fabio Rocha

unread,
May 18, 2020, 6:14:47 PM5/18/20
to blink-dev

Thanks for the write-up, Frédéric. Just a couple of comments.

 

Basically, this is very similar to the existing web platform API registerProtocolHandler() and I believe it would be good to share as much logic/code as possible on this and ensure consistency between various implementations

 

Internally the plan is to reuse a lot of the implementation of registerProtocolHandler(), which is why we align on parameters, safelist, etc. Externally, however, we think it's important to provide good ergonomics to end-users and PWA developers, and in that sense we think it's best to align with other declarative properties being proposed to the manifest [12][13]. It's a trade off we're willing to experiment with.

 

(1) An alternative to extend the capacity of registerProtocolHandler() instead of introducing new manifest keys is discarded in your explainer [1]. However, it's still not clear to me whether there is a consensus in Chromium about which approach is best (see also [2] for a similar discussion regarding extension). I personally don't have strong opinion on what the answer to the previous question is but I have the feeling that the manifest approach needs special handling to work with the runtime permission model (reported in [3]), is not flexible enough to allow potential future "programmable" extension (e.g. [4] proposed by the dweb community) and leads to more code to write and maintain (at least manifest parsing).

 

There isn't consensus yet, but reiterating on the ergonomics point above, we always thought registerProtocolHandler() lacked some of it. End-users don't quite understand the concept of protocols/schemes, so the need for user gesture and the current prompts don't quite make a good experience, which is probably one of the reasons why the API isn't highly used. For PWAs, we think there could be an improvement here by having that as part of the manifest and handling that more gracefully by installing the protocols when installing the PWA (transparently to end-users). Sure, that gives us a couple of other problems [3] to worry about but those can be worked out with the same solution being proposed for file handlers [14][15] -- getting permission at runtime in a more intuitive way. The plan is to follow the guidelines outlined here in the "Controlling Access to Powerful Web Platform Features" document by Dominick [16].

 

(2) AFAIK WebKit is not interested in implementing custom handler but Mozilla implements registerProtocolHandler() and WebExtensions's protocol_handlers's API and have general bugs opened regarding PWA [5] [6] [7]. You indicated "No public signals" for Firefox but I think it would be good to get their opinion on this feature if possible, perhaps by opening an issue at [8]. In particular I believe they could have the same considerations regarding reusing/extending registerProtocolHandler(). Or regarding your proposal for "Different apps registering the same protocol" [9] that they already implement in the case of registerProtocolHandler(). Have you obtained feedback from Mozilla since you posted the initial intent email?

 

I indicated "No public signals" because I didn't hear from them in the many forums where this was publicized, but to be honest I didn't know about [8]. Thanks for that pointer -- I'll make sure I open an issue there shortly.


(3) We probably want to allow the same schemes as registerProtocolHandler(). The "switch to blocklist" approach issue mentioned by Matt [10] has been stuck for a while and I'm not very optimistic that a consensus is going to happen anytime soon. So extending the safelist seems a good short term approach and recent discussions in WHATWG suggests that extending the safelist would need at least some documentation at [11]. That's what have done so for other community proposals and I'm happy to help here too if necessary.

 

100% agreement here. We're aligning with registerProtocolHandler(), and that includes reusing the same safelisted schemes as noted in our explainer, the PR against the spec [17], etc. That said, we will propose that the safelist is extended at some point in the near future, for the same reasons you've mentioned above. Thanks for pushing that conversation forward, I'll definitely reach out when the time comes. 


--

[12] https://github.com/WICG/file-handling/blob/master/explainer.md

[13] https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/PwaUriHandler/explainer.md

[14] https://github.com/WICG/file-handling/blob/master/explainer.md#security-and-privacy-considerations

Reply all
Reply to author
Forward
0 new messages