Handle URLs in Progressive Web Apps

Native applications on many operating systems can be associated with URLs. They can request to be launched, instead of the browser, when associated URLs are activated.

Progressive Web Apps (PWAs) can also handle URLs in the same way, to create a more engaging experience.

Enable URL handling

URL handling is an experimental feature. To enable the URL handling experiment:

1. In Microsoft Edge, go to edge://flags.

2. In the Search flags text box, type "url handling". The Desktop PWA URL handling setting appears.

3. Change the setting from Default to Enabled, and then click the Restart button.

   

URL handling is an origin trial in Microsoft Edge. Learn how to enroll your site in an origin trial.

Define which URLs your app handles

The first thing to do is declare which URLs your app handles. This is done in your app manifest file, using the url_handlers array member.

Each entry in the url_handlers array contains a origin string, which is a pattern for matching origins.

{
    "url_handlers": [
        {
            "origin": "https://contoso.com"
        },
        {
            "origin": "https://*.contoso.com"
        },
        {
            "origin": "https://conto.so"
        }
    ]
}

In the above example, the app is registered to handle URLs that have their origins set to contoso.com or any of its subdomains, as well as conto.so.

Verify the origin ownership

Microsoft Edge needs to verify the Progressive Web App's ownership of the handled URLs to successfully launch the app. This is required when the handled URL and the Progressive Web App (PWA) are both on the same origin and when they're not. In most cases, the PWA will handle URLs that have the same origin, but this isn't required.

Origin ownership is established with the web-app-origin-association JSON file, which is used by Microsoft Edge to validate the handshake between the PWA and the URL.

Let's take the example of a PWA hosted at https://app.contoso.com trying to handle https://contoso.com and https://partnerapp.com URLs.

• To establish the PWA's ownership of the contoso.com origin, the following JSON content needs to be available at https://contoso.com/.well-known/web-app-origin-association.

  {
      "web_apps": [
          {
              "manifest": "https://app.contoso.com/manifest.json",
              "details": {
                  "paths": [
                      "/*"
                  ]
              }
          }
      ]
  }
  

• To establish the PWA's ownership of the partnerapp.com origin, the same JSON content needs to be available at https://partnerapp.com/.well-known/web-app-origin-association.

  {
      "web_apps": [
          {
              "manifest": "https://app.contoso.com/manifest.json",
              "details": {
                  "paths": [
                      "/*"
                  ]
              }
          }
      ]
  }
  

To learn more about the valid members in web-app-origin-association, see the URL Handlers explainer.

Testing URL handling

Testing your app's URL handling from a web browser won't work, since in-browser page navigation doesn't trigger URL handling at the OS level.

To test the feature, send yourself a URL in a chat message app, or a desktop email client like Windows Mail. You can also use the Windows Run app:

1. Press Windows logo key+R.
2. Enter a URL that your app handles.
3. Press Enter.

Demo

DevTools Tips is a demo Progressive Web App (PWA) that handles URLs for its own domain, so that the app opens instead of the website when a URL for its domain is used.

To test URL handling on the DevTools Tips demo:

1. Enable URL handling in Microsoft Edge.

2. Go to the DevTools Tips PWA.

3. Click the App available. Install DevTools Tips () icon in the Address bar to install the DevTools Tips app locally.

4. Press Windows logo key + R to open the Windows Run dialog.

5. Enter a URL for one of the tips on the site, such as https://devtoolstips.org/tips/en/find-css-changes/.

6. Press Enter.

Windows knows that your app can handle URLs, but since there may be other apps that can handle URLs, Windows asks you which app to use. Select the DevTools Tips app. If you want to avoid seeing this dialog every time, select Remember my choice.

The DevTools Tips app launches and displays the Tips page.

You can find the source code on GitHub.

• The DevTools Tips app registers the handled URLs in the manifest.json file.
• The website establishes the app's ownership in the web-app-origin-association file.

See also

• Handling URLs in PWAs video.
• PWAs as URL Handlers.