diff --git a/microsoft-edge/progressive-web-apps/how-to/handle-urls.md b/microsoft-edge/progressive-web-apps/how-to/handle-urls.md index bda1893243..7fffd50e17 100644 --- a/microsoft-edge/progressive-web-apps/how-to/handle-urls.md +++ b/microsoft-edge/progressive-web-apps/how-to/handle-urls.md @@ -6,7 +6,7 @@ ms.author: msedgedevrel ms.topic: conceptual ms.service: microsoft-edge ms.subservice: pwa -ms.date: 09/15/2022 +ms.date: 08/29/2025 --- # Handle links to a PWA @@ -44,23 +44,75 @@ No code is required for automatic link handling to work, but end users can opt-o ## Handle links from other origins by using scope extensions -Scope extensions make it possible for a PWA to capture navigation to paths, subdomains, or even sites other than its own scope. This can be useful for PWAs that span multiple domains for localization purposes. For example, a PWA may span `contoso.com`, `contoso.co.uk`, and `contoso.fr`. +Scope extensions make it possible for a Progressive Web App (PWA) to capture navigation to domains, subdomains, or paths other than its own scope. Scope extensions allow web apps that rely on multiple top-level domains, multiple subdomains, or multiple paths to be presented as a single web app. -The manifest of a PWA defines which part of the hosting domain the PWA is scoped to. For example, the `www.contoso.com` domain name may have a PWA defined under `www.contoso.com/app` with its scope set to `/app`. In this case, all the web pages available within the `www.contoso.com/app` path are part of the PWA scope. However, the web pages within the `www.contoso.com/foo` path are not part of the PWA scope. Furthermore, web pages that are available at `bar.contoso.com/app` or `www.contoso.co.uk` are also not part of the PWA scope. +Scope extension can be useful for cases such as PWAs that handle localization by using multiple domains, subdomains, or paths. -#### Origin trial +#### PWA scope when not using scope extensions -As of October 17, 2024, the scope extensions feature is an origin trial. For status, see [Web app scope extensions feature](https://chromestatus.com/feature/5746537956114432) at Chrome Platform Status. +The manifest of a PWA defines which part of the hosting domain, such as a specific path, the PWA is scoped to. For example, the `www.contoso.com` domain name may have a PWA defined under the path `www.contoso.com/app`, with its scope set to `/app`. -When the feature can be used in Microsoft Edge and is no longer in origin trial, the feature will be documented in the present article. See [Scope Extensions for Web Apps](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md), an Explainer in the **manifest-incubations** repo. +In that case, all webpages within the `www.contoso.com/app` path are part of the PWA scope. However, if you don't use scope extensions, the following webpages are not part of that PWA scope: -See also: -* [Use origin trials in Microsoft Edge](../../origin-trials/index.md) +* Webpages at a different domain, such as `www.contoso.co.uk`. +* Webpages at a different subdomain, such as `bar.contoso.com`. +* Webpages at a different path, such as `www.contoso.com/foo`. - -## See also + +#### Extending scope to other domains, subdomains, or paths + +By using scope extensions, a PWA can span other domains, subdomains, or paths. For example: + +A PWA can span the following top-level domains: +* `contoso.com` +* `contoso.co.uk` +* `contoso.fr` + +A PWA can span the following subdomains: +* `www.contoso.com` +* `bar.contoso.com` -* [PWAs as URL Handlers](https://web.dev/pwa-url-handler/) +A PWA can span the following paths: +* `www.contoso.com/app` +* `www.contoso.com/foo` + + + +#### The `scope_extensions` web app manifest member + +The `scope_extensions` web app manifest member enables a web app to extend its scope to other origins. + +For example, this web app manifest file resides at the domain `sample-app.com`, and extends the scope to a different domain, `example.com`: + +```json +{ + "name": "Example app", + "display": "standalone", + "start_url": "/index.html", + "scope_extensions": [ + { + "type": "origin", + "origin": "https://example.com" + } + ] +} +``` + +The origins that are listed in the `scope_extensions` member must confirm that they are associated with the web app by hosting a configuration file named `.well-known/web-app-origin-association`. The configuration file must list the web app's origin. + +For example, this `.well-known/web-app-origin-association` configuration file resides at the domain `example.com`, and lists the web app's origin as the domain `sample-app.com`: + +```json +{ + "https://sample-app.com/": { + "scope": "/" + } +} +``` + +See also: +* [scope_extensions](https://developer.mozilla.org/docs/Web/Progressive_web_apps/Manifest/Reference/scope_extensions) at MDN. +* [Scope Extensions for Web App Manifest](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md)