Android In app purchase

n-app Billing Overview

In-app Billing is a Google Play service that provides checkout processing for in-app purchases. To use the service, your application sends a billing request for a specific in-app product. The service then handles all of the checkout details for the transaction, including requesting and validating the form of payment and processing the financial transaction. When the checkout process is complete, the service sends your application the purchase details, such as the order number, the order date and time, and the price paid. At no point does your application have to handle any financial transactions; that role is provided by Google Play's in-app billing service.

Product and Purchase Types

In-app Billing supports different product types and purchase types to give you flexibility in how you monetize your app. In all cases, you define your products using the Google Play Developer Console, including product type, purchase type, SKU, price, description, and so on. For more information, see Administering In-app Billing.

Product Types

With In-app Billing, you can sell two types of products — in-app products and subscriptions. The billing characteristics of the two types are very different, but the In-app Billing API lets you handle the two product types in your app using the same communication model, data structures, and user interactions, as described later in this document.
  • In-app products — Items that a user would purchase one-at-a-time. For example, typical in-app products would let users purchase digital content, unlock functionality in an app, pay for one-time charges, or add almost anything to the application experience. Unlike with priced applications, once the user has purchased an in-app product there is no refund window. Users desiring refunds must contact the developer directly.
    In-app products can be sold using either the "managed per user account" or "unmanaged" purchase type. In-app products are always explicitly associated with one and only one app. That is, one app cannot purchase an in-app product published for another app, even if they are from the same developer. In-app products are supported in all versions of In-app Billing.
  • Subscriptions — Items that are sold with a developer-specified, recurring billing interval. When a user purchases a subscription, Google Play and its payment processor automatically bill the user's account at the specified interval and price, charging the amount to the original payment method. Once the user purchases a subscription, Google Play continues billing the account indefinitely, without requiring approval or action from the user. The user can cancel the subscription at any time.
    Subscriptions can only be sold using the "managed per user account" purchase type. As with in-app products, once the user has purchased an in-app product there is no refund window. Users desiring refunds must contact the developer directly. For more information about subscriptions and how to sell them in your apps, see the Subscriptions document.

Purchase Types

In-app Billing offers two purchase types that you can use when selling in-app products, "managed per user account" and "unmanaged". The purchase type controls how Google Play handles and tracks purchases for the products.
  • Managed per user account — Items that can be purchased only once per user account on Google Play. When a user purchases an item that uses the "managed per user account" purchase type, Google Play permanently stores the transaction information for each item on a per-user basis. This enables you to later query Google Play to restore the state of the items a specific user has purchased. If a user attempts to purchase a managed item that has already been purchased, Google Play prevents the user from purchasing the item again and displays an "Item already purchased" error.
    The "managed per user account" purchase type is useful if you are selling items such as game levels or application features. These items are not transient and usually need to be restored whenever a user reinstalls your application, wipes the data on their device, or installs your application on a new device.
  • Unmanaged — Items that do not have their transaction information stored on Google Play. This means that you cannot later query Google Play to retrieve transaction information for those items. For "unmanaged" purchases, you are responsible for managing the transaction information. Also, Google Play does not attempt to prevent the user from purchasing an item multiple times if it uses the "unmanaged" purchase type. It's up to you to control how many times an unmanaged item can be purchased.
    The "unmanaged" purchase type is useful if you are selling consumable items, such as fuel or magic spells. These items are consumed within your application and are usually purchased multiple times.

In-app Billing Architecture

Your app accesses the In-app Billing service using an API that is exposed by the Google Play app installed on the device. The Google Play app then uses an asynchronous message loop to convey billing requests and responses between your application and the Google Play server. In practice, your application never directly communicates with the Google Play server (see figure 1). Instead, your application sends billing requests to the Google Play application over interprocess communication (IPC) and receives purchase responses from the Google Play application in the form of asynchronous broadcast intents. Your application does not manage any network connections between itself and the Google Play server or use any special APIs from the Android platform.

Figure 1. Your application sends and receives billing messages through the Google Play application, which handles all communication with the Google Play server.
Some in-app billing implementations may also use a private remote server to deliver content or validate transactions, but a remote server is not required to implement in-app billing. A remote server can be useful if you are selling digital content that needs to be delivered to a user's device, such as media files or photos. You might also use a remote server to store users' transaction history or perform various in-app billing security tasks, such as signature verification. Although you can handle all security-related tasks in your application, performing those tasks on a remote server is recommended because it helps make your application less vulnerable to security attacks.
A typical in-app billing implementation relies on three components:
  • Service (namedBillingService in the sample application), which processes purchase messages from the application and sends billing requests to the Google Play in-app billing service.
  • BroadcastReceiver (namedBillingReceiver in the sample application), which receives all asynchronous billing responses from the Google Play application.
  • A security component (named Security in the sample application), which performs security-related tasks, such as signature verification and nonce generation. For more information about in-app billing security, seeSecurity controls later in this document.
You may also want to incorporate two other components to support in-app billing:
  • A response Handler (named ResponseHandler in the sample application), which provides application-specific processing of purchase notifications, errors, and other status messages.
  • An observer (named PurchaseObserver in the sample application), which is responsible for sending callbacks to your application so you can update your user interface with purchase information and status.
In addition to these components, your application must provide a way to store information about users' purchases and some sort of user interface that lets users select items to purchase. You do not need to provide a checkout user interface. When a user initiates an in-app purchase, the Google Play application presents the checkout user interface to your user. When the user completes the checkout process, your application resumes.

In-app Billing Messages

When the user initiates a purchase, your application sends billing messages to Google Play's in-app billing service (named MarketBillingService) using simple IPC method calls. The Google Play application responds to all billing requests synchronously, providing your application with status notifications and other information. The Google Play application also responds to some billing requests asynchronously, providing your application with error messages and detailed transaction information. The following section describes the basic request-response messaging that takes place between your application and the Google Play application.

In-app billing requests

Your application sends in-app billing requests by invoking a single IPC method (sendBillingRequest()), which is exposed by the MarketBillingService interface. This interface is defined in an Android Interface Definition Language file (IMarketBillingService.aidl). You can download this AIDL file with the in-app billing sample application.
The sendBillingRequest() method has a single Bundle parameter. The Bundle that you deliver must include several key-value pairs that specify various parameters for the request, such as the type of billing request you are making, the item that is being purchased and its type, and the application that is making the request. For more information about the Bundle keys that are sent with a request, see In-app Billing Service Interface.
One of the most important keys that every request Bundle must have is the BILLING_REQUEST key. This key lets you specify the type of billing request you are making. Google Play's in-app billing service supports the following five types of billing requests:
    This request verifies that the Google Play application supports in-app billing. You usually send this request when your application first starts up. This request is useful if you want to enable or disable certain UI features that are relevant only to in-app billing.
    This request sends a purchase message to the Google Play application and is the foundation of in-app billing. You send this request when a user indicates that he or she wants to purchase an item in your application. Google Play then handles the financial transaction by displaying the checkout user interface.
    This request retrieves the details of a purchase state change. A purchase changes state when a requested purchase is billed successfully or when a user cancels a transaction during checkout. It can also occur when a previous purchase is refunded. Google Play notifies your application when a purchase changes state, so you only need to send this request when there is transaction information to retrieve.
    This request acknowledges that your application received the details of a purchase state change. Google Play sends purchase state change notifications to your application until you confirm that you received them.
    This request retrieves a user's transaction status for managed purchases and subscriptions. You should send this request only when you need to retrieve a user's transaction status, which is usually only when your application is reinstalled or installed for the first time on a device.

In-app Billing Responses

The Google Play application responds to in-app billing requests with both synchronous and asynchronous responses. The synchronous response is a Bundle with the following three keys:
    This key provides status information and error information about a request.
    This key provides a PendingIntent, which you use to launch the checkout activity.
    This key provides you with a request identifier, which you can use to match asynchronous responses with requests.
Some of these keys are not relevant to every request. For more information, see Messaging sequence later in this document.
The asynchronous response messages are sent in the form of individual broadcast intents and include the following:
    This response contains a Google Play server response code, and is sent after you make an in-app billing request. A server response code can indicate that a billing request was successfully sent to Google Play or it can indicate that some error occurred during a billing request. This response is not used to report any purchase state changes (such as refund or purchase information). For more information about the response codes that are sent with this response, see Server Response Codes for In-app Billing.
    This response indicates that a purchase has changed state, which means a purchase succeeded, was canceled, or was refunded. This response contains one or more notification IDs. Each notification ID corresponds to a specific server-side message, and each messages contains information about one or more transactions. After your application receives an IN_APP_NOTIFY broadcast intent, you send aGET_PURCHASE_INFORMATION request with the notification IDs to retrieve message details.
    This response contains detailed information about one or more transactions. The transaction information is contained in a JSON string. The JSON string is signed and the signature is sent to your application along with the JSON string (unencrypted). To help ensure the security of your in-app billing messages, your application can verify the signature of this JSON string.
The JSON string that is returned with the PURCHASE_STATE_CHANGED intent provides your application with the details of one or more billing transactions. An example of this JSON string for a subscription item is shown below:
{ "nonce" : 1836535032137741465,
  "orders" :
    [{ "notificationId" : "android.test.purchased",
       "orderId" : "",
       "packageName" : "com.example.dungeons",
       "productId" : "android.test.purchased",
       "developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ",
       "purchaseTime" : 1290114783411,
       "purchaseState" : 0,
       "purchaseToken" : "rojeslcdyyiapnqcynkjyyjh" }]
For more information about the fields in this JSON string, see In-app Billing Broadcast Intents.

Messaging sequence

The messaging sequence for a typical purchase request is shown in figure 2. Request types for eachsendBillingRequest() method are shown in bold, broadcast intents are shown in italic. For clarity, figure 2 does not show the RESPONSE_CODE broadcast intents that are sent for every request.
The basic message sequence for an in-app purchase request is as follows:
  1. Your application sends a purchase request (REQUEST_PURCHASE type), specifying a product ID and other parameters.
  2. The Google Play application sends your application a Bundle with the following keys: RESPONSE_CODE,PURCHASE_INTENT, and REQUEST_ID. The PURCHASE_INTENT key provides a PendingIntent, which your application uses to start the checkout UI for the given product ID.
  3. Your application launches the pending intent, which launches the checkout UI.
    Note: You must launch the pending intent from an activity context and not an application context.
  4. When the checkout flow finishes (that is, the user successfully purchases the item or cancels the purchase), Google Play sends your application a notification message (an IN_APP_NOTIFY broadcast intent). The notification message includes a notification ID, which references the transaction.
  5. Your application requests the transaction information by sending a GET_PURCHASE_STATE_CHANGEDrequest, specifying the notification ID for the transaction.
  6. The Google Play application sends a Bundle with a RESPONSE_CODE key and a REQUEST_ID key.
  7. Google Play sends the transaction information to your application in a PURCHASE_STATE_CHANGEDbroadcast intent.
  8. Your application confirms that you received the transaction information for the given notification ID by sending a confirmation message (CONFIRM_NOTIFICATIONS type), specifying the notification ID for which you received transaction information.
  9. The Google Play application sends your application a Bundle with a RESPONSE_CODE key and a REQUEST_IDkey.

Figure 2. Message sequence for a purchase request.
Keep in mind, you must send a confirmation when you receive transaction information from Google Play (step 8 in figure 2). If you don't send a confirmation message, Google Play will continue sending IN_APP_NOTIFYmessages for the transactions you have not confirmed. As a best practice, you should not send aCONFIRM_NOTIFICATIONS request for a purchased item until you have delivered the item to the user. This way, if your application crashes or something else prevents your application from delivering the product, your application will still receive an IN_APP_NOTIFY broadcast intent from Google Play indicating that you need to deliver the product. Also, as a best practice, your application must be able to handle IN_APP_NOTIFY messages that contain multiple orders.
The messaging sequence for a restore transaction request is shown in figure 3. Request types for eachsendBillingRequest() method are shown in bold, broadcast intents are shown in italic. For clarity, figure 3 does not show the RESPONSE_CODE broadcast intents that are sent for every request.

Figure 3. Message sequence for a restore transactions request.
The request triggers three responses. The first is aBundle with aRESPONSE_CODE key and aREQUEST_ID key. Next, the Google Play application sends a RESPONSE_CODE broadcast intent, which provides status information or error information about the request. As always, theRESPONSE_CODE message references a specific request ID, so you can determine which request a RESPONSE_CODE message pertains to.
The RESTORE_TRANSACTIONS request type also triggers a PURCHASE_STATE_CHANGED broadcast intent, which contains the same type of transaction information that is sent during a purchase request. Unlike with a purchase request, however, the transactions are given without any associated notification IDs, so you do not need to respond to this intent with a CONFIRM_NOTIFICATIONS message.
Note: You should use the RESTORE_TRANSACTIONS request type only when your application is installed for the first time on a device or when your application has been removed from a device and reinstalled.
The messaging sequence for checking whether in-app billing is supported is shown in figure 4. The request type for the sendBillingRequest() method is shown in bold.

Figure 4. Message sequence for checking whether in-app billing is supported.
The synchronous response for aCHECK_BILLING_SUPPORTEDrequest provides a Bundle with a server response code. A RESULT_OKresponse code indicates that in-app billing is supported; aRESULT_BILLING_UNAVAILABLEresponse code indicates that in-app billing is unavailable because the API version you specified is unrecognized or the user is not eligible to make in-app purchases (for example, the user resides in a country that does not allow in-app billing). A SERVER_ERROR can also be returned, indicating that there was a problem with the Google Play server.

Handling IN_APP_NOTIFY messages

Usually, your application receives an IN_APP_NOTIFY broadcast intent from Google Play in response to aREQUEST_PURCHASE message (see figure 2). The IN_APP_NOTIFY broadcast intent informs your application that the state of a requested purchase has changed. To retrieve the details of that purchase, your application sends a GET_PURCHASE_INFORMATION request. Google Play responds with a PURCHASE_STATE_CHANGEDbroadcast intent, which contains the details of the purchase state change. Your application then sends aCONFIRM_NOTIFICATIONS message, informing Google Play that you have received the purchase state change information.
In some special cases, you may receive multiple IN_APP_NOTIFY messages even though you have confirmed receipt of the purchase information, or you may receive IN_APP_NOTIFY messages for a purchase change even though you never initiated the purchase. Your application must handle both of these special cases.

Handling multiple IN_APP_NOTIFY messages

for more  ....

No comments:

Post a Comment