Language: HTML | XAML

How to manage a large catalog of in-app products (HTML)

Applies to Windows and Windows Phone

Windows 8.1 and Windows Phone 8.1 introduce a new solution for apps that offer in-app product catalogs that extend beyond the Store limitation of 200 product listings per developer account. This solution allows you to create just a handful of product entries for specific price tiers, with each one able to represent hundreds of products within a catalog.

To enable this capability a new overload of the RequestProductPurchaseAsync method was introduced to purchase an app-defined offer associated with an in-app product listed in the Store. In addition to specifying an offer and product association during the call, your app should also pass a ProductPurchaseDisplayProperties object that contains the large catalog offer details. If these details are not provided, the details for the listed product will be used instead.

The Store will only use the OfferId from the purchase request in the resulting PurchaseResults. This process does not directly modify the information originally provided when listing the in-app product in the Store.

What you need to know

Technologies

Prerequisites

  • This topic covers Store support for the representation of multiple in-app products using a single in-app product listing in the Store. If you are unfamiliar with in-app products please review Enable in-app product purchases to learn about license information, and how to properly list your in-app product in the Store.

  • This topic also references code examples provided in the Trial app and in-app purchase sample available in the MSDN Code Gallery. This sample is a great way to get hands-on experience with the different monetization options provided for Windows Runtime apps.

  • 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 CurrentAppSimulator docs.

Make the purchase request for the in-app product

The purchase request for a specific product within a large catalog is handled in much the same way as any other purchase request within an app. When your app calls the new RequestProductPurchaseAsync method overload, your app provides both an OfferId, and a ProductPurchaseDisplayProperties object populated with the name of the in-app product.


function purchaseAndFulfillOfferAsProduct() {
	var offerId = "1234";
	var displayPropertiesName = "MusicOffer1";
	var displayProperties = new ProductPurchaseDisplayProperties(displayPropertiesName);

	currentApp.requestProductPurchaseAsync("product1", offerId, displayProperties).done(
		function (purchaseResults) {
			if (purchaseResults.status === ProductPurchaseStatus.succeeded) {
				grantFeatureLocally("product1", purchaseResults.transactionId);
				fulfillProduct1("product1", purchaseResults.transactionId, purchaseResults.offerId);
			} else if (purchaseResults.status === ProductPurchaseStatus.notFulfilled) {
				if (isNotLocallyFulfilled("product1", purchaseResults.transactionId)) {
					grantFeatureLocally("product1", purchaseResults.transactionId);
				}
				fulfillProduct1("product1", purchaseResults.transactionId, purchaseResults.offerId);
			} else if (purchaseResults.status === ProductPurchaseStatus.notPurchased) {
				log("Product 1 was not purchased.", "sample", "status");
			}
		},
		function () {
			log("Unable to buy product 1.", "sample", "error");
		});
}

Report fulfillment of the in-app product

Your app will need to report product fulfillment to the Store as soon as the offer has been fulfilled locally. In a large catalog scenario, if your app does not report offer fulfillment, the user will be unable to purchase any in-app offers using that same Store product listing.

As mentioned earlier, the Store only uses provided offer info to populate the PurchaseResults, and does not create a persistent association between a large catalog offer and Store product listing. As a result you need to track user entitlement for products, and provide product-specific context (such as the name of the item being purchased or details about it) to the user outside of the RequestProductPurchaseAsync operation.

The following code demonstrates the fulfillment call, and a UI messaging pattern in which the specific offer info is inserted. In the absence of that specific product info, the example uses info from the product ListingInformation.


function fulfillProduct1(productId, transactionId, offerId) {
	var displayPropertiesName = document.getElementById("displayPropertiesName").value;
	if (displayPropertiesName === "") {
		displayPropertiesName = product1ListingName;
	}
	var offerIdMsg = " with offer id " + offerId;
	if (!offerId) {
		offerIdMsg = " with no offer id";
	}

	currentApp.reportConsumableFulfillmentAsync(productId, transactionId).done(
		function (result) {
			switch (result) {
				case FulfillmentResult.succeeded:
					log("You bought and fulfilled " + displayPropertiesName  + offerIdMsg, "sample", "status");
					break;
				case FulfillmentResult.nothingToFulfill:
					log("There is no purchased product 1 to fulfill.", "sample", "status");
					break;
				case FulfillmentResult.purchasePending:
					log("You bought product 1. The purchase is pending so we cannot fulfill the product.", "sample", "status");
					break;
				case FulfillmentResult.purchaseReverted:
					log("You bought product 1. But your purchase has been reverted.", "sample", "status");
					// Since the user's purchase was revoked, they got their money back.
					// You may want to revoke the user's access to the consumable content that was granted.
					break;
				case FulfillmentResult.serverError:
					log("You bought product 1. There was an error when fulfilling.", "sample", "status");
					break;
			}
		},
		function (error) {
			log("You bought Product 1. There was an error when attempting to fulfill.", "sample", "error");
		});
}

Related topics

Trial app and in-app purchase sample
Enable in-app product purchases
Enable consumable in-app product purchases
Your app's description
RequestProductPurchaseAsync
ProductPurchaseDisplayProperties

 

 

Show:
© 2014 Microsoft