Receiving a Protocol Launch Request
,By associating your app with a particular protocol, the OS sends any launch requests that specify that protocol to your app. The OS does this by launching your app and providing a deep-link URI that may include actions encoded in the URI to be performed by your app.
It is your app’s responsibility to recognize the incoming protocol request and redirect to a page that can handle it.
Detecting a Protocol Launch
The deep-link URI that is received by your app includes a query string parameter named encodedLaunchUri. The value of this parameter is the URL that was provided to the Windows.System.Launcher. The value has two parts: a protocol name portion that comes before the colon character (:) and the payload message, which can be any text, formatted to suit the needs of your app.
For example, in the following URI, unleashed is the protocol name:
unleashed:AMessagePayloadWithSomeUsefulInformationEncoded
When your app is launched as a result of a protocol association, the app can use a URI mapping to redirect to a page designed to handle the launch request.
The App.xaml file in the WPUnleashed.FileAndProtocolAssociations has a UriMapping for the /Protocol URL that redirects to the ProtocolMessageView.xaml page. See the following excerpt:
<Application.RootVisual>
<phone:PhoneApplicationFrame
Navigated="CompleteInitializePhoneApplication"
NavigationFailed="RootFrame_NavigationFailed">
<phone:PhoneApplicationFrame.UriMapper>
<navigation:UriMapper>
<navigation:UriMapper.UriMappings>
<navigation:UriMapping Uri="/Protocol"
MappedUri="/ProtocolMessageView.xaml" />
</navigation:UriMapper.UriMappings>
</navigation:UriMapper>
</phone:PhoneApplicationFrame.UriMapper>
</phone:PhoneApplicationFrame>
</Application.RootVisual>
The entire protocol string, including the protocol name, is passed to the mapped page, ProtocolMessageView.xaml.
As you saw earlier with the FileView landing page, the ProtocolMessageView page passes the query string dictionary to its viewmodel during its OnNavigateTo method; as shown:
protected override void OnNavigatedTo(NavigationEventArgs e)
{
base.OnNavigatedTo(e);
ViewModel.Load(NavigationContext.QueryString);
}
The viewmodel’s Load method attempts to retrieve the encodedLaunchUri query string parameter as shown in Listing 30.5. It then removes the protocol name and colon that prepends the string. The viewmodel’s Message property is populated with the result.
LISTING 30.5. ProtocolMessageViewModel.Load Method
public async Task Load(IDictionary<string, string> queryStringDictionary)
{
string encodedLaunchUrl;
if (!queryStringDictionary.TryGetValue("encodedLaunchUri", out encodedLaunchUrl))
{
MessageService.ShowError(
"Unable to locate the encodedLaunchUri in the query string.");
return;
}
int messageIndex = encodedLaunchUrl.IndexOf(":") + 1;
if (messageIndex < 1)
{
MessageService.ShowError("Protocol message not found.");
return;
}
string messageContent = encodedLaunchUrl.Substring(messageIndex);
Message = messageContent;
}
With the protocol association in place and the landing page constructed, you now look at launching a protocol URI.