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 can also handle URLs in the same way, and doing so can create a more engaging experience.

Note

At the moment, in-browser page navigation doesn't trigger PWA URL handling.

Enable URL handling

URL handling is still experimental, to enable it:

  1. Go to edge://flags in Microsoft Edge.

  2. Select Search flags and type "url handling".

  3. Select Default > Enabled > Restart.

    Enable the URL handling API experiment.

URL Handling is also 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 PWA's ownership of the handled URLs to successfully launch the app. This is required when the handled URL and the 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 is not 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 does not 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:

  • Press Windows logo key + R.
  • Enter a URL your app handles.
  • Press Enter.

Note

At the moment, only PWAs that were installed from the default system browser can handle URLs.

Demo

DevTools Tips is a PWA that handles URLs to its own domain so that the app opens instead of the website when one is used.

To test URL handling on DevTools Tips:

Windows knows that your app is registered to handle this URL and asks you to choose which app you want to use. Select the DevTools Tips apps. You can also select Remember my choice to avoid seeing this dialog every time.

Selecting an application to handle URLs on Windows.

The app launches and displays the tips page.

You can find the source code on GitHub. In particular, the app registers the handled URLs in the manifest.json file and the website establishes the app's ownership in the web-app-origin-association file.

See also