A partial archive of discourse.wicg.io as of Saturday February 24, 2024.

[Proposal] PWAs as URI Handlers


Hello WICG,

Developers can create a more engaging experience if Progressive Web Apps (PWAs) are able to register as handlers for http(s) uniform resource identifiers (URIs). We have a proposal that would enable PWAs to register as URI handlers and be launched when associated URIs are activated in native applications.


It is common for native applications to register themselves as URI Handlers: once registered with the user’s consent, such applications can be launched directly when the user clicks on links.

There is not currently a platform agnostic way for a PWA to register as a URI handler. Clicking on a link that points to content in an installed PWA opens that content in a default browser’s tab instead of launching the PWA in an application window. If the user installed the PWA, it is likely that they would like to experience an app-like experience instead.


We propose a platform agnostic scheme for PWAs to register as URI handlers, allowing PWA developers to opt in using the web app manifest, and URI content owners to opt in using a pwa-site-association file.

More details can be found in this explainer.

Thank you for your consideration.


Hi @mgiuca, would love to get your thoughts on this.


Clicking on a link that points to content in an installed PWA opens that content in a default browser’s tab instead of launching the PWA in an application window

Is this true? On Chrome, after installing a PWA, I’m prompted to choose between the PWA experience and my default browser when opening links that fall within the scope of the PWA. This is covered (as i understand it) by the deep links section of the Web App Manifest spec.


Thank you for pointing that out. On Chrome in Android, the prompt does show up when opening in-scope links. That is a behavior congruent with the deep links section of the Web App Manifest spec. It works because intent filters are registered for in-scope URI with Android during the WebAPK installation. I believe this mechanism is itself called “deep linking”.

This proposal aims to bring that same user experience to desktop platforms as well, without relying on the intent filter deep linking mechanism. This goal is also in line with the deep links section of the Web App Manifest spec.

Additionally, this proposal aims to give the PWA developer more control over which URIs are handled through an application experience and which are not. It is analogous to giving the developer more control over how intent filters are formed in their Android WebAPK. sw-launch has the same goal of giving the developer more control but does it by providing a programmatic API.

Additionally, this proposal introduces the concept of handling associated, out of scope URI. This is not specifically allowed or disallowed by the current Web App Manifest spec.


Not just chrome on android! Chrome on desktop has the same behavior as well when desktop PWAs are installed (it shows the native experience for in-scope links). I’m not 100% sure whether this behavior is mediated by the operating system or the browser—my guess is that it varies between operating systems. Given that, and the deep links section of the manifest, I think your Goals 1-6 are already handled by the spec, so you might want to rewrite the Introduction and Goals section to focus on use-cases that aren’t already enabled by the existing platform.

This is good context, thank you! I didn’t see anything about this goal or about sw-launch in the explainer, that would be very good context to add—you should probably add both a high-level problem statement that addresses this and concrete example use cases to the explainer. Additionally, it would be great to explain why you think your solution is better suited to address this problem then sw-launch, or at least how you see your two solutions interacting, so developers aren’t confused by having two solutions to solve the same problem.

Yeah, I saw that in the explainer, but I wasn’t sure if it was core to your spec since it wasn’t mentioned in your goals section or your problem statement. I think this behavior adds a lot of complexity to the proposed solution, and I’m not sure how it would interact with the other parts of the spec. While you’re right that the Web App Manifest spec doesn’t forbid it, a close reading does present some complications:

If an application context is created as a result of the user agent being asked to navigate to a deep link, the user agent MUST immediately navigate to the deep link with replacement enabled. Otherwise, when the application context is created, the user agent MUST immediately navigate to the start URL with replacement enabled.

This wouldn’t fall under the first if statement, since deep links are defined to be in-scope links, and it would be handled by the Otherwise, case. So when launching an out of scope link, the user agent would have to immediately navigate to the start URL, making it impossible for the web app author to tell which out-of-scope link was handled, or do any specific behavior based on the out of scope link.

This section could be amended, of course, but given that the use-cases you provided in the introduction and goals section, the whole thing (adding a well-known route, adding a file format, adding a whole life-cycle of site association renewal) seems like a lot of complication for very little benefit.


Which OS and version of Chome are you using to observe this behavior? So far I have been unable to repro on Windows 10(84) and OSX(79). I know that “link capturing”, the predecessor of sw-launch would have enabled that behavior. Could that have been what you observed?


Hello WICG chairs. This API now has interest from Google (see issue link below) and Microsoft. I would like to request to move the explainer to a WICG repo for incubation. Thank you for your kind attention.

cc. @marcosc, @cwilso, @yoavweiss, @travisleithead


It’s possible! I guess this must have been a very early version of Desktop PWA support on Chrome MacOS, sometime around 2018. I remember links from other sites navigating to the installed PWA by default, possibly with some sort of pop-up. From my perusal of the Chromium bug tracker it looks like this feature was removed, citing site compatibility issues, but I couldn’t find any documentation on what the site compatibility issues were. This was the main tracking bug, but a quick perusal of the linked issues didn’t turn up any broken web pages, just a list of broken Chromium behaviors—mostly a ton of different ways navigation contexts can get created. This document created after removing the flag in question has a list of those. It seems like the site issues mentioned didn’t make it into the sw-launch event explainer either… maybe @mgiuca or @g-ortuno remembers.

Maybe a simpler alternative would be a property that opted-in to this behavior?


Thanks for pointing us to that issue. IMO as co-chair, this meets the qualification to begin incubation. I’ve created a repo for you to start with at: https://github.com/WICG/pwa-url-handler

Thanks! -travis