Create a Microsoft pubCenter Account

To create your pubCenter account, login to your Windows Phone Developer Center account and go to the Account Summary page. Under the Ad Network heading, you will see a link to create your pubCenter account. Click the link to get started.

Alternatively, you may go to http://pubcenter.microsoft.com and sign up by clicking the Sign up now button. However, you will need to be sure to go back to your Dev Center account and input your pubCenter Account number there to ensure that you properly tie the two accounts together. From the pubCenter site, click the Sign up now button as shown in Figure 14-1.

You will then be prompted for your Windows Live ID login credentials (Figure 14-2). If you do not have a Windows Live ID account, you may create one by clicking the link, “Sign up for a new Windows Live ID now.”

Upon entering your Live ID credentials on the pubCenter sign up page, click the Sign In button.

At this point, you will have the opportunity to enter information about your business. If you signed up directly on the pubcenter.com site, outside of the Developer Center Dashboard, take note of your pubCenter account ID. Login to your Windows Phone Developer Center Account, go to the Account summary page, and enter in your pubCenter account ID to associate the two accounts.

Create Application Ad Units

Once you have a pubCenter account associated with your Windows Phone Developer Center account, you can create ad units for your application within your Windows Phone Developer Center Dashboard when you initiate a new application submission. Prior to the pubCenter account integration within the Windows Phone Developer Center, you were able to register your application and create the related ad units through pubCenter, incorporate the ads in your application, and then submit your application to the Windows Phone store. This, in my opinion, seemed to follow a natural order.

Now, you will notice that you will need to “start” your application submission process before you are ready to submit your application simply to generate your ad unit Ids that you will need to include in your application. This requires you to pause the submission process, go back to your app, and incorporate the related application Id and ad unit Ids that were generated for your in-app advertisements. At that point, you can revisit your application submission to complete the process by uploading your new XAP file and related images.

To create ad units for your application, click the Submit App link in your dashboard.  On the Submit app page, click the App info link (Figure 14-3).

On the App info page, enter a name for your application and select a category. The name entered here is simply the name associated to your application in your Dev Center Dashboard, so don’t get hung up on trying to select the perfect app name just yet. The application name the customer sees is the one defined in your application project. We will discuss the app submission process in detail in Recipe 14-3. However, the category you select is important, as well as the related subcategory (when applicable), as this will determine the type of advertisements that are delivered to your application and displayed in the AdControl. Once you save the app info and return to the Submit app page, you will be able to select the Add in-app advertising link. Click this link to navigate to the in-app advertising page, as shown in Figure 14-4.

The first thing that you will define is an alias for your application. To simplify things, you will likely use your application’s name or the name you defined as the app alias for your Dev Center account (back in the App info page).

Next, you will want to generate one or more ad units for your application. Note that you may define multiple ad units, of different sizes, for a single application. The dropdown list provides the following ad sizes:

• 300 X 50
• 480 X 80
• 480 X 640
• 480 X 800
• 480 X 853

Microsoft guidelines recommend using an ad size of 480 X 80 for mobile applications. The larger sizes are meant for non-Windows Phone applications. The smaller ad size of 300 X 50 is provided for backward compatibility. However, the smaller ad size should still be rendered in an AdControl with a size of 480 X 80.

To generate an ad unit, enter a name in the Ad unit name text box, select a size from the Size dropdown list, and then click the Generate ad unit ID link. Once your first ad unit Id is generated, notice that your pubCenter Application ID will change from “None” to a GUID. This GUID is unique to your application and will remain the same across all ad units that you generate for this application. Your application Id and ad unit Ids are unique to your application and should not be shared.

Use the Microsoft AdControl

The Microsoft AdControl is contained within the Microsoft.Advertising.Mobile.UI namespace. You must include the following capabilities in your Application Manifest when incorporating in-app ads using the Microsoft AdControl: ID_CAP_PHONEDIALER, ID_CAP_IDENTITY_USER, and ID_CAP_MEDIALIB_PHOTO.

To include an AdControl on your page, simply drag-and-drop the AdControl from your toolbox to your page. Alternatively, you can manually enter the necessary XAML markup, which requires including the following namespace declaration within the PhoneApplicationPage element, xmlns:UI="clr-namespace:Microsoft.Advertising.Mobile.UI;assembly=Microsoft.Advertising.Mobile.UI", as well as the AdControl markup:

<UI:AdControl
     x:Name="myAdControl"
     IsAutoRefreshEnabled="True"
     Width="480"
     Height="80"
     ApplicationId="INSERT YOUR APPLICATION ID HERE"
     AdUnitId="INSERT YOUR AD UNIT ID HERE"
     ErrorOccurred="AdControl_ErrorOccurred" />

Within the markup, you must explicitly set the Width and Height of your AdControl to the recommended size of 480 X 80. You must also enter the ApplicationId and AdUnitId values in the markup. Attempting to bind these properties to a ViewModel property will crash. It doesn’t seem to take binding very well. Also note that you will need to handle the ErrorOccurred event, because the AdControl is notorious for crashing unexpectedly. Handling the ErrorOccurred event will give you the opportunity to recreate the instance of the AdControl programmatically and possibly recover gracefully, as shown in Listing 14-1.

Listing 14-1. Reinstantiate the AdControl Within the ErrorOccurred Event

private string applicationId = "INSERT YOUR APPLICATION ID HERE";
private string adUnitId = "INSERT YOUR AD UNIT ID HERE";
private void AdControl_ErrorOccurred(object sender, Microsoft.Advertising.AdErrorEventArgs e)
{
        myAdControl = new AdControl(applicationId, adUnitId, true);
}

Handling the ErrorOccurred event alone will not necessarily rectify scenarios where ads are not displaying as expected in your application. There may be instances where the AdControl will not render at all due to a lack of ad availability. This may be a result of low ad inventory in the Mobile Ad Exchange for your application’s selected category and/or related subcategory. The availability of ads is dependent on advertisers’ actively participating in the marketplace. As well, the categories configured for your ad units may not have ads available, which may require you to modify the application’s defined category, or associated subcategory, within your Dev Center Account to allow your application to receive ads from a broader market.

When incorporating the AdControl in your application, note that you must test the application on a device in order to view the ads in your application. Applications running within the emulator will not receive live ads. Alternatively, for testing within the emulator, you may use the Application Id of test_client and one of the following ad unit Ids: TextAd, Image480_80, or Image300_50.

When designing your application with in-app advertisements, it is good practice to adhere to the recommended usage guidelines, as follows:

1. Ensure your AdControl is configured at the the recommended size of 480 X 80, and ad units are generated at this size only.
2. Place the AdControl at the top or bottom of the page
3. When a page contains a ScrollViewer control, place the AdControl outside of the ScrollViewer so that the ad always remains in view.
4. When a page contains a Pivot control, place the AdControl outside of the Pivot control so that the ad always remains in view or place a separate AdControl within each pivot item to display different ads.
5. When a page contains a Panorama control, place the ad outside of the Panorama control so that the ad always remains in view, or place a separate AdControl within each panorama page to display different ads.
6. Ensure that if your application uses alternate foreground and background colors, instead of the standard system colors, that the AdControl’s border and text content are readable when the device theme is set to either light or dark theme.

Let’s take a look at how this all comes together. Launch Visual Studio 2012 and open the sample project in the Chapter 14MyWindowsPhoneApp directory.  Double-click the MyAdPage.xaml file to view the XAML markup. You will notice that AdControl markup is similar to the markup that was depicted earlier in this section, with the only modification being that we have specified the use of the test application Id and ad unit Id, so that we can view the ad in the emulator. Open the code behind for this page, to see that the only code on this page is that which handles the AdControl’s ErrorOccurred event. The majority of the work involved when including ads within your app are primarily in the application and ad unit configuration in your Windows Phone Developer Center account.

Launch the application in the emulator to see how in-app advertisements will look within the application. As shown in Figure 14-5, the first page simply contains 3 buttons: Single Page, Pivot Page, and Panorama Page. The Single Page displays the ads at the top of the page.

Tap each one of these buttons to view how the AdControl placement works within each page. Figure 14-6 depicts the ad placement within a panorama page.

As you can see, it is very easy to incorporate in-app advertisements within your Windows Phone application. Through your Windows Phone Developer Center account and pubCenter account integration, along with the Microsoft Advertising SDK, you can include in-app advertisments in your existing app in no time and with minimal code.

The Code

Launch Visual Studio 2012, and open the TrafficView application located in the Chapter 14TrafficViewWithTrialStart directory. In the App.xaml.cs file, include the following using directive: using Microsoft.Phone.Marketplace;

Next, we need to add a new static property that will contain a new instance of the LicenseInformation object, along with a new static boolean property that we will use to store the return value of the LicenseInformation.IsTrial method call. We will also create a method called CheckLicense, which will be called from the Application_Launching and Application_Activated events, as shown in Listing 14-2.

Listing 14-2. Cache the Check for Trial Version License in the App Code Behind

private static LicenseInformation licenseInfo = new LicenseInformation();
private static bool isTrial = true;
public static bool IsTrial
{
    get
    {
        return isTrial;
    }
    set
    {
        isTrial = value;
    }
}
 
private void CheckLicense()
{
#if DEBUG
    IsTrial = true;
#else
    IsTrial = licenseInformation.IsTrial();
#endif
}
 
private void Application_Launching(object sender, LaunchingEventArgs e)
{
    CheckLicense();
}
 
private void Application_Activated(object sender, ActivatedEventArgs e)
{
    CheckLicense();
}

Note that we also included a special check using #if DEBUG...#else...#endif to set the IsTrial property to True when running in Debug mode. Since there is no license information available when running within the emulator, this is how we will simulate a trial mode experience for testing purposes.

Next, open the MainPage.xaml file and add a button to the bottom of the page, which will allow the user to buy the full version of the application, and include an event handler for the Tap event. This button will only display only when the application is running as a trial version:

<Button Name="trialButton"
        Content="buy the full version"
        Tap="trialButton_Tap"/>

In the MainPage code behind, override the OnNavigatedTo event, and set the Visibility of the button to display only when the IsTrial static property within the App class is set to True. As well, include a call to the view model’s LoadTrafficList event, so that we can be sure to refresh the list with a limited number of traffic views.

Also, we will need to instantiate a new MarketplaceDetailTask object and store it in a class level variable in the MainPage code behind. Within the trialButton_Tap event, we simply need to call the Show method on the instance of the MarketplaceDetailTask object. The resulting code is shown in Listing 14-3.

Listing 14-3. Managing the UI Based on Whether the App is Running in Trial Mode

protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
{
   trialButton.Visibility = (App.IsTrial) ? System.Windows.Visibility.Visible : System.Windows.Visibility.Collapsed;
   App.ViewModel.LoadTrafficList();
}
MarketplaceDetailTask task = new MarketplaceDetailTask();
private void trialButton_Tap(object sender, System.Windows.Input.GestureEventArgs e)
{
    task.Show();
}

Finally, within the TrafficViewModel class, we need to modify the LoadTrafficList method to ensure that only two of the four traffic views are loaded in the dropdown list when running in trial mode, as shown in Listing 14-4.

Listing 14-4. Limit Traffic View Options When Running in Trial Mode

public void LoadTrafficList()
{
    TrafficItems = new ObservableCollection<TrafficItemViewModel>();
    TrafficItems.Add(new TrafficItemViewModel { Description = "E.C. Row near Lauzon Pkwy", ImageName = "loc27.jpg" });
    TrafficItems.Add(new TrafficItemViewModel { Description = "Howard near Hwy 3", ImageName = "loc10.jpg" });
 
    if (App.IsTrial == false)
    {
        //only include the additional views when it's a full version application
        TrafficItems.Add(new TrafficItemViewModel { Description = "Hwy 401 near Hwy 3", ImageName = "loc89.jpg" });
        TrafficItems.Add(new TrafficItemViewModel { Description = "St. Clair College near Hwy 3", ImageName = "loc08.jpg" });
    }
 
    LoadLastAppState();
}

With that in place, we can now run our application in the emulator to see what the user experience will be like when the application is installed as a trial. Notice that the “buy full version” button appears at the bottom, and our dropdown list of traffic views only lists 2 possible views, as illustrated in Figure 14-8.

Tap the buy button to simulate the experience the user will have when attempting to purchase the full featured version of the application. As depicted in Figure 14-9, you can see a shadow of a product page in the emulator, but an error is displayed indicating that there was a problem with the request. If the error code listed is 805a0194, then this indicates a “successful” execution of the MarketplaceDetailTask.Show method in the emulator.

When the application is actually running as a trial application that was downloaded from the Windows Phone Store onto an actual device, the buy action will launch the application’s product page, allowing the user to buy the full version of the application.

That is all it takes to include a trial version of your application! In my opinion, I think it’s a pretty sweet deal that Microsoft handles the license management for Windows Phone publishers, which in turn simplifies life tremendously for the average developer turned publisher. You only need to create a single app and include simple boolean checks to turn on/off features to provide a trial mode of your application. If this doesn’t knock your socks off, then I don’t know what else will!

Application Manifest Configuration

Verify the settings within your Application Manifest are configured properly across all sections: Application UI, Capabilities, Requirements, and Packaging.

• Application UI tab: This tab is where you will define your application’s display name, description, app icon, and tile images.
• Capabilities tab: The appropriate capabilities must be included in your manifest to ensure that your application runs properly.
• Requirements tab: You may also specify minimum hardware requirements to ensure that users can only install your application if their device is able to execute the features within it (e.g., a camera application should require that a device has a rear-facing camera, at a minimum).
• Packaging tab: This tab is where you will specify your author name, publisher name, version number, default language, and supported languages.  Note that your Windows Phone 8 app will fail certification if the Default Language is not set.

Capturing Screenshots for Application Submission

You will need to ensure that you have taken at least one screenshot of your application in each of the supported resolutions, which will be uploaded during the application submission process.

To capture the necessary screenshots for the app submission process, build your application in Visual Studio 2012 using the Release configuration, select the emulator for the desired resolution that you wish to simulate, then select “Deploy [app name]” from the Build menu to install your application within the emulator. Once it is successfully deployed, you should launch your application in the emulator through the application list in the emulator.

Next, click the button in the sidebar that appears to the right of the emulator. This will cause the Additional Tools screen to display, as shown in Figure 14-10.

Click on the Screenshot tab. You will notice that the tab page contains two buttons: Capture and Save. As well, notice that the resolution of the screen is displayed in the bottom left corner of the page. Click the Capture button. An image of your screenshot will appear in the Screenshot page (Figure 14-11).

Click Save... to launch the Windows Save As dialog box. Select the directory location where you wish to keep your screenshots contained within, and provide a unique name for the image. When generating screenshots for multiple resolutions, I prefer to create subdirectories for each of the resolutions that I will be supporting, and store the respective screenshots in the proper directories. This simplifies the application submission process when it comes time to upload the necessary screenshots for each resolution.

Submitting Your Application to the Windows Phone Store

Once you have confirmed that the Application Manifest is configured properly, build a Release version of your application in Visual Studio. This will be the XAP file that you will submit to the Store.