Skip to content

Commit c5d0d6f

Browse files
mikehoffmsmikehoffms
authored
PWA scope extensions (#3549)
* draft * eg location of config files * expand scenario details * remove path from subdomain example * remove domain from list of subdomains * restore explainer link * refactor dup text in list * avoid 'may' * example is domains * strike 'all of' * strike 'explainer', no net gain clarity * new para at For example * condense 3 example sections * inc rvw
1 parent 4343f2d commit c5d0d6f

File tree

1 file changed

+63
-11
lines changed

1 file changed

+63
-11
lines changed

‎microsoft-edge/progressive-web-apps/how-to/handle-urls.md

Lines changed: 63 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ ms.author: msedgedevrel
66
ms.topic: conceptual
77
ms.service: microsoft-edge
88
ms.subservice: pwa
9-
ms.date: 09/15/2022
9+
ms.date: 08/29/2025
1010
---
1111
# Handle links to a PWA
1212

@@ -44,23 +44,75 @@ No code is required for automatic link handling to work, but end users can opt-o
4444
<!-- ====================================================================== -->
4545
## Handle links from other origins by using scope extensions
4646

47-
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`.
47+
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.
4848

49-
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.
49+
Scope extension can be useful for cases such as PWAs that handle localization by using multiple domains, subdomains, or paths.
5050

5151

5252
<!-- ------------------------------ -->
53-
#### Origin trial
53+
#### PWA scope when not using scope extensions
5454

55-
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.
55+
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`.
5656

57-
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.
57+
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:
5858

59-
See also:
60-
* [Use origin trials in Microsoft Edge](../../origin-trials/index.md)
59+
* Webpages at a different domain, such as `www.contoso.co.uk`.
60+
* Webpages at a different subdomain, such as `bar.contoso.com`.
61+
* Webpages at a different path, such as `www.contoso.com/foo`.
6162

6263

63-
<!-- ====================================================================== -->
64-
## See also
64+
<!-- ------------------------------ -->
65+
#### Extending scope to other domains, subdomains, or paths
66+
67+
By using scope extensions, a PWA can span other domains, subdomains, or paths. For example:
68+
69+
A PWA can span the following top-level domains:
70+
* `contoso.com`
71+
* `contoso.co.uk`
72+
* `contoso.fr`
73+
74+
A PWA can span the following subdomains:
75+
* `www.contoso.com`
76+
* `bar.contoso.com`
6577

66-
* [PWAs as URL Handlers](https://web.dev/pwa-url-handler/)
78+
A PWA can span the following paths:
79+
* `www.contoso.com/app`
80+
* `www.contoso.com/foo`
81+
82+
83+
<!-- ------------------------------ -->
84+
#### The `scope_extensions` web app manifest member
85+
86+
The `scope_extensions` web app manifest member enables a web app to extend its scope to other origins.
87+
88+
For example, this web app manifest file resides at the domain `sample-app.com`, and extends the scope to a different domain, `example.com`:
89+
90+
```json
91+
{
92+
"name": "Example app",
93+
"display": "standalone",
94+
"start_url": "/index.html",
95+
"scope_extensions": [
96+
{
97+
"type": "origin",
98+
"origin": "https://example.com"
99+
}
100+
]
101+
}
102+
```
103+
104+
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.
105+
106+
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`:
107+
108+
```json
109+
{
110+
"https://sample-app.com/": {
111+
"scope": "/"
112+
}
113+
}
114+
```
115+
116+
See also:
117+
* [scope_extensions](https://developer.mozilla.org/docs/Web/Progressive_web_apps/Manifest/Reference/scope_extensions) at MDN.
118+
* [Scope Extensions for Web App Manifest](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md)

0 commit comments

Comments
 (0)