In-app purchase testing for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

In-app purchase is a new feature in Windows Phone 8 that gives app users the ability to purchase items from within your Windows Phone 8 app. You have three options for testing in-app purchase capabilities in your app before publishing the app for purchase.

You can test in-app purchase in your Windows Phone app by following one of these techniques.

• Creating a Dev Center beta app and adding beta in-app products

• Adding the mock in-app purchase library to your solution

• Setting up an in-app purchase mock service by using IIS

Creating a Dev Center beta app and adding beta in-app products

One method of testing your app’s in-app feature is to create a Dev Center beta app and add beta in-app products. In the Windows Phone Dev Center, you can upload your app to the Windows Phone Store as a beta app. Then, add your beta in-app products to the app. Test the in-app purchase process with the beta app.

Adding the mock in-app purchase library to your solution

As an alternative to testing in-app purchase by creating a Dev Center beta app, you can add the mock in-app purchase library to your solution. In Visual Studio, add the mock in-app purchase library as an additional project to your solution. This library contains mock in-app purchase functions that can be used to test your app's in-app purchase functionality by using the emulator. You must modify your app to call the functions contained in the mock library when testing your app locally.

This simple mock library is designed to make it easier to work with in-app purchase without needing to set up an actual service. The library is a thin wrapper around the In-App Purchase APIs. Based on how you initialize the library, it will either mock all the responses of the products you defined for testing or pass through all calls to the live In-App Purchase API. This allows you to target various test scenarios by using the real APIs or mock APIs based on changing a flag value.

The library is designed to mimic the way in-app purchase works. When in "Mock Mode" the library maintains a list of your receipts as well as state information for every license. This allows you to exercise the entire browse, search, purchase, and fulfillment flow. When in "Mock Mode" the library doesn’t activate the in-app mock purchase screen, but provides a simple message box to complete the in-app purchase flow while testing in the emulator.

Downloading the mock in-app purchase library and sample app

Download the mock in-app purchase library and sample app from the Mock In-App Purchase Library.

Using the mock in-app purchase library

The mock in-app purchase library is written in C# code.

In each .cs file that you use in-app purchase functionality, include the following using statement code block:

#if DEBUG
using MockIAPLib;
using Store = MockIAPLib;
#else
using Windows.ApplicationModel.Store;
#endif

This statement allows you to switch between testing in-app purchase by using the mock library or making real in-app purchase calls as a published app. When you test, you must build your app in debug mode. For debug mode, in the Solution Configurations drop-down list in Visual Studio, click Debug. When you’re ready to build your app for Windows Phone Store deployment, change to release mode by selecting Release from the Solution Configurations drop-down list.

To initialize the mock library, add the following code to the App.xaml.cs file at the end of the App constructor:

            SetupMockIAP();

Then, add the SetupMockIAP method to initialize the mock library and add factious products. A sample SetupMockIAP method looks like the following:

        private void SetupMockIAP()
        {
#if DEBUG
            MockIAP.Init();

            MockIAP.RunInMockMode(true);
            MockIAP.SetListingInformation(1, "en-us", "A description", "1", "TestApp");

            // Add some more items manually.
            ProductListing p = new ProductListing
            {
                Name = "img.2",
                ImageUri = new Uri("/Res/Image/2.jpg", UriKind.Relative),
                ProductId = "img.2",
                ProductType = Windows.ApplicationModel.Store.ProductType.Durable,
                Keywords = new string[] { "image" },
                Description = "An image",
                FormattedPrice = "1.0",
                Tag = string.Empty
            };
            MockIAP.AddProductListing("img.2", p);
#endif
        }

Notice that the code contained in the method will be executed only when the project is running in debug mode.

An alternate way to populate the in-app purchase products is to use an XML snippet that lists all the offers you want to use for testing.

The XML looks like the following:

<?xml version="1.0"?>
<ProductListings>
    <ProductListing Key="test1" Purchased="true" Fulfilled="true">
        <Name>Testproduct</Name>
        <Description>A sample product listing</Description>
        <ProductId>test.durable.1</ProductId>
        <ProductType>Durable</ProductType>
        <FormattedPrice>$1.00</FormattedPrice>
        <ImageUri></ImageUri>
        <Keywords>test;product</Keywords>
        <Tag>Additional text</Tag>
    </ProductListing>
</ProductListings>

To load this XML in the "Mock Store", you use the following method call:

MockIAP.PopulateIAPItemsFromXml(Xml);

The following code shows how to load the products for testing.

ListingInformation li = await CurrentApp.LoadListingInformationAsync();

For additional details about using the mock library, download the mock library and sample app as described in the Download the mock in-app purchase library and sample app section of this topic.

Setting up an in-app purchase mock service by using IIS

As an alternative to testing in-app purchase by creating a Dev Center beta app or by adding the mock in-app purchase library to your solution, you also can set up an in-app purchase mock service by using Microsoft Internet Information Services (IIS).

Using Visual Studio, you can use the Windows Phone emulator to test your app’s in-app purchase behavior. The Windows Phone emulator connects to the mock service that’s deployed either to your local machine or to a server that can be reached from the emulator.

Benefits of testing in-app purchase by using the mock service

The in-app purchase mock service offers the following benefits:

• Helps you test the end-to-end flow of in-app purchases during your development process by using the Windows Phone emulator.

• Doesn’t require you to submit any data in the Dev Center or change any code to have this solution function.

• Allows for you to iterate quickly through product configuration changes and integration with your app.

• Allows you to simulate the platform interaction between your app and the Windows Phone platform.

The following diagram illustrates the actions that are relevant when you use the in-app purchase mock service.

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

• A) Deploy mock service: Download and set up the mock service on IIS.

• B) Add product list: Add and configure the mock product list (catalog) for your app to test.

• C) List products: Retrieve the list of mock products.

• D) Purchase products: Choose the mock products to purchase and make purchase from mock service.

• E) Enumerate licenses: Enumerate all licenses available for products in your app and determine whether the products have already been licensed, or whether fulfillment of some products is still required.

• F) Fulfillment acknowledged: Acknowledge that the mock products have successfully been purchased.

• G) Get receipts: Retrieve receipts for all mock products purchased.

• H) Fulfill: (Optional) Download digital content from your server.

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

Prerequisites

Before you start, make sure that you have the following software installed on your computer:

• Visual Studio 2010 or later versions

• IIS 7 and ASP.NET 4.5

  For installation steps, see Install IIS and ASP.NET Modules.

• Web Deploy

  To deploy the mock service deployment package, Web Deploy (msdeploy.exe) must be installed on the computer that runs the deployment file. For info about how to install Web Deploy, see Introducing Web Deploy.

You may also need to install HTTP Activation for WCF services and create a firewall exception for HTTP requests to IIS. For more info, see How to connect to a local web service from the Windows Phone 8 emulator.

Setting up the emulator

The following steps are needed to set up the emulator:

1. Deploy the mock service on a local machine.

2. Configure the emulator to connect to the mock service.

3. Configure the product catalog so that it’s used by your app.

4. Update your app manifest to use a particular APP ID.

Step 1 - Deploy the mock service on a local machine

The following deployment steps involve downloading and setting up the mock catalog service deployment package.

Download the mock catalog service deployment package

To deploy the mock catalog service to IIS you must download the Mock Catalog Service Deployment Package which is contained as a zip file in the Mock Catalog Service Source Code.

Set up the mock service on IIS

1. Open IIS Manager.

2. In the Connections pane, right-click the Sites node in the hierarchy, and then click Add Website.

3. In the Add Website dialog box, set the Site name to the following:

   IAPCatalogMockService

4. Set the Physical Path to the following:

   <path>\IapcatalogMockService\CatalogMockService

5. Set the permissions of the folder where this site is deployed so that IIS_IUSRS has access.

6. Deploy CatalogMock service package, which uses the site named IAPCatalogMockService, based on the following steps:

   1. Open the Command Prompt window as an Administrator.

   2. Open the folder named Mock-Project-Deployment Package\Deployment Package.

   3. Deploy the mock service by entering the following at the command prompt:

      CatalogServiceMockDeploymentPackage.deploy.cmd /Y

For more info about IIS, see Create a Web Site (IIS 7). Note that deployment instructions related to the mock service is also available in the CatalogServiceMockDeploymentPackage.deploy-readme.txt file.

Verify that the mock service is available and deployed correctly

1. Get the list of commands supported by running the following GET request:

   https://localhost/v8/help

   The response should contain the following:

URI	Method	Description
/catalog/apps/{appid}	GET	Service at https://localhost/v8/catalog/apps/{APPID}
/catalog/apps/{appid}/iaps	POST	Service at https://localhost/v8/catalog/apps/{APPID}/iaps
/images/{imageid}	GET	Service at https://localhost/v8/images/{IMAGEID}

2. Be able to view the preconfigured image returned by making the following GET request:

   http://[machine IP address]/v8/images/102a19e4-e6f2-495a-acc7-203bb6c742b9?imagetype=icon_iap

Window IP Configuration will be displayed in the command window. Find the IP address next to **IPv4 Address** in the **Ethernet adapter vEthernet (Internal Ethernet Port Windows Phone Emulator Internal Switch)** section.

Verify other calls the service will handle by reviewing the file named Testcalls.txt. The Testcalls.txt file can be found at the root of the download package. For more info, see Download the mock catalog service deployment package.

Step 2 - Configure the emulator to connect with the mock catalog service

This section describes how to configure the Windows Phone emulator to connect to the mock service that you deployed on the server. If you have deployed the mock service on the same machine where you have your Windows Phone emulator set up, you will need to get the IP address associated with the emulator. This section describes how to get the IP address associated with the emulator.

Follow these steps to point the emulator to the mock service:

1. Install Windows Phone SDK 8.0, if it’s not already installed.

2. Remove the read-only flag on the VHD.

   1. Opened File Explorer and navigate to C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v8.0\Emulation\Images.

   2. Removed the read-only attribute for each differential VHD. For instance, right-click on file Flash.480x800.vhd -> Properties. Clear Read-only, and then press OK.

3. Open Disk Management.

   • Select Action, and then select Attach VHD to mount a new Visual Hard Drive (Disk) on your machine.

     Repeat this step for each of the supported resolutions you want to use.

4. Find the windows partition that contains the HOSTS file by using the following steps:

   1. Using File Explorer, navigate to the etc folder located at [drive]\Windows\System32\drivers\etc.

   2. Open Notepad as an Administrator.

   3. From Notepad, open the HOST file based on the path found in the File Explorer.

   4. Add entry to the HOST file by following the format:

      #<IP address of the emulator mock service> marketplaceedgeservice.windowsphone.com

Important Note:
Be certain to follow this step so the mock service will function correctly.

5. Save the file. Be sure not to save the file as a .txt file.

5. Detach VHD Disk that you created previously by right-clicking the Disk and selecting Detach VHD.

6. Use Hyper V-Manager to remove the cached copy of the VHD based on the following steps:

   1. Launch Hyper V-Manager.

   2. Connect to your local machine.

      You will see Virtual Machines listed. Look for Emulator WVGA.%computername%.

   3. Right-click Shutdown if the emulator hasn’t closed.

   4. Right-click Delete.

7. When running the emulator from your Windows Phone app, make sure you run the same emulator for the VHD in which you updated the above host file.

Step 3 - Configure the product catalog for your app to use

Configure your in-app purchase product catalog by modifying the associated XML. You will find the XML file named iapcatalog.xml in the folder where the mock service is deployed.

The mock service uses XML as input. The service reads this XML file (iapcatalog.xml) based on the path to the app's directory.

The XML is formatted as follows:

<Catalog>
  <Item> 
    <ProductId>Test1</ProductId> <!—The unique Product Identifier -->
    <Title>Test Item 1</Title> 
    <Description>This is a test item</Description>
    <Type>iapconsumable</Type>
    <Tag>
      { Order: 1, Rewards: [ { Name: 'Credits', Quantity: 100 }, { Name: 'Coins', Quantity: 10000 } ] }
    </Tag>
  </Item>
</Catalog>

For more info about the elements in the product catalog XML file, see In-app product properties.

Step 4 - Update your manifest to use a particular APP ID

Update the manifest file for your app to use the APP ID that you used to communicate with the mock service.

In Visual Studio, update the value to the following:

ee29a261-80d0-4bdf-89bd-28b1ebbc8bd3

Run your app

You can now run your app in test mode. The app will call the mock service rather than attempting to call the Store service.

See Also

Other Resources

How to connect to a local web service from the Windows Phone 8 Emulator

Deploying an ASP.NET Web Application to IIS as a Test Environment