How to launch the default app for a URI (Windows Store apps using JavaScript and HTML)

Learn how to launch the default app for a URI. URIs allow you to launch another app on the system to perform a specific task. For example, if you want to allow the user to send a mail to a contact in your app you can use the mailto: URI to launch the user’s default e-mail app.

The following steps will show you how to use the Windows.System.Launcher API to launch the default handler for a URI.

Instructions

Step 1: Create the URI

Create a Windows.Foundation.Uri object for the URI to launch. This URI uses the http scheme name.

// The URI to launch
var uriToLaunch = "http://www.bing.com";

// Create a Uri object from a URI string 
var uri = new Windows.Foundation.Uri(uriToLaunch);

Step 2: Launch the URI

Windows provides several different options for launching the default handler for a URI. These are described in the following chart and in the sections below.

These examples use the Windows.System.Launcher.launchUriAsync method to launch the URI. This is an overloaded method.

Default launch

Call launchUriAsync(Uri) to launch the URI created in step 1 using the default app for the http URI.

// Launch the URI
Windows.System.Launcher.launchUriAsync(uri).then(   
   function (success) {
      if (success) {
        // URI launched
      } else {
        // URI launch failed
      }
   });

Launch with a warning dialog

Call launchUriAsync(Uri, LauncherOptions) to launch the URI created in step 1 with a warning. The treatAsUntrusted property indicates that the system should display a warning.

// Launch the URI with a warning prompt
var options = new Windows.System.LauncherOptions();
options.treatAsUntrusted = true;

Windows.System.Launcher.launchUriAsync(uri, options).then(
   function (success) {
      if (success) {
        // URI launched
      } else {
        // URI launch failed
      }
   });

Launch with a recommended app fallback

In some cases the user may not have an app installed to handle the URI that you are launching. By default, Windows will handle these cases by providing the user with a link to search for an appropriate app on the Store. If you would like to give the user a specific recommendation for which app to acquire in this scenario, you may do so by passing that recommendation along with the URI you are launching. To do this, call the Windows.System.Launcher.LaunchUriAsync(Uri, LauncherOptions) method with LauncherOptions.preferredApplicationPackageFamilyName set to the package family name of the app in the Store that you want to recommend. Then set the LauncherOptions.preferredApplicationDisplayName to the name of that app. Windows will use this information to replace the general option to search for an app in the store with a specific option to acquire the recommended app from the Store.

Note  you must set both of these options to recommend an app. Setting one without the other will result in a failure.

// Set the recommended app.
var options = new Windows.System.LauncherOptions();
options.preferredApplicationPackageFamilyName = "Contoso.URIApp_8wknc82po1e";
options.preferredApplicationDisplayName = "Contoso URI App";

// Launch the URI and pass in the recommended app 
// in case the user has no apps installed to handle the URI
Windows.System.Launcher.launchUriAsync(uri, options).then(
   function (success) {
      if (success) {
        // Uri launched
      } else {
        // Uri launch failed
      }
   });

Remarks

Your app cannot select the app that is launched. The user determines which app is launched. The user can select either a Windows Store app or a desktop app.

When launching a URI your app must be the foreground app, that is, it must be visible to the user. This requirement helps ensure that the user remains in control. To meet this requirement make sure that you tie all URI launches directly to the UI of your app. The user should always have to take some action to initiate a URI launch. If you attempt to launch a URI and your app is not in the foreground the launch will fail and your error callback will be invoked.

You must specify the privateNetworkClientServer capability in order to launch intranet URIs, for example a file:/// URI pointing to a network location.

You cannot use this method to launch a URI in the local zone. For example, apps cannot use the file:/// URI to access files on the local computer. Instead, you must use the Storage APIs to access files. If you attempt to launch an intranet URI without the correct capability or a local zone URI the launch will fail and your error callback will be invoked.

Complete example

See Association launching sample.

Related topics

Tasks

How to handle protocol activation

How to launch the default app for a file

Guidelines

Guidelines and checklist for file types and URIs

Reference

Windows.System.Launcher.launchUriAsync

Build date: 10/26/2012