Search Extensibility Overview for Windows Phone

Within each class of search results, a quick card is associated with one or more categories, referred to as extensions. Extensions provide a more granular way of describing an item. The WMAppManifest.xml and Extras.xml files are used to specify the extensions that are relevant to your application. How these extensions are specified is described in the following sections.

The extensions specified in the WMAppManifest.xml and Extras.xml files are used by Bing to ensure that the appropriate applications are surfaced to end users from quick cards. It is important that your application specifies only extensions that are relevant. Applications that abuse App Connect risk being pulled from the Marketplace.

For example, if your application is relevant to automotive products, the Bing_Products_Car_and_Garage extension could be used to extend related product cards. An application that is relevant to technology companies could use the Bing_Places_Computers_and_Technology extension to extend related place cards. There is only one extension for movies playing in theaters; use Bing_Movies to extend the movie card. If an extension is not relevant to your application, do not specify it in the WMAppManifest.xml and Extras.xml files.

Tip:
Applications relevant to movies that are no longer in theaters can use the Bing_Products_Movies extension.

To gain a better understanding of which extensions Bing associates with various search terms, experiment with the Quick Card Sample application. For example, if you navigate to a place card for a restaurant near you, the Quick Card Sample will appear in the corresponding apps pivot page (the Quick Card Sample must be installed on your device or emulator). If you tap on the application, it will launch and display the corresponding extension under the Category heading, Bing_Places_Food_and_Dining. For more information about how to use this application with the various types of quick cards, see the sample Readme.htm file.

Note:

To aid application development and enable discovery, the Quick Card Sample registers for all possible extensions. Doing so allows you to view the URI parameters for most quick cards. However, because this sample registers for all possible extensions, it would not likely pass application certification. For an example that demonstrates how to use search extensions in an appropriately limited fashion, see the Search Extensibility Sample.

To surface relevant applications in the apps pivot page of a quick card, your application needs to register with the search functionality on the device to specify the extensions that are relevant to the application. During registration, the following details are specified:

• Extensions: In the WMAppManifest.xml file, the Extensions element is used to list each extension, a category of quick card that the application supports. For example, specifying the extension named Bing_Products_Baby_and_Nursery would indicate that your application is relevant to quick cards related to baby and nursery products.

• Application Title: In the Extras.xml file, the AppTitle element is used to specify the title of the application, as you would like it to appear in the apps pivot page of the quick card.

• Captions: In the Extras.xml file, the CaptionString element is used to specify a caption that you would like to appear in the apps pivot page, below the application title. You can group each caption string with multiple extensions that the application has registered for in the application manifest.

When a quick card is invoked, your application will appear in the quick card’s apps pivot page if it has registered for any of the same extensions that are associated with the quick card.

When your application is launched from a quick card, information about the quick card is passed to your application via a deep link URI. Deep linking allows navigation to a specific page in your application. Parameters in the deep link URI contain the quick card details, which vary depending on the type of quick card.

For example, a deep link URI for a Place quick card (a place card) contains the parameters PlaceName, PlaceLatitude, PlaceLongitude, PlaceAddress, and Category. For more information, see Search Registration and Launch Reference for Windows Phone.

Use the application manifest file, WMAppManifest.xml, to specify the extensions that are relevant to your application. Add an element named Extensions as the last child element in the App element. Inside an Extensions element, add an Extension element for each category that is relevant to your application. The values specified inside these elements are used to register with the search functionality on the device when the application is installed. For more details about the available extensions, see Search Registration and Launch Reference for Windows Phone.

The following example shows an excerpt from a WMAppManifest.xml file that registers for four different extensions. Note that this combination of extensions would be appropriate only for an application that is relevant to computing, software, video game, and electronics products.

    <Extensions>
      <!-- Product extensions for an application relevant to computing, electronics, software, and video game products. -->
      <Extension ExtensionName="Bing_Products_Computing" ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5661}" TaskID="_default" ExtraFile="Extensions\\Extras.xml" />
      <Extension ExtensionName="Bing_Products_Electronics" ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5661}" TaskID="_default" ExtraFile="Extensions\\Extras.xml" />
      <Extension ExtensionName="Bing_Products_Software" ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5661}" TaskID="_default" ExtraFile="Extensions\\Extras.xml" />
      <Extension ExtensionName="Bing_Products_Video_Games" ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5661}" TaskID="_default" ExtraFile="Extensions\\Extras.xml" />
    </Extensions>

Note:
For a list of all available search extensions, see Search Registration and Launch Reference for Windows Phone.

Each Extension element uses the following four attributes to describe the extension:

• ExtensionName: Specifies the name of the extension that the application supports. An extension is a specific category of search results.

• ConsumerID: Identifies that the extension is for extending search. All search extensions require the same value, 5B04B775-356B-4AA0-AAF8-6491FFEA5661.

• TaskID: Corresponds to the name of the default task that is specified in the Tasks element of the same file. Usually this value is _default.

• ExtraFile: The location of the Extras.xml file. The file must reside in a folder Extensions and be named Extras.xml.

For more information about the application manifest file, see Application Manifest File for Windows Phone.

Next, create an XML file named Extras.xml in a folder named Extensions. Use the Extras.xml file to specify the captions that will appear in the apps pivot page for each of the extensions that are relevant to your application. Add an AppTitle element to specify the application title in the languages that it supports. Add a Consumer element to group the search extension details. Inside that element, add an ExtensionsInfo element for each caption that you want to specify. Inside that element, the Extensions element lists the extensions applicable to the caption described in the corresponding CaptionString element.

The following example shows an Extras.xml file that specifies two captions.

<?xml version="1.0" encoding="utf-8" ?>
<ExtrasInfo>
  
  <!-- Application title-->
  <AppTitle>
    <default>Sample for Product Results</default>
    <fr-FR>Exemple pour les Produits</fr-FR>
  </AppTitle>

  <!-- Search-related captions -->
  <Consumer ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5661}">

    <!-- Computer products caption -->
    <ExtensionInfo>
      <Extensions>
        <ExtensionName>Bing_Products_Computing</ExtensionName>
        <ExtensionName>Bing_Products_Software</ExtensionName>
      </Extensions>
      <CaptionString>
        <default>Research computer product details</default>
        <fr-FR>Recherche retraits d’ordinateurs</fr-FR>
      </CaptionString>
    </ExtensionInfo>

    <!-- Electronics products caption -->
    <ExtensionInfo>
      <Extensions>
        <ExtensionName>Bing_Products_Video_Games</ExtensionName>
        <ExtensionName>Bing_Products_Electronics</ExtensionName>
      </Extensions>
      <CaptionString>
        <default>Research electronics product details</default>
        <fr-FR>Recherche retraits d’électronique</fr-FR>
      </CaptionString>
    </ExtensionInfo>

  </Consumer>
</ExtrasInfo>

In this example, the first caption is for computer products that are relevant to the extensions named Bing_Products_Computing and Bing_Products_Software. The second caption is for electronic products that are relevant to the extensions named Bing_Products_Video_Games and Bing_Products_Electronics. Each caption specifies a default text string and a French text string.

Important Note:
Because the Extras.xml file can contain localized strings, it must be UTF-8 encoded. All strings must be present within the file; strings cannot be referenced from a resource file.

The Extras.xml file comprises these elements:

• ExtrasInfo: The root of all Extras.xml files.

• AppTitle: Contains the default and localized strings representing the title of the application, as it will appear in the apps pivot page. Only one AppTitle element is allowed.

• ConsumerID: Must correspond to the search extensions value, 5B04B775-356B-4AA0-AAF8-6491FFEA5661.

• ExtensionInfo: Groups a caption with one or more extensions.

• ExtensionName: The name of the extension associated with the caption specified in the CaptionString element. Extensions listed here must match the extensions in WMAppManifest.xml.

• CaptionString: Specifies the default and localized caption strings for the caption associated with the extensions in the Extensions element.

Note:
A default string, specified by the default element, is required for each caption. Localized strings are optional. When specified and used in the corresponding language-locale, a localized string will override the default string.

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.

When your application is launched from the apps pivot page of a quick card, a deep link URI used to navigate to your application. Because all App Connect deep link URIs for search follow the same format and do not include the name of your application page, you must direct navigation from the quick card to the appropriate page in your application.

For example, the following demonstrates an App Connect deep link URI sent from a movie card for a fictitious movie titled “The Trey Research Company”:

/SearchExtras?MovieName=The%20Trey%20Research%20Company&Category=Bing_Movies

To map an App Connect URI to a page in your application, we recommend that you create your own URI-mapper class based on the URIMapperBase class (in the System.Windows.Navigation namespace). In the URI-mapper class, override the MapUri method to map incoming URIs to pages in your application. We also recommend that you re-encode each of the URI parameter values to handle any special characters that could be sent from the quick cards. For more information, see How to: Extend Search with App Connect for Windows Phone.

After you create a URI-mapper class for your application, assign it to the frame of the application in the App.xaml.cs file. The following example shows how to assign the QuickCardUriMapper class, from the Quick Card Sample, to the application frame.

// Assign the quick card URI-mapper class to the application frame.
RootFrame.UriMapper = new QuickCardUriMapper();

For examples that show the QuickCardUriMapper class in use, see the Quick Card Sample and Search Extensibility Sample.

After you map App Connect deep links to a particular page in your application, you need to add code to the corresponding page to extract the quick card parameters from the deep link URI. To extract the quick card parameters, use the QueryString property from the NavigationContext object of the page. This property is a dictionary of key/value pairs representing each of the parameters and their values. Typically, an application will parse the parameters from the deep link URI during the page’s Loaded event. For a step-by-step example, see How to: Extend Search with App Connect for Windows Phone.

The following code shows an example of an event-handling method for the page Loaded event that searches for the ProductName parameter in the URI.

private void ItemPage_Loaded(object sender, RoutedEventArgs e)
{
    // Temporary text for the product name in the URI, if available   
    string productName = "Product not found";

    // Flag to indicate whether the application contains information
    // for the product specified by the ProductName parameter
    bool productFound = false;

    // Loop through the App Connect parameters in the URI.
    foreach (string strKey in this.NavigationContext.QueryString.Keys)
    {
        // Look for the "ProductName" parameter.
        if (strKey == "ProductName")
        {
            // Extract the value of the ProductName parameter. 
            string tempName = this.NavigationContext.QueryString[strKey];

            // See whether the app contains information for the product.
            // Return true if information is found, and false if not.
            if (FindProduct(tempName))
            {
                // If found, replace the temporary text with 
                // the product name and set the flag to true.
                productName = tempName;
                productFound = true;
            }
        }
    }

    if (productFound)
    {
        // The application contains information about the product.
        // Business logic
    }
    else
    {
        // The application does not contain information about the product.
        // Business logic
    }
}

When working with App Connect deep link URIs, it is important to consider the following points:

• During an App Connect application launch, the default task is the only task invoked on the page.

• All quick card parameters are optional. Prepare your application to handle a subset of the possible parameters from a quick card.

• Parameter names are case-sensitive.

• Parameter values may contain spaces.

• If a parameter contains multiple values, they are comma-delimited.

Test your application icon in the apps pivot page. When your application is displayed in the apps pivot page of a quick card, an accent-colored square is not placed behind your application icon (the application icon corresponds to the ApplicationIcon.png file in your project). To ensure that it appears with a light or dark theme, avoid transparency in your application icon.

For example, an application icon featuring an all-white symbol on a transparent background will disappear in the apps pivot page when a light theme is used, regardless of the accent color. This is shown in the following image.

In this example, the application icon for the application named sdkSearchExtensbility has a white image with a transparent background. The corresponding App Connect title for this application is Trey Research Product Recalls. Because the accent color is red, the icon appears with a red background in the system-wide apps page. While some of the icon can be seen in the dark theme, it is not visible in the apps pivot page of the quick card when the white theme is used.

In this example, the WPAppManifest.xml file is temporarily edited. The DefaultTask element navigating to the main page is commented and a DefaultTask element is added, showing an App Connect deep link URI for a Movie quick card.

Note:
To conform to XML standards in the application manifest file, the ampersand symbol used to separate App Connect URI parameters is replaced with “&amp”. When your application starts, before the URI is used, “amp” is removed from the URI.

<!--<DefaultTask  Name ="_default" NavigationPage="MainPage.xaml"/>-->
<DefaultTask Name="_default" NavigationPage="SearchExtras?MovieName=Test&amp;Category=Bing_Movies" />

For more information about how to do this, see the Debugging the Application section in How to: Extend Search with App Connect for Windows Phone.

In this example, the WPAppManifest.xml file is temporarily edited. The DefaultTask element for a standard launch to the main page is commented out and a DefaultTask element is added, showing an App Instant Answer launch URI for “XBOX 360”.

<!--<DefaultTask  Name ="_default" NavigationPage="MainPage.xaml"/>-->
<DefaultTask  Name ="_default" NavigationPage="MainPage.xaml?bing_query=XBOX 360"/>

For more information about how to do this, see the Simulating an App Instant Answer Launch section in How to: Integrate with App Instant Answer for Windows Phone.