Docs Documentation Learn Certifications Q&A Code Samples Shows Events  Search Sign in

Windows App Development Explore Ｓ Development Ｓ Platforms Ｓ Resources Ｓ Dashboard

 Filter by title  / Apps / UWP / Develop / Launching, resuming, and background tasks /  Ｄ ／  ｧ In this article

Enable apps for websites using app URI

Launch the Microsoft Store app
Register to handle http and https links in the app
Launch the Windows Maps app manifest
Launch the People app

Launch screen snipping

handlers Associate your app and website with a JSON file
Handle links on Activation to link to content
Article • 11/30/2020 • 6 minutes to read • 9 contributors   Test it out: Local validation tool
Support web-to-app linking with app
URI handlers
Apps for Websites associates your app with a website so that when someone opens a link to your Show more Ｓ
Ｔ Launch an app through file activation
website, your app is launched instead of opening the browser. If your app is not installed, your website
Auto-launching with AutoPlay opens in the browser as usual. Users can trust this experience because only verified content owners can
Reserved file and URI scheme names register for a link. Users will be able to check all of their registered web-to-app links by going to
Ｔ Use app services and extensions Settings > Apps > Apps for websites.
Ｔ Support your app with background tasks
To enable web-to-app linking you will need to:
Ｔ Connected apps and devices (Project
Rome) Identify the URIs your app will handle in the manifest file

Ｔ Splash screens
A JSON file that defines the association between your app and your website. with the app Package
Family Name at the same host root as the app manifest declaration.
Ｔ Threading and async programming
Handle the activation in the app.
Ｔ Develop games
Ｔ Publish
７ Note
API reference
Starting with the Windows 10 Creators update, supported links clicked in Microsoft Edge will
 Download PDF
launch the corresponding app. Supported links clicked in other browsers (for example, Internet
Explorer, etc.), will keep you in the browsing experience.

Register to handle http and https links in the

app manifest
Your app needs to identify the URIs for the websites it will handle. To do so, add the
Windows.appUriHandler extension registration to your app’s manifest file Package.appxmanifest.

For example, if your website’s address is “msn.com” you would make the following entry in your app’s
manifest:

XML ＝ Copy

<Applications>
<Application ... >
...
<Extensions>
<uap3:Extension Category="windows.appUriHandler">
<uap3:AppUriHandler>
<uap3:Host Name="msn.com" />
</uap3:AppUriHandler>
</uap3:Extension>
</Extensions>
</Application>
</Applications>

The declaration above registers your app to handle links from the specified host. If your website has
multiple addresses (for example: m.example.com, www.example.com, and example.com) then add a
separate <uap3:Host Name=... /> entry inside of the <uap3:AppUriHandler> for each address.

Associate your app and website with a JSON

file
To ensure that only your app can open content on your website, include your app's package family
name in a JSON file located in the web server root, or at the well-known directory on the domain. This
signifies that your website gives consent for the listed apps to open content on your site. You can find
the package family name in the Packages section in the app manifest designer.

） Important

The JSON file should not have a .json file suffix.

Create a JSON file (without the .json file extension) named windows-app-web-link and provide your
app’s package family name. For example:

JSON ＝ Copy

[{
"packageFamilyName" : "Your app's package family name, e.g MyApp_9jmtgj1pbbz6e",
"paths" : [ "*" ],
"excludePaths" : [ "/news/*", "/blog/*" ]
}]

Windows will make an https connection to your website and will look for the corresponding JSON file
on your web server.

Wildcards
The JSON file example above demonstrates the use of wildcards. Wildcards allow you to support a wide
variety of links with fewer lines of code. Web-to-app linking supports two types of wildcards in the
JSON file:

Wildcard Description

* Represents any substring

? Represents a single character

For example, given "excludePaths" : [ "/news/*", "/blog/*" ] in the example above, your app will
support all paths that start with your website’s address (for example, msn.com), except those under
/news/ and /blog/ . msn.com/weather.html will be supported, but not msn.com/news/topnews.html.

Multiple apps
If you have two apps that you would like to link to your website, list both of the application package
family names in your windows-app-web-link JSON file. Both apps can be supported. The user will be
presented with a choice of which is the default link if both are installed. If they want to change the
default link later, they can change it in Settings > Apps for Websites. Developers can also change the
JSON file at any time and see the change as early as the same day but no later than eight days after the
update.

JSON ＝ Copy

[{
"packageFamilyName": "Your apps's package family name, e.g MyApp_9jmtgj1pbbz6e",
"paths": [ "*" ],
"excludePaths" : [ "/news/*", "/blog/*" ]
},
{
"packageFamilyName": "Your second app's package family name, for example, MyApp2_8jmtgj2pbb
"paths": [ "/example/*", "/links/*" ]
}]

To provide the best experience for your users, use exclude paths to make sure that online-only content
is excluded from the supported paths in your JSON file.

Exclude paths are checked first and if there is a match the corresponding page will be opened with the
browser instead of the designated app. In the example above, ‘/news/*’ includes any pages under that
path while ‘/news*’ (no forward slash trails 'news') includes any paths under ‘news*’ such as ‘newslocal/’,
‘newsinternational/’, and so on.

Handle links on Activation to link to content

Navigate to App.xaml.cs in your app’s Visual Studio solution and in OnActivated() add handling for
linked content. In the following example, the page that is opened in the app depends on the URI path:

CS ＝ Copy

protected override void OnActivated(IActivatedEventArgs e)

{
Frame rootFrame = Window.Current.Content as Frame;
if (rootFrame == null)
{
...
}

// Check ActivationKind, Parse URI, and Navigate user to content

Type deepLinkPageType = typeof(MainPage);
if (e.Kind == ActivationKind.Protocol)
{
var protocolArgs = (ProtocolActivatedEventArgs)e;
switch (protocolArgs.Uri.AbsolutePath)
{
case "/":
break;
case "/index.html":
break;
case "/sports.html":
deepLinkPageType = typeof(SportsPage);
break;
case "/technology.html":
deepLinkPageType = typeof(TechnologyPage);
break;
case "/business.html":
deepLinkPageType = typeof(BusinessPage);
break;
case "/science.html":
deepLinkPageType = typeof(SciencePage);
break;
}
}

if (rootFrame.Content == null)
{
// Default navigation
rootFrame.Navigate(deepLinkPageType, e);
}

// Ensure the current window is active

Window.Current.Activate();
}

Important Make sure to replace the final if (rootFrame.Content == null) logic with
rootFrame.Navigate(deepLinkPageType, e); as shown in the example above.

Test it out: Local validation tool

You can test the configuration of your app and website by running the App host registration verifier
tool which is available in:

%windir%\system32\AppHostRegistrationVerifier.exe

Test the configuration of your app and website by running this tool with the following parameters:

AppHostRegistrationVerifier.exe hostname packagefamilyname filepath

Hostname: Your website (for example, microsoft.com)

Package Family Name (PFN): Your app’s PFN
File path: The JSON file for local validation (for example, C:\SomeFolder\windows-app-web-link)

If the tool does not return anything, validation will work on that file when uploaded. If there is an error
code, it will not work.

You can enable the following registry key to force path matching for side-loaded apps as part of local
validation:

HKCU\Software\Classes\LocalSettings\Software\Microsoft\Windows\CurrentVersion\
AppModel\SystemAppData\YourApp\AppUriHandlers

Keyname: ForceValidation Value: 1

Test it: Web validation

Close your application to verify that the app is activated when you click a link. Then, copy the address of
one of the supported paths in your website. For example, if your website’s address is “msn.com”, and
one of the support paths is “path1”, you would use http://msn.com/path1

Verify that your app is closed. Press Windows Key + R to open the Run dialog box and paste the link in
the window. Your app should launch instead of the web browser.

Additionally, you can test your app by launching it from another app using the LaunchUriAsync API. You
can use this API to test on phones as well.

If you would like to follow the protocol activation logic, set a breakpoint in the OnActivated event
handler.

AppUriHandlers tips:
Make sure to only specify links that your app can handle.
List all of the hosts that you will support. Note that www.example.com and example.com are
different hosts.
Users can choose which app they prefer to handle websites in Settings.
Your JSON file must be uploaded to an https server.
If you need to change the paths that you wish to support, you can republish your JSON file
without republishing your app. Users will see the changes in 1-8 days.
All sideloaded apps with AppUriHandlers will have validated links for the host on install. You do
not need to have a JSON file uploaded to test the feature.
This feature works whenever your app is a UWP app launched with LaunchUriAsync or a Windows
desktop app launched with ShellExecuteEx. If the URL corresponds to a registered App URI
handler, the app will be launched instead of the browser.

See also
Web-to-App example project windows.protocol registration Handle URI Activation Association
Launching sample illustrates how to use the LaunchUriAsync() API.

Recommended content

Launch the default app for a URI - UWP applications

Learn how to launch the default app for a Uniform Resource Identifier (URI). URIs allow you to launch another
app to perform a specific task. This topic also provides an overview of the many URI schemes built into Windows.

Installing Windows 10 apps from a web page - MSIX

In this section, we will review the steps you need to take to allow users to install your apps directly from the web
page.

Create an App Installer file manually - MSIX

This article describes how to install a related set via App Installer, including how to create a *.appinstaller file that
defines your related set.

Handle URI activation - UWP applications

Learn how to register an app to become the default handler for a Uniform Resource Identifier (URI) scheme
name.

Show more Ｓ

Feedback

Submit and view feedback for

This product ６ This page

６ View all page feedback

 English (United States) ０ Theme Previous Version Docs Blog Contribute Privacy & Cookies Terms of Use Trademarks © Microsoft 2022