App launch URIs in Windows Phone 8

By wenlu

July 23, 2013   Comments

wp8, windows-phone, uris


Windows Phone 8 provides a variety of ways of launching your application.  They all pass a URI to the RootFrame of the application. If you want to map the URI to another in order to customize the behaviour of the app depending on different launching scenarios, you can make a custom URI mapper class inherited from UriMapperBase and then set the URI mapper to RootFrame in InitializePhoneApplication() method.

In this post, we’ll list and group the URIs coming from the different methods of launching an application.

Launching your app from the application list or from a primary tile will lead to a URI defined as NavigationPage for DefaultTask in the WMAppManifest.xml. There are other launching methods sharing the same results, such as launching app from apps listed in photo hubs, music+videos Hub, wallet, and system voice command (not defined by Voice Command Definition (VCD) file).

Some launching methods lead to extra parameters being passed with the URI defined as NavigationPage for DefaultTask in the WMAppManifest.xml. For example, when launching app through LaunchApp NFC tag or PeerFinder, ms_nfp_launchargs parameter is passed. When launching app through lens picker and auto-upload apps listed in photos+camera settings, Action parameter is passed. Moreover, launching app from “Edit” or “Share” in photo hubs will lead to a URI not only with Action parameter but also FileId parameter for the file to be processed further. Launching app from “open in <your app>” in photo hubs will also lead to a URI with an Action parameter and a token parameter to indicate which file should be opened.

There are other launching methods that lead to URIs defined by the system:

  • Launching an app from a custom URI will lead to a URI starting with “/Protocol” together with parameter encodedLaunchUri passed to RootFrame of the app.
  • Launching an app by opening a file with a specific extension ends up with a URI starting with “/FileTypeAssociation” together with parameter fileToken passed to RootFrame of the app.
  • Launching app from Search passes to RootFrame of the app with a URI starting with “/SearchExtras” with parameters related to the quick cards specified by the app.

Some launching methods allow the application to define the URI more freely:

In summary, developers can take advantage of the multiple available ways of launching their apps in order to enhance the visibility and reach of their apps to end users. We hope this article helped you understand how the launch URI can differ in various situations.