Enable in-app product purchases

Note

This article demonstrates how to use members of the Windows.ApplicationModel.Store namespace. If your app targets Windows 10, version 1607, or later, we recommend that you use members of the Windows.Services.Store namespace to manage add-ons (also known as in-app products or IAPs) instead of the Windows.ApplicationModel.Store namespace. For more information, see In-app purchases and trials.

Whether your app is free or not, you can sell content, other apps, or new app functionality (such as unlocking the next level of a game) from right within the app. Here we show you how to enable these products in your app.

Note

In-app products cannot be offered from a trial version of an app. Customers using a trial version of your app can only buy an in-app product if they purchase a full version of your app.

Prerequisites

  • A Windows app in which to add features for customers to buy.
  • When you code and test new in-app products 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 %userprofile%\AppData\local\packages\<package name>\LocalState\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 Using the WindowsStoreProxy.xml file with CurrentAppSimulator.
  • This topic also references code examples provided in the Store sample. This sample is a great way to get hands-on experience with the different monetization options provided for Universal Windows Platform (UWP) apps.

Step 1: Initialize the license info for your app

When your app is initializing, get the LicenseInformation object for your app by initializing the CurrentApp or CurrentAppSimulator to enable purchases of an in-app product.

void InitializeApp()
{
    // Some app initialization code...

    // Initialize the license info for use in the app that is uploaded to the Store.
    // Uncomment the following line in the release version of your app.
    //   licenseInformation = CurrentApp.LicenseInformation;

    // Initialize the license info for testing.
    // Comment the following line in the release version of your app.
    licenseInformation = CurrentAppSimulator.LicenseInformation;

    // Other app initialization code...
}

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

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

Important

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

  1. Create an in-app offer token

    You identify each in-app product in your app by a token. This token is a string that you define and use in your app and in the Store to identify a specific in-app product. 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

    You must put the code for each feature that is associated with an in-app product 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 product feature named featureName in a license-specific conditional block. The string, featureName, is the token that uniquely identifies this product within the app and is also used to identify it in the Store.

    if (licenseInformation.ProductLicenses["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 purchase the product or feature offered by the in-app product. They can't purchase them through the Store in the same way they purchased the full app.

    Here's how to test to see if your customer already owns an in-app product 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 page with a friendly "Buy this app!" button).

    async void BuyFeature()
    {
        if (!licenseInformation.ProductLicenses["featureName"].IsActive)
        {
            try
            {
                // The customer doesn't own this feature, so
                // show the purchase dialog.
                await CurrentAppSimulator.RequestProductPurchaseAsync("featureName", false);
    
                //Check the license state to determine if the in-app purchase was successful.
            }
            catch (Exception)
            {
                // The in-app purchase was not completed because
                // an error occurred.
            }
        }
        else
        {
            // The customer already owns this feature.
        }
    }
    

Step 3: 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 4: Configure the in-app product offer in the Store

In the Dev Center dashboard, define the product ID, type, price, and other properties for your in-app product. Make sure that you configure it identically to the configuration you set in WindowsStoreProxy.xml when testing. For more information, see IAP submissions.

Remarks

If you're interested in providing your customers with consumable in-app product options (items that can be purchased, used up, and then purchased again if desired), move on to the Enable consumable in-app product purchases topic.

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