In-app Billing Version 3

The In-app Billing Version 3 API makes it easier for you to integrate In-app Billing into your applications. The features in this version include improved synchronous purchase flow, APIs to let you easily track ownership of consumable goods, and local caching of in-app purchase data.

Product Types

You define your products using the Bazaar Payment Panel, including product type, SKU, price, description, and so on. For more information, see Administering In-app Billing. The Version 3 API only supports the managed in-app product type.

Managed In-app Products

Managed in-app products are items that have their ownership information tracked and managed by Bazaar. When a user purchases a managed in-app item, Bazaar stores the purchase information for each item on a per-user basis. This enables you to later query Bazaar at any time to restore the state of the items a specific user has purchased. This information is persistent on the Bazaar servers even if the user uninstalls the application or if they change devices.

If you are using the Version 3 API, you can also consume managed items within your application. You would typically implement consumption for items that can be purchased multiple times (such as in-game currency, fuel, or magic spells). Once purchased, a managed item cannot be purchased again until you consume the item, by sending a consumption request to Bazaar. To learn more about in-app product consumption, see Consuming Items

Subscriptions

A subscription is a product type offered in In-app Billing that lets you sell content, services, or features to users from inside your app with recurring monthly or annual billing. You can sell subscriptions to almost any type of digital content, from any type of app or game. To understand how subscriptions work, see In-app Billing Subscriptions.

you can use the same purchase flow for buying subscriptions and retrieving subscription purchase information as with in-app products. For a code example, see Implementing Subscriptions.

Important: Unlike in-app products, subscriptions cannot be consumed.

Purchasing Items

A typical purchase flow with the Version 3 API is as follows:

1. Your application sends a isBillingSupported request to Bazaar to determine that the target version of the In-app Billing API that you are using is supported.
2. When your application starts or user logs in, it's good practice to check with Bazaar to determine what items are owned by the user. To query the user's in-app purchases, send a getPurchases request. If the request is successful, Bazaar returns a Bundle containing a list of product IDs of the purchased items, a list of the individual purchase details, and a list of the signatures for the purchases.
3. Usually, you'll want to inform the user of the products that are available for purchase. To query the details of the in-app products that you defined in Bazaar, your application can send a getSkuDetails request. You must specify a list of product IDs in the query request. If the request is successful, Bazaar returns a Bundle containing product details including the product’s price, title, description, and the purchase type.
4. If an in-app product is not owned by the user, you can initiate a purchase for it. To start a purchase request, your application sends a getBuyIntent request, specifying the product ID of the item to purchase, along with other parameters. You should record the product ID when you create a new in-app product in the Developer Console.
   1. Bazaar returns a Bundle that contains a PendingIntent which you application uses to start the checkout UI for the purchase.
   2. Your application launches the pending intent by calling the startIntentSenderForResult method.
   3. When the checkout flow finishes (that is, the user successfully purchases the item or cancels the purchase), Bazaar sends a response Intent to your onActivityResult method. The result code of the onActivityResult has a result code that indicates whether the purchase was successful or canceled. The response Intent contains information about the purchased item, including a purchaseToken String that is generated by Bazaar to uniquely identify this purchase transaction. The Intent also contains the signature of the purchase, signed with your private developer key.

To learn more about the Version 3 API calls and server responses, see In-app Billing Reference.

Consuming Items

You can use the consumption mechanism to track the user's ownership of in-app products.

In Version 3, all in-app products are managed. This means that the user's ownership of all in-app item purchases is maintained by Bazaar, and your application can query the user's purchase information when needed. When the user successfully purchases an item, that purchase is recorded in Bazaar. Once an item is purchased, it is considered to be "owned". Items in the "owned" state cannot be purchased from Bazaar. You must send a consumption request for the "owned" item before Bazaar makes it available for purchase again. Consuming the item reverts it to the "unowned" state, and discards the previous purchase data.

To retrieve the list of product's owned by the user, your application sends a getPurchases call to Bazaar. Your application can make a consumption request by sending a consumePurchase call. In the request argument, you must specify the item's unique purchaseToken String that you obtained from Bazaar when it was purchased. Bazaar returns a status code indicating if the consumption was recorded successfully.

Non-consumable and Consumable Items

It's up to you to decide if you want to handle your in-app products as non-consumable or consumable items.

Non-consumable Items

Typically, you would not implement consumption for items that can only be purchased once in your application and provide a permanent benefit. Once purchased, these items will be permanently associated to the user's Bazaar account. An example of a non-consumable item is a premium upgrade or a level pack.

Consumable items

In contrast, you can implement consumption for items that can be made available for purchase multiple times. Typically, these items provide certain temporary effects. For example, the user's in-game character might gain life points or gain extra gold coins in their inventory. Dispensing the benefits or effects of the purchased item in your application is called provisioning the in-app product. You are responsible for controlling and tracking how in-app products are provisioned to the users.

Important: Before provisioning the consumable item in your application, you must send a consumption request to Bazaar and receive a successful response indicating that the consumption was recorded.

Managing consumable purchases in your application

Here is the basic flow for purchasing a consumable item:

1. Launch a purchase flow with a getBuyIntent call
2. Get a response Bundlefrom Bazaar indicating if the purchase completed successfully.
3. If the purchase was successful, consume the purchase by making a consumePurchase call.
4. Get a response code from Bazaar indicating if the consumption completed successfully.
5. If the consumption was successful, provision the product in your application.

Subsequently, when the user starts up or logs in to your application, you should check if the user owns any outstanding consumable items; if so, make sure to consume and provision those items. Here's the recommended application startup flow if you implement consumable items in your application:

1. Send a getPurchases request to query the owned items for the user.
2. If there are any consumable items, consume the items by calling consumePurchase. This step is necessary because the application might have completed the purchase order for the consumable item, but stopped or got disconnected before the application had the chance to send a consumption request.
3. Get a response code from Bazaar indicating if the consumption completed successfully.
4. If the consumption was successful, provision the product in your application.

Local Caching

Because the Bazaar client now caches In-app Billing information locally on the device, you can use the Version 3 API to query for this information more frequently, for example through a getPurchases call. Unlike with previous versions of the API, many Version 3 API calls will be serviced through cache lookups instead of through a network connection to Bazaar, which significantly speeds up the API's response time.