Introduction

In-App Billing (IAB)

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

---

;

Figure 1. The basic sequence for a purchase request.

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.

Figure 2. The basic sequence for a consumption request.

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 ItemsTypically, 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 itemsIn 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.

Administering In-app Billing

In-app billing frees you from processing financial transactions, but you still need to perform a few administrative tasks, including setting up and maintaining your product list on the Bazaar Payment Panel.

You must have a Bazaar Developer account to create a product list. If you already have an account on Bazaar, you can use your existing account. You do not need to register for a new account to support in-app billing.

If you do not have an account, you can register as a Bazaar developer and set up an account at the Developer Zone.

Creating a Product List

---

The Bazaar Payment Panel provides a product list for each of your published applications. You can sell an item using Bazaar's in-app billing feature only if the item is listed on an application's product list. Each application has its own product list; you cannot sell items that are listed in another application's product list.

You can access an application's product list by clicking the Products/Services link in applications listed in your developer account (see figure 1). The Products/Services You can access this panel if you have registered you app before and have a contract

A product list specifies items you are selling in an application. For each item, the product list contains information such as a product id, product description, and price. The product list stores only metadata about the items you are selling in your application. It does not store any digital content. You are responsible for storing and delivering the digital content that you sell in your applications.

Figure 1. You can access an application's product list by clicking the Products/Services link in the main navigation.

In addition, an application package can have only one product list. If you create a product list for an application, and you use the multiple APK feature to distribute more than one APK for that application, the product list applies to all APK versions that are associated with the application listing. You cannot create individual product lists for each APK if you are using the multiple APK feature.

You can add items to a product list two ways: you can add items one at a time by using the In-app Products UI (see figure 2), or you can add a batch of items by importing the items from a comma-separated values (CSV) file. Adding items one at a time is useful if your application has only a few in-app items or you are adding only a few items to a product list for testing purposes. The CSV file method is useful if your application has a large number of in-app items.

Adding items one at a time to a product list

To add an item to a product list using the In-app Products UI, follow these steps:

1. Log in to your account.
2. In the panel, under the application name, click Products/Services.
3. Click Add new product (see figure 2) and provide details about the item you are selling and then click Save or Publish.

Figure 2. The Add New Product page lets you add items to an application's product list.

You must enter the following information for each item in a product list:

• In-app Product IDProduct IDs are unique across an application's namespace. A product ID must start with a lowercase letter or a number, and must be composed using only lowercase letters (a-z), numbers (0-9), underlines (_), and dots (.). The product ID "android.test" is reserved, as are all product IDs that start with "android.test."In addition, you cannot modify an item's product ID after it is created, and you cannot reuse a product ID.
• Publishing StateAn item's publishing state can be Published or Unpublished . To be visible to a user during checkout, an item's publishing state must be set to Published and the item's application must be published on Bazaar. 
• TitleThe title is a short descriptor for the item. For example, "Sleeping potion." Titles must be unique across an application's namespace. Every item must have a title. The title is visible to users during checkout. For optimum appearance, titles should be no longer than 25 characters; however, titles can be up to 55 characters in length.
• DescriptionThe description is a long descriptor for the item. For example, "Instantly puts creatures to sleep. Does not work on angry elves." Every item must have a description. The description is visible to users during checkout. Descriptions can be up to 80 characters in length.
• PriceYou must provide a default price in IR Rials currency.

Note: Be sure to plan your product ID namespace. You cannot reuse or modify product IDs after you save them.

Adding a batch of items to a product list

To add a batch of items to a product list using a CSV file, you first need to create your CSV file. The data values that you specify in the CSV file represent the same data values you specify manually through the In-app Products UI (see Adding items one at a time to a product list).

If you are importing and exporting CSV files with in-app products, please keep tax-inclusive pricing in mind prices you provide must include tax.

The CSV file uses commas (,) and semi-colons (;) to separate data values. Commas are used to separate primary data values, and semi-colons are used to separate subvalues. For example, the syntax for the CSV file is as follows:

"product_id","publish_state","title; description","country; price"

Descriptions and usage details are provided below.

• product_idThis is equivalent to the In-app Product ID setting in the In-app Products UI. If you specify a product_id that already exists in a product list, and you choose to overwrite the product list while importing the CSV file, the data for the existing item is overwritten with the values specified in the CSV file. The overwrite feature does not delete items that are on a product list but not present in the CSV file.
• publish_stateThis is equivalent to the Publishing State setting in the In-app Products UI. Can be published or unpublished.
• localeThis is equivalent to the Language setting in the In-app Products UI. You must have an entry for the default locale. The default locale must be the first entry in the list of locales, and it must include a title and description. If you want to provide translated versions of the title and description in addition to the default, you must use the following syntax rules:If autotranslate is true, you must specify the default locale, default title, default description, and other locales using the following format:"true,"default_locale; default_locale_title; default_locale_description; locale_2; locale_3, ..."If autotranslate is false, you must specify the default locale, default title, and default description as well as the translated titles and descriptions using the following format:"false,"default_locale; default_locale_title; default_locale_description; locale_2; locale_2_title; local_2_description; locale_3; locale_3_title; locale_3_description; ..."See table 1 for a list of the language codes you can use with the locale field.
• titleThis is equivalent to the Title setting in the In-app Products UI. If the title contains a semicolon, it must be escaped with a backslash (for example, "\;"). A backslash should also be escaped with a backslash (for example, "\\">.
• descriptionThis is equivalent to the Description in the In-app Products UI. If the description contains a semicolon, it must be escaped with a backslash (for example, "\;"). A backslash should also be escaped with a backslash (for example, "\\">.
• countryThe country for which you are specifying a price. You can only list countries that your application is targeting. The country codes are two-letter uppercase ISO country codes (such as "US") as defined by ISO 3166-2.
• priceThis is equivalent to the Price in the In-app Products UI. The price must be specified in micro-units. To convert a currency value to micro-units, you multiply the real value by 1,000,000. For example, if you want to sell an in-app item for $1.99 you specify 1990000 in the price field.

To import the items that are specified in your CSV file, do the following:

1. Log in to your account.
2. In the panel, under the application name, click Products/Services.
3. On the In-app Products List page, click Import CSV and select your CSV file.The CSV file must be on your local computer or on a local disk that is connected to your computer.
4. Select the Overwrite checkbox if you want to overwrite existing items in your product list.This option overwrites values of existing items only if the value of the product_id in the CSV file matches the In-app Product ID for an existing item in the product list. Overwriting does not delete items that are on a product list but not present in the CSV file.
5. On the In-app Products List page, click Import from CSV.

Working with Order Numbers

---

When a user purchases an in-app item, Bazaar assigns the transaction a unique and permanent order number.Bazaar provides that order number to you at the conclusion of the purchase flow, as the value of the orderId field of the PURCHASE_STATE_CHANGED intent.

In your app, you can use the order number as a general-purpose identifier for the in-app purchase transaction. After the purchase, you can use the order number as a means of tracking the transaction in reconciliation reports and for customer support.

The order number itself is a string consisting of ascii characters, with a format assigned and managed by Bazaar.

Bazaar assigns a Merchant Order Number and reports the Merchant Order Number as the value of orderID. Here's an example:

"orderId" : "keXQZxQmY74kNU_J"

Getting an app's license key

The Bazaar Payment Panel provides a public licensing key for each app. To get the key for an app, load Dealer Apps's page in the Developer Console and click the RSA Key. The key for the app is available for copy/paste in License Key for this Application field, as shown in the figure below.

Figure 4. You can find the license key for each app in the Dealer Apps's page.