Chapter 7 - Interacting with Windows Marketplace
To distribute your applications, you must package them and upload them to the Microsoft® Windows® Marketplace. For your application to be accepted, it must meet the Windows Marketplace certification requirements that are discussed later in this chapter. You can specify the price if you want to sell your application, or you can offer it as a free download. It will appear in the Windows Marketplace hub on users' phones when they search for new applications. You can also use the Marketplace Trial API if you want to enable a reduced feature set and allow users to download and try the application before they purchase it. The applications can be installed on the phone using a wired or Wi-Fi connection, or over the air.
|Windows Marketplace provides the central hub for users to find and install applications for their phone.|
You can also incorporate targeted advertising into your applications by using the Microsoft Advertising Exchange for Mobile hub. Applications can interact with Microsoft Advertising service though a special API, providing a simple way to earn additional income by including advertising within your applications.
This chapter describes the typical application development and publishing life cycle, the application certification requirements, how you package the application, the Windows Marketplace submission and validation process, and how you can access Windows Marketplace and the Microsoft Advertising Exchange for Mobile hub from within your applications.
The Application Development and Publishing Life Cycle
When you create an application for Windows Phone 7, you can publish it on Windows Marketplace to make it available to users. The overall process involves interaction with both the Windows Phone 7 developer portal and the Window Marketplace portal. Figure 1 shows a high-level view of the stages of building and publishing an application for Windows Phone 7.
|The App Hub (http://create.msdn.com/) provides all the tools and publishing facilities required for your applications.|
After you create, test, and debug your application using the tools available from the App Hub, you can register as a vendor and upload your application to the App Hub. As part of this process, you must create an account and verify your identity to obtain a publisher certificate.
After you complete the registration process, you can submit your application. After it passes the validation and certification stages, it is signed with your publisher certificate and published to the Windows Marketplace application warehouse.
The Marketplace hub on the phone allows users to purchase your application, download it, and install it on their phones. As mentioned earlier, you can also create and publish trial versions of your application. The App Hub provides analysis of downloads, sales information, and user ratings. In addition, you can manage your application and update it (by deploying a new version) as required.
|Users can also find and buy your Windows Phone 7 application by using Zune software on their computers. For more information about finding and buying Windows Phone 7 applications, see "Find and buy apps in Marketplace" (http://www.microsoft.com/windowsphone/en-us/howto/wp7/apps/find-and-buy-apps-in-marketplace.aspx).|
The following sections of this chapter describe the requirements and processes for publishing your applications on Windows Phone Marketplace. For more information about the development platform and application life cycle, see the previous chapters of this book and "Application Platform Overview for Windows Phone" on MSDN® (http://msdn.microsoft.com/en-us/library/ff402531(VS.92).aspx).
For more information about creating trial versions of your applications, see Appendix A, "Tools, Frameworks, and Processes," in this book and "Creating Trial Applications for Windows Phone" on MSDN (http://msdn.microsoft.com/en-us/library/ff967554(VS.92).aspx).
The home page for App Hub is http://create.msdn.com/.
Application Certification Requirements
To ensure the quality and usability of applications distributed through Windows Marketplace, every application must pass through a validation process after submission and before it is made available for download. The following are the core tenets of this validation process:
- Applications must be reliable. This is reflected by the implementation of published best practices for creating reliable applications.
- Applications must use resources efficiently. They must execute efficiently on the phone and not have a negative impact on performance.
- Applications must not interfere with the functionality of the phone. They must not modify settings, or they must prompt the user before changing any user preferences or the behavior of other applications.
- Applications are free from viruses and malicious software. They must be safe for users to install and run.
|Your Windows Phone 7 applications must conform to a series of requirements before they can be made available on Windows Marketplace.|
In addition, applications must meet several other requirements. These include complying with the Microsoft policies for acceptable content and ensuring that localized metadata and content are accurately represented for the application's supported geographic regions. The full set of requirements falls into four main categories: application code restrictions; run-time behavior, performance and metrics; user opt-in and privacy; and media and visual content. The following sections provide an overview of the requirements within each of these categories.
For full documentation of all the requirements, download Windows Phone 7 Application Certification Requirements from the Microsoft Download Center (http://go.microsoft.com/?linkid=9730556).
Application Code Restrictions
This section describes the requirements for your Windows Phone 7 applications in terms of the code you write, the way the application works, and the way that you compile it.
Your application must run on any Windows Phone 7 device, regardless of model, screen size, keyboard hardware, or manufacturer.
The application must use only the Windows Phone Application Platform documented APIs, and it must not use PInvoke or COM interoperability. If you use controls from the System.Windows.Controls namespace, you must not call any APIs in the Microsoft.Xna.Framework.Game or Microsoft.Xna.Framework.Graphics assemblies.
The application runs in a sandbox on the device. Application code must be type-safe when compiled to Microsoft intermediate language (MSIL) code. You cannot use unsafe code or security critical code. You also cannot redistribute the Windows Phone assemblies; however, you can redistribute the Panorama, Pivot, and Map control assemblies if these are used in your application.
|Make sure you handle all exceptions in your application code, and compile it using the Release or Retail configuration.|
The application must also handle all exceptions raised by the .NET Framework, must not terminate unexpectedly or become unresponsive to user input, and it must display user-friendly error messages. A visual progress indicator must be displayed when executing time-consuming activities, such as downloading data over network connections, and you must provide an option to cancel this type of activity.
When you compile your application for distribution, you must do so using the Release or Retail configuration. It must not be compiled using the debug configuration, and it must not contain debugging symbols or output. However, you can submit an application with obfuscated code if you want.
Finally, the application must not use reflection to discover and invoke types that require security permissions. The repackaging process that takes place before distribution does not detect invoking types in this way, so the generated manifest will not request the required permissions. This will cause the application to fail at run time.
Run-time Behavior, Performance, and Metrics
To maintain a consistent user experience, the Back button must only be used for backward navigation in the application. Pressing the Back button must return the application to the previous page, or—if the user is already on the initial page—must close the application. If the current page displays a context menu or a dialog box, pressing the Back button must close the menu or dialog box and cancel the backward navigation to the previous page. The only exceptions to this are in games, where the Back button may display a context menu or dialog box, navigate to the previous menu screen, or close the menu.
|Your application must start up and be responsive within 20 seconds, and use no more than 90 MB of memory unless the device has extended memory installed.|
The certification requirements for Windows Phone 7 applications specify both the startup performance of applications and some limitations on the use of resources. For example, the application must render the main user interface (UI) startup screen (not the splash screen) within five seconds on a typical physical device, and it must be responsive to user input within twenty seconds. The application must also complete execution in response to both the Activated and Deactivated events within ten seconds or it will be terminated by the operating system.
In addition, the application must not use more than 90 MB of RAM memory on the device unless it first queries the properties of the DeviceExtendedProperties class, and this class reports that more than 256 MB of memory is installed. The application must be able to run whether or not this extended memory is available, and it should vary its behavior only at run time to take advantage of additional memory, if required.
Your application should, as far as is appropriate, minimize its use of hardware resources, services, and device capabilities to preserve battery power. For example, it should use the location service and the push notification service only when required (which also minimizes the load on these Microsoft services).
An application in the foreground can continue to run when the phone screen is locked by setting the PhoneApplicationService.ApplicationIdleDetectionMode property (you must prompt the user to allow this). When an application is running under a locked screen, it must minimize power usage as much as possible.
User Opt-in and Privacy
Your application must maintain user privacy. In particular, it must protect data provided by the user and must not pass any user-identifiable or personal information to another service or application unless you provide full details of how the information will be used and the user agrees to this (the opt-in approach).
If the application includes person-to-person communication such as chat features, and these features can be set up from the device, you must take steps to ascertain that the user is at least 13 years old before enabling this feature.
|Many types of applications will use features that require user opt-in.|
You must also obtain the user's consent before your application uses the location service to identify the user's location or if it uses the Microsoft Push Notification Service (MPNS) to send notifications to the user's phone. For example, the application must ask the user for explicit permission to receive a toast notification before it first calls the BindtoShellToast method for the first time.
For information about the different types of notifications, see "Types of Push Notifications for Windows Phone" on MSDN (http://msdn.microsoft.com/en-us/library/ff941124(VS.92).aspx).
|You must not rely on the push notification service for delivering critical messages of any kind because timeliness of delivery—or delivery at all—cannot be guaranteed.|
If your application relies on the location feature and passes the location information to another application or service (such as a social community site), you must periodically remind users by displaying a message or including a visual indication on screen that location data is being sent to another service.
Users must also be able to turn off the location feature and push notifications within the application, and the application must either continue to work or present the user with a suitable message if it cannot work with the feature turned off. It must not simply fail when the feature is disabled.
An application in the foreground can continue to run when the phone screen is locked by setting the ApplicationIdleDetectionMode property. If you design your application with this capability, you must first obtain consent from the user to run in this mode and provide them with an option to disable it.
Your application must also ask users for permission before performing large downloads. Typically, this means asking for permission for data downloads greater than 50 MB that the application requires or for the use of services or communication protocols that may incur excessive communication costs.
Application Media and Visual Content
The visual appearance and content of an application must conform to a series of requirements. For example, in terms of styling, the UI must be readable and usable if the user changes the color scheme from the default white on black.
Windows Phone 7 applications and Windows Marketplace initially support localization into only English, French, Italian, German, and Spanish. However, it is likely that other languages will be added over time. All Windows Marketplace materials and application content must be correctly localized into the chosen language. For example, an application that is submitted in French must have a product description, UI text, screen shots, and icons in French. You can submit an application for multiple languages as a single package. If you submit separate language versions, each is validated and certified separately.
|Localization of an application includes all the resources you upload to Windows Marketplace.|
For information about the localization features in Windows Phone 7, see "Globalization and Localization Overview for Windows Phone" on MSDN (http://msdn.microsoft.com/en-us/library/ff462083(VS.92).aspx).
Your applications must also abide by a series of restrictions on the content and links to content located elsewhere. These restrictions include the appropriate use of licensed content and trademarks; they also include limitations based on preventing illegal content such as libel and slander, threatening behavior, violence, pornography, and discrimination. There are very strict limits that prevent an application from containing content related to hate speech and defamation; the use or promotion of alcohol, tobacco, weapons, and drugs; certain adult-related content; and excessive profanity.
Finally, there are a series of restrictions that apply specifically to music-related or photo-related applications, and to advertising. These specify how users must be able to launch your application, and the types of advertising content that is acceptable. Although your applications can contain most types of advertising, they cannot, for example, promote other phone service plans or phone application marketplaces.
However, your application can play music in the background, even when its primary function is not related to music or video experiences.
Packaging the Application
You must package your application as a XAP file to be able to upload it to Windows Marketplace. The Windows Phone Tools for Visual Studio and the special versions of Microsoft Visual Studio® Express and Microsoft Expression Blend® design software included in the Windows Phone Tools automatically create a XAP file that you can upload.
|Applications for Windows Phone 7 are distributed as XAP files that you can create using the Windows Phone Tools.|
A XAP file contains a series of artifacts that are required to install the application on a Windows Phone. These include the following:
- A valid Windows Phone application manifest file named WMAppManifest.xml, with the application title contained in the <Title> element, and including a list of permission demands for device capabilities
- A valid .NET Framework application manifest file named AppManifest.xaml that lists the assemblies used by the application
- The assembly (DLL) files specified in the AppManifest.xaml file
- Any user controls or XAML files required by the application
- The resources, icons, images, media, and other content files that the application requires; the application icon must be a 62-by-62 pixel PNG file, and the application tile image used on the Start screen must be a 173-by-173 pixel PNG file.
The maximum size of the XAP package file you can upload is 400 MB, including all the media or other content that is included in the XAP file but not compiled into the application as resources.
If the package to download to the phone exceeds 20 MB in size, users will not be able to download it from Windows Marketplace when using a GPRS or 3G phone connection. Packages over 20 MB in size must be downloaded and installed over a Wi-Fi or physical wired connection.
If your application requires a separate download in order to work, such as an additional data package, and if the separate download exceeds 50 MB, you must inform the user and obtain permission to download it.
|XAP packages larger than 20 MB cannot be downloaded over the air using a phone connection.|
The Windows Marketplace Repackaging Process
The validation process, which the Windows Marketplace applies to all submitted applications, automatically unpacks and then repackages the application. It unpacks all the contents of the submitted XAP file and performs a range of validation checks on these. Afterward, it creates a new WMAppManifest.xml file based on the results of the validation process and repackages all the original content with the new WMAppManifest.xml into the XAP package that users will download.
The updated WMAppManifest.xml file contains a product identifier that is used in Windows Marketplace to uniquely identify the application download package; it also includes an indicator of the application type (such as a music and videos hub application). However, the main feature of the validation process that it is important for developers to understand is the way that the security permission demands are applied in the new WMAppManifest.xml file.
By default, the WMAppManifest.xml file created by the Windows Phone Tools templates in Visual Studio and Expression Blend contains permission demands for all the device capabilities. These include networking, location, microphone, push notifications, and more. However, applications distributed through Windows Marketplace advertise the capabilities they require, and users can be sure that an application that does not indicate it uses (for example) the location service, actually will not use it internally without the user being aware.
To ensure that this is the case, the validation process searches the application code for calls to any of the device capabilities that require permission. If the way that these are used in the application meets the certification requirements, the validation process includes that permission demand in the WMAppManifest.xml file and the product metadata displayed by Windows Marketplace. If a feature is not used, the permission demand is removed from the WMAppManifest.xml file. Therefore, code can use only the features for which it is certified, and any attempt to use other features (such as using reflection to invoke a feature) will fail because the application does not have the relevant permission.
|Using reflection to invoke device capabilities is likely to cause your application to fail at run time because it will not have the security permissions required to run properly. Therefore, it will fail certification.|
You can perform the same detection process as is carried out by the submission validation process on your own computer by using the Windows Phone Capability Detection Tool to check that the correct capabilities are detected.
The Windows Phone Capability Detection Tool (CapabilityDetection.exe) is installed by default in the %ProgramFiles%\Microsoft SDKs\Windows Phone\v7.0\Tools\CapDetect folder. For information on using this tool, see "How to: Use the Windows Phone Capability Detection Tool" on MSDN (http://msdn.microsoft.com/en-gb/library/gg180730(v=VS.92).aspx).
|The Windows Phone Capability Detection Tool is part of the October 2010 update to the Windows Phone Tools, which is available from the Microsoft Download Center (http://www.microsoft.com/downloads/en/details.aspx?FamilyID=49B9D0C5-6597-4313-912A-F0CCA9C7D277&displaylang=en).|
After the validation process completes, the XAP file is rebuilt, including all the original content plus a file named WMAppPRHeader.xml that contains the Digital Rights Management (DRM) information. The DRM information controls how and where the application can be used, and it manages the trial period where applicable.
Summary of the Submission and Validation Process
The following steps provide an overview of how you can submit an application to Windows Marketplace and the validation and certification processes that occur:
- Go to the App Hub website (http://create.msdn.com/) and click Sign In to log on to App Hub. You must have a Windows Live® ID to log on.
- If you do not already have an App Hub account, you must register, sign the application provider agreement, select your account type (different accounts are available for businesses, students, Microsoft Partner Program members, and individuals) and provide the details required for your account.
Note: Information, such as a tax identification number, is required to establish a vendor account. For companies, this information should come from an authorized officer of your company. Non-U.S. residents and corporations must obtain a U.S. non-resident tax payer ID (ITIN) to submit to Microsoft, together with a local country tax registration number.
- Finally, you must pay the annual subscription fee, and then wait until your account is validated and approved.
- The validation and approval process has three stages. You will receive an email to validate your email address. You will also receive an email from the company, GeoTrust that validates applicants. The response to this email must come from an officer of the company if you are registering a company. Individuals will need to validate themselves to GeoTrust. The third stage is to complete the vetting process by submitting the required documents to GeoTrust before you are issued a publication certificate.
- After the validation process is complete, your account is active, and you have a publication certificate, you can go back to the portal and upload your application XAP file. You must pay a fee for each application you publish. You must enter the required metadata for the application, such as the description, category, support email address, and iconography. You must also specify the distribution countries and pricing information for your application. You can upload screen shots of your application for use in the Windows Marketplace catalog.
- The application XAP file is validated and, providing that validation succeeds, you can specify that it is published as soon as the certification process is complete, or it can be held unpublished until you decide to publish it at a later time. If it fails validation, you can view the test results to see why it failed.
- The certification process for the application begins. The XAP file is unpacked and the content is checked to ensure it complies with all publishing requirements. These include both automated and manual technical testing, policy checking, and market validation. If the application meets all the requirements, it is repackaged and signed with a Windows Marketplace certificate. You can visit the Dashboard page to see a list of your applications, together with their current validation and publication status.
- You cannot update existing applications on Windows Marketplace. If you want to update a published application, you must resubmit it as a new product.
For a more detailed description of the registration process, see "App Hub Registration Walkthrough" on App Hub (http://create.msdn.com/en-US/home/about/developer_registration_walkthrough).
For a more detailed description of the submission process, see "App Hub Application Submission Walkthrough" on App Hub (http://create.msdn.com/en-US/home/about/app_submission_walkthrough).
For useful frequently asked questions (FAQ) for App Hub that include prices and estimates of how long the certification process takes, see the App Hub website (http://create.msdn.com/en-us/home/faq).
Displaying Advertisements in an Application
One way that you may consider increasing revenue from your Windows Phone 7 applications is to display advertisements within some or all of the pages. An easy way to accomplish this is to download and install the Microsoft Advertising SDK for Mobile on your development computer and insert the Ad Control (provided as a separate assembly within the download) into your pages.
|You can earn money by displaying advertisements within your applications.|
The Ad Control calls the Microsoft Ad Exchange to fetch an advertisement each time it is displayed. Typically, this is a small image that displays above the application bar in the phone and does not dramatically decrease the space available to your application UI. When a user clicks the advertisement, either a page on the advertiser's web site is displayed in a browser within the context of your application, or the Ad Control can initiate a phone call to the advertiser. You will receive payment from Microsoft based on the number of impressions displayed.
Microsoft Ad Exchange is an exchange where advertisers can bid for advertising slots on Windows Phone 7 devices. It automatically selects a suitable advertisement to display based on the properties you specify for the Ad Control and the advertiser's profile and other parameters within Microsoft Ad Exchange. You can specify values that influence the way that the exchange selects an advertisement. These properties include the type of application, keywords you provide, demographic information, if available (for example, if you collect this in your application through a registration process), and current location data if you collect this as the application executes and update it in the Ad Control properties.
For more information about the Mobile Advertising SDK for Windows Phone 7 and Microsoft Advertising Exchange for Mobile, see "Monetize your Windows Phone 7 Apps" on the Microsoft Advertising website (http://advertising.microsoft.com/mobile-apps).
Accessing Windows Marketplace within an Application
It is possible to access Windows Marketplace using code within a Windows Phone 7 application. This is a useful way to offer users of your application other applications that you publish, or to help them find upgrades and new versions of the application.
|Your applications can interact with the Windows Marketplace hub on the phone.|
The Windows Phone 7 operating system includes an API that allows your application to open the Windows Marketplace hub on the phone to show specific types of content, such as applications, music, or podcasts. You can also open the hub showing a filtered list of items from one of these categories using a search string, or it can show just a specific item if you specify its GUID content identifier. Finally, you can open the Reviews screen. You can also include a direct link to a specific product on Windows Marketplace in non-Windows Phone 7 applications (such as websites and desktop applications).
For information about using these features, see the section, "Windows Marketplace," in Appendix C, "Leveraging Device Capabilities."
All links in this book are accessible from the book's online bibliography. The URL to the bibliography can be found in the preface, in the final section, entitled, "Where to Go for More Information."
- Which of the following are valid ways that you can distribute your Windows Phone 7 applications?
- Publish it as a full product for sale through Windows Marketplace.
- Create an installer and sell it on a CD-ROM.
- Create a trial version and offer it free to users through Windows Marketplace.
- Plug in each phone to the USB port and copy it directly to the phone.
- Which of the following services are available through the Windows Phone Developer Portal?
- Developer registration service.
- Tools for building Windows Phone 7 applications.
- Windows Marketplace account management.
- Application submission service for your applications.
- Which of the following are not requirements for obtaining certification for an application?
- Applications must be free from viruses and malicious software.
- Applications must be reliable.
- Applications must allow users to select music files on their phone.
- Applications must minimize use of resources.
- Which of the following programming techniques are permitted in an application?
- The application can terminate if the phone does not have extended memory installed.
- The code can use PInvoke or COM interop to execute native code.
- The application can use code that is not type safe if this is absolutely necessary.
- The application can use reflection to discover and invoke types that require security permissions.
- For which of the following functions must the application prompt the user to obtain consent before using that feature?
- The location service.
- Person-to-person communication, such as chat features.
- Downloading additional content or data.
- Which of the following tasks are executed during the application submission process?
- Unpacking and validating the content of the XAP file.
- Recreating the permissions demands in the manifest file.
- Removing any content that does not conform to content-restriction policies.
- Adding a Digital Rights Management (DRM) header.