Language: HTML | XAML

Enable in-app purchases from your app (HTML)

Applies to Windows and Windows Phone

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.

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).

To see how this experience looks to the customer, see The in-app purchase experience for a customer. Note that a customer can only make an in-app purchase if they've purchased a full version of your app.

What you need to know

Technologies

Prerequisites

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

Instructions

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 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
}

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.

Step 2: 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.

Important  You must add all the in-app offers 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 offers later, you must update your app and re-submit a new version.

  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 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

    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 Store.

    
    
    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 purchase the product or feature offered by the in-app offer. 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 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 page with a friendly "Buy this app!" button).

    
    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 () {
                    //Check the license state to determine if 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 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 offer in the Store

Before you submit your app to the Store, add each in-app offer 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.

Step 5: Describe the in-app offer in the 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 when submitting your app. If your app supports more than one language, you must describe each in-app offer in every language that your app supports.

Provide a 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. For more details on specific parts of an in-app purchase description, see Your app's description.

Remarks

If you're interested in providing your customers with consumable in-app purchase options, move on to the Enable in-app purchase of consumables topic.

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

Related topics

Enable in-app purchase of consumables
Trial app and in-app purchase sample

 

 

Show:
© 2014 Microsoft