How to support in-app purchases

Your app can offer products and features that your customers can buy from within the app. Here we show you how to enable these offers in your app.

To see how this experience looks to the customer, see The in-app purchase experience for a customer.

Note  A customer can only make an in-app purchase if they've purchased a full version of your app.

If you’d like to try working with in-app purchases and other key Windows 8 features, download the hands-on labs for Windows 8. These labs provide a modular, step-by-step introduction to creating a sample Windows Store app in the programming language of your choice (JavaScript and HTML or C# and XAML).

What you need to know

Technologies

• Windows Runtime
• Windows.ApplicationModel.Store

Prerequisites

• A Windows Store app in which to add features for customers to buy.

Instructions

Step 1: Decide which features to sell separately

Design your app in such a way that the features you want to sell are separate from the core experience. For example, a note-taking app that asks your customer to pay extra for the ability to save notes won't be popular. But a feature that lets the customer pay for additional value outside of the core experience, like the ability to save to a provider-specific cloud sharing service, could justify an additional cost to the customer.

Think through your feature model completely before you write a line of code. The features that you intend to enable as in-app purchases should be as compartmentalized and separate as possible from a code perspective as well, so you can easily incorporate them into your licensing model, and so your app can't invoke them through other code paths (or duplicate it by similar behaviors).

Here are some questions to ask while planning which features to sell or license separately.

1. What's the total cost to the customer?

   If your app is free and the customer can buy features from inside the app itself, you can get away with charging for essential parts. On the other hand, if the customer had to pay for your app, and then finds out that much of the essential experience or features are locked behind your in-app purchasing model, he or she won't be happy, and you can lose a sale.

   Try to strike a good balance between the initial cost of the app and the pricing of any additional features. Focus on selling features that add to a strong core experience, rather than those that are essential to it, and plan your pricing accordingly. Understand what the final cost of ownership is for the app.

2. How long will the features be valid after a user buys them?

   Features enabled through in-app purchases can work for as long as the customer has a valid license for their app, or they can be limited in some way. The LicenseInformation class supports a time limit where the feature can work for a number of days and then stop. How long the feature works is something that you configure when you describe the in-app offer in your Dashboard.

3. Do competing apps offers the same features for free?

   Charging for features that are available at no cost in similar apps can limit sales of your own app. Make sure that your features are clearly worth the additional charge relative to the competition, or consider a different license model.

Now that you're done planning your license model for in-app purchases, let's set it up!

Step 2: Initialize the license info for your app

When your app is initializing, get the LicenseInformation object for your app as shown in this example.

Note  When you code and test new in-app offers for the first time, you must use the CurrentAppSimulator object instead of the CurrentApp object. This way you can verify your license logic using simulated calls to the license server instead of calling the live server. To do this, you need to customize the file named “WindowsStoreProxy.xml” in <installation_folder>\Microsoft\Windows Store\ApiData. The Microsoft Visual Studio simulator creates this file when you run your app for the first time—or you can also load a custom one at runtime. For more info, see CurrentAppSimulator docs.

Initialize the CurrentApp or CurrentAppSimulator to enable the app's in-app purchases.

function appInit()
{
    // some app initialization functions

        // Get current product object 
        // Execute only one of these statements. 
        // The next line is commented out for testing.
        // currentApp = Windows.ApplicationModel.Store.CurrentApp;

        // The next line is commented out for production/release.
        currentApp = Windows.ApplicationModel.Store.CurrentAppSimulator;

        // We should have either a real or a simulated CurrentProduct object here.

        // Get the license info
        licenseInformation = currentApp.licenseInformation;

    // other app initializations function
}

Step 3: Add the in-app offers to your app

For each feature that you want to make available through an in-app purchase, create an in-app offer and add it to your app.

1. Create an in-app offer token

   You identify each in-app offer in your app by an in-app offer token. This token is a string that you define and use in your app and in the Windows Store to identify a specific in-app offer. Give it a unique (to your app) and meaningful name so that you can quickly identify the correct feature it represents while you are coding. Here are some examples of names:

   • "SpaceMissionLevel4"
   • "ContosoCloudSave"
   • "RainbowThemePack".

2. Code the feature in a conditional block

   Important  You must add to your app all the in-app offers that you want to present to your customers before you submit your app to the Windows Store. If you want to add new in-app offers later, you must update your app and submit a new version to the Windows Store.

   You must put the code for each feature that is associated with an in-app offer in a conditional block that tests to see if the customer has a license to use that feature.

   Here's an example that shows how you can code a feature named featureName in a license-specific conditional block. The string, featureName, is the token that uniquely identifies this feature within the app and is also used to identify it in the Windows Store.

   JavaScript

   C#

   Copy

   
   
   if (licenseInformation.productLicenses.lookup("featureName").isActive) 
   {
       // the customer can access this feature
   }
   else 
   {
       // the customer can't access this feature
   }
   
   
   

3. Add the purchase UI for this feature

   Your app must also provide a way for your customers to buy the product or feature offered by the in-app offer. Your customers buy them only through your app. They can't get them through the Windows Store in the same way they got your app.

   Here's how to test to see if your customer already owns an in-app offer and, if they don't, displays the purchase dialog so they can buy it. Replace the comment "show the purchase dialog" with your custom code for the purchase dialog (such as a window with a friendly "Buy this app!" button).

   JavaScript

   C#

   Copy

   
   function buyFeature1() {
       if (!licenseInformation.productLicenses.lookup("featureName").isActive)
       {
           // The customer doesn't own this feature, so 
           // show the purchase dialog.
   								
           // note: currentApp is a reference to CurrentAppSimulator from a previous declaration
           currentApp.requestProductPurchaseAsync("featureName", false).then(
               function () {
                   // the in-app purchase was successful
               }, 
               function () {
                   // The in-app purchase was not completed because 
                   // there was an error.
               });
       } 
       else
       {
           // The customer already owns this feature.
       }
   }
   
   

Step 4: Change the test code to the final calls

This is an easy step: change every reference to CurrentAppSimulator to CurrentApp in your app's code. You don't need to provide the WindowsStoreProxy.xml file any longer, so remove it from your app's path (although you may want to save it for reference when you configure the in-app offer in the next step).

Step 5: Configure the in-app offer in the Windows Store

Before you submit your app to the store, add each in-app offer to the Advanced features page in the Submit an app workflow. This is where you specify the in-app offer's token, price, and feature lifetime. Make sure that you configure it identically to the configuration you set in WindowsStoreProxy.xml when testing, or all of that hard work you spent testing may be wasted!

Step 6: Describe the in-app offer in the Windows Store

After you upload your app's package to the store, you can enter the description of each in-app offer on the Description page in the Submit an app workflow. If your app supports more than one language, you must describe each in-app offer in every language that your app supports.

Provide clear, specific description that precisely calls out what the feature adds to the app. If you aren't clear about the value of the feature above and beyond what the app itself provides, it will be hard for you to sell it.

Remarks

If you need to use receipts to verify that user made an in-app purchase, be sure to review Verifying purchases using receipts.

Build date: 3/19/2013