In-app purchase 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 contains the following sections.

• Overview
• Terminology
• Best practices
• Related Topics

Overview

Windows Phone 8 introduces in-app purchase, a new way for you to earn more money with your apps. Through in-app purchase you can sell digital content in your app. Windows Phone 8 offers a consistent purchase experience on the phone, safe handling of personal information, all of which contribute to a confident purchase experience for the consumer. As an app developer, you have a familiar API to work with, reliable payout, in-app product management tools, and geo-distributed services, which all add up to being able to achieve meaningful commerce from within your app. The relationship can be summarized as follows:

You provide:

• products that can be sold in your app

• clear and accurate product information

• the ability to initiate a purchase from within your app, that is, a “buy button”

• product delivery and/or enablement, also known as fulfillment

Microsoft provides:

• product management tools through the Windows Phone Dev Center

• geo-distributed services

• a purchase user experience that is consistent across all apps on the phone

• the ability to pay you in 190 countries or regions

• proof of purchase authenticity through secure receipts

The following diagram illustrates the actions that are relevant to in-app purchase and the parties involved.

Each flow in the preceding diagram is described in the following list.

• A) Submit app: As the app developer, you submit your app to the Windows Phone Store using your account in the Dev Center. For more information about app submission, see Understanding app and in-app product submission.

• B) Submit product list: You can also upload a list of products that you want to sell in your app to the Store using your account in the Dev Center. During this process, you give each product a name, description, and price, and define where it can be sold. You then associate each product with one of your apps. Note that you define the products in the Dev Center so app users can buy them using the Microsoft commerce platform through the Store. The products themselves are maintained by you on your own servers or infrastructure. They are not hosted in the Dev Center, the Store, or any other Microsoft service. For more information about in-app product submission, see Understanding app and in-app product submission.

• C) List products: Using the In-App Purchase API available in Windows Phone 8, your app queries for a list of products associated with the app. This gives the app user the option to purchase these products from within the app.

• D) Purchase products: After initiating the purchase, the user is presented with a purchasing experience that’s part of the Windows Phone 8 platform. When the purchase is complete, your app can fulfill the purchase by either enabling some defined app feature or by downloading some digital content from your hosted services. We believe that a consistent, secure purchase and billing mechanism for all apps helps the user trust this commercial platform. To learn more about the APIs we offer to enable in-app purchase in your app, see In-App Purchase API overview for Windows Phone 8.

• E) Enumerate licenses: When you app launches, is resumed, or following a purchase, you use the in-app purchase APIs to enumerate all licenses this user has for products in your app. Using this information, you can determine whether the user already has the products they licensed, or whether fulfillment of some products is still required.

• F) Get receipts: You can retrieve receipts for all products purchased by the user. A receipt is verification that a transaction has taken place. The receipt also contains a digital signature that you can use to verify the integrity of the receipt and make sure no tampering took place.

• G) Send license receipt: If fulfillment of a purchase requires new digital content, you typically download this content by services you own or manage, passing the digitally signed receipt for the purchase to the server.

• H) Fulfill: The digital content is downloaded from your server.

Important Note:
There are several requirements related to the use of in-app purchase that your app must meet to pass certification and be eligible for listing in the Windows Phone Store. For more info, see App policies for Windows Phone.

Terminology

Best practices

Following is a list of guidance that you should consider as you build your in-app purchase scenarios.

License enumeration and storage

Licensing is a critical part of in-app purchase. By retrieving licensing info, your app can provide which in-app products the user has a license to use. These products can be consumables or durables. There are specific conditions under which license information should be verified to ensure that the user gets the experience, and the in-app products, to which they are entitled. Any mistakes or errors in this process may frustrate the user and lead to lower sales, bad reviews, and a bad reputation for you or your app.

• Use our license storage and enumeration API. We optimized memory, performance, and security characteristics of CurrentApp.LicenseInformation to be callable on start, activate, and resume. Because license state can change without the app receiving a notification, you should rely on this API as the primary source of truth about what the user currently owns rather than storing the returned licenses in your own local storage.

• Protect your consumables. We provide information about purchases, not the state of consumables. For example, if a user purchases a bag of 100 gold coins in your app, it’s your responsibility to track the consumption of that product in a secure way so that the user always sees the correct state of that product, for example, the number of gold coins that remain. Malicious users may attempt to exploit your storage, artificially increasing the count of owned consumables. Proper security mechanisms should be employed to secure this data.

Testing your in-app purchase scenarios

In-app purchase is server-based commerce. It relies on communication with Microsoft back-end services to list products, enumerate licenses, and process purchases. It may also rely on your servers to deliver purchased in-app products if needed. There are a lot of moving parts, and your level of control over the availability, robustness, and stability of each aspect of the process varies. It is very important that you test your in-app purchase scenarios to make sure you deliver a robust and stable experience to your customers. We recommend that you consider the following approach to testing in this area.

• Unit test your functionality and isolate the In-App Purchase API through wrapping or shimming. When developing an app that relies on services, it is important to be able to test the app (system under test) without the need to have access to live running services. This is important for many reasons. The system under test is your app, not the services it relies on. You also want to be able to test the full spectrum of scenarios that can arise in the real world, without waiting for them to happen. So, having a way to isolate the service’s dependency, and replace it with predictable test data, is a very valuable and effective approach. Additional benefits to this approach can also be the speed at which you can sanity-check functionality as well as the ability to test when the real-world services are not available. For example, because you’re not connecting to internet services, there will be no latency caused by the quality of internet connection. For any app that involves commerce, you should consider unit testing as your first level of testing. The intention is not to replace end-to-end scenario tests, but instead to reduce cost and increase code quality by testing early and often. For more information on unit testing see the following:

  • Verifying Code by Using Unit Tests

  • Working with Unit Tests

• Perform end-to-end testing using a beta app distribution. When you are ready to test your app using live services, you should consider first distributing your app as a beta app. In this beta environment, you have complete control of who can download and run the app. This way, you can test the app against your in-app product catalog using Microsoft live commerce services and your own back-end servers on actual phones. When an in-app product is associated with a beta app, it’s known as a beta item and it‘s neither visible nor for sale in the live Windows Phone Store. You can test every aspect of your app in this private environment. Although the user experience shows prices as entered in the Dev Center, all in-app purchases made from beta apps are free. Beta users can clear their license data by uninstalling and reinstalling the app.

• When testing your app locally in the Windows Phone Emulator for Windows Phone 8, all in-app purchases are free. No real commercial transactions take place. Each time you reinstall the app in the emulator, the license data is cleared from the emulator.

In-app purchase can be tested using three techniques:

• Create a Dev Center beta app and add beta in-app products.

• Add the mock in-app purchase mock library to your solution.

• Set up an in-app purchase mock service using Microsoft Internet Information Services (IIS).

For more information about in-app purchase testing, see In-app purchase testing for Windows Phone 8.

Fulfilling purchases

Fulfillment is the process of making sure that your customers get the goods they purchased in a timely manner. For an app, this typically means as soon as the purchase has been verified. Because license information can change without your app being notified, it’s also necessary to verify current license state when a user starts your app, resumes from tombstone, uses fast application switching, or makes purchases on multiple phones. This is a critical part of the success of your app. If you don’t handle these cases, in some scenarios, users will end up never receiving goods they have purchased. Here’s some guidance related to fulfillment, which can help you avoid a bad user experience:

• LicenseInformation.IsActive protects you by verifying the validity of the license and should be called prior to fulfilling a purchase. However, this call is expensive and should not be called on app startup or resume. Call it at the last possible moment and avoid blocking the UI thread.

• When you believe a product purchase has completed, first verify that a license exists for that product ID, then check to see whether IsActive is true on that license. Fulfill active licenses immediately. IsActive should always be true for all licenses. If you encounter a license for which IsActive is false, the user has an invalid license installed. This can happen if the device has been compromised by a hacker. You should let the user know that you cannot verify the purchase and they should contact you to verify their purchase. If the purchase appears to be valid according to your records, contact Microsoft support.

• When something goes wrong, it’s a good idea to help the user as much as you can. If the only remediation available is to contact you, it’s best to be transparent and use friendly, clear language. Here's an example:

  “Something has gone wrong and we can’t verify your purchase. Try restarting your app to see if this fixes the issue. If it doesn’t, you can contact us at [email], let us know what you purchased, and we’ll figure out what went wrong.”

Receipts

A receipt records the purchase of goods. Each transaction that is carried out using in-app purchase has an associated receipt that can be retrieved using the GetProductReceiptAsync method. When you request a receipt for the purchase of a product, an XML receipt is sent to you and contains the following information.

The receipt also contains a digital signature that can be used to verify the integrity of the receipt and make sure no tampering took place. When fulfilling durables through your servers, always send the receipt along with the user ID that you have defined for the user who purchased the durable. This should be sent over a secure, HTTPS connection. As an added level of security, you should pass a secret with each call to your servers to increase the confidence that the request is being sent from your app. Taking these precautions will reduce the attack surface for your products and enable you to confidentially fulfill your user’s durable purchases wherever and whenever necessary.

Managing app updates and versioning

It is very likely that during the lifetime of your app you will perform an update to the app. From an in-app purchase perspective, it’s very important to maintain the state of all products the user owns during an app upgrade. When the app upgrade is complete, you need to examine all licenses and fulfill or reprovision all purchased products. For example, if the user purchased level 6 of your game and then carries out an app upgrade, you need to automatically unlock level 6 of the game when the game starts. Windows Phone doesn’t support restoration of consumables. The management of consumables is your responsibility and you will need to make sure that the state of each consumable is restored after an app upgrade or reinstallation.

See Also

Other Resources

In-App Purchase API overview for Windows Phone 8

In-app purchase testing for Windows Phone 8

Interactions and usability with Windows Phone