Complexities w/ registerProtocolHandler seem confusing for developer & user. Simplification idea

[dmurph]

It seems like the duplication of functionality here is confusing for both developers & users:

1. How does ordering work?
2. Do icons apply to already registered protocol handling from tabs?
3. When do tabs win? When not? How does the user change this?

I propose to help solve this that this manifest addition serves to just 'enhance' the existing register protocol handler API. So the website still has to use the existing API, but this manifest addition does the following:

• robust way to attach icons to protocols (in cases of 'hub' apps that would handle multiple protocols, where the favicon doesn't serve well)
• This also allows a nice 'uninstall' behavior, where on uninstall all of the protocol handlers are automatically unregistered. Very nice for the user
• Keeps the user interaction for registered the handler (for some cases this might be nice)
• Allows protocol handler existence & information to be available to entities like web app stores.
• Possibility of pre-registering the handlers on install in trusted situations

Thoughts?

[dmurph]

In that proposal, there still are SOME edge cases here, but much less than if both APIs were active. Example: registration before the webapp is installed. I think we could resolve that by saying the registration is updates (like, the icon etc) by the webapp install (or by the 'new' existence of a manifest, if there wasn't one before), and then uninstalling the webapp would un-register the protocol handler.

Feel free to pick apart this strawman - the main feedback I have is with the complexity of the double APIs for the same thing, and it seems like the best way to reduce that is to keep the old API and have the manifest just enhance it.

[fabiorocha]

Hey Daniel, thanks for the issue!

It seems like the duplication of functionality here is confusing for both developers & users:

1. How does ordering work?

We can possibly iterate on the document a bit, but the current proposal is that the APIs are independent and don't interact with each other. registerProtocolHandler registers a website as a handler and protocol_handlers will be tied to an app and its lifecycle, i.e., the only way to register an app as handler is by installing it, and the only way to unregister is by uninstalling it. No dynamic registrations will be allowed for apps and calling registerProtocolHandler from an app context will have no effect on the app but on the website instead, much like any other JS APIs. So in practice, ordering should not be an issue.

/cc @connor-moody / @samtan-msft / @mgiuca - Does this align with our previous discussions?

2. Do icons apply to already registered protocol handling from tabs?

Protocols already registered from tabs will not be tied to the web app protocol_handlers as per the above. Also, we removed icons from our proposal recently due to the lack of a strong case for it. Making additive changes to APIs is better and if the need comes we can revisit (see #278 and whatwg/html#5425).

3. When do tabs win? When not? How does the user change this?

Per the above, we'll have different mechanisms for tabs, apps and potentially for extensions (see #280 and this) to register as protocol handlers. In case of conflicts, it is up to the implementer to decide what wins. In practice, disambiguation dialogs and settings pages are good places to let the user be in control and decide what should happen.

I propose to help solve this that this manifest addition serves to just 'enhance' the existing register protocol handler API. So the website still has to use the existing API, but this manifest addition does the following:

• robust way to attach icons to protocols (in cases of 'hub' apps that would handle multiple protocols, where the favicon doesn't serve well)
• This also allows a nice 'uninstall' behavior, where on uninstall all of the protocol handlers are automatically unregistered. Very nice for the user
• Keeps the user interaction for registered the handler (for some cases this might be nice)
• Allows protocol handler existence & information to be available to entities like web app stores.
• Possibility of pre-registering the handlers on install in trusted situations

All good suggestions, but given the above I think mostly inapplicable. What do you think?

[dmurph]

Thanks for giving me all of that context, I'm still coming up to speed.

Hey Daniel, thanks for the issue!

It seems like the duplication of functionality here is confusing for both developers & users:

1. How does ordering work?

We can possibly iterate on the document a bit, but the current proposal is that the APIs are independent and don't interact with each other. registerProtocolHandler registers a website as a handler and protocol_handlers will be tied to an app and its lifecycle, i.e., the only way to register an app as handler is by installing it, and the only way to unregister is by uninstalling it. No dynamic registrations will be allowed for apps and calling registerProtocolHandler from an app context will have no effect on the app but on the website instead, much like any other JS APIs. So in practice, ordering should not be an issue.

/cc @connor-moody / @samtan-msft / @mgiuca - Does this align with our previous discussions?

I see the following confusing cases in the current design:

Pre-PWA double-registration:

1. Website A registers itself as a protocol handler using registerProtocolHandler, pre-PWA days
2. Website A creates a PWA, and wants to retain the same functionality
3. Confusing/error prone: Website A has to have special logic about whether to call registerProtocolHandler or not, based on if it is a PWA.
4. Confusing: Users now see 2 entries for Website A when choosing protocol handler
5. Potentially confusing: handling protocol for website A still goes to a browser tab instead of a PWA

registerProtocolHander un-registration:
registerProtocolHander already has an un-registering problem as well (no way to request to do this as a website).

Two APIs, one functionality:
Having two ways to register a protocol handler seems confusing.

1. Do icons apply to already registered protocol handling from tabs?

Protocols already registered from tabs will not be tied to the web app protocol_handlers as per the above. Also, we removed icons from our proposal recently due to the lack of a strong case for it. Making additive changes to APIs is better and if the need comes we can revisit (see #278 and whatwg/html#5425).

1. When do tabs win? When not? How does the user change this?

Per the above, we'll have different mechanisms for tabs, apps and potentially for extensions (see #280 and this) to register as protocol handlers. In case of conflicts, it is up to the implementer to decide what wins. In practice, disambiguation dialogs and settings pages are good places to let the user be in control and decide what should happen.

I'm skeptical that this is an easy 'implementations will figure this out later' piece of the puzzle, and I'm also skeptical of the 'dialogs & settings' answer being a good one. User agents usually try very hard to not introduce any new dialogs or settings to the user, and if that can be avoided by simpler API design then it might be nice.

I propose to help solve this that this manifest addition serves to just 'enhance' the existing register protocol handler API. So the website still has to use the existing API, but this manifest addition does the following:

• robust way to attach icons to protocols (in cases of 'hub' apps that would handle multiple protocols, where the favicon doesn't serve well)
• This also allows a nice 'uninstall' behavior, where on uninstall all of the protocol handlers are automatically unregistered. Very nice for the user
• Keeps the user interaction for registered the handler (for some cases this might be nice)
• Allows protocol handler existence & information to be available to entities like web app stores.
• Possibility of pre-registering the handlers on install in trusted situations

All good suggestions, but given the above I think mostly inapplicable. What do you think?

I think it's inapplicable if you go with your current design, sure. That proposal solves some of the rough edges I see, although probably has some of it's own.

I would expect pushback around spec design that requires dialogs or settings for users to solve edge cases. It would be really nice for the spec to not need that. But perhaps the current proposal is the best solution :)

At the very least, I think the 'double registration' edge case should be highlighted as a rough edge for developers, user agents, and users, and some examples that could lead to confusion.

[dmurph]

Updating after a chat offline to clear up some confusion:

It sounds like the reason the current design was chosen over a design described above (where the manifest fields are used as 'additions' to the current API) is to continue to allow the existence of a 'website' url protocol handler along with a 'webapp' protocol handler, so that the webapp doesn't override the current experience.

Put another way, a user who has already added, say, 'yahoomail.com' as their mailto: protocol handler, and maybe Yahoo Mail created a PWA, the PWA would be a separate protocol handler. So the user could choose between either the PWA or the website version to handle this protocol, as they would register separately. Open With... Yahoo Mail (Website), Yahoo Mail (WebApp)

I still prefer not having two registration entry points here, and I'm fine with us doing the behavior of 'always overriding the previous browser-based registration when a PWA is installed'. This, however, would remove the use-case of still opening the protocol in a tab (if you installed the PWA). I see the main 3 benefits of this API being uninstall hooks, metadata additions, and declarative visibility of the handlers for something like a web app store to process, and I think we can keep all of those benefits w/o having a new registration API entry point by just having this compliment the existing API (so a developer would still call registerProtocolHandler, and the user agent would use the manifest attributes to further add metadata to that request, as well as allowing those protocols to 'deregister' on uninstallation). Avoiding having more settings and dialogs is ideal.

Another idea - we could easy word the spec to support both of these designs. We could say that the user agent 'MAY' register the protocol handler right away, but 'MAY' also wait for a call to registerProtocolHandler in the website to fully seal the deal. Maybe this is a best-of-both-worlds scenario.

I'm willing to be convinced otherwise though, especially if there are use cases here that I'm not thinking of :)

[dmurph]

@b1tr0t do you have any opinions here?

[fabiorocha]

Thanks, Daniel!

It sounds like the reason the current design was chosen over a design described above (where the manifest fields are used as 'additions' to the current API) is to continue to allow the existence of a 'website' url protocol handler along with a 'webapp' protocol handler, so that the webapp doesn't override the current experience.

Correct. Also, there's a need for certain classes of applications to have things like "file handlers" and "protocol handlers" tied to their lifecycle, meaning that they start handling files and protocols (or at least being an option to handle those things) as soon as they're installed, without further need for user gestures. registerProtocolHandler currently doesn't solve this.

Put another way, a user who has already added, say, 'yahoomail.com' as their mailto: protocol handler, and maybe Yahoo Mail created a PWA, the PWA would be a separate protocol handler. So the user could choose between either the PWA or the website version to handle this protocol, as they would register separately. Open With... Yahoo Mail (Website), Yahoo Mail (WebApp)

I still prefer not having two registration entry points here, and I'm fine with us doing the behavior of 'always overriding the previous browser-based registration when a PWA is installed'. This, however, would remove the use-case of still opening the protocol in a tab (if you installed the PWA). I see the main 3 benefits of this API being uninstall hooks, metadata additions, and declarative visibility of the handlers for something like a web app store to process, and I think we can keep all of those benefits w/o having a new registration API entry point by just having this compliment the existing API (so a developer would still call registerProtocolHandler, and the user agent would use the manifest attributes to further add metadata to that request, as well as allowing those protocols to 'deregister' on uninstallation).

I personally find the ergonomics of this more confusing, both to users and developers. Having an app take over the protocol by having it installed can create some confusion to users. As a developer, having a manifest entry that only works in conjunction with an HTML5 API call seems weird ergonomics (do we have something like this today so I can change my mind?).

Avoiding having more settings and dialogs is ideal.

I agree with this. Note however, that we wouldn't be introducing new dialogs and settings, we'd be merely adding more options to the existing dialogs/settings (where applicable). Users would still get a dialog if yahoomail.com registered for mailto: but say, the Yahoo! mail desktop app was installed -- the Yahoo! mail PWA, once installed, would then come as third option in that same dialog.

Another idea - we could easy word the spec to support both of these designs. We could say that the user agent 'MAY' register the protocol handler right away, but 'MAY' also wait for a call to registerProtocolHandler in the website to fully seal the deal. Maybe this is a best-of-both-worlds scenario.

This is interesting, but the least confusing way I see this working is by having an extra property on a protocol_handler entry on the manifest (below), but I guess then we'd be deviating from our intent to keep both APIs similar. Did you envision something different?

"protocol_handlers": [
    {
      "protocol": "web+jngl",
      "url": "/lookup?type=%s",
      "waitRegisterProtocolHandler": "true"
    },
    {
      "protocol": "web+jnglstore",
      "url": "/shop?for=%s"
    }
]

Overall, I don't disagree there might be some confusion here, but I think other approaches share similar problems. My hope is that by keeping the APIs similar and tying the manifest-based one to the application lifecycle, we can avoid confusion for developers -- instead of having the two interact with each other. To avoid confusion for users we'd have to experiment on the best UX but I don't think we're too far off here, as we're somewhat reusing what is already in place.

[connor-moody]

I agree that it feels more intuitive to keep declarative PWA protocol_handlers from interacting with the registerProtocolHandler API (after all, no one is confused by the “name” manifest property even though there is some conceptual overlap with a tab’s <title></title>).

I can’t think of any reasons why user agent settings UI couldn’t support site registrations side by side with app registrations. I’d prefer browser UI to handle these double registration edge cases and put forward a simple protocol_handlers API rather than cater towards edge cases in the manifest API. If we feel that the burden would be too great on user agents to resolve double registrations through UI, I'm also fine with an optional manifest field similar to what Fabio proposed.

[b1tr0t]

What if by default it takes you back to wherever you registered the handler.

I.e. return to the tab if you registered in tab, in the standalone PWA if you registered in standalone.

Apps are permitted to re-request the registration to change the destination. So for example, a PWA could re-request the handler once it's standalone. This leaves developers with the ability to either choose the best destination for their app on behalf of the user, or offer web UI to let the user choose.

[connor-moody]

@b1tr0t , if I am understanding correctly, you are suggesting that calling rph() on a site would register the site as a handler and calling rph() once a site has been installed as a PWA will register the PWA as a handler?

In this scenario, if a developer wants their PWA to be registered as a handler, they have to include UI or logic that knows whether or not the PWA has been installed. A developer would have to deal with the conditional behavior or rph() and deal with conditional manifest entries of protocol_handlers that only apply when rph() has been called. That doesn't seem like an intuitive API design to me, but maybe I am missing something here.

If we allow rph() to interact with PWA protocol_handlers, whatever resolution we come up with wouldn't even address the interaction between rph() / PWA protocol_handlers and extension protocol_handlers (discussed here). Coming up with logical interactions for 3 registration scenarios seems like a tall order. I still think keeping separate registration entry points from interacting seems like the most intuitive solution.