├── CONTRIBUTING.md ├── LICENSE.md ├── PRIVACY_AND_SECURITY.md ├── README.md ├── explainer.md ├── handle_links ├── Security and Privacy Self-Review Questionnaire.md └── explainer.md └── w3c.json /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Web Platform Incubator Community Group 2 | 3 | This repository is being used for work in the W3C Web Platform Incubator Community Group, governed by the [W3C Community License 4 | Agreement (CLA)](http://www.w3.org/community/about/agreements/cla/). To make substantive contributions, 5 | you must join the CG. 6 | 7 | If you are not the sole contributor to a contribution (pull request), please identify all 8 | contributors in the pull request comment. 9 | 10 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows: 11 | 12 | ``` 13 | +@github_username 14 | ``` 15 | 16 | If you added a contributor by mistake, you can remove them in a comment with: 17 | 18 | ``` 19 | -@github_username 20 | ``` 21 | 22 | If you are making a pull request on behalf of someone else but you had no part in designing the 23 | feature, you can remove yourself with the above syntax. 24 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All Reports in this Repository are licensed by Contributors 2 | under the 3 | [W3C Software and Document License](http://www.w3.org/Consortium/Legal/2015/copyright-software-and-document). 4 | 5 | Contributions to Specifications are made under the 6 | [W3C CLA](https://www.w3.org/community/about/agreements/cla/). 7 | 8 | Contributions to Test Suites are made under the 9 | [W3C 3-clause BSD License](https://www.w3.org/Consortium/Legal/2008/03-bsd-license.html) 10 | 11 | -------------------------------------------------------------------------------- /PRIVACY_AND_SECURITY.md: -------------------------------------------------------------------------------- 1 | # Answers to [Security and Privacy Questionnaire](https://www.w3.org/TR/security-privacy-questionnaire/) 2 | 3 | This has been created by copy-and-pasting from https://w3ctag.github.io/security-questionnaire/, as requested in the TAG review instructions. 4 | 5 | 1. What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary? 6 | 7 | No information is exposed to Web sites or other parties as part of this feature. 8 | 9 | 2. Is this specification exposing the minimum amount of information necessary to power the feature? 10 | 11 | Yes. 12 | 13 | 3. How does this specification deal with personal information or personally-identifiable information or information derived thereof? 14 | 15 | No personal information is collected, used, or exposed via this feature. 16 | 17 | 4. How does this specification deal with sensitive information? 18 | 19 | No sensitive information is collected, used, or exposed via this feature. 20 | 21 | 5. Does this specification introduce new state for an origin that persists across browsing sessions? 22 | 23 | No. 24 | 25 | 6. What information from the underlying platform, e.g. configuration data, is exposed by this specification to an origin? 26 | 27 | None. 28 | 29 | 7. Does this specification allow an origin access to sensors on a user’s device? 30 | 31 | No. 32 | 33 | 8. What data does this specification expose to an origin? Please also document what data is identical to data exposed by other features, in the same or different contexts. 34 | 35 | None. 36 | 37 | 9. Does this specification enable new script execution/loading mechanisms? 38 | 39 | No. 40 | 41 | 10. Does this specification allow an origin to access other devices? 42 | 43 | No. 44 | 45 | 11. Does this specification allow an origin some measure of control over a user agent’s native UI? 46 | 47 | Yes. It allows an origin to request app content from an installed web app from that origin be displayed in an app window. The user still has complete control over the choice of UI. The change of UI has no effect on security or privacy controls. Analysis: app-like UI for web apps is an existing, validated feature in many user agents. 48 | 49 | 12. What temporary identifiers might this specification create or expose to the web? 50 | 51 | No identifiers are created or exposed to the web. 52 | 53 | 13. How does this specification distinguish between behavior in first-party and third-party contexts? 54 | 55 | This feature cannot be used by third-party resources. The only access is through the first-party controlled web app manifest. 56 | 57 | 14. How does this specification work in the context of a user agent’s Private Browsing or "incognito" mode? 58 | 59 | This feature has no effect in Private Browsing or "incognito" modes because PWA features cannot be used in those modes. 60 | 61 | 15. Does this specification have a "Security Considerations" and "Privacy Considerations" section? 62 | 63 | Yes. See these links: 64 | * https://github.com/WICG/pwa-url-handler/blob/master/explainer.md#security-considerations 65 | * https://github.com/WICG/pwa-url-handler/blob/master/explainer.md#privacy-considerations 66 | 67 | 16. Does this specification allow downgrading default security characteristics? 68 | 69 | No. 70 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | # Progressive Web Apps as URL Handlers 3 | 4 | Author: Lu Huang <>
5 | 6 | Date: 2020-05-28 7 | 8 | This site contains proposal for a new capability that would allow web applications to register as URL handlers. Web applications that are URL handlers can be launched to handle URL link activations. We welcome contributions to this proposal. 9 | 10 | [Explainer](explainer.md) 11 | 12 | [Privacy and security self-review](PRIVACY_AND_SECURITY.md) 13 | -------------------------------------------------------------------------------- /explainer.md: -------------------------------------------------------------------------------- 1 | # PWAs as URL Handlers 2 | 3 | Authors: [Lu Huang](https://github.com/LuHuangMSFT) <luhua@microsoft.com> 4 | 5 | Input from: [Mike Jackson](mailto:mjackson@microsoft.com), [Mandy Chen](mailto:mandy.chen@microsoft.com), [Howard Wolosky](mailto:howard.wolosky@microsoft.com), [Matt Giuca](mailto:mgiuca@google.com) 6 | 7 | ## Obsolete 8 | 9 | This API proposal is obsolete in favor of [`scope_extensions`](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md) and link capturing. 10 | Context: https://docs.google.com/document/d/1w9qHqVJmZfO07kbiRMd9lDQMW15DeK5o-p-rZyL7twk 11 | 12 | ## Status of this Document 13 | 14 | This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. 15 | 16 | * This document status: **Active** 17 | * Expected venue: [W3C Web Applications Working Group](https://www.w3.org/2019/webapps/) 18 | * Current version: this document 19 | 20 | ## Introduction 21 | 22 | Developers can create a more engaging experience if Progressive Web Apps (PWAs) are able to register as handlers for https uniform resource identifiers (URLs). This document proposes a scheme for a PWA to register as a URL handler and be launched when associated URLs are activated. PWA developers and end users are the customers of this solution. 23 | 24 | Today, native applications on many operating systems (Windows, Android, iOS, MacOS) can be associated with http(s) URLs. They can request to be launched as URL handlers when associated URLs are activated. For example, a user could click on a link to a news story from an e-mail. An associated native app for viewing news stories would automatically be launched to handle the activation of the link. Web developers would be able to build more compelling PWA experiences with stronger user engagement if PWAs could request to be URL handlers through their web app manifests. 25 | 26 | PWAs may have different levels of URL handling ability depending on the capabilities of the host OS. Whenever URL activations launch a conforming browser, that browser should have the ability to launch a registered PWA to render the requested content. In the best case, it would be possible for URL activations anywhere in the user's system to launch PWAs because they are registered as URL handlers with the OS. We are proposing changes below that could help accomplish this. 27 | 28 | ## Goals 29 | 30 | 1. Enable PWA developers to opt-in to URL handling features using the web app manifest. 31 | 2. Enable the default browser to support URL activation by launching a PWA. 32 | 3. Where possible, enable registration of PWAs as URL handlers with the operating system. 33 | 4. Provide a better user experience by allowing users to explicitly choose an installed PWA in app pickers and disambiguation dialogs. 34 | 5. Protect content owners by only allowing associated PWAs to act as URL handlers for their content. 35 | 6. Keep the user in control of choosing the best experience for them, whether that is in the browser, in a native app, or in a PWA. 36 | 37 | ## Non-Goals 38 | 39 | * Custom URL protocol registration and handling. A separate explainer for that can be found [here](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/URLProtocolHandler/explainer.md). 40 | 41 | * Launching PWAs due to in-browser link navigation. Capturing from navigation needs to address additional concerns around security and privacy. It is excluded here to reduce complexity. This explainer focuses on scenarios where the URL activation comes from outside the browser. Nothing written here should prevent URL handling from working on navigations in the future. 42 | 43 | ## Use Case 44 | 45 | There is one use case that we wish to address in this explainer: URL activation in native applications. 46 | 47 | The user clicks on a Spotify link in their native e-mail application, (eg., [https://open.spotify.com/album/7FA9xfqPrBaja1sEv15DU2](https://open.spotify.com/album/7FA9xfqPrBaja1sEv15DU2) in the Outlook app), which launches their default browser through the OS. Because the user already has the Spotify PWA installed and registered as a URL handler with their default browser, the URL activation launches the PWA instead of a new tab. 48 | 49 | ## Proposed Solution 50 | 51 | 1. Modify the web app manifest specification to include an `url_handlers` member. 52 | * Allows PWAs to handle URLs from multiple different origins. 53 | * Allows PWA developers to opt-in to URL handling in the same way across different platforms. 54 | 55 | 2. Specifying a `web-app-origin-association` file format for validating out-of-scope URL associations. 56 | * Provides a web standard option for association with web apps. 57 | * Protects content owners by letting them define which PWAs are allowed to associate with their sites. 58 | * Gives content owners control over which URLs are allowed to be handled by each associated PWA. 59 | 60 | 3. If a browser is launched to handle a URL activation, it should look for matching, installed PWAs to handle that URL. 61 | 62 | 4. If multiple PWAs match a given URL, browsers should display a disambiguation dialog to allow users to choose one or continue in a browser window. 63 | 64 | 5. On OSes with adequate support, conforming browsers should register PWAs as URL handlers at the OS level instead. 65 | * Allows any native app, including browsers, to launch participating PWAs using OS URL launch. 66 | 67 | **Changes 1-4** allow PWAs to handle URL activations at the browser level without needing to integrate with the OS. As long as a URL activation (clicking on a link) launches a conforming browser, the browser has the ability to launch the matching PWA. A PWA will not be launched through URL activations from the OS if it is not known to the default browser. 68 | 69 | To allow PWAs to handle URLs that are outside of their own scope, it is necessary to introduce a mechanism for the owner of those URLs to opt-in to URL handling by PWAs. **Change 2** introduces the concept of a `web-app-origin-association` file that will serve this purpose. This file is similar to the [Apple App Site Association File](https://developer.apple.com/documentation/safariservices/supporting_associated_domains_in_your_app#3001215), the [`assetlinks.json`](https://developer.android.com/training/app-links/verify-site-associations) file in Android, and the [`windows-app-web-link`](https://docs.microsoft.com/en-us/windows/uwp/launch-resume/web-to-app-linking#associate-your-app-and-website-with-a-json-file) file in Windows. What differs is that the `web-app-origin-association` file does not reference PWAs using a platform-specific app id but by their web app manifest URL. 70 | 71 | **Change 5** will also allow PWAs to handle URL activations at the OS level on supporting platforms. If the PWA is able to register as a URL handler with the OS, it could be launched whenever a URL activation is handled by the OS, regardless of the default browser setting. Most native applications rely on the OS for URL activation. In terms of user experience, the OS could now prompt the user to choose between the PWA and the default browser using the system app disambiguation dialog. The user is able to make an explicit choice to select the PWA and configure their default setting from there. (Implementation note: because most OSes do not know of or treat PWAs as first-class applications, it may not be possible to register them directly with the OS as URL handlers. Supporting changes will need to be made in PWA implementation and/or in the OS to enable this. A notable exception is Chrome's implementation of PWAs on Android using `WebAPK` . Because `WebAPK` s are recognized by the Android OS, Chrome PWAs are able to fully integrate with OS features like the app picker.) 72 | 73 | ### Manifest Changes 74 | 75 | | Field | Required / Optional | Description | Type | Default | 76 | | :---------- | :------------------ | :-------------------------------------------- | :------- | :------ | 77 | | `url_handlers` | Optional | Origins of URLs that the app wishes to handle | object[] | `[]` | 78 | 79 | We propose adding a new _optional_ member `url_handlers` to the manifest object of `object[]` type. Each object in `url_handlers` contains a `origin` string, which is a pattern for matching origins. These patterns are allowed to have a wildcard (*) prefix in order to include multiple sub-domains. URLs that match these origins could be handled by this web app. 80 | 81 | Each `url_handlers` object is a request from the PWA to handle URLs from a specific origin or origins. The browser should validate with each origin that the app is recognized and if so retrieve the patterns for allowed URLs. On an OS that allows for deeper integration, the browser should also register URL handling requests with the OS and keep them in sync with the app. 82 | 83 | Example web app manifest at `https://contoso.com/manifest.json` : 84 | 85 | ``` json 86 | { 87 | "name": "Contoso Business App", 88 | "display": "standalone", 89 | "icons": [ 90 | { 91 | "src": "images/icons-144.png", 92 | "type": "image/png", 93 | "sizes": "144x144" 94 | } 95 | ], 96 | "capture_links": "existing_client_event", 97 | "url_handlers" : [ 98 | { 99 | "origin": "https://contoso.com" 100 | }, 101 | { 102 | "origin": "https://conto.so" 103 | }, 104 | { 105 | "origin": "https://*.contoso.com" 106 | } 107 | ] 108 | } 109 | ``` 110 | 111 | Example web app manifest at `https://partnerapp.com/manifest.json` 112 | 113 | ``` json 114 | { 115 | "name": "Contoso Business App", 116 | "display": "standalone", 117 | "icons": [ 118 | { 119 | "src": "images/icons-144.png", 120 | "type": "image/png", 121 | "sizes": "144x144" 122 | } 123 | ], 124 | "capture_links": "existing_client_event", 125 | "url_handlers": [ 126 | { 127 | "origin": "https://contoso.com" 128 | }, 129 | { 130 | "origin": "https://conto.so" 131 | }, 132 | { 133 | "origin": "https://*.contoso.com" 134 | } 135 | ] 136 | } 137 | ``` 138 | 139 | (`capture_links` from the [Declarative Link Capturing](https://github.com/WICG/sw-launch/blob/master/declarative_link_capturing.md) proposal added to examples for comparison.) 140 | 141 | A PWA matches a URL for URL handling if the URL matches one of the origin strings in `url_handlers` and the browser is able to validate that the origin agrees to let this app handle such a URL. 142 | 143 | `url_handlers` can contain an origin that encompasses requesting PWA's scope and also other unrelated origins. Not restricting URLs to the same scope or domain as the requesting PWA allows the developer to use different domain names for the same content but handle them with the same PWA. See [this section](#web-app-to-origin-association) for how `url_handlers` requests can be validated with origins. Navigation redirection is not a good alternative with respect to offline scenarios. 144 | 145 | #### Wildcard Matching 146 | 147 | The wildcard character `*` can be used to match one or more characters. 148 | 149 | A wildcard prefix can be used in `url_handlers` origin strings to match for different subdomains. The prefix must be `*.` for this usage. The scheme is still assumed to be https when using a wildcard prefix. 150 | 151 | For eg. `*.contoso.com` matches `tenant.contoso.com` and `www.tenant.contoso.com` but not `contoso.com` . There may be other ways of specifying a group of related origins such as [First Party Sets](https://github.com/krgovind/first-party-sets). This feature would not be necessary if there was a way to specify a multi-origin app scope with a similar matching pattern. 152 | 153 | ### web app to origin association 154 | 155 | Browsers must validate a handshake between a PWA and an origin to successfully register URL handlers. Origins can declare associations with specific web apps to complete this handshake. Web apps can be identified by their manifest URL currently before a [unique identifier](https://github.com/w3c/manifest/issues/586) is standardized. An origin should be allowed to specify URL patterns to fine-tune URL paths for URL handling. 156 | 157 | We propose a platform-independent association json file format that origins could use for the handshake. 158 | 159 | #### web-app-origin-association file 160 | 161 | Example 1: web-app-origin-association file at both `www.contoso.com/.well-known/web-app-origin-association` and `https://conto.so/.well-known/web-app-origin-association` : 162 | 163 | ``` json 164 | { 165 | "web_apps": [ 166 | { 167 | "manifest": "https://contoso.com/manifest.json", 168 | "details": { 169 | "paths": [ 170 | "/*" 171 | ], 172 | "exclude_paths": [ 173 | "/blog", 174 | "/about" 175 | ] 176 | } 177 | }, 178 | { 179 | "manifest": "https://partnerapp.com/manifest.json", 180 | "details": { 181 | "paths": [ 182 | "/public/data/*" 183 | ] 184 | } 185 | } 186 | ] 187 | } 188 | ``` 189 | 190 | Example 2: web-app-origin-association file at `https://tenant.contoso.com/.well-known/web-app-origin-association` : 191 | 192 | ``` json 193 | { 194 | "web_apps": [ 195 | { 196 | "manifest": "https://contoso.com/manifest.json", 197 | "details": { 198 | "paths": [ 199 | "/*" 200 | ], 201 | "exclude_paths": [ 202 | "/only/for/partnerapp/*" 203 | ] 204 | } 205 | }, 206 | { 207 | "manifest": "https://partnerapp.com/manifest.json", 208 | "details": { 209 | "paths": [ 210 | "/*" 211 | ] 212 | } 213 | } 214 | ] 215 | } 216 | ``` 217 | 218 | Example 1 shows that the origins `https://contoso.com` and `https://conto.so` can both use the same file to associate with the PWA that has a web app manifest at `www.contoso.com/manifest.json` . In practice, the file at `contoso.so` could be a redirect. 219 | 220 | Example 2 shows that the origin `https://tenant.contoso.com` allows the PWAs with web app manifests at `https://contoso.com/manifest.json` and `https://partnerapp.com/manifest.json` to handle a subset of its URLs. 221 | 222 | This file must contain valid JSON. The top-level structure is an object, with a member named `web_apps`. `web_apps` is an array of objects and each object represents an entry for a unique web app. Each object contains: 223 | 224 | | Field | Required / Optional | Description | Type | Default | 225 | | :------------ | :------------------ | :------------------------------------------------------- | :----- | :------ | 226 | | `manifest` | Required | URL string of the web app manifest of the associated PWA | string | N/A | 227 | | `details` | Optional | Contains arrays of URL patterns | object | N/A | 228 | 229 | Each `details` object contains: 230 | | Field | Required / Optional | Description | Type | Default | 231 | | :-------------- | :------------------ | :------------------------------- | :------- | :------ | 232 | | `paths` | Optional | Array of allowed path strings | string[] | `[]` | 233 | | `exclude_paths` | Optional | Array of disallowed path strings | string[] | `[]` | 234 | 235 | #### File Location 236 | 237 | To make use of the web-app-origin-association file, we suggest that association files be placed in a `.well-known` directory within the root path of the origin. In order to match an origin with a `*.` prefix, we suggest that the corresponding association file be placed relative to the root path of the domain. Eg. an origin `*.contoso.com` could have a `web-app-origin-association` file at `contoso.com/.well-known/web-app-origin-association`. 238 | 239 | Alternatively, we suggest browsers locate it using a `` element in the header section of the main document at the origin's root path. 240 | 241 | #### Failure to Associate 242 | 243 | If necessary association validation cannot be completed successfully during PWA installation for any reason, the browser must not register the app as an active URL handler for the affected URLs. The browser should try to complete installation with as many valid URL handling registrations as possible. 244 | 245 | #### Periodic Revalidation 246 | 247 | An origin could modify its associations with PWAs at any time. Conforming browsers must regularly attempt to revalidate the associations of installed web apps. If a URL handler registration fails to revalidate because the association data has changed or is no longer available, the browser must disable or remove registrations that are no longer valid. 248 | 249 | #### Shortened URLs 250 | 251 | Web applications often provide users with shortened URLs for convenience. If developers would like register these URLs for URL handling, they need access to the short URL origin to place a validation file. This may not be possible with third party URL shortening services that the developer does not control. 252 | 253 | ### Browser Changes 254 | 255 | To support basic, browser-level registration of URL handlers, browsers should make the following changes: 256 | 257 | 1. Validate and register the `url_handlers` data from PWA manifests during PWA installation and periodically revalidate installed apps. 258 | 259 | 2. Perform adequate validation to address security and privacy concerns. They may do so using a web-app-origin-association file or another method of their choosing. 260 | 261 | 3. When starting with a URL parameter, determine if there are any matching PWA URL handlers. 262 | 263 | * If there is a match, launch the PWA and load the URL in a new standalone window instead of the browser window. 264 | 265 | * If the launch URL is not within the app scope, browsers can delegate to a document event handler. If there is an existing app window with a loaded document, browsers can try to find a suitable event handler there. If not found, the browser could fall back to opening a new app window, waiting for a document to load, then looking for a suitable event handler. 266 | 267 | * If there is a manifest member that specifies a behavior for launching web apps from link activations (for eg. `capture_links` in [Declarative Link Capture](https://github.com/WICG/sw-launch/blob/master/declarative_link_capturing.md)), app launch should try to follow that launch behavior specification. 268 | 269 | * If there is more than one match, display the choices and collect the user's input with a disambiguation dialog. 270 | 271 | 4. Keep URL handling registrations in sync with the PWA's lifecycle (i.e. during manifest update, uninstall, etc.) 272 | 273 | #### User preferences 274 | 275 | If URL handlers are registered and launched at the browser level, the browser should allow the user to enable/disable URL handlers, set default launch behavior, etc through browser settings. If URL handlers are registered and launched at the OS level, the browser should direct the user to the OS settings. 276 | 277 | #### Handling multiple registrations 278 | 279 | The association file is able to contain association objects for multiple PWA handlers. Multiple PWAs are able to request to handle the same URL. In cases where there are multiple registered handlers available, the browser or OS should present options to the user and allow the user to decide which handler to use. 280 | 281 | ### Operating System Changes 282 | 283 | To provide OS level registration of URL handlers, browsers' PWA implementations need to integrate more deeply with the OS application platform. This is to allow the OS to recognize PWAs as apps that can be launched and can therefore serve as URL handlers. There may be different approaches to accomplishing this with different OS platforms. OS changes may be necessary to enable this integration. In OS or browser versions where this integration cannot be implemented, the behavior should default to URL handling by the browser. 284 | 285 | ## Security Considerations 286 | 287 | URL handlers, if improperly implemented, can be used to hijack traffic for websites. This is why the app association mechanism is an important part of the proposed scheme. Associations must be validated when PWAs are installed, and again periodically to evaluate any new changes in the association file and web app manifest. 288 | 289 | If a browser registers apps with the OS as URL handlers, the OS must trust that browser to validate the PWA-to-site association or implement suitable validation itself. If the OS delegates the validation to browsers, it must be clear which browsers are compliant with the validation requirements. 290 | 291 | If an associated site is overtaken by a malicious actor, it is possible for users to be exposed to malicious content through the PWA handling those URLs. To mitigate this risk, the browser may want to suppress the PWA launch or get user confirmation using a security mechanism which detects risky URLs. 292 | 293 | Conforming browsers may want to limit the maximum processed entries of `url_handlers` to N and the numbers of allowed and disallowed paths (in `web-app-origin-association` or equivalent) each to M. This will limit the amount of work the manifest parser does and further limit the risk of URL hijacking. 294 | 295 | URL handler registrations should only be performed for installed PWAs as users expect installed applications to be more deeply integrated with the OS. Furthermore, conforming browsers should not activate PWAs as URL handlers for any URL without an explicit user confirmation. 296 | 297 | ## Privacy Considerations 298 | 299 | Third-party websites would not be able to leverage this API to detect installed web apps by observing navigations to first-party URL links if there is no difference in in-browser navigation behavior. 300 | 301 | Although not an immediate privacy concern, fingerprinting risks should be thoroughly examined when designing web APIs that activate URL handlers instead of performing regular in-browser navigation. Further mitigation such as obfuscation of launch timing may be necessary. 302 | 303 | Native applications can already use OS APIs to enumerate installed applications on the user's system. For example, native applications in Windows can use the [FindAppUriHandlersAsync](https://docs.microsoft.com/en-us/uwp/api/windows.system.launcher.findappurihandlersasync) API to enumerate URL handlers. If PWAs register as OS level URL handlers in Windows, their presence would be visible to other applications. 304 | 305 | ## Relation to other proposals 306 | 307 | ### [Declarative Link Capturing](https://github.com/WICG/sw-launch/blob/master/declarative_link_capturing.md) (DLC) 308 | 309 | [Declarative link capturing](https://github.com/WICG/sw-launch/blob/master/declarative_link_capturing.md) would allow a developer to opt-in all app scope URLs to link capturing behavior with simple changes to their web app manifest. If Declarative Link Capturing and URL Handling features are both available, browsers may reduce overlap in functionality by prioritizing DLC behavior over URL handling behavior: if a URL matches the app scope of an installed app with DLC enabled, there is no need to further match against the URL handling registrations of other apps. 310 | 311 | DLC aims to provide a choice of different app launch behaviors. To avoid overlap in the proposals, URL Handling should use a default, non-configurable launch behavior and support the standardization of a manifest member like `capture_links`. 312 | 313 | ### [Service Worker Scope Pattern Matching](https://github.com/wanderview/service-worker-scope-pattern-matching/blob/master/explainer.md) (SWSPM) 314 | 315 | This proposal uses a wildcard and pattern matching syntax that is compatible with the manifest syntax designed for scope pattern matching. If there are multiple manifest members that use URL pattern matching, URL Handling should continue to use a compatible syntax for developers' ease of use. 316 | 317 | ## OS Specific Implementation Notes 318 | 319 | ### Windows 320 | 321 | * Starting from the Windows 10 Anniversary update, the ["Apps for Websites"](https://docs.microsoft.com/en-us/windows/uwp/launch-resume/web-to-app-linking) capability allows the registration of apps to handle URLs from associated websites. 322 | 323 | ### Android 324 | 325 | * Chrome installs a PWA on Android by generating and installing a [WebAPK](https://developers.google.com/web/fundamentals/integration/webapks). 326 | * When a Chrome PWA is installed on Android, it can [register a set of intent filters](https://developers.google.com/web/fundamentals/integration/webapks?hl=ro#android_intent_filters) for all URLs within the scope of the app. 327 | * This means that Chrome PWAs already handle associated URLs on Android at the OS level using intent filters. This is also known as Deep Linking. 328 | * Additionally, Android apps are also able to register to be URL handlers by using Android App Links. 329 | * App Links require server side verification of the relationship to the app while Deep Links do not. 330 | * Deep Linking will show an app picker but App Linking will take the user directly to the app. 331 | 332 | Other browsers (e.g., Edge) on Android are able to add PWAs to the home screen but are not able to register intent filters. They likely need to also be able to use a WebAPK implementation or similar to enable URL handling. 333 | 334 | ### iOS, MacOS 335 | 336 | * iOS allows the association of apps to websites using [Universal Links](https://developer.apple.com/ios/universal-links/). 337 | * Newer versions of MacOS also support Universal Links. 338 | * Safari implements a subset of PWA features. 339 | * Safari is currently the only browser able to install a PWA as an iOS app. 340 | * Universal links/link capturing is not available to iOS PWAs. 341 | 342 | ## Open Questions 343 | 344 | * In order to validate an origin with sub-domain wildcard prefix ( `*.contoso.com` ), is it reasonable to locate the validation file relative to the domain? This breaks from the assumption that the domain and its sub-domains are separate origins and may have further security implications. 345 | -------------------------------------------------------------------------------- /handle_links/Security and Privacy Self-Review Questionnaire.md: -------------------------------------------------------------------------------- 1 | # Security and Privacy Self-Review Questionnaire for `handle-links` 2 | 3 | **01. What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary?** 4 | 5 | This feature does not expose any information to the web page or other parties. 6 | 7 | **02. Do features in your specification expose the minimum amount of information necessary to enable their intended uses?** 8 | 9 | It doesn’t expose any more information than necessary. 10 | 11 | **03. How do the features in your specification deal with personal information, personally-identifiable information (PII), or information derived from them?** 12 | 13 | There is no instance where the feature deals with any PII. 14 | 15 | **04. How do the features in your specification deal with sensitive information?** 16 | 17 | There is no instance where the feature would deal with sensitive information. 18 | 19 | **05. Do the features in your specification introduce new state for an origin that persists across browsing sessions?** 20 | No. 21 | 22 | **06. Do the features in your specification expose information about the underlying platform to origins?** 23 | 24 | The feature does not expose any information about the underlying platform to the origin. 25 | 26 | **07. Does this specification allow an origin to send data to the underlying platform?** 27 | 28 | No. 29 | 30 | **08. Do features in this specification enable access to device sensors?** 31 | 32 | No. 33 | 34 | **09. What data do the features in this specification expose to an origin? Please also document what data is identical to data exposed by other features, in the same or different contexts.** 35 | 36 | Nothing is exposed to an origin. 37 | 38 | **10. Do features in this specification enable new script execution/loading mechanisms?** 39 | 40 | No. 41 | 42 | **11. Do features in this specification allow an origin to access other devices?** 43 | 44 | No. 45 | 46 | **12. Do features in this specification allow an origin some measure of control over a user agent's native UI?** 47 | 48 | Yes. (Can cause the content to be displayed in an app window). 49 | 50 | **13. What temporary identifiers do the features in this specification create or expose to the web?** 51 | 52 | None. 53 | 54 | **14. How does this specification distinguish between behavior in first-party and third-party contexts?** 55 | 56 | N/A 57 | 58 | **15. How do the features in this specification work in the context of a browser’s Private Browsing or Incognito mode?** 59 | 60 | Won’t trigger the feature while on Private Browsing. 61 | 62 | **16. Does this specification have both "Security Considerations" and "Privacy Considerations" sections?** 63 | 64 | Yes. 65 | 66 | **17. Do features in your specification enable origins to downgrade default security protections?** 67 | 68 | No. 69 | 70 | **18. How does your feature handle non-"fully active" documents?** 71 | 72 | *** 73 | 74 | **19. What should this questionnaire have asked?** 75 | N/A 76 | -------------------------------------------------------------------------------- /handle_links/explainer.md: -------------------------------------------------------------------------------- 1 | # Web App Link Handling Manifest Options 2 | 3 | Authors: [Diego Gonzalez](https://github.com/diekus), [Lu Huang](https://github.com/luhuangmsft) 4 | 5 | ## Status of this Document 6 | This document is a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. 7 | * This document status: **Active** 8 | * Expected venue: [W3C Web Incubator Community Group](https://wicg.io/) 9 | * **Current version: this document** 10 | 11 | ## Introduction 12 | 13 | When clicking on a link, the default behavior is that the browser will open and navigate to the specified URL. However, if a compatible application is installed, a user might prefer to have that application launch and "open" said link. This is the case for native apps that range from media consumption to productivity, where if installed, will open when clicking on a link with related content. This is generally the preferred way to interact with the referenced content. 14 | 15 | To achieve this, an installed application might want to register itself to handle links and create this seamless flow. From a UX perspective, it is desirable to give users choice on how they prefer the link to be opened, and it is important since it creates the cohesive and integrated experience mentioned previously. 16 | 17 | The `handle_links` manifest entry aims to allow registration of installed web applications as link handlers, to grant them the possibility of opening links like their native counterparts. 18 | 19 | ## Goals 20 | 21 | * Allow web apps to handle links that are within their [scope](https://www.w3.org/TR/appmanifest/#understanding-scope). 22 | 23 | ## Non-Goals 24 | 25 | * Customize app launch behavior (see [launch_handler](https://github.com/WICG/sw-launch/blob/main/launch_handler.md) for this). 26 | * Extending the scope of the links that can be handled by the installed web app (see [scope extensions](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md) for this). 27 | 28 | ## Use Cases 29 | 30 | The generic use case is as follows: A user clicks on a link that refers to content within scope a web app they have installed on their machine. The link opens in the web app instead of the browser. This is behavior that currently occurs on commerce, streaming and productivity apps. 31 | 32 | For example, if a user gets a link to edit a presentation they were shared, that presentation can open in the installed web app where they can proceed to work on it. 33 | 34 | In a similar vein, a user can click on a link of a music streaming service (www.streamify.com/player?trackid=demotrack) to open the referenced track in the installed PWA. 35 | 36 | ## Proposed Solution 37 | 38 | ### `handle_links` manifest member 39 | 40 | We propose the addition of the `handle_links` member to the web app manifest that specifies the default link handling for the installed web app. The shape of this member is as follows: 41 | 42 | ``` 43 | "handle_links": "auto" | "preferred" | "not-preferred" 44 | ``` 45 | 46 | * `preferred`: the user agent should open in-scope links within the installed application. 47 | * `not-preferred`: the user agent should not open links within the installed application. 48 | * `auto`: The user agent should select the appropriate behavior for the platform. 49 | 50 | These options indicate an app's link handling preference. They should be seen as suggestions from an app to the user agent. 51 | * `auto`: Default value if `handle_links` is not found in the manifest. The user agent may choose between `preferred` and `not-preferred`. 52 | * `preferred`: The user agent should handle links using matching app clients and may promote link handling behavior. 53 | * `not-preferred`: The user agent should not handle links using matching app clients and may not promote link handling behavior. 54 | 55 | ## Privacy and Security Considerations 56 | 57 | ### Privacy 58 | 59 | No considerable privacy concerns are expected, but we welcome community feedback. 60 | 61 | ### Security 62 | 63 | The developer options described in this explainer works on app manifest scope and depends on the scope boundary for security. No additional security concerns are expected, but we welcome community feedback. 64 | 65 | ## Related Proposals 66 | 67 | ### URL Handlers 68 | The `handle_links` proposal is intended to be a part replacement to the [PWA as URL Handlers proposal](https://github.com/WICG/pwa-url-handler/blob/main/explainer.md). The functionality of `url_handlers` is now divided between `scope_extensions` and `handle_links`. 69 | 70 | ### `scope_extensions` 71 | 72 | The [`scope_extensions`](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md) proposal allows web apps to extend their scope to other origins. When used in conjunction with `handle_links` the web app can open links from the new extended scope. 73 | 74 | ### `launch_handler` 75 | 76 | The [`launch_handler`](https://github.com/WICG/sw-launch/blob/main/launch_handler.md) proposal enables web apps to customize their launch behavior across all types of app launch triggers. This can work with `handle_links` by specifying how/where to open/route the links. 77 | -------------------------------------------------------------------------------- /w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "group": [80485] 3 | , "contacts": ["travisleithead"] 4 | , "repo-type": "cg-report" 5 | } 6 | --------------------------------------------------------------------------------