How to integrate with App Instant Answer for Windows Phone 8

May 10, 2014

Applies to: Windows Phone 8 and Windows Phone Silverlight 8.1 | Windows Phone OS 7.1

 

Starting with Windows Phone OS 7.1, your Windows Phone app can be launched from App Instant Answer. App Instant Answer presents a link to relevant Windows Phone apps with search results. If launched from App Instant Answer, your app can determine the search terms that lead to the launch, and immediately use those terms to provide a rich user experience based on those terms.

This topic describes how to create a basic app that determines if it was launched by App Instant Answer, what the corresponding search terms were, and how to simulate an App Instant Answer launch. For information about other ways to integrate your app with the search experience, see Search extensibility for Windows Phone 8.

This topic covers the following major steps:

  1. Creating the UI

  2. Checking for an App Instant Answer launch

  3. Completing the app

  4. Simulating an App Instant Answer launch

In this section, you create a basic UI to display the App Instant Answer parameter and value, or a message stating that the app wasn’t launched by App Instant Answer. The corresponding TextBlock controls are collapsed or made visible depending on how the app is launched.

To create the UI

  1. Open the Windows Phone SDK and create a new project using the Windows Phone App  template.

  2. After the new project loads, in the MainPage.xaml file, replace the grid named LayoutRoot with the following code.

        <!--LayoutRoot is the root grid where all page content is placed-->
        <Grid x:Name="LayoutRoot" Background="Transparent">
            <Grid.RowDefinitions>
                <RowDefinition Height="Auto"/>
                <RowDefinition Height="*"/>
            </Grid.RowDefinitions>
    
            <!--TitlePanel contains the name of the application and page title-->
            <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,28">
                <TextBlock 
                    x:Name="ApplicationTitle" 
                    Text="APP INSTANT ANSWER EXAMPLE" 
                    Style="{StaticResource PhoneTextNormalStyle}"/>
                <TextBlock 
                    x:Name="PageTitle" 
                    Text="URI details" 
                    Margin="9,-7,0,0" 
                    Style="{StaticResource PhoneTextTitle1Style}"/>
    
                <!-- Made visible when app is launched by App Instant Answer, otherwise collapsed. -->
                <TextBlock
                    x:Name="txtUriParameterName"
                    Text="bing_query" 
                    TextWrapping="Wrap" 
                    Style="{StaticResource PhoneTextExtraLargeStyle}"
                    Visibility="Collapsed"/>
                <TextBlock
                    x:Name="txtUriParameterValue"
                    Text="URI parameter value here" 
                    TextWrapping="Wrap" 
                    Style="{StaticResource PhoneTextAccentStyle}"
                    Visibility="Collapsed"/>
    
                <!-- Made visible when app is not launched by App Instant Answer, otherwise collapsed. -->
                <TextBlock
                    x:Name="txtNoLaunch"
                    Text="This app was not launched by an App Instant Answer." 
                    TextWrapping="Wrap" 
                    Style="{StaticResource PhoneTextSubtleStyle}"
                    Visibility="Collapsed"/>
                
            </StackPanel>
        </Grid>
    
    

    The TextBlock controls named txtUriParameterName and txtUriParameterValue display the App Instant Answer URI parameter name and value, respectively. The value corresponds to the search terms that lead to the app launch. The TextBlock named txtNoLaunch displays a message indicating that App Instant Answer didn’t launch the app.

  3. In the code-behind file for the main page, MainPage.xaml.cs, add the following code to the MainPage constructor.

                // Configure event handler for page Loaded event.
                this.Loaded += new RoutedEventHandler(MainPage_Loaded);
    
    

    When the page loads, it calls the MainPage_Loaded event, a method created in the next step.

In this section, you add code to check the launch URI for the presence of the bing_query URI parameter. If bing_query is present, the app was launched from App Instant Answer. If not, it was a standard app launch.

To check for an App Instant Answer launch

  • In MainPage.xaml.cs, add the following code to the MainPage class.

            void MainPage_Loaded(object sender, RoutedEventArgs e)
            {
                try
                {
                    // Try to obtain App Instant Answer URI parameter & value.
                    string tempSearchTerms = NavigationContext.QueryString["bing_query"];
    
                    // Show App Instant Answer URI parameter and value.
                    ShowUriParameter(tempSearchTerms);            
                }
                catch
                {
                    // Hide App Instant Answer URI parameter and value.
                    HideUriParameter();
                }
            }
    
    

    If the bing_query parameter is present in the launch URI, the call to the NavigationContext QueryString returns the search terms that lead to the launch. ShowUriParameter and HideUriParameter are helper methods that are created in the next step.

In this section, you create the helper methods that collapse UI elements or make them visible. These methods are called depending on how the app was launched.

To complete the app

  • In MainPage.xaml.cs, add the following code to the MainPage class.

            void ShowUriParameter(string searchTerms)
            {
                // Hide message that app was not launched by App Instant Answer.
                txtNoLaunch.Visibility = Visibility.Collapsed;
    
                // Show URI parameter and value.
                txtUriParameterName.Visibility = Visibility.Visible;
                txtUriParameterValue.Visibility = Visibility.Visible;
                txtUriParameterValue.Text = searchTerms;
            }
    
            void HideUriParameter()
            {
                // Show message that app was not launched by App Instant Answer.
                txtNoLaunch.Visibility = Visibility.Visible;
    
                // Hide URI parameter and value.
                txtUriParameterName.Visibility = Visibility.Collapsed;
                txtUriParameterValue.Visibility = Visibility.Collapsed;
            }
    
    

In this section, you modify the app manifest file to simulate an app launch from App Instant Answer. Simulating an App Instant Answer launch is required because it isn’t possible to control when App Instant Answer displays Windows Phone apps with search results.

NoteNote:

You must submit your app to the Windows Phone Store before App Instant Answer can feature your app with search results.

To simulate an App Instant Answer launch

  1. Open the app manifest file: In Solution Explorer, expand Properties to locate the WMAppManifest.xml file. Then right-click the file name, click Open with, and select XML (Text) Editor.

  2. In the app manifest file, WMAppManifest.xml, comment the DefaultTask element. This element specifies a standard app launch.

  3. In WMAppManifest.xml, add the following code to the Tasks element.

          <!-- To simulate App Instant Answer launch from search terms "Xbox 360 4 GB Console with Kinect" -->
          <DefaultTask  Name ="_default" NavigationPage="MainPage.xaml?bing_query=Xbox+360+4+GB+Console+with+Kinect"/>
    
    

    This DefaultTask element simulates an App Instant Answer launch from a Bing search on the terms “Xbox 360 4 GB Console with Kinect”.

    Caution noteCaution:

    Uncomment the original DefaultTask element when you are finished debugging so that your app can perform a standard launch. Commenting this element prevents real App Instant Answer launches from working properly. Only one DefaultTask element can be present at a time.

  4. Press F5 to debug your app and deploy it to the emulator or device.

  5. Observe that the app launches to the main page and displays the bing_query parameter and the search terms specified in the DefaultTask element.

  6. In WMAppManifest.xml, comment the temporary DefaultTask element and uncomment the original. When finished, the Tasks element should look like the following code.

        <Tasks>
          <DefaultTask  Name ="_default" NavigationPage="MainPage.xaml"/>
          
          <!-- To simulate App Instant Answer launch from search terms "Xbox 360 4 GB Console with Kinect" -->
          <!--<DefaultTask  Name ="_default" NavigationPage="MainPage.xaml?bing_query=Xbox+360+4+GB+Console+with+Kinect"/>-->
        </Tasks>
    
    
  7. Press F5 to debug your app and deploy it to the emulator or device.

  8. Observe that the app launches to the main page and displays the message for a standard launch.

Show:
© 2014 Microsoft