Registering your WP7 app with Bing Search Extras

A handy new feature coming in the Mango update for WP7 devices is the Search Extras. Essentially it allows a developer to deeply integrate his application with the phones experience. The video below will give you a quick overview of how to do it, but they skip over some relevant information.

Lets assume that you want to integrate a Craigslist applition in with the search results. From a high level you need to put which extensions you support in you WMAppManifest.xml, add an Extras.xml file with more metadata, and set up URI Mapping in your app. I feel like it is more work than I should have to do, but the tools are still beta, and they could change. Either way it is still pretty easy.

WMAppManifest.xml

There are four kinds of extensions you can subscribe to, and many differnet categories in each kind. Listing them all here would take too much room, so I'll just point you to the page. Keep in mind each set has different launch parameters, and you cannot change them. I'll get to that later.

Once you know what extensions you are going to subscribe to, you need to add them into your WMAppManifest. There is a new Extensions element you can add to the Deployment/App node. Each extension you support gets it own entry.

<Extensions>
  <Extension
    ExtensionName="Products"
    ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5661}"
    TaskID="_default"
    ExtraFile="Extensions\\Extras.xml" />
  <Extension
    ExtensionName="Bing_Products_Movies"
    ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5661}"
    TaskID="_default"
    ExtraFile="Extensions\\Extras.xml" />
</Extensions>

Here is the first thing I think needs changed. The ConsumerID node needs to be that exact guid, and the ExtraFile need to be in that location. I feel like we could omit those two nodes, and have the device infer the information. It doesn't make sense to me to have to tell it when you don't have an option to change it.

Extras.xml

Now create a folder at the root of your project called Extensions, and add an xml file called Extras.xml to it. this file contains the metadata for what your app will display when shown as a search extra. You specify what caption you want displayed next to your app for each extension.

<?xml version="1.0" encoding="utf-8"?>

<ExtrasInfo>
  <AppTitle>
    <default>Craigslist Search</default>
    <fr-FR>Craigslist recherche</fr-FR>
  </AppTitle>

  <Consumer ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5661}">     
    <ExtensionInfo>
      <Extensions>
        <ExtensionName>Bing_Products_Movies</ExtensionName>
        <ExtensionName>Bing_Products_Software</ExtensionName>
      </Extensions>
      <CaptionString>
        <default>Look for cheap movies and software on Craigslist</default>
        <fr-FR>Recherchez les films bon marchés et logiciels Craigslist</fr-FR>
      </CaptionString>
    </ExtensionInfo>

    <ExtensionInfo>
      <Extensions>
        <ExtensionName>Bing_Products_Video_Games</ExtensionName>
        <ExtensionName>Bing_Products_Toys</ExtensionName>
      </Extensions>
      <CaptionString>
        <default>Look for pre-owned games on Craigslist</default>
        <fr-FR>Recherchez les jeux neufsm Craigslist</fr-FR>
      </CaptionString>
    </ExtensionInfo>

    <ExtensionInfo>
      <Extensions>
        <ExtensionName>Products</ExtensionName>
      </Extensions>
      <CaptionString>
        <default>Look for stuff on Craigslist</default>
      </CaptionString>
    </ExtensionInfo>
  </Consumer>
</ExtrasInfo>

Once again, the ConsumerID needs to be that value. It feels odds having to include it in a second place, but that's how it goes. A few other things to note:

• you can have more than one ExtensionName per ExtensionInfo. In the sample above you will see Look for cheap movies and software on Craigslist when movies and software are displayed, but Look for pre-owned games on Craigslist is displayed when games and toys are displayed. Notice you can also specify what to show be other languages. The default one is required, but the language specific ones are optional.
• You can specify up to 50 captions in Extras.xml, for a maximum of 50 ExtensionInfo elements. Each ExtensionInfo element can contain up to 50 different ExtensionName elements.

URI Mapping

When an extra is launched from a search, it targets a specific page, and paramers. You cannot change them, but you can re-route them. In the case of a product search it will target /SearchExtras?ProductName=<product_name>&Category=<extension_names> where SearchExtras is the page, ProductName is the name of the product the selected, and Category is the category it is in. But lets say your app uses SearchResults.xaml, not SearchExtras. 

step 1: Open App.xaml and add  xmlns:nav="clr-namespace:System.Windows.Navigation;assembly=Microsoft.Phone" as a namespace directive

<Application 
    x:Class="WindowsPhoneApplication1.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"       
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone"
    xmlns:shell="clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone"
    xmlns:nav="clr-namespace:System.Windows.Navigation;assembly=Microsoft.Phone">

step 2: Add a UIRMapping resource in App.xaml. Notice the line highlighted. You need to change YourPage.xaml.

<!--Application Resources-->
    <Application.Resources>
     
        <!-- Map Search Extras deep links to Item page -->
        <nav:UriMapper x:Key="UriMapper">
            <nav:UriMapper.UriMappings>
                <nav:UriMapping Uri="/SearchExtras" MappedUri="/YourPage.xaml"/>
            </nav:UriMapper.UriMappings>
        </nav:UriMapper>
        
    </Application.Resources>

step 3: Load it in the App.cs constructor.

public App()
{
    RootFrame.UriMapper = Resources["UriMapper"] as UriMapper;
}

If you have done all of that correctly, all you have to do is configure your page to look for the given parameters. I chose to do this in the Page_Loaded event.

private void PhoneApplicationPage_Loaded(object sender, RoutedEventArgs e)
{
    string query;
    if (NavigationContext.QueryString.Keys.Contains("ProductName"))
    {
        query = NavigationContext.QueryString["ProductName"];
        SearchCraigsList(query);
    }
}

There you go. You should now see your app in the Extras section when you are looking at a category you subscribed to. I do have two more things to note.

• Right now there are Beta extensions, and Production extensions. A beta extension is broad (Product) and Production are specific (Bing_Product_Toys). As of now, I can't get the Production extensions to work, only the Beta. Also, submitting your app with Beta extensions enabled will cause it to fail certifiction. Make sure your remove it.
• The Visual Studio debugger will detach when a new instance of the app is launched. In order to debug this experience you need to trick your app into thinking it was lauched from Search Extras. In WMAppManifest.xml there is a task name _default. comment this line out and add another like the one below. This will simulate the app being launched from Search Extras.

<Tasks>
  <!--<DefaultTask  Name ="_default" NavigationPage="MainPage.xaml"/>-->
  <DefaultTask Name="_default" NavigationPage="SearchExtras?ProductName=XBox 360&Category=Bing_Products_Electronics" />
</Tasks>

Continue Reading »

An article by jkaiser No Comments