Search extensibility for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This topic describes how your app can extend the Search experience on Windows Phone. The goal of Search extensibility is to save users time. Users that search the web with the Search button can launch a relevant page in your app directly from Bing search results and quick cards. For example, when launched from a product card, your app could automatically provide details about a product that your user was searching for. For a step-by-step example of using Search extensibility, see How to extend the Search experience for Windows Phone 8.

Important Note:
Apps that abuse Search extensibility risk being pulled from the Windows Phone Store. Register only for search extensions that are relevant to your app. To learn more about which extensions Bing associates with various quick cards, experiment with the Quick Card Sample.

This topic contains the following sections.

• Integrating with search result items
• Search extensibility architecture
• Development overview
• Global availability
• App Instant Answer
• Debugging on Windows Phone
• Related Topics

Integrating with search result items

Search results on Windows Phone include detailed quick cards. Each quick card contains information that your app can use to extend the search experience. The particular information that a quick card contains depends on the type of search that is performed. There are four classes of quick cards:

• Places: locations listed in the local pivot page of search results

• Products: items listed under the products heading in the web pivot page of search results

• Movies: movies currently playing in theaters listed under the “Movies near…” heading in the web pivot page of search results

• Events: events listed on the see+do pivot page of Local Scout (event cards are available only in Windows Phone 8)

In each quick card, data about the search result is displayed. This includes content like photos, descriptions, ratings, reviews, and some item-specific data like price comparisons in the Product card or the duration of a movie in theaters in the Movie card.

Each quick card includes a pivot page that is named apps. This pivot page is dedicated to apps that extend the search experience. These apps can provide a rich user experience by providing functionality that is uniquely based on information from the quick card.

The following image shows an example of navigating from Bing search results to the Search Extensibility Sample app.

In this example, the user taps the hardware Search button and searches for “baby doll strollers”. Bing returns results from the web, including a list of products in the web pivot page. Next the user chooses a stroller from the list of products. That launches a Products quick card for the particular stroller. The stroller’s quick card has multiple pivot pages, including about and apps. In the apps pivot page, the app that extends Search for that type of product appears. When the user clicks the icon for the app, the app launches, providing the user with a rich experience based on the quick card details for the stroller.

Search extensibility architecture

Using Search extensibility with your app involves your WMAppManifest.xml app manifest file, an Extras.xml file, and at least one app page to receive a deep link URI from the search result quick card. This is summarized in the following diagram.

Search extensions

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 to describe an item that is featured by a quick card. The WMAppManifest.xml file is used to specify the extensions that are relevant to your app. How these extensions are specified is described in the following sections.

The extensions specified in the WMAppManifest.xml are used by Bing to ensure that the appropriate apps are surfaced to end users from quick cards. It is important that your app specifies only extensions that are relevant. Apps that abuse Search extensibility risk being pulled from the Store.

For example, if your app is relevant to automotive products, the Bing_Products_Car_and_Garage extension could be used to extend related product cards. An app that is relevant to technology businesses 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 isn’t relevant to your app, don’t specify it in the WMAppManifest.xml file.

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

Surfacing relevant apps to quick cards

To surface relevant apps in the apps pivot page of a quick card, your app needs to register with the search functionality on the device to specify the extensions that are relevant to the app. 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 app supports. For example, specifying the extension named Bing_Products_Baby_and_Nursery would indicate that your app is relevant to quick cards related to baby and nursery products.

• App Title (Windows Phone OS 7.1 only): In the Extras.xml file, the AppTitle element is used to specify the title of the app, as you would like it to appear in the apps pivot page of the quick card. With Windows Phone 8, the app title from the Apps list is used instead.

• 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 app title. You can group each caption string with a single extension that the app has registered for in the app manifest.

When a quick card is invoked, your app 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.

Launching apps from a quick card

When your app is launched from a quick card, information about the quick card is passed to your app via a deep link URI. Deep linking allows navigation to a specific page in your app. 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, PhoneNumber, and Category. For more information, see Search registration and launch reference for Windows Phone 8.

Development overview

To prepare your app to use Search extensibility, you need to perform the following steps:

1. Register Search extensions: Update your app manifest file to specify the extensions that are relevant to your app.

2. Specify captions: Create an 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 app.

3. Map the URI from the Quick Card: Navigate the search experience from the quick card deep link URI to the appropriate landing page in your app.

4. Handle app launch: Extract the quick card parameters from the deep link URI and help the user complete their task.

5. Test your App icon: Confirm that your app icon appears in the apps pivot page with a light or dark theme; avoid using a transparent background in your ApplicationIcon.png file.

These steps are discussed in greater detail in the following sections of this topic.

1. Register Search extensions

Use the XML (Text) Editor to edit the app manifest file, WMAppManifest.xml; the Windows Phone Manifest Designer does not support extensions. For more info, see How to modify the app manifest file for Windows Phone 8.

After you open the app manifest file, 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 app. The values specified inside these elements are used to register with the search functionality on the device when the app is installed. For more details about the available extensions, see Search registration and launch reference for Windows Phone 8.

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 app 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>

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

• ExtensionName: Specifies the name of the extension that the app 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 app manifest file, see App manifest file for Windows Phone 8.

2. Specify captions

Next, create an XML file named Extras.xml in a folder named Extensions. Use the Extras.xml file to specify the app title and caption that will appear in the apps pivot page for each of the extensions that are relevant to your app.

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

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

  <!-- App title (used only with Windows Phone OS 7.1) -->
  <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>
      </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_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 extension named Bing_Products_Computing. The second caption is for electronic products that are relevant to the extension named 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 can’t be referenced from a resource file.

The Extras.xml file comprises these elements:

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

• AppTitle (used only in Windows Phone OS 7.1): 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 a single extension.

• ExtensionName: The name of the extension associated with the caption specified in the CaptionString element. The extension listed here must also be listed in WMAppManifest.xml. Don’t specify the same extension name in more than one ExtensionInfo element. This prevents your app from appearing on a quick card.

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

• default (and the language-local element): 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 overrides the default string.

You can specify up to 50 captions in Extras.xml, for a maximum of 50 ExtensionInfo elements. Each ExtensionInfo element may contain no more than one ExtensionName element. The same CaptionString element (having the same caption text) can be used in more than one ExtensionInfo element, but an extension specified in an ExtensionName element can’t appear multiple times. Each extension can appear only once in the ExtrasInfo element.

3. Map the URI from the quick card

When your app is launched from the apps pivot page of a quick card, a deep link URI used to navigate to your app. Because all deep link URIs for Search follow the same format and don’t include the name of your app page, you must direct navigation from the quick card to the appropriate page in your app.

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

/SearchExtras?MovieName=The+Trey+Research+Company&ReleaseDate=129836124000000000&Category=Bing_Movies

To map a deep link URI to a page in your app, 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 app. 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 the Search experience for Windows Phone 8.

After you create a URI mapper class for your app, assign it to the frame of the app in the App.xaml.cs file. The following example shows how to assign the QuickCardUriMapper class, from the Quick Card Sample, to the app 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.

4. Handle app launch

After you map Search extensibility deep links to a particular page in your app, 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 app parses the parameters from the deep link URI during the page’s Loaded event. For a step-by-step example, see How to extend the Search experience for Windows Phone 8.

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 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 deep link URIs from quick cards, it is important to consider the following points:

• During an app launch, the default task is the only task invoked on the page.

• All quick card parameters are optional. Prepare your app 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.

5. Test your app icon

Test your app icon in the apps pivot page. When your app is displayed in the apps pivot page of a quick card, an accent-colored square isn’t placed behind your app icon (the app 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 app icon.

For example, an app icon featuring an all-white symbol on a transparent background disappears 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 app icon for the app named sdkSearchExtensbility has a white image with a transparent background. 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 isn’t visible in the apps pivot page of the quick card when the white theme is used.

Global availability

To extend the search experience, the following must be present in the market corresponding to the device Browser & search language setting:

• **Windows Phone Store **: Store must be available so that it can feature and sell your app.

• Bing Quick Cards: The applicable quick card must be available so that it can display your app in the apps pivot page.

Bing uses the Browser & search language setting to determine which market is applicable to the device. This is specified in Settings, on the region+language page.

At the time of writing, Store and quick cards aren’t available in all markets. The following table lists the markets that have both a Windows Phone Store and one or more quick cards. For the most up-to-date list of Windows Phone markets, see Regional info.

App Instant Answer

App Instant Answer, introduced with Windows Phone OS 7.1, displays links to Windows Phone apps with search results for apps that are relevant to search terms. No registration of extension details are required for an app to appear in search results. If your app is launched from App Instant Answer, you can parse the launch URI to determine the query that corresponds to the launch. For more information about integrating your app with App Instant Answer, see How to integrate with App Instant Answer for Windows Phone 8.

The following image shows how App Instant Answer displays a link to a relevant app with search results.

In this example, App Instant Answer displays a link to the Xbox LIVE Extras Windows Phone app with the search results for an “xbox” search. All App Instant Answer launches navigate to the main page of your app, as they would in a standard app launch. You can’t specify a different navigation target.

The deep link URI from an App Instant Answer launch includes only one parameter, named bing_query. The following example shows a launch URI from an App Instant Answer (when the default navigation page is set to MainPage.xaml). In this example, the user was searching for “fun game”.

/MainPage.xaml?bing_query=fun+game

Debugging on Windows Phone

The Windows Phone Emulator for Windows Phone OS 7.1 (Emulator 7.1) breaks from the debugging process when an app is relaunched. To debug a Search extensibility or App Instant Answer launch, you need to simulate the navigation URI. To do this, temporarily edit the DefaultTask element in your app manifest file, WMAppManifest.xml.

This debugging limitation doesn’t apply to Windows Phone 8 apps. When debugging a Windows Phone 8 app, you can set breakpoints in the URI mapper and use the debugging tools to examine the contents of the deep link URI. Although simulating a search extensibility launch isn’t necessary in Windows Phone 8, you may want to use it as a convenient way to launch your app with a specific URI.

Simulating a quick card launch

In this example, the WMAppManifest.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 a deep link URI for a Movie quick card.

<!--<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 app on Windows Phone OS 7.1 section in How to extend the Search experience for Windows Phone 8.

Simulating an App Instant Answer launch

In this example, the WMAppManifest.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 8.

See Also

Other Resources

Search registration and launch reference for Windows Phone 8

How to extend the Search experience for Windows Phone 8

How to integrate with App Instant Answer for Windows Phone 8

Quick Card Sample

Search Extensibility Sample