×
Namespaces

Variants
Actions
(Difference between revisions)

URI associations for Windows Phone

From Nokia Developer Wiki
Jump to: navigation, search
chintandave_er (Talk | contribs)
(Chintandave er - used Icode template, bold page name)
hamishwillee (Talk | contribs)
m (Hamishwillee -)
(46 intermediate revisions by 11 users not shown)
Line 1: Line 1:
[[Category:Windows Phone]][[Category:Near Field Communication (NFC)]][[Category:Windows Phone 8]]
+
[[Category:Files/Data on Windows Phone]][[Category:NFC on Windows Phone]][[Category:Code Examples]][[Category:Windows Phone 8]][[Category:XAML]]
{{Abstract|This article explains how to associate your application with an uri format in order to launch it when such uri is detected }}  
+
{{Abstract|This article explains how to associate your application with an URI scheme in order to launch it when interaction with such URI is detected.}}  
{{Note|This is a community entry in the [[Windows Phone 8 Wiki Competition 2012Q4]].}}
+
{{SeeAlso|
 +
* [[URI associations for Windows Phone]]
 +
* [[URI Association Schemes List]] (known schemes)
 +
* [[Designing URI scheme handlers]]
 +
* [http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662937%28v=vs.105%29.aspx URI schemes for launching built-in apps for Windows Phone 8 ]
 +
* [http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj207065%28v=vs.105%29.aspx#BKMK_Reservedprotocolnames Reserved URI scheme names]
 +
* [http://code.msdn.microsoft.com/wpapps/URI-Association-Sample-7915a233 Windows Phone DevCenter URI Association Sample]}}
 
{{ArticleMetaData <!-- v1.2 -->
 
{{ArticleMetaData <!-- v1.2 -->
|sourcecode= <!-- Link to example source code e.g. [[Media:The Code Example ZIP.zip]] -->
+
|sourcecode= [[Media:UriAssociation.zip]], [[Media:appcommunication.zip]]
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|devices= <!-- Devices tested against - e.g. ''devices=Nokia 6131 NFC, Nokia C7-00'') -->
 
|devices= <!-- Devices tested against - e.g. ''devices=Nokia 6131 NFC, Nokia C7-00'') -->
Line 9: Line 15:
 
|platform= Windows Phone 8
 
|platform= Windows Phone 8
 
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
 
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->  
+
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->
|signing=<!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
+
|signing= <!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 
|keywords= Custom URI
 
|keywords= Custom URI
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|translated-by= <!-- [[User:XXXX]] -->
 
|translated-by= <!-- [[User:XXXX]] -->
|translated-from-title= <!-- Title only -->  
+
|translated-from-title= <!-- Title only -->
 
|translated-from-id= <!-- Id of translated revision -->
 
|translated-from-id= <!-- Id of translated revision -->
|review-by=<!-- After re-review: [[User:username]] -->
+
|review-by= <!-- After re-review: [[User:username]] -->
 
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 
|update-by= <!-- After significant update: [[User:username]]-->
 
|update-by= <!-- After significant update: [[User:username]]-->
Line 26: Line 32:
  
 
== Introduction ==
 
== Introduction ==
Windows phone 8 introduced the possibility for your app to register to a predifined kind of uri. This will allow you to launch your application from various source and with various parameters.
+
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 follow
+
The URI will have to be formatted as follows:
 
<code>
 
<code>
"<Custom Protocol Name>"''':'''"<The landing page>""<Some optional parameters if needed>"
+
 
 +
<Custom Protocol Name>:<The landing page>?[First parameter name]=[First parameter value]&[Second parameter name]=[Second parameter value]
 +
 
 
</code>
 
</code>
  
 
For example:
 
For example:
 
<code>
 
<code>
myappuri:MainPage.xaml?Category=5
+
myappuri:MainPage?Category=5&Subcategory=3
 
</code>
 
</code>
  
== How to register for an uri association ==
+
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:
  
To register an uri for your app you will have to manually edit your manifest.
+
<code>
In the solutions explorer open the ''properties'' folder, right click on the '''WMAppManifest.xml''' and select '''View Code'''
+
myappuri:45645645645
 +
</code>
 +
 
 +
== How to register for an URI association ==
  
Scroll down to the end of the '''Tokens''' element and add an '''Extensions'''' element with a '''Protocol'''' children like this:
+
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:
  
 
<code xml>
 
<code xml>
Line 50: Line 61:
 
</code>
 
</code>
  
Just replace '''myappuri'''' by the uri you want to use. The other parameters are mandatory and must stay like this.
+
Just replace '''myappuri''' value with the URI you want to use. The other parameters are mandatory and must stay like this.
  
 +
== What URI scheme should I use? ==
  
== How to detect that your user launched the app from the uri association ==
+
To ensure you don't accidentally re-use a URI [http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj207065(v%3Dvs.105).aspx#BKMK_Reservedprotocolnames reserved by the operating system or default applications] or a URI registered to another [[URI Association Schemes List|third party app]], we recommend you include your company and app name in your URI as shown (see [[Designing URI scheme handlers]] for more detail):
You will have to implement a custom uri mapper class that will parse the Uri at the launch of your application and try to detect the source.
+
<companyName>-<nameOfApp>
  
Following the sample provided above, the {{Icode|UriMapper}} would look like this in our case
+
{{Tip|Don't forget to document your app URI scheme and include it in our [[URI Association Schemes List]].}}
 +
 
 +
Developers can also create and use protocols that are intended for general "classes" of apps. For example, developers of Calendar apps might agree a common protocol, and allow end-users to determine what app they choose to download or use as the handler. Note that there is nothing to stop developers using any protocol that isn't reserved for the default apps/operating system.
 +
 
 +
== How to detect that your user launched the app from the URI association ==
 +
You will have to implement a custom {{Icode|UriMapper}} that will parse the {{Icode|Uri}} at the launch of your application and try to detect the source. Following the sample provided above, the {{Icode|UriMapper}} would look like this in our case:
  
 
<code csharp>
 
<code csharp>
Line 66: Line 83:
 
             tempUri = System.Net.HttpUtility.UrlDecode(uri.ToString());
 
             tempUri = System.Net.HttpUtility.UrlDecode(uri.ToString());
 
             // URI association launch for my app detected
 
             // URI association launch for my app detected
             if (tempUri.Contains("myappuri:MainPage.xaml?Category="))
+
             if (tempUri.Contains("myappuri:MainPage?Category="))
 
             {
 
             {
 
                 // Get the category (after "Category=").
 
                 // Get the category (after "Category=").
Line 80: Line 97:
 
</code>
 
</code>
  
One more step to ensure that your application will use your new {{Icode|UriMapper}}, go to '''App.xamls.cs''' file in the {{Icode|InitializePhoneApplication()}} method and add this line
+
One more step to ensure that your application will use your new {{Icode|UriMapper}}, go to '''App.xamls.cs''' file in the {{Icode|InitializePhoneApplication()}} method and add this line:
 +
 
 
<code csharp>
 
<code csharp>
 
RootFrame.UriMapper = new AssociationUriMapper();
 
RootFrame.UriMapper = new AssociationUriMapper();
 
</code>
 
</code>
  
Your app will now try to detect if it was launched from the normal way or from uri association, and in this case it will parse the parameters provided and redirect to the proper page.
+
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 retrieve 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:
 +
 
 +
<code csharp>
 +
protected override void OnNavigatedTo(NavigationEventArgs e)
 +
{
 +
    if (NavigationContext.QueryString.ContainsKey("Category"))
 +
    {
 +
        Category = int.Parse(NavigationContext.QueryString["Category"]);
 +
    }
 +
    base.OnNavigatedTo(e);
 +
}
 +
</code>
  
 
== What will and will not work ==
 
== What will and will not work ==
Disclamer, this is based on personnal experimentation. I do not say that all of this will never worked but from what I was able to test it is currently not working.
+
{{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: ===
+
=== What will trigger your URI association and launch your app: ===
*Get the uri from NFC tag
+
*Get the URI from NFC tag.
*Get the uri by mail
+
*Get the URI by mail.
*Click on a html link containing the uri
+
*Click on a HTML link containing the URI.
*Webpage redirection with a custom protocol
+
*Webpage redirection with a custom protocol.
 +
*Get the URI from NFC device sharing an URI (e.g. {{Icode|PublishUriMessage(Uri)}} from {{Icode|ProximityDevice}}).
  
=== What will '''NOT''' trigger your uri association and launch your app: ===
+
=== What will '''NOT''' trigger your URI association and launch your app ===
*Enter directly the uri in the webbrowser
+
*Enter directly the URI in the Web Browser.
*Get the uri by SMS
+
*Scan a QR code from Bing search.
*Scan a QR code from bing search
+
  
== Reference ==
+
=== What MAY trigger your URI association and launch your app ===
[http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj206987(v=vs.105).aspx Official documentation about uri associations on MSDN]
+
*Get the URI by SMS. It seems to depend on the uri your registered and could be connected to its length
  
[http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj207065(v=vs.105).aspx Reserved files and uri associations]
+
== What if many applications registered the same name ==
 +
 
 +
In this case the user will be prompted to select which application he want to launch
 +
 
 +
<gallery widths="240px" heights="400px">
 +
File:ChooseApp.png|App Chooser Windows
 +
</gallery>
 +
 
 +
== Inter-app communication ==
 +
 
 +
URI associations can also be used to provide a simple form of inter-app communication. Two apps that register URI associations could send each other messages in their respective URI association parameters (typically apps use URI parameters to choose what page or information to display, but their usage is completely app dependent and could be used for messaging). The [[Media:appcommunication.zip |code example]] shows how this can be done with two apps sending text and displaying it in each other's UI. Note that the launching process will request to install the other app is installed if it has not been.
 +
 
 +
For this to work correctly it is necessary that communicating apps share a common protocol. A more generalised approach might be to define a "standard" protocol for messaging, or for querying other apps about what messaging protocols they support (ie send them a message with "tell me your protocols" and parse the response"). This would allow arbitrary communications with apps that support a set of protocols.
 +
 
 +
== 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 add the scheme to the [[URI Association Schemes List]] to advertise it to other developers.
 +
 
 +
== Code sample ==
 +
[[Media:UriAssociation.zip|UriAssociation.zip]]
 +
 
 +
[[Media:appcommunication.zip|appcommunication.zip]]  Code sample for section 'Inter-app communication'
 +
 
 +
== Reference ==
 +
* [http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj206987(v=vs.105).aspx Official documentation about URI associations on MSDN]
 +
* [http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj207065(v=vs.105).aspx Reserved files and URI associations]
 +
* [http://de.slideshare.net/nokia-developer/lumia-app-labs-developing-windows-phone-8-apps-with-file-and-uri-associations LUMIA APP LABS: DEVELOPING WINDOWS PHONE 8 APPS WITH FILE AND URI ASSOCIATIONS]
 +
* [http://code.msdn.microsoft.com/wpapps/URI-Association-Sample-7915a233 Windows Phone DevCenter URI Association Sample]

Revision as of 02:54, 4 July 2013

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 File.png
WP Metro Icon NFC.png
SignpostIcon XAML 40.png
WP Metro Icon WP8.png
Article Metadata
Code ExampleCompatibility
Platform(s): Windows Phone 8
Windows Phone 8
Article
Keywords: Custom URI
Created: MaMi (28 Nov 2012)
Last edited: hamishwillee (04 Jul 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.

What URI scheme should I use?

To ensure you don't accidentally re-use a URI reserved by the operating system or default applications or a URI registered to another third party app, we recommend you include your company and app name in your URI as shown (see Designing URI scheme handlers for more detail):

<companyName>-<nameOfApp>

Tip.pngTip: Don't forget to document your app URI scheme and include it in our URI Association Schemes List.

Developers can also create and use protocols that are intended for general "classes" of apps. For example, developers of Calendar apps might agree a common protocol, and allow end-users to determine what app they choose to download or use as the handler. Note that there is nothing to stop developers using any protocol that isn't reserved for the default apps/operating system.

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 retrieve 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.pngNote: 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

Inter-app communication

URI associations can also be used to provide a simple form of inter-app communication. Two apps that register URI associations could send each other messages in their respective URI association parameters (typically apps use URI parameters to choose what page or information to display, but their usage is completely app dependent and could be used for messaging). The code example shows how this can be done with two apps sending text and displaying it in each other's UI. Note that the launching process will request to install the other app is installed if it has not been.

For this to work correctly it is necessary that communicating apps share a common protocol. A more generalised approach might be to define a "standard" protocol for messaging, or for querying other apps about what messaging protocols they support (ie send them a message with "tell me your protocols" and parse the response"). This would allow arbitrary communications with apps that support a set of protocols.

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 add the scheme to the URI Association Schemes List to advertise it to other developers.

Code sample

UriAssociation.zip

appcommunication.zip Code sample for section 'Inter-app communication'

Reference

1005 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×