Namespaces
Variants
Actions

URI associations for Windows Phone 8

Jump to: navigation, search

This article explains how to associate your application with an URI scheme in order to launch it when interaction with such URI is detected.

WP Metro Icon WP8.png
Article Metadata
Code Example
Compatibility
Platform(s): Windows Phone 8
Article
Keywords: Custom URI
Created: MaMi (28 Nov 2012)
Last edited: ltomuta (11 Feb 2013)

Contents

Introduction

Windows Phone 8 introduces the possibility for your app to register to a predefined kind of URI scheme. This will allow you to launch your application from various sources and with various optional parameters. The URI will have to be formatted as follows: 

<Custom Protocol Name>:<The landing page>?[First parameter name]=[First parameter value]&[Second parameter name]=[Second parameter value]

For example: 

myappuri:MainPage?Category=5&Subcategory=3

Note that its not mandatory to put the landing page after the semi colon, but it is a good practice. You can use an ID like this: 

myappuri:45645645645

How to register for an URI association

To register an URI scheme for your app you will have to manually edit the app manifest. In the Solution Explorer open the Properties folder, right click on the WMAppManifest.xml file and select View Code. Scroll down to the end of the Tokens element and add an Extensions element with a Protocol children like this: 

<Extensions>
  <Protocol Name="myappuri" NavUriFragment="encodedLaunchUri=%s" TaskID="_default" />
</Extensions>

Just replace myappuri value with the URI you want to use. The other parameters are mandatory and must stay like this.

Warning.png
Warning: Some URI schemes are reserved by the operating system or default applications. To see the full list, check this MSDN Article.

How to detect that your user launched the app from the URI association

You will have to implement a custom UriMapper that will parse the Uri at the launch of your application and try to detect the source. Following the sample provided above, the UriMapper would look like this in our case: 

    class AssociationUriMapper : UriMapperBase
    {
        private string tempUri;
        public override Uri MapUri(Uri uri)
        {
            tempUri = System.Net.HttpUtility.UrlDecode(uri.ToString());
            // URI association launch for my app detected
            if (tempUri.Contains("myappuri:MainPage?Category="))
            {
                // Get the category (after "Category=").
                int categoryIndex = tempUri.IndexOf("Category=") + 9;
                string category = tempUri.Substring(categoryIndex);
                // Redirect to the MainPage.xaml with the proper category to be displayed
                return new Uri("/MainPage.xaml?Category=" + category, UriKind.Relative);
            }
            // Otherwise perform normal launch.
            return uri;
          }
      }

One more step to ensure that your application will use your new UriMapper, go to App.xamls.cs file in the InitializePhoneApplication() method and add this line: 

RootFrame.UriMapper = new AssociationUriMapper();

Your app will now try to detect if it was launched from the normal way or from the URI association, and in this case it will parse the parameters provided and redirect to the proper page.

How to retrive the parameters once you have been redirected

Like for any page navigation in Windows Phone you'll have to check the QueryString in NavigationContext once you've reached your target page to retrieve your parameters 

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    if (NavigationContext.QueryString.ContainsKey("Category"))
    {
        Category = int.Parse(NavigationContext.QueryString["Category"]);
    }
    base.OnNavigatedTo(e);
}

What will and will not work

Note.png
Note: This article is based on personal experimentation. I do not say that all of this will never work but from what I was able to test it is currently not working.

What will trigger your URI association and launch your app:

  • Get the URI from NFC tag.
  • Get the URI by mail.
  • Click on a HTML link containing the URI.
  • Webpage redirection with a custom protocol.
  • Get the URI from NFC device sharing an URI (e.g. PublishUriMessage(Uri) from ProximityDevice).

What will NOT trigger your URI association and launch your app

  • Enter directly the URI in the Web Browser.
  • Scan a QR code from Bing search.

What MAY trigger your URI association and launch your app

  • Get the URI by SMS. It seems to depend on the uri your registered and could be connected to its length

What if many applications registered the same name

In this case the user will be prompted to select which application he want to launch

  • App Chooser Windows

Document your custom URI protocol

Your application can now be started by and can receive data from other applications. But in order for this to work, you must document your protocol. You can use this document as a catalog and advertise your protocol by adding it to the table below.

Custom URI Link to documentation
fb:// http://www

Code sample

Media:UriAssociation.zip

Reference

Official documentation about URI associations on MSDN

Reserved files and URI associations

Retrieved from "http://www.developer.nokia.com/Community/Wiki/index.php?title=URI_associations_for_Windows_Phone_8&oldid=183750"
This page was last modified on 11 February 2013, at 22:20.
1000 page views in the last 30 days.
Featured links
Develop
Distribution
Blogs
Community
Resources
Site Map
Terms & Conditions
Privacy Policy
Nokia Developer aims to help you create apps and publish them so you can connect with users around the world.

京ICP备05048969号  © Copyright Nokia 2013 All rights reserved