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.

products

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

You can create a product list for any published application or any draft application that's been uploaded and saved to the Developer Console. However, the application's manifest must include the com.farsitel.bazaar.permission.PAY_THROUGH_BAZAAR permission.

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.

products-add

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 ID

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

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

  • Title

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

  • Description

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

  • Price

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

csv-import

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_id

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

    This is equivalent to the Publishing State setting in the In-app Products UI. Can be published or unpublished.

  • locale

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

  • title

    This 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, "\\">.

  • description

    This 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, "\\">.

  • country

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

  • price

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

apps-fa

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