MarketBillingService.
- CHECK_BILLING_SUPPORTEDrequestsREQUEST_PURCHASErequests
@@ -290,12 +408,17 @@ parent.link=index.html
Binding to the MarketBillingService
-Binding to the MarketBillingService is relatively easy if you've already added the IMarketBillingService.aidl file to your project. The following code sample shows how to use the {@link android.content.Context#bindService bindService()} method to bind a service to the MarketBillingService. You could put this code in your service's {@link android.app.Activity#onCreate onCreate()} method.
Binding to the MarketBillingService is relatively easy if you've already added the
+IMarketBillingService.aidl file to your project. The following code sample shows how to
+use the {@link android.content.Context#bindService bindService()} method to bind a service to the
+MarketBillingService. You could put this code in your service's {@link
+android.app.Activity#onCreate onCreate()} method.
try {
boolean bindResult = mContext.bindService(
- new Intent("com.android.vending.billing.MarketBillingService.BIND"), this, Context.BIND_AUTO_CREATE);
+ new Intent("com.android.vending.billing.MarketBillingService.BIND"), this,
+ Context.BIND_AUTO_CREATE);
if (bindResult) {
Log.i(TAG, "Service bind successful.");
} else {
@@ -306,7 +429,10 @@ try {
}
-After you bind to the service, you need to create a reference to the IMarketBillingService interface so you can make billing requests via IPC method calls. The following code shows you how to do this using the {@link android.content.ServiceConnection#onServiceConnected onServiceConnected()} callback method.
After you bind to the service, you need to create a reference to the
+IMarketBillingService interface so you can make billing requests via IPC method calls.
+The following code shows you how to do this using the {@link
+android.content.ServiceConnection#onServiceConnected onServiceConnected()} callback method.
/**
@@ -318,24 +444,51 @@ try {
}
-You can now use the mService reference to invoke the sendBillingRequest() method.
You can now use the mService reference to invoke the
+sendBillingRequest() method.
For a complete implementation of a service that binds to the MarketBillingService, see the BillingService class in the sample application.
For a complete implementation of a service that binds to the MarketBillingService,
+see the BillingService class in the sample application.
Sending billing requests to the MarketBillingService
-Now that your {@link android.app.Service} has a reference to the IMarketBillingService interface, you can use that reference to send billing requests (via IPC method calls) to the MarketBillingService. The MarketBillingService IPC interface exposes a single public method (sendBillingRequest()), which takes a single {@link android.os.Bundle} parameter. The Bundle that you deliver with this method specifies the type of request you want to perform, using various key-value pairs. For instance, one key indicates the type of request you are making, another indicates the item being purchased, and another identifies your application. The sendBillingRequest() method immediately returns a Bundle containing an initial response code. However, this is not the complete purchase response; the complete response is delivered with an asynchronous broadcast intent. For more information about the various Bundle keys that are supported by the MarketBillingService, see In-app Billing Service Interface.
Now that your {@link android.app.Service} has a reference to the
+IMarketBillingService interface, you can use that reference to send billing requests
+(via IPC method calls) to the MarketBillingService. The
+MarketBillingService IPC interface exposes a single public method
+(sendBillingRequest()), which takes a single {@link android.os.Bundle} parameter. The
+Bundle that you deliver with this method specifies the type of request you want to perform, using
+various key-value pairs. For instance, one key indicates the type of request you are making, another
+indicates the item being purchased, and another identifies your application. The
+sendBillingRequest() method immediately returns a Bundle containing an initial response
+code. However, this is not the complete purchase response; the complete response is delivered with
+an asynchronous broadcast intent. For more information about the various Bundle keys that are
+supported by the MarketBillingService, see In-app Billing
+Service Interface.
You can use the sendBillingRequest() method to send five types of billing requests. The five request types are specified using the BILLING_REQUEST Bundle key. This Bundle key can have the following five values:
You can use the sendBillingRequest() method to send five types of billing requests.
+The five request types are specified using the BILLING_REQUEST Bundle key. This Bundle
+key can have the following five values:
-
-
CHECK_BILLING_SUPPORTED—verifies that the Android Market application supports in-app billing.
- REQUEST_PURCHASE—sends a purchase request for an in-app item.GET_PURCHASE_INFORMATION—retrieves transaction information for a purchase or refund.
- CONFIRM_NOTIFICATIONS—acknowledges that you received the transaction information for a purchase or refund.
- RESTORE_TRANSACTIONS—retrieves a user's transaction history for managed purchases.
+ CHECK_BILLING_SUPPORTED—verifies that the Android Market application + supports in-app billing.
+ REQUEST_PURCHASE—sends a purchase request for an in-app item.
+ GET_PURCHASE_INFORMATION—retrieves transaction information for a purchase + or refund.
+ CONFIRM_NOTIFICATIONS—acknowledges that you received the transaction + information for a purchase or refund.
+ RESTORE_TRANSACTIONS—retrieves a user's transaction history for managed + purchases.
To make any of these billing requests, you first need to build an initial {@link android.os.Bundle} that contains the three keys that are required for all requests: BILLING_REQUEST, API_VERSION, and PACKAGE_NAME. The following code sample shows you how to create a helper method named makeRequestBundle() that does this.
To make any of these billing requests, you first need to build an initial {@link
+android.os.Bundle} that contains the three keys that are required for all requests:
+BILLING_REQUEST, API_VERSION, and PACKAGE_NAME. The following
+code sample shows you how to create a helper method named makeRequestBundle() that does
+this.
protected Bundle makeRequestBundle(String method) {
@@ -346,13 +499,18 @@ protected Bundle makeRequestBundle(String method) {
return request;
-To use this helper method, you pass in a String that corresponds to one of the five types of billing requests. The method returns a Bundle that has the three required keys defined. The following sections show you how to use this helper method when you send a billing request.
+
To use this helper method, you pass in a String that corresponds to one of the five
+types of billing requests. The method returns a Bundle that has the three required keys defined. The
+following sections show you how to use this helper method when you send a billing request.
-
Important: You must make all in-app billing requests from your application's main thread.
+Important: You must make all in-app billing requests from your +application's main thread.
Verifying that in-app billing is supported (CHECK_BILLING_SUPPPORTED)
-The following code sample shows how to verify whether the Android Market application supports in-app billing. In the sample, mService is an instance of the MarketBillingService interface.
The following code sample shows how to verify whether the Android Market application supports
+in-app billing. In the sample, mService is an instance of the
+MarketBillingService interface.
/**
@@ -363,19 +521,37 @@ protected Bundle makeRequestBundle(String method) {
// Do something with this response.
}
-The makeRequestBundle() method constructs an initial Bundle, which contains the three keys that are required for all requests: BILLING_REQUEST, API_VERSION, and PACKAGE_NAME. The request returns a synchronous {@link android.os.Bundle} response, which contains only a single key: RESPONSE_CODE. The RESPONSE_CODE key can have the following values:
The makeRequestBundle() method constructs an initial Bundle, which contains the
+three keys that are required for all requests: BILLING_REQUEST,
+API_VERSION, and PACKAGE_NAME. The request returns a synchronous {@link
+android.os.Bundle} response, which contains only a single key: RESPONSE_CODE. The
+RESPONSE_CODE key can have the following values:
RESULT_OK—in-app billing is supported.
- RESULT_BILLING_UNAVAILABLE—in-app billing is not available because the API version you specified is not recognized or the user is not eligible to make in-app purchases (for example, the user resides in a country that prohibits in-app purchases).
- RESULT_ERROR—there was an error connecting with the Android Market application.
- RESULT_DEVELOPER_ERROR—the application is trying to make an in-app billing request but the application has not declared thecom.android.vending.BILLINGpermission in its manifest. Can also indicate that an application is not properly signed, or that you sent a malformed request.
+ RESULT_BILLING_UNAVAILABLE—in-app billing is not available because the API + version you specified is not recognized or the user is not eligible to make in-app purchases (for + example, the user resides in a country that prohibits in-app purchases).
+ RESULT_ERROR—there was an error connecting with the Android Market + application.
+ RESULT_DEVELOPER_ERROR—the application is trying to make an in-app billing + request but the application has not declared thecom.android.vending.BILLING+ permission in its manifest. Can also indicate that an application is not properly signed, or that + you sent a malformed request.
The CHECK_BILLING_SUPPORTED request does not trigger any asynchronous responses (broadcast intents).
The CHECK_BILLING_SUPPORTED request does not trigger any asynchronous responses
+(broadcast intents).
We recommend that you invoke the CHECK_BILLING_SUPPORTED request within a RemoteException block. When your code throws a RemoteException it indicates that the remote method call failed, which means that the Android Market application is out of date and needs to be updated. In this case, you can provide users with an error message that contains a link to the Updating Android Market Help topic.
We recommend that you invoke the CHECK_BILLING_SUPPORTED request within a
+RemoteException block. When your code throws a RemoteException it
+indicates that the remote method call failed, which means that the Android Market application is out
+of date and needs to be updated. In this case, you can provide users with an error message that
+contains a link to the Updating Android Market
+Help topic.
The sample application demonstrates how you can handle this error condition (see DIALOG_CANNOT_CONNECT_ID in Dungeons.java).
The sample application demonstrates how you can handle this error condition (see
+DIALOG_CANNOT_CONNECT_ID in Dungeons.java).
Making a purchase request (REQUEST_PURCHASE)
@@ -383,13 +559,19 @@ protected Bundle makeRequestBundle(String method) {- Send the
REQUEST_PURCHASErequest.
- - Launch the {@link android.app.PendingIntent} that is returned from the Android Market application. +
- Launch the {@link android.app.PendingIntent} that is returned from the Android Market + application.
- Handle the broadcast intents that are sent by the Android Market application.
Making the request
-You must specify four keys in the request {@link android.os.Bundle}. The following code sample shows how to set these keys and make a purchase request for a single in-app item. In the sample, mProductId is the Android Market product ID of an in-app item (which is listed in the application's product list), and mService is an instance of the MarketBillingService interface.
You must specify four keys in the request {@link android.os.Bundle}. The following code sample
+shows how to set these keys and make a purchase request for a single in-app item. In the sample,
+mProductId is the Android Market product ID of an in-app item (which is listed in the
+application's product
+list), and mService is an instance of the MarketBillingService
+interface.
/**
@@ -404,13 +586,26 @@ protected Bundle makeRequestBundle(String method) {
// Do something with this response.
}
-The makeRequestBundle() method constructs an initial Bundle, which contains the three keys that are required for all requests: BILLING_REQUEST, API_VERSION, and PACKAGE_NAME. The ITEM_ID key is then added to the Bundle prior to invoking the sendBillingRequest() method.
The makeRequestBundle() method constructs an initial Bundle, which contains the
+three keys that are required for all requests: BILLING_REQUEST,
+API_VERSION, and PACKAGE_NAME. The ITEM_ID key is then added
+to the Bundle prior to invoking the sendBillingRequest() method.
The request returns a synchronous {@link android.os.Bundle} response, which contains three keys: RESPONSE_CODE, PURCHASE_INTENT, and REQUEST_ID. The RESPONSE_CODE key provides you with the status of the request and the REQUEST_ID key provides you with a unique request identifier for the request. The PURCHASE_INTENT key provides you with a {@link android.app.PendingIntent}, which you can use to launch the checkout UI.
The request returns a synchronous {@link android.os.Bundle} response, which contains three keys:
+RESPONSE_CODE, PURCHASE_INTENT, and REQUEST_ID. The
+RESPONSE_CODE key provides you with the status of the request and the
+REQUEST_ID key provides you with a unique request identifier for the request. The
+PURCHASE_INTENT key provides you with a {@link android.app.PendingIntent}, which you
+can use to launch the checkout UI.
Launching the pending intent
-How you use the pending intent depends on which version of Android a device is running. On Android 1.6, you must use the pending intent to launch the checkout UI in its own separate task instead of your application's activity stack. On Android 2.0 and higher, you can use the pending intent to launch the checkout UI on your application's activity stack. The following code shows you how to do this. You can find this code in the PurchaseObserver.java file in the sample application.
How you use the pending intent depends on which version of Android a device is running. On
+Android 1.6, you must use the pending intent to launch the checkout UI in its own separate task
+instead of your application's activity stack. On Android 2.0 and higher, you can use the pending
+intent to launch the checkout UI on your application's activity stack. The following code shows you
+how to do this. You can find this code in the PurchaseObserver.java file in the sample
+application.
void startBuyPageActivity(PendingIntent pendingIntent, Intent intent) {
@@ -443,19 +638,37 @@ void startBuyPageActivity(PendingIntent pendingIntent, Intent intent) {
}
-Important: You must launch the pending intent from an activity context and not an application context. Also, you cannot use the singleTop launch mode to launch the pending intent. If you do either of these, the Android system will not attach the pending intent to your application process. Instead, it will bring Android Market to the foreground, disrupting your application.
Important: You must launch the pending intent from an activity
+context and not an application context. Also, you cannot use the singleTop launch mode to launch the
+pending intent. If you do either of these, the Android system will not attach the pending intent to
+your application process. Instead, it will bring Android Market to the foreground, disrupting your
+application.
Handling broadcast intents
-A REQUEST_PURCHASE request also triggers two asynchronous responses (broadcast intents). First, the Android Market application sends a RESPONSE_CODE broadcast intent, which provides error information about the request. Next, if the request was successful, the Android Market application sends an IN_APP_NOTIFY broadcast intent. This message contains a notification ID, which you can use to retrieve the transaction details for the REQUEST_PURCHASE request.
A REQUEST_PURCHASE request also triggers two asynchronous responses (broadcast
+intents). First, the Android Market application sends a RESPONSE_CODE broadcast intent,
+which provides error information about the request. Next, if the request was successful, the Android
+Market application sends an IN_APP_NOTIFY broadcast intent. This message contains a
+notification ID, which you can use to retrieve the transaction details for the
+REQUEST_PURCHASE request.
Keep in mind, the Android Market application also sends an IN_APP_NOTIFY for refunds. For more information, see Handling IN_APP_NOTIFY messages.
Keep in mind, the Android Market application also sends an IN_APP_NOTIFY for
+refunds. For more information, see Handling
+IN_APP_NOTIFY messages.
Retrieving transaction information for a purchase or refund (GET_PURCHASE_INFORMATION)
-You retrieve transaction information in response to an IN_APP_NOTIFY broadcast intent. The IN_APP_NOTIFY message contains a notification ID, which you can use to retrieve transaction information.
You retrieve transaction information in response to an IN_APP_NOTIFY broadcast
+intent. The IN_APP_NOTIFY message contains a notification ID, which you can use to
+retrieve transaction information.
To retrieve transaction information for a purchase or refund you must specify five keys in the request {@link android.os.Bundle}. The following code sample shows how to set these keys and make the request. In the sample, mService is an instance of the MarketBillingService interface.
To retrieve transaction information for a purchase or refund you must specify five keys in the
+request {@link android.os.Bundle}. The following code sample shows how to set these keys and make
+the request. In the sample, mService is an instance of the
+MarketBillingService interface.
/**
@@ -468,15 +681,36 @@ void startBuyPageActivity(PendingIntent pendingIntent, Intent intent) {
// Do something with this response.
}
-The makeRequestBundle() method constructs an initial Bundle, which contains the three keys that are required for all requests: BILLING_REQUEST, API_VERSION, and PACKAGE_NAME. The additional keys are then added to the bundle prior to invoking the sendBillingRequest() method. The REQUEST_NONCE key contains a cryptographically secure nonce (number used once) that you must generate. The Android Market application returns this nonce with the PURCHASE_STATE_CHANGED broadcast intent so you can verify the integrity of the transaction information. The NOTIFY_IDS key contains an array of notification IDs, which you received in the IN_APP_NOTIFY broadcast intent.
The makeRequestBundle() method constructs an initial Bundle, which contains the
+three keys that are required for all requests: BILLING_REQUEST,
+API_VERSION, and PACKAGE_NAME. The additional keys are then added to the
+bundle prior to invoking the sendBillingRequest() method. The
+REQUEST_NONCE key contains a cryptographically secure nonce (number used once) that you
+must generate. The Android Market application returns this nonce with the
+PURCHASE_STATE_CHANGED broadcast intent so you can verify the integrity of the
+transaction information. The NOTIFY_IDS key contains an array of notification IDs,
+which you received in the IN_APP_NOTIFY broadcast intent.
The request returns a synchronous {@link android.os.Bundle} response, which contains two keys: RESPONSE_CODE and REQUEST_ID. The RESPONSE_CODE key provides you with the status of the request and the REQUEST_ID key provides you with a unique request identifier for the request.
The request returns a synchronous {@link android.os.Bundle} response, which contains two keys:
+RESPONSE_CODE and REQUEST_ID. The RESPONSE_CODE key provides
+you with the status of the request and the REQUEST_ID key provides you with a unique
+request identifier for the request.
A GET_PURCHASE_INFORMATION request also triggers two asynchronous responses (broadcast intents). First, the Android Market application sends a RESPONSE_CODE broadcast intent, which provides status and error information about the request. Next, if the request was successful, the Android Market application sends a PURCHASE_STATE_CHANGED broadcast intent. This message contains detailed transaction information. The transaction information is contained in a signed JSON string (unencrypted). The message includes the signature so you can verify the integrity of the signed string.
A GET_PURCHASE_INFORMATION request also triggers two asynchronous responses
+(broadcast intents). First, the Android Market application sends a RESPONSE_CODE
+broadcast intent, which provides status and error information about the request. Next, if the
+request was successful, the Android Market application sends a PURCHASE_STATE_CHANGED
+broadcast intent. This message contains detailed transaction information. The transaction
+information is contained in a signed JSON string (unencrypted). The message includes the signature
+so you can verify the integrity of the signed string.
Acknowledging transaction information (CONFIRM_NOTIFICATIONS)
-To acknowledge that you received transaction information you send a CONFIRM_NOTIFICATIONS request. You must specify four keys in the request {@link android.os.Bundle}. The following code sample shows how to set these keys and make the request. In the sample, mService is an instance of the MarketBillingService interface.
To acknowledge that you received transaction information you send a
+CONFIRM_NOTIFICATIONS request. You must specify four keys in the request {@link
+android.os.Bundle}. The following code sample shows how to set these keys and make the request. In
+the sample, mService is an instance of the MarketBillingService
+interface.
/**
@@ -488,17 +722,35 @@ void startBuyPageActivity(PendingIntent pendingIntent, Intent intent) {
// Do something with this response.
}
-The makeRequestBundle() method constructs an initial Bundle, which contains the three keys that are required for all requests: BILLING_REQUEST, API_VERSION, and PACKAGE_NAME. The additional NOTIFY_IDS key is then added to the bundle prior to invoking the sendBillingRequest() method. The NOTIFY_IDS key contains an array of notification IDs, which you received in an IN_APP_NOTIFY broadcast intent and also used in a GET_PURCHASE_INFORMATION request.
The makeRequestBundle() method constructs an initial Bundle, which contains the
+three keys that are required for all requests: BILLING_REQUEST,
+API_VERSION, and PACKAGE_NAME. The additional NOTIFY_IDS key
+is then added to the bundle prior to invoking the sendBillingRequest() method. The
+NOTIFY_IDS key contains an array of notification IDs, which you received in an
+IN_APP_NOTIFY broadcast intent and also used in a GET_PURCHASE_INFORMATION
+request.
The request returns a synchronous {@link android.os.Bundle} response, which contains two keys: RESPONSE_CODE and REQUEST_ID. The RESPONSE_CODE key provides you with the status of the request and the REQUEST_ID key provides you with a unique request identifier for the request.
The request returns a synchronous {@link android.os.Bundle} response, which contains two keys:
+RESPONSE_CODE and REQUEST_ID. The RESPONSE_CODE key provides
+you with the status of the request and the REQUEST_ID key provides you with a unique
+request identifier for the request.
A CONFIRM_NOTIFICATIONS request triggers a single asynchronous response—a RESPONSE_CODE broadcast intent. This broadcast intent provides status and error information about the request.
A CONFIRM_NOTIFICATIONS request triggers a single asynchronous response—a
+RESPONSE_CODE broadcast intent. This broadcast intent provides status and error
+information about the request.
Note: As a best practice, you should not send a CONFIRM_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 Android Market indicating that you need to deliver the product.
Note: As a best practice, you should not send a
+CONFIRM_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 Android Market indicating that you need to deliver the product.
Restoring transaction information (RESTORE_TRANSACTIONS)
-To restore a user's transaction information, you send a RESTORE_TRANSACTIONS request. You must specify four keys in the request {@link android.os.Bundle}. The following code sample shows how to set these keys and make the request. In the sample, mService is an instance of the MarketBillingService interface.
To restore a user's transaction information, you send a RESTORE_TRANSACTIONS
+request. You must specify four keys in the request {@link android.os.Bundle}. The following code
+sample shows how to set these keys and make the request. In the sample, mService is an
+instance of the MarketBillingService interface.
/**
@@ -510,36 +762,73 @@ void startBuyPageActivity(PendingIntent pendingIntent, Intent intent) {
// Do something with this response.
}
-The makeRequestBundle() method constructs an initial Bundle, which contains the three keys that are required for all requests: BILLING_REQUEST, API_VERSION, and PACKAGE_NAME. The additional REQUEST_NONCE key is then added to the bundle prior to invoking the sendBillingRequest() method. The REQUEST_NONCE key contains a cryptographically secure nonce (number used once) that you must generate. The Android Market application returns this nonce with the transactions information contained in the PURCHASE_STATE_CHANGED broadcast intent so you can verify the integrity of the transaction information.
The makeRequestBundle() method constructs an initial Bundle, which contains the
+three keys that are required for all requests: BILLING_REQUEST,
+API_VERSION, and PACKAGE_NAME. The additional REQUEST_NONCE
+key is then added to the bundle prior to invoking the sendBillingRequest() method. The
+REQUEST_NONCE key contains a cryptographically secure nonce (number used once) that you
+must generate. The Android Market application returns this nonce with the transactions information
+contained in the PURCHASE_STATE_CHANGED broadcast intent so you can verify the
+integrity of the transaction information.
The request returns a synchronous {@link android.os.Bundle} response, which contains two keys: RESPONSE_CODE and REQUEST_ID. The RESPONSE_CODE key provides you with the status of the request and the REQUEST_ID key provides you with a unique request identifier for the request.
A RESTORE_TRANSACTIONS request also triggers two asynchronous responses (broadcast intents). First, the Android Market application sends a RESPONSE_CODE broadcast intent, which provides status and error information about the request. Next, if the request was successful, the Android Market application sends a PURCHASE_STATE_CHANGED broadcast intent. This message contains the detailed transaction information. The transaction information is contained in a signed JSON string (unencrypted). The message includes the signature so you can verify the integrity of the signed string.
The request returns a synchronous {@link android.os.Bundle} response, which contains two keys:
+RESPONSE_CODE and REQUEST_ID. The RESPONSE_CODE key provides
+you with the status of the request and the REQUEST_ID key provides you with a unique
+request identifier for the request.
A RESTORE_TRANSACTIONS request also triggers two asynchronous responses (broadcast
+intents). First, the Android Market application sends a RESPONSE_CODE broadcast intent,
+which provides status and error information about the request. Next, if the request was successful,
+the Android Market application sends a PURCHASE_STATE_CHANGED broadcast intent. This
+message contains the detailed transaction information. The transaction information is contained in a
+signed JSON string (unencrypted). The message includes the signature so you can verify the integrity
+of the signed string.
Other service tasks
-You may also want your {@link android.app.Service} to receive intent messages from your {@link android.content.BroadcastReceiver}. You can use these intent messages to convey the information that was sent asynchronously from the Android Market application to your {@link android.content.BroadcastReceiver}. To see an example of how you can send and receive these intent messages, see the BillingReceiver.java and BillingService.java files in the sample application. You can use these samples as a basis for your own implementation. However, if you use any of the code from the sample application, be sure you follow the guidelines in Security and Design.
You may also want your {@link android.app.Service} to receive intent messages from your {@link
+android.content.BroadcastReceiver}. You can use these intent messages to convey the information that
+was sent asynchronously from the Android Market application to your {@link
+android.content.BroadcastReceiver}. To see an example of how you can send and receive these intent
+messages, see the BillingReceiver.java and BillingService.java files in
+the sample application. You can use these samples as a basis for your own implementation. However,
+if you use any of the code from the sample application, be sure you follow the guidelines in Security and Design.
Creating a BroadcastReceiver
-The Android Market application uses broadcast intents to send asynchronous billing responses to your application. To receive these intent messages, you need to create a {@link android.content.BroadcastReceiver} that can handle the following intents:
+The Android Market application uses broadcast intents to send asynchronous billing responses to +your application. To receive these intent messages, you need to create a {@link +android.content.BroadcastReceiver} that can handle the following intents:
- com.android.vending.billing.RESPONSE_CODE
-
This broadcast intent contains an Android Market response code, and is sent after you make an in-app billing request. For more information about the response codes that are sent with this response, see Android Market Response Codes for In-app Billing.
+This broadcast intent contains an Android Market response code, and is sent after you make an + in-app billing request. For more information about the response codes that are sent with this + response, see Android Market Response + Codes for In-app Billing.
- com.android.vending.billing.IN_APP_NOTIFY
-
This response indicates that a purchase has changed state, which means a purchase succeeded, was canceled, or was refunded. For more information about notification messages, see In-app Billing Broadcast Intents
+This response indicates that a purchase has changed state, which means a purchase succeeded, + was canceled, or was refunded. For more information about notification messages, see In-app Billing + Broadcast Intents
- com.android.vending.billing.PURCHASE_STATE_CHANGED
-
This broadcast intent contains detailed information about one or more transactions. For more information about purchase state messages, see In-app Billing Broadcast Intents
+This broadcast intent contains detailed information about one or more transactions. For more + information about purchase state messages, see In-app Billing + Broadcast Intents
Each of these broadcast intents provide intent extras, which your {@link android.content.BroadcastReceiver} must handle. The intent extras are listed in the following table (see table 1).
+Each of these broadcast intents provide intent extras, which your {@link +android.content.BroadcastReceiver} must handle. The intent extras are listed in the following table +(see table 1).
-Table 1. Description of broadcast intent extras that are sent in response to billing requests.
+Table 1. Description of broadcast intent extras that are +sent in response to billing requests.
com.android.vending.billing.RESPONSE_CODE |
request_id |
- A long representing a request ID. A request ID identifies a specific billing request and is returned by Android Market at the time a request is made. |
+ A long representing a request ID. A request ID identifies a specific billing
+ request and is returned by Android Market at the time a request is made. |
com.android.vending.billing.RESPONSE_CODE |
@@ -561,12 +851,17 @@ void startBuyPageActivity(PendingIntent pendingIntent, Intent intent) {
|||
com.android.vending.billing.IN_APP_NOTIFY |
notification_id |
- A String representing the notification ID for a given purchase state change. Android Market notifies you when there is a purchase state change and the notification includes a unique notification ID. To get the details of the purchase state change, you send the notification ID with the GET_PURCHASE_INFORMATION request. |
+ A String representing the notification ID for a given purchase state change.
+ Android Market notifies you when there is a purchase state change and the notification includes a
+ unique notification ID. To get the details of the purchase state change, you send the notification
+ ID with the GET_PURCHASE_INFORMATION request. |
com.android.vending.billing.PURCHASE_STATE_CHANGED |
inapp_signed_data |
- A String representing the signed JSON string. The JSON string contains information about the billing transaction, such as order number, amount, and the item that was purchased or refunded. |
+ A String representing the signed JSON string. The JSON string contains
+ information about the billing transaction, such as order number, amount, and the item that was
+ purchased or refunded. |
com.android.vending.billing.PURCHASE_STATE_CHANGED |
@@ -575,7 +870,9 @@ void startBuyPageActivity(PendingIntent pendingIntent, Intent intent) {
The following code sample shows how to handle these broadcast intents and intent extras within a {@link android.content.BroadcastReceiver}. The BroadcastReceiver in this case is named BillingReceiver, just as it is in the sample application.
The following code sample shows how to handle these broadcast intents and intent extras within a
+{@link android.content.BroadcastReceiver}. The BroadcastReceiver in this case is named
+BillingReceiver, just as it is in the sample application.
public class BillingReceiver extends BroadcastReceiver {
@@ -623,13 +920,28 @@ public class BillingReceiver extends BroadcastReceiver {
}
-In addition to receiving broadcast intents from the Android Market application, your {@link android.content.BroadcastReceiver} must handle the information it received in the broadcast intents. Usually, your {@link android.content.BroadcastReceiver} does this by sending the information to a local service (discussed in the next section). The BillingReceiver.java file in the sample application shows you how to do this. You can use this sample as a basis for your own {@link android.content.BroadcastReceiver}. However, if you use any of the code from the sample application, be sure you follow the guidelines that are discussed in Security and Design .
In addition to receiving broadcast intents from the Android Market application, your {@link
+android.content.BroadcastReceiver} must handle the information it received in the broadcast intents.
+Usually, your {@link android.content.BroadcastReceiver} does this by sending the information to a
+local service (discussed in the next section). The BillingReceiver.java file in the
+sample application shows you how to do this. You can use this sample as a basis for your own {@link
+android.content.BroadcastReceiver}. However, if you use any of the code from the sample application,
+be sure you follow the guidelines that are discussed in Security and Design .
Verifying Signatures and Nonces
-Android Market's in-app billing service uses two mechanisms to help verify the integrity of the transaction information you receive from Android Market: nonces and signatures. A nonce (number used once) is a cryptographically secure number that your application generates and sends with every GET_PURCHASE_INFORMATION and RESTORE_TRANSACTIONS request. The nonce is returned with the PURCHASE_STATE_CHANGED broadcast intent, enabling you to verify that any given PURCHASE_STATE_CHANGED response corresponds to an actual request that you made. Every PURCHASE_STATE_CHANGED broadcast intent also includes a signed JSON string and a signature, which you can use to verify the integrity of the response.
Android Market's in-app billing service uses two mechanisms to help verify the integrity of the
+transaction information you receive from Android Market: nonces and signatures. A nonce (number used
+once) is a cryptographically secure number that your application generates and sends with every
+GET_PURCHASE_INFORMATION and RESTORE_TRANSACTIONS request. The nonce is
+returned with the PURCHASE_STATE_CHANGED broadcast intent, enabling you to verify that
+any given PURCHASE_STATE_CHANGED response corresponds to an actual request that you
+made. Every PURCHASE_STATE_CHANGED broadcast intent also includes a signed JSON string
+and a signature, which you can use to verify the integrity of the response.
Your application must provide a way to generate, manage, and verify nonces. The following sample code shows some simple methods you can use to do this.
+Your application must provide a way to generate, manage, and verify nonces. The following sample +code shows some simple methods you can use to do this.
private static final SecureRandom RANDOM = new SecureRandom();
@@ -650,27 +962,42 @@ public class BillingReceiver extends BroadcastReceiver {
}
-Your application must also provide a way to verify the signatures that accompany every PURCHASE_STATE_CHANGED broadcast intent. The Security.java file in the sample application shows you how to do this. If you use this file as a basis for your own security implementation, be sure to follow the guidelines in Security and Design and obfuscate your code.
Your application must also provide a way to verify the signatures that accompany every
+PURCHASE_STATE_CHANGED broadcast intent. The Security.java file in the
+sample application shows you how to do this. If you use this file as a basis for your own security
+implementation, be sure to follow the guidelines in Security and Design and
+obfuscate your code.
You will need to use your Android Market public key to perform the signature verification. The following procedure shows you how to retrieve Base64-encoded public key from the Android Market publisher site.
+You will need to use your Android Market public key to perform the signature verification. The +following procedure shows you how to retrieve Base64-encoded public key from the Android Market +publisher site.
- Log in to your publisher account.
- On the upper left part of the page, under your name, click Edit profile. -
- On the Edit Profile page, scroll down to the Licensing & In-app Billing panel (see figure 2). +
- On the Edit Profile page, scroll down to the Licensing & In-app Billing panel (see figure + 2).
- Copy your public key.
Important: To keep your public key safe from malicious users and hackers, do not embed your public key as an entire literal string. Instead, construct the string at runtime from pieces or use bit manipulation (for example, XOR with some other string) to hide the actual key. The key itself is not secret information, but you do not want to make it easy for a hacker or malicious user to replace the public key with another key.
+Important: To keep your public key safe from malicious users and +hackers, do not embed your public key as an entire literal string. Instead, construct the string at +runtime from pieces or use bit manipulation (for example, XOR with some other string) to hide the +actual key. The key itself is not secret information, but you do not want to make it easy for a +hacker or malicious user to replace the public key with another key.
- Figure 2. The Licensing and In-app Billing panel of your account's Edit Profile page lets you see your public key. + Figure 2. The Licensing and In-app Billing panel of your account's Edit Profile + page lets you see your public key.
Modifying Your Application Code
-After you finish adding in-app billing components to your project, you are ready to modify your application's code. For a typical implementation, like the one that is demonstrated in the sample application, this means you need to write code to do the following:
+After you finish adding in-app billing components to your project, you are ready to modify your +application's code. For a typical implementation, like the one that is demonstrated in the sample +application, this means you need to write code to do the following:
- Create a storage mechanism for storing users' purchase information. @@ -681,13 +1008,26 @@ public class BillingReceiver extends BroadcastReceiver {
- Implementing In-app Billing -
- Security and Design +
- Implementing In-app + Billing +
- Security and + Design
- Testing In-app Billing -
- Administering In-app Billing -
- In-app Billing Reference +
- Administering In-app + Billing +
- In-app Billing + Reference
- A {@link android.app.Service} (named
BillingServicein the sample application), which processes purchase messages from the application and sends billing requests to Android Market's in-app billing service.
- - A {@link android.content.BroadcastReceiver} (named
BillingReceiverin the sample application), which receives all asynchronous billing responses from the Android Market application.
- - A security component (named
Securityin the sample application), which performs security-related tasks, such as signature verification and nonce generation. For more information about in-app billing security, see Security controls later in this document.
+ - A {@link android.app.Service} (named
BillingServicein the sample application), + which processes purchase messages from the application and sends billing requests to Android + Market's in-app billing service.
+ - A {@link android.content.BroadcastReceiver} (named
BillingReceiverin the sample + application), which receives all asynchronous billing responses from the Android Market + application.
+ - A security component (named
Securityin the sample application), which performs + security-related tasks, such as signature verification and nonce generation. For more information + about in-app billing security, see Security controls later in this + document. - A response {@link android.os.Handler} (named
ResponseHandlerin the sample application), which provides application-specific processing of purchase notifications, errors, and other status messages.
- - An observer (named
PurchaseObserverin the sample application), which is responsible for sending callbacks to your application so you can update your user interface with purchase information and status.
+ - A response {@link android.os.Handler} (named
ResponseHandlerin the sample + application), which provides application-specific processing of purchase notifications, errors, + and other status messages.
+ - An observer (named
PurchaseObserverin the sample application), which is + responsible for sending callbacks to your application so you can update your user interface with + purchase information and status. CHECK_BILLING_SUPPORTED-This request verifies that the Android Market 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 verifies that the Android Market 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.
REQUEST_PURCHASE-This request sends a purchase message to the Android Market 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. Android Market then handles the financial transaction by displaying the checkout user interface.
+This request sends a purchase message to the Android Market 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. Android Market then handles the financial transaction by displaying + the checkout user interface.
GET_PURCHASE_INFORMATION-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. Android Market 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 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. Android Market notifies your + application when a purchase changes state, so you only need to send this request when there is + transaction information to retrieve.
CONFIRM_NOTIFICATIONS-This request acknowledges that your application received the details of a purchase state change. Android Market sends purchase state change notifications to your application until you confirm that you received them.
+This request acknowledges that your application received the details of a purchase state + change. Android Market sends purchase state change notifications to your application until you + confirm that you received them.
RESTORE_TRANSACTIONS-This request retrieves a user's transaction status for managed purchases. 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.
+This request retrieves a user's transaction status for managed + purchases. 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.
RESPONSE_CODEThis key provides status information and error information about a request.
PURCHASE_INTENT-This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout activity.
+This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout + activity.
REQUEST_ID-This key provides you with a request identifier, which you can use to match asynchronous responses with requests.
+This key provides you with a request identifier, which you can use to match asynchronous + responses with requests.
com.android.vending.billing.RESPONSE_CODE-This response contains an Android Market 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 Android Market 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 contains an Android Market 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 Android Market 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.
com.android.vending.billing.IN_APP_NOTIFY-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_NOTIFYbroadcast intent, you send aGET_PURCHASE_INFORMATIONrequest with the notification IDs to retrieve message details.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_NOTIFYbroadcast intent, you send aGET_PURCHASE_INFORMATION+ request with the notification IDs to retrieve message details.com.android.vending.billing.PURCHASE_STATE_CHANGED-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.
+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.
Creating a storage mechanism for storing purchase information
-You must set up a database or some other mechanism for storing users' purchase information. The sample application provides an example database (PurchaseDatabase.java); however, the example database has been simplified for clarity and does not exhibit the security best practices that we recommend. If you have a remote server, we recommend that you store purchase information on your server instead of in a local database on a device. For more information about security best practices, see Security and Design.
+You must set up a database or some other mechanism for storing users' purchase information. The +sample application provides an example database (PurchaseDatabase.java); however, the example +database has been simplified for clarity and does not exhibit the security best practices that we +recommend. If you have a remote server, we recommend that you store purchase information on your +server instead of in a local database on a device. For more information about security best +practices, see Security and +Design.
-Note: If you store any purchase information on a device, be sure to encrypt the data and use a device-specific encryption key.
+Note: If you store any purchase information on a device, be sure to +encrypt the data and use a device-specific encryption key.
Creating a user interface for selecting items
-You must provide users with a means for selecting items that they want to purchase. Android Market provides the checkout user interface (which is where the user provides a form of payment and approves the purchase), but your application must provide a control (widget) that invokes the sendBillingRequest() method when a user selects an item for purchase.
You must provide users with a means for selecting items that they want to purchase. Android
+Market provides the checkout user interface (which is where the user provides a form of payment and
+approves the purchase), but your application must provide a control (widget) that invokes the
+sendBillingRequest() method when a user selects an item for purchase.
You can render the control and trigger the sendBillingRequest() method any way you want. The sample application uses a spinner widget and a button to present items to a user and trigger a billing request (see Dungeons.java). The user interface also shows a list of recently purchased items.
You can render the control and trigger the sendBillingRequest() method any way you
+want. The sample application uses a spinner widget and a button to present items to a user and
+trigger a billing request (see Dungeons.java). The user interface also shows a list of
+recently purchased items.
Downloads
See also
-
-
Android Market In-app Billing is an Android Market 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 Android Market's in-app billing service.
+Android Market In-app Billing is an Android Market 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 Android Market's in-app billing +service.
In-app Billing Architecture
-In-app billing uses an asynchronous message loop to convey billing requests and billing responses between your application and the Android Market server. In practice, your application never directly communicates with the Android Market server (see figure 1). Instead, your application sends billing requests to the Android Market application over interprocess communication (IPC) and receives purchase responses from the Android Market application in the form of asynchronous broadcast intents. Your application does not manage any network connections between itself and the Android Market server or use any special APIs from the Android platform.
+In-app billing uses an asynchronous message loop to convey billing requests and billing responses +between your application and the Android Market server. In practice, your application never directly +communicates with the Android Market server (see figure 1). Instead, your application sends billing +requests to the Android Market application over interprocess communication (IPC) and receives +purchase responses from the Android Market application in the form of asynchronous broadcast +intents. Your application does not manage any network connections between itself and the Android +Market server or use any special APIs from the Android platform.
-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.
+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.
- Figure 1. Your application sends and receives billing messages through the Android Market application, which handles all communication with the Android Market server.
+ Figure 1. Your application sends and receives billing messages through the + Android Market application, which handles all communication with the Android Market server.A typical in-app billing implementation relies on three components:
-
-
You may also want to incorporate two other components to support in-app billing:
-
-
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 Android Market application presents the checkout user interface to your user. When the user completes the checkout process, your application resumes.
+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 Android +Market 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 Android Market's in-app billing service (named MarketBillingService) using simple IPC method calls. The Android Market application responds to all billing requests synchronously, providing your application with status notifications and other information. The Android Market 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 Android Market application.
When the user initiates a purchase, your application sends billing messages to Android Market's
+in-app billing service (named MarketBillingService) using simple IPC method calls. The
+Android Market application responds to all billing requests synchronously, providing your
+application with status notifications and other information. The Android Market 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 Android Market 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.
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 {@link android.os.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 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.
+
The sendBillingRequest() method has a single {@link android.os.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 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. Android Market's in-app billing service supports the following five types of billing requests:
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. Android Market's in-app billing service supports the following five types of billing
+requests:
In-app Billing Responses
-The Android Market application responds to in-app billing requests with both synchronous and asynchronous responses. The synchronous response is a {@link android.os.Bundle} with the following three keys:
+The Android Market application responds to in-app billing requests with both synchronous and +asynchronous responses. The synchronous response is a {@link android.os.Bundle} with the following +three keys:
Some of these keys are not relevant to every request. For more information, see Messaging sequence later in this document.
+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:
+The asynchronous response messages are sent in the form of individual broadcast intents and +include the following:
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 is shown below:
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 is shown below:
{ "nonce" : 1836535032137741465,
"orders" :
@@ -137,34 +237,57 @@ parent.link=index.html
}
-For more information about the fields in this JSON string, see In-app Billing Broadcast Intents.
+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 each sendBillingRequest() 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 messaging sequence for a typical purchase request is shown in figure 2. Request types for
+each sendBillingRequest() 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:
-
-
- Your application sends a purchase request (
REQUEST_PURCHASEtype), specifying a product ID and other parameters.
- - The Android Market application sends your application a Bundle with the following keys:
RESPONSE_CODE,PURCHASE_INTENT, andREQUEST_ID. ThePURCHASE_INTENTkey provides a {@link android.app.PendingIntent}, which your application uses to start the checkout UI for the given product ID.
+ - Your application sends a purchase request (
REQUEST_PURCHASEtype), specifying a + product ID and other parameters.
+ - The Android Market application sends your application a Bundle with the following keys:
+
RESPONSE_CODE,PURCHASE_INTENT, andREQUEST_ID. The +PURCHASE_INTENTkey provides a {@link android.app.PendingIntent}, which your + application uses to start the checkout UI for the given product ID. - Your application launches the pending intent, which launches the checkout UI. -
- When the checkout flow finishes (that is, the user successfully purchases the item or cancels the purchase), Android Market sends your application a notification message (an
IN_APP_NOTIFYbroadcast intent). The notification message includes a notification ID, which references the transaction.
- - Your application requests the transaction information by sending a
GET_PURCHASE_STATE_CHANGEDrequest, specifying the notification ID for the transaction.
- - The Android Market application sends a Bundle with a
RESPONSE_CODEkey and aREQUEST_IDkey. - - Android Market sends the transaction information to your application in a
PURCHASE_STATE_CHANGEDbroadcast intent.
- - Your application confirms that you received the transaction information for the given notification ID by sending a confirmation message (
CONFIRM_NOTIFICATIONStype), specifying the notification ID for which you received transaction information.
- - The Android Market application sends your application a Bundle with a
RESPONSE_CODEkey and aREQUEST_IDkey.
+ - When the checkout flow finishes (that is, the user successfully purchases the item or cancels
+ the purchase), Android Market sends your application a notification message (an
+
IN_APP_NOTIFYbroadcast intent). The notification message includes a notification ID, + which references the transaction.
+ - Your application requests the transaction information by sending a
+
GET_PURCHASE_STATE_CHANGEDrequest, specifying the notification ID for the + transaction.
+ - The Android Market application sends a Bundle with a
RESPONSE_CODEkey and a +REQUEST_IDkey. + - Android Market sends the transaction information to your application in a
+
PURCHASE_STATE_CHANGEDbroadcast intent.
+ - Your application confirms that you received the transaction information for the given
+ notification ID by sending a confirmation message (
CONFIRM_NOTIFICATIONStype), + specifying the notification ID for which you received transaction information.
+ - The Android Market application sends your application a Bundle with a
+
RESPONSE_CODEkey and aREQUEST_IDkey.
Note: You must launch the pending intent from an activity context and not an application context.
+Note: You must launch the pending intent from an activity context +and not an application context.
Figure 2. Message sequence for a purchase request.
-The messaging sequence for a restore transaction request is shown in figure 3. Request types for each sendBillingRequest() 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.
The messaging sequence for a restore transaction request is shown in figure 3. Request types for
+each sendBillingRequest() 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.
@@ -173,11 +296,20 @@ parent.link=index.html
The request triggers three responses. The first is a {@link android.os.Bundle} with a RESPONSE_CODE key and a REQUEST_ID key. Next, the Android Market application sends a RESPONSE_CODE broadcast intent, which provides status information or error information about the request. As always, the RESPONSE_CODE message references a specific request ID, so you can determine which request a RESPONSE_CODE message pertains to.
The request triggers three responses. The first is a {@link android.os.Bundle} with a
+RESPONSE_CODE key and a REQUEST_ID key. Next, the Android Market
+application sends a RESPONSE_CODE broadcast intent, which provides status information
+or error information about the request. As always, the RESPONSE_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, although you do not need to respond to this intent with a CONFIRM_NOTIFICATIONS message.
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, although you do not need to respond to this
+intent with a CONFIRM_NOTIFICATIONS message.
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.
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.
@@ -186,15 +318,43 @@ parent.link=index.html
The synchronous response for a CHECK_BILLING_SUPPORTED request provides a Bundle with a server response code. A RESULT_OK response code indicates that in-app billing is supported; a RESULT_BILLING_UNAVAILABLE response 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 Android Market server.
The synchronous response for a CHECK_BILLING_SUPPORTED request provides a Bundle
+with a server response code. A RESULT_OK response code indicates that in-app billing
+is supported; a RESULT_BILLING_UNAVAILABLE response 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 Android Market server.
Handling IN_APP_NOTIFY messages
-Usually, your application receives an IN_APP_NOTIFY broadcast intent from Android Market in response to a REQUEST_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. Android Market responds with a PURCHASE_STATE_CHANGED broadcast intent, which contains the details of the purchase state change. Your application then sends a CONFIRM_NOTIFICATIONS message, informing Android Market that you've received the purchase state change information.
Usually, your application receives an IN_APP_NOTIFY broadcast intent from Android
+Market in response to a REQUEST_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. Android Market responds with a
+PURCHASE_STATE_CHANGED broadcast intent, which contains the details of the purchase
+state change. Your application then sends a CONFIRM_NOTIFICATIONS message, informing
+Android Market that you've received the purchase state change information.
When Android Market receives a CONFIRM_NOTIFICATIONS message for a given message, it usually stops sending IN_APP_NOTIFY intents for that message. However, there are some cases where Android Market may send repeated IN_APP_NOTIFY intents for a message even though your application has sent a CONFIRM_NOTIFICATIONS message. This can occur if a device loses network connectivity while you are sending the CONFIRM_NOTIFICATIONS message. In this case, Android Market might not receive your CONFIRM_NOTIFICATIONS message and it could send multiple IN_APP_NOTIFY messages until it receives acknowledgement that you received the message. Therefore, your application must be able to recognize that the subsequent IN_APP_NOTIFY messages are for a previously processed transaction. You can do this by checking the orderID that's contained in the JSON string because every transaction has a unique orderId.
When Android Market receives a CONFIRM_NOTIFICATIONS message for a given message, it
+usually stops sending IN_APP_NOTIFY intents for that message. However, there are some
+cases where Android Market may send repeated IN_APP_NOTIFY intents for a message even
+though your application has sent a CONFIRM_NOTIFICATIONS message. This can occur if a
+device loses network connectivity while you are sending the CONFIRM_NOTIFICATIONS
+message. In this case, Android Market might not receive your CONFIRM_NOTIFICATIONS
+message and it could send multiple IN_APP_NOTIFY messages until it receives
+acknowledgement that you received the message. Therefore, your application must be able to recognize
+that the subsequent IN_APP_NOTIFY messages are for a previously processed transaction.
+You can do this by checking the orderID that's contained in the JSON string because
+every transaction has a unique orderId.
There are two cases where your application may also receive IN_APP_NOTIFY broadcast intents even though your application has not sent a REQUEST_PURCHASE message. Figure 5 shows the messaging sequence for both of these cases. Request types for each sendBillingRequest() method are shown in bold, broadcast intents are shown in italic. For clarity, figure 5 does not show the RESPONSE_CODE broadcast intents that are sent for every request.
There are two cases where your application may also receive IN_APP_NOTIFY broadcast
+intents even though your application has not sent a REQUEST_PURCHASE message. Figure 5
+shows the messaging sequence for both of these cases. Request types for each
+sendBillingRequest() method are shown in bold, broadcast intents are
+shown in italic. For clarity, figure 5 does not show the RESPONSE_CODE
+broadcast intents that are sent for every request.
@@ -203,32 +363,77 @@ parent.link=index.html
In the first case, your application can receive an IN_APP_NOTIFY broadcast intent when a user has your application installed on two (or more) devices and the user makes an in-app purchase from one of the devices. In this case, Android Market sends an IN_APP_NOTIFY message to the second device, informing the application that there is a purchase state change. Your application can handle this message the same way it handles the response from an application-initiated REQUEST_PURCHASE message, so that ultimately your application receives a PURCHASE_STATE_CHANGED broadcast intent message that includes information about the item that has been purchased. This applies only to items that have their purchase type set to "managed per user account."
In the first case, your application can receive an IN_APP_NOTIFY broadcast intent
+when a user has your application installed on two (or more) devices and the user makes an in-app
+purchase from one of the devices. In this case, Android Market sends an IN_APP_NOTIFY
+message to the second device, informing the application that there is a purchase state change. Your
+application can handle this message the same way it handles the response from an
+application-initiated REQUEST_PURCHASE message, so that ultimately your application
+receives a PURCHASE_STATE_CHANGED broadcast intent message that includes information
+about the item that has been purchased. This applies only to items that have their purchase type set
+to "managed per user account."
In the second case, your application can receive an IN_APP_NOTIFY broadcast intent when Android Market receives a refund notification from Google Checkout. In this case, Android Market sends an IN_APP_NOTIFY message to your application. Your application can handle this message the same way it handles responses from an application-initiated REQUEST_PURCHASE message so that ultimately your application receives a PURCHASE_STATE_CHANGED message that includes information about the item that has been refunded. The refund information is included in the JSON string that accompanies the PURCHASE_STATE_CHANGED broadcast intent. Also, the purchaseState field in the JSON string is set to 2.
In the second case, your application can receive an IN_APP_NOTIFY broadcast intent
+when Android Market receives a refund notification from Google Checkout. In this case, Android
+Market sends an IN_APP_NOTIFY message to your application. Your application can handle
+this message the same way it handles responses from an application-initiated
+REQUEST_PURCHASE message so that ultimately your application receives a
+PURCHASE_STATE_CHANGED message that includes information about the item that has been
+refunded. The refund information is included in the JSON string that accompanies the
+PURCHASE_STATE_CHANGED broadcast intent. Also, the purchaseState field in
+the JSON string is set to 2.
Security Controls
-To help ensure the integrity of the transaction information that is sent to your application, Android Market signs the JSON string that is contained in the PURCHASE_STATE_CHANGED broadcast intent. Android Market uses the private key that is associated with your publisher account to create this signature. The publisher site generates an RSA key pair for each publisher account. You can find the public key portion of this key pair on your account's profile page. It is the same public key that is used with Android Market licensing.
To help ensure the integrity of the transaction information that is sent to your application,
+Android Market signs the JSON string that is contained in the PURCHASE_STATE_CHANGED
+broadcast intent. Android Market uses the private key that is associated with your publisher account
+to create this signature. The publisher site generates an RSA key pair for each publisher account.
+You can find the public key portion of this key pair on your account's profile page. It is the same
+public key that is used with Android Market licensing.
When Android Market signs a billing response, it includes the signed JSON string (unencrypted) and the signature. When your application receives this signed response you can use the public key portion of your RSA key pair to verify the signature. By performing signature verification you can help detect responses that have been tampered with or that have been spoofed. You can perform this signature verification step in your application; however, if your application connects to a secure remote server then we recommend that you perform the signature verification on that server.
+When Android Market signs a billing response, it includes the signed JSON string (unencrypted) +and the signature. When your application receives this signed response you can use the public key +portion of your RSA key pair to verify the signature. By performing signature verification you can +help detect responses that have been tampered with or that have been spoofed. You can perform this +signature verification step in your application; however, if your application connects to a secure +remote server then we recommend that you perform the signature verification on that server.
-In-app billing also uses nonces (a random number used once) to help verify the integrity of the purchase information that's returned from Android Market. Your application must generate a nonce and send it with a GET_PURCHASE_INFORMATION request and a RESTORE_TRANSACTIONS request. When Android Market receives the request, it adds the nonce to the JSON string that contains the transaction information. The JSON string is then signed and returned to your application. When your application receives the JSON string, you need to verify the nonce as well as the signature of the JSON string.
In-app billing also uses nonces (a random number used once) to help verify the integrity of the
+purchase information that's returned from Android Market. Your application must generate a nonce and
+send it with a GET_PURCHASE_INFORMATION request and a RESTORE_TRANSACTIONS
+request. When Android Market receives the request, it adds the nonce to the JSON string that
+contains the transaction information. The JSON string is then signed and returned to your
+application. When your application receives the JSON string, you need to verify the nonce as well as
+the signature of the JSON string.
For more information about best practices for security and design, see Security and Design.
+For more information about best practices for security and design, see Security and Design.
In-app Billing Requirements and Limitations
-Before you get started with in-app billing, be sure to review the following requirements and limitations.
+Before you get started with in-app billing, be sure to review the following requirements and +limitations.
-
-
- In-app billing can be implemented only in applications that you publish through Android Market. +
- In-app billing can be implemented only in applications that you publish through Android + Market.
- You must have a Google Checkout Merchant account to use Android Market In-app Billing. -
- If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing requires version 2.3.4 (or higher) of the Android Market application. -
- An application can use in-app billing only if the device is running Android 1.6 (API level 4) or higher. -
- You can use in-app billing to sell only digital content. You cannot use in-app billing to sell physical goods, personal services, or anything that requires physical delivery. -
- Android Market does not provide any form of content delivery. You are responsible for delivering the digital content that you sell in your applications. -
- You cannot implement in-app billing on a device that never connects to the network. To complete in-app purchase requests, a device must be able to access the Android Market server over the network. +
- If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of + the MyApps application. If your device is running any other version of Android, in-app billing + requires version 2.3.4 (or higher) of the Android Market application. +
- An application can use in-app billing only if the device is running Android 1.6 (API level 4) + or higher. +
- You can use in-app billing to sell only digital content. You cannot use in-app billing to sell + physical goods, personal services, or anything that requires physical delivery. +
- Android Market does not provide any form of content delivery. You are responsible for + delivering the digital content that you sell in your applications. +
- You cannot implement in-app billing on a device that never connects to the network. To + complete in-app purchase requests, a device must be able to access the Android Market server over + the network.
For more information about in-app billing requirements, see In-App Billing Availability and Policies.
+For more information about in-app billing requirements, see In-App Billing Availability +and Policies.
diff --git a/docs/html/guide/market/billing/billing_reference.jd b/docs/html/guide/market/billing/billing_reference.jd index 292823dc9f5ce..a95f3898057b7 100755 --- a/docs/html/guide/market/billing/billing_reference.jd +++ b/docs/html/guide/market/billing/billing_reference.jd @@ -14,15 +14,21 @@ parent.link=index.htmlDownloads
See also
-
-
- Overview of In-app Billing -
- Implementing In-app Billing -
- Security and Design -
- Testing In-app Billing -
- Administering In-app Billing +
- Overview of In-app + Billing +
- Implementing In-app + Billing +
- Security and + Design +
- Testing In-app + Billing +
- Administering In-app + Billing
Android Market Server Response Codes for In-app Billing
-The following table lists all of the server response codes that are sent from Android Market to your application. Android Market sends these response codes asynchronously as response_code extras in the com.android.vending.billing.RESPONSE_CODE broadcast intent. Your application must handle all of these response codes.
The following table lists all of the server response codes that are sent from Android Market to
+your application. Android Market sends these response codes asynchronously as
+response_code extras in the com.android.vending.billing.RESPONSE_CODE
+broadcast intent. Your application must handle all of these response codes.
Table 1. Summary of response codes returned by Android Market.
+Table 1. Summary of response +codes returned by Android Market.
RESULT_OK |
- Indicates that the request was sent to the server successfully. When this code is returned in response to a CHECK_BILLING_SUPPORTED request, indicates that billing is supported. |
+ Indicates that the request was sent to the server successfully. When this code is returned in
+ response to a CHECK_BILLING_SUPPORTED request, indicates that billing is
+ supported. |
RESULT_USER_CANCELED |
- Indicates that the user pressed the back button on the checkout page instead of buying the item. | +Indicates that the user pressed the back button on the checkout page instead of buying the + item. |
RESULT_SERVICE_UNAVAILABLE |
@@ -61,11 +74,15 @@ parent.link=index.html
||
RESULT_BILLING_UNAVAILABLE |
- Indicates that in-app billing is not available because the API_VERSION that you specified is not recognized by the Android Market application or the user is ineligible for in-app billing (for example, the user resides in a country that prohibits in-app purchases). |
+ Indicates that in-app billing is not available because the API_VERSION that you
+ specified is not recognized by the Android Market application or the user is ineligible for in-app
+ billing (for example, the user resides in a country that prohibits in-app purchases). |
RESULT_ITEM_UNAVAILABLE |
- Indicates that Android Market cannot find the requested item in the application's product list. This can happen if the product ID is misspelled in your REQUEST_PURCHASE request or if an item is unpublished in the application's product list. |
+ Indicates that Android Market cannot find the requested item in the application's product
+ list. This can happen if the product ID is misspelled in your REQUEST_PURCHASE
+ request or if an item is unpublished in the application's product list. |
RESULT_ERROR |
@@ -74,16 +91,26 @@ parent.link=index.html
||
RESULT_DEVELOPER_ERROR |
- Indicates that an application is trying to make an in-app billing request but the application has not declared the com.android.vending.BILLING permission in its manifest. Can also indicate that an application is not properly signed, or that you sent a malformed request, such as a request with missing Bundle keys or a request that uses an unrecognized request type. | +Indicates that an application is trying to make an in-app billing request but the application + has not declared the com.android.vending.BILLING permission in its manifest. Can also indicate + that an application is not properly signed, or that you sent a malformed request, such as a + request with missing Bundle keys or a request that uses an unrecognized request type. |
In-app Billing Service Interface
-The following section describes the interface for Android Market's in-app billing service. The interface is defined in the IMarketBillingService.aidl file, which is included with the in-app billing sample application.
The interface consists of a single request method sendBillingRequest(). This method takes a single {@link android.os.Bundle} parameter. The Bundle parameter includes several key-value pairs, which are summarized in table 2.
The following section describes the interface for Android Market's in-app billing service. The
+interface is defined in the IMarketBillingService.aidl file, which is included with the
+in-app billing sample
+application.
The interface consists of a single request method sendBillingRequest(). This method
+takes a single {@link android.os.Bundle} parameter. The Bundle parameter includes several key-value
+pairs, which are summarized in table 2.
Table 2. Description of Bundle keys passed in a sendBillingRequest() request.
Table 2. Description of Bundle keys passed in a
+sendBillingRequest() request.
BILLING_REQUEST |
String |
- CHECK_BILLING_SUPPORTED, REQUEST_PURCHASE, GET_PURCHASE_INFORMATION, CONFIRM_NOTIFICATIONS, or RESTORE_TRANSACTIONS |
+ CHECK_BILLING_SUPPORTED, REQUEST_PURCHASE,
+ GET_PURCHASE_INFORMATION, CONFIRM_NOTIFICATIONS, or
+ RESTORE_TRANSACTIONS |
Yes | -The type of billing request you are making with the sendBillingRequest() request. The possible values are discussed more below this table. |
+ The type of billing request you are making with the sendBillingRequest() request.
+ The possible values are discussed more below this table. |
API_VERSION |
int |
1 | Yes | -The version of Android Market's in-app billing service you are using. The current version is 1. | +The version of Android Market's in-app billing service you are using. The current version is + 1. | |
PACKAGE_NAME |
@@ -120,28 +151,42 @@ parent.link=index.html
String |
Any valid product identifier. | Required for REQUEST_PURCHASE requests. |
- The product ID of the item you are making a billing request for. Every in-app item that you sell using Android Market's in-app billing service must have a unique product ID, which you specify on the Android Market publisher site. | +The product ID of the item you are making a billing request for. Every in-app item that you + sell using Android Market's in-app billing service must have a unique product ID, which you + specify on the Android Market publisher site. | |
NONCE |
long |
Any valid long value. |
- Required for GET_PURCHASE_INFORMATION and RESTORE_TRANSACTIONS requests. |
- A number used once. Your application must generate and send a nonce with each GET_PURCHASE_INFORMATION and RESTORE_TRANSACTIONS request. The nonce is returned with the PURCHASE_STATE_CHANGED broadcast intent, so you can use this value to verify the integrity of transaction responses form Android Market. |
+ Required for GET_PURCHASE_INFORMATION and RESTORE_TRANSACTIONS
+ requests. |
+ A number used once. Your application must generate and send a nonce with each
+ GET_PURCHASE_INFORMATION and RESTORE_TRANSACTIONS request. The nonce is
+ returned with the PURCHASE_STATE_CHANGED broadcast intent, so you can use this value
+ to verify the integrity of transaction responses form Android Market. |
NOTIFY_IDS |
Array of long values |
Any valid array of long values |
- Required for GET_PURCHASE_INFORMATION and CONFIRM_NOTIFICATIONS requests. |
- An array of notification identifiers. A notification ID is sent to your application in an IN_APP_NOTIFY broadcast intent every time a purchase changes state. You use the notification to retrieve the details of the purchase state change. |
+ Required for GET_PURCHASE_INFORMATION and CONFIRM_NOTIFICATIONS
+ requests. |
+ An array of notification identifiers. A notification ID is sent to your application in an
+ IN_APP_NOTIFY broadcast intent every time a purchase changes state. You use the
+ notification to retrieve the details of the purchase state change. |
DEVELOPER_PAYLOAD |
String |
Any valid String less than 256 characters long. |
No | -A developer-specified string that can be specified when you make a REQUEST_PURCHASE request. This field is returned in the JSON string that contains transaction information for an order. You can use this key to send supplemental information with an order. For example, you can use this key to send index keys with an order, which is useful if you are using a database to store purchase information. We recommend that you do not use this key to send data or content. |
+ A developer-specified string that can be specified when you make a
+ REQUEST_PURCHASE request. This field is returned in the JSON string that contains
+ transaction information for an order. You can use this key to send supplemental information with
+ an order. For example, you can use this key to send index keys with an order, which is useful if
+ you are using a database to store purchase information. We recommend that you do not use this key
+ to send data or content. |
CHECK_BILLING_SUPPORTED-This request verifies that the Android Market 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 verifies that the Android Market 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.
REQUEST_PURCHASE-This request sends a purchase message to the Android Market 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. Android Market then handles the financial transaction by displaying the checkout user interface.
+This request sends a purchase message to the Android Market 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. Android Market then handles the financial transaction by displaying + the checkout user interface.
GET_PURCHASE_INFORMATION-This request retrieves the details of a purchase state change. A purchase state change can occur when a purchase request is billed successfully or when a user cancels a transaction during checkout. It can also occur when a previous purchase is refunded. Android Market 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 retrieves the details of a purchase state change. A purchase state change can + occur when a purchase request is billed successfully or when a user cancels a transaction during + checkout. It can also occur when a previous purchase is refunded. Android Market notifies your + application when a purchase changes state, so you only need to send this request when there is + transaction information to retrieve.
CONFIRM_NOTIFICATIONS-This request acknowledges that your application received the details of a purchase state change. That is, this message confirms that you sent a
+GET_PURCHASE_INFORMATIONrequest for a given notification and that you received the purchase information for the notification.This request acknowledges that your application received the details of a purchase state + change. That is, this message confirms that you sent a
GET_PURCHASE_INFORMATION+ request for a given notification and that you received the purchase information for the + notification.RESTORE_TRANSACTIONS-This request retrieves a user's transaction status for managed purchases (see Choosing a Purchase Type for more information). You should send this message 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.
+This request retrieves a user's transaction status for managed purchases (see Choosing a + Purchase Type for more information). You should send this message 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.
Every in-app billing request generates a synchronous response. The response is a {@link android.os.Bundle} and can include one or more of the following keys:
+Every in-app billing request generates a synchronous response. The response is a {@link +android.os.Bundle} and can include one or more of the following keys:
RESPONSE_CODEThis key provides status information and error information about a request.
PURCHASE_INTENT-This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout activity.
+This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout + activity.
REQUEST_ID-This key provides you with a request identifier, which you can use to match asynchronous responses with requests.
+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 certain types of requests. Table 3 shows which keys are returned for each request type.
+Some of these keys are not relevant to certain types of requests. Table 3 shows which keys are +returned for each request type.
-Table 3. Description of Bundle keys that are returned with each in-app billing request type.
+Table 3. Description of Bundle keys that are returned with +each in-app billing request type.
CHECK_BILLING_SUPPORTED |
RESPONSE_CODE |
- RESULT_OK, RESULT_BILLING_UNAVAILABLE, RESULT_ERROR, RESULT_DEVELOPER_ERROR |
+ RESULT_OK, RESULT_BILLING_UNAVAILABLE, RESULT_ERROR,
+ RESULT_DEVELOPER_ERROR |
|||||||||||||||||
REQUEST_PURCHASE |
@@ -219,45 +286,77 @@ parent.link=index.html
| nonce | -A number used once. Your application generates the nonce and sends it with the GET_PURCHASE_INFORMATION request. Android Market sends the nonce back as part of the JSON string so you can verify the integrity of the message. |
+ A number used once. Your application generates the nonce and sends it with the
+ GET_PURCHASE_INFORMATION request. Android Market sends the nonce back as part of the
+ JSON string so you can verify the integrity of the message. |
| notificationId | -A unique identifier that is sent with an IN_APP_NOTIFY broadcast intent. Each notificationId corresponds to a specify message that is waiting to be retrieved on the Android Market server. Your application sends back the notificationId with the GET_PURCHASE_INFORMATION message so Android Market can determine which messages you are retrieving. |
+ A unique identifier that is sent with an IN_APP_NOTIFY broadcast intent. Each
+ notificationId corresponds to a specify message that is waiting to be retrieved on
+ the Android Market server. Your application sends back the notificationId with the
+ GET_PURCHASE_INFORMATION message so Android Market can determine which messages you
+ are retrieving. |
| orderId | -A unique order identifier for the transaction. This corresponds to the Google Checkout Order ID. | +A unique order identifier for the transaction. This corresponds to the Google Checkout Order + ID. |
| packageName | @@ -283,7 +389,8 @@ parent.link=index.html||
| productId | -The item's product identifier. Every item has a product ID, which you must specify in the application's product list on the Android Market publisher site. | +The item's product identifier. Every item has a product ID, which you must specify in the + application's product list on the Android Market publisher site. |
| purchaseTime | @@ -292,10 +399,12 @@ parent.link=index.html||
| purchaseState | -The purchase state of the order. Possible values are 0 (purchased), 1 (canceled), or 2 (refunded). | +The purchase state of the order. Possible values are 0 (purchased), 1 (canceled), or 2 + (refunded). |
| developerPayload | -A developer-specified string that contains supplemental information about an order. You can specify a value for this field when you make a REQUEST_PURCHASE request. |
+ A developer-specified string that contains supplemental information about an order. You can
+ specify a value for this field when you make a REQUEST_PURCHASE request. |
Downloads
See also
-
-
- Overview of In-app Billing -
- Implementing In-app Billing -
- Security and Design -
- Administering In-app Billing -
- In-app Billing Reference +
- Overview of In-app + Billing +
- Implementing In-app + Billing +
- Security and + Design +
- Administering In-app + Billing +
- In-app Billing + Reference
The Android Market publisher site provides several tools that help you test your in-app billing implementation before it is published. You can use these tools to create test accounts and purchase special reserved items that send static billing responses to your application.
+The Android Market publisher site provides several tools that help you test your in-app billing +implementation before it is published. You can use these tools to create test accounts and purchase +special reserved items that send static billing responses to your application.
-To test in-app billing in an application you must install the application on an Android-powered device. You cannot use the Android emulator to test in-app billing. The device you use for testing must run a standard version of the Android 1.6 or later platform (API level 4 or higher), and have the most current version of the Android Market application installed. If a device is not running the most current Android Market application, your application won't be able to send in-app billing requests to Android Market. For general information about how to set up a device for use in developing Android applications, see Using Hardware Devices.
+To test in-app billing in an application you must install the application on an Android-powered +device. You cannot use the Android emulator to test in-app billing. The device you use for testing +must run a standard version of the Android 1.6 or later platform (API level 4 or higher), and have +the most current version of the Android Market application installed. If a device is not running the +most current Android Market application, your application won't be able to send in-app billing +requests to Android Market. For general information about how to set up a device for use in +developing Android applications, see Using Hardware +Devices.
The following section shows you how to set up and use the in-app billing test tools.
Testing in-app purchases with static responses
-We recommend that you first test your in-app billing implementation using static responses from Android Market. This enables you to verify that your application is handling the primary Android Market responses correctly and that your application is able to verify signatures correctly.
+We recommend that you first test your in-app billing implementation using static responses from +Android Market. This enables you to verify that your application is handling the primary Android +Market responses correctly and that your application is able to verify signatures correctly.
-To test your implementation with static responses, you make an in-app billing request using a special item that has a reserved product ID. Each reserved product ID returns a specific static response from Android Market. No money is transferred when you make in-app billing requests with the reserved product IDs. Also, you cannot specify the form of payment when you make a billing request with a reserved product ID. Figure 1 shows the checkout flow for the reserved item that has the product ID android.test.purchased.
+To test your implementation with static responses, you make an in-app billing request using a +special item that has a reserved product ID. Each reserved product ID returns a specific static +response from Android Market. No money is transferred when you make in-app billing requests with the +reserved product IDs. Also, you cannot specify the form of payment when you make a billing request +with a reserved product ID. Figure 1 shows the checkout flow for the reserved item that has the +product ID android.test.purchased.
Figure 1. Checkout flow for the special reserved item android.test.purchased.
-You do not need to list the reserved products in your application's product list. Android Market already knows about the reserved product IDs. Also, you do not need to upload your application to the publisher site to perform static response tests with the reserved product IDs. You can simply install your application on a device, log into the device, and make billing requests using the reserved product IDs.
+You do not need to list the reserved products in your application's product list. Android Market +already knows about the reserved product IDs. Also, you do not need to upload your application to +the publisher site to perform static response tests with the reserved product IDs. You can simply +install your application on a device, log into the device, and make billing requests using the +reserved product IDs.
There are four reserved product IDs for testing static in-app billing responses:
- android.test.purchased
-
When you make an in-app billing request with this product ID, Android Market responds as though you successfully purchased an item. The response includes a JSON string, which contains fake purchase information (for example, a fake order ID). In some cases, the JSON string is signed and the response includes the signature so you can test your signature verification implementation using these responses.
+When you make an in-app billing request with this product ID, Android Market responds as + though you successfully purchased an item. The response includes a JSON string, which contains + fake purchase information (for example, a fake order ID). In some cases, the JSON string is + signed and the response includes the signature so you can test your signature verification + implementation using these responses.
- android.test.canceled
-
When you make an in-app billing request with this product ID Android Market responds as though the purchase was canceled. This can occur when an error is encountered in the order process, such as an invalid credit card, or when you cancel a user's order before it is charged.
+When you make an in-app billing request with this product ID Android Market responds as + though the purchase was canceled. This can occur when an error is encountered in the order + process, such as an invalid credit card, or when you cancel a user's order before it is + charged.
- android.test.refunded
-
When you make an in-app billing request with this product ID, Android Market responds as though the purchase was refunded. Refunds cannot be initiated through Android Market's in-app billing service. Refunds must be initiated by you (the merchant). After you process a refund request through your Google Checkout account, a refund message is sent to your application by Android Market. This occurs only when Android Market gets notification from Google Checkout that a refund has been made. For more information about refunds, see Handling IN_APP_NOTIFY messages and In-app Billing Pricing.
+When you make an in-app billing request with this product ID, Android Market responds as + though the purchase was refunded. Refunds cannot be initiated through Android Market's in-app + billing service. Refunds must be initiated by you (the merchant). After you process a refund + request through your Google Checkout account, a refund message is sent to your application by + Android Market. This occurs only when Android Market gets notification from Google Checkout that + a refund has been made. For more information about refunds, see Handling + IN_APP_NOTIFY messages and In-app Billing + Pricing.
- android.test.item_unavailable
-
When you make an in-app billing request with this product ID, Android Market responds as though the item being purchased was not listed in your application's product list.
+When you make an in-app billing request with this product ID, Android Market responds as + though the item being purchased was not listed in your application's product list.
In some cases, the reserved items may return signed static responses, which lets you test signature verification in your application. To test signature verification with the special reserved product IDs, you may need to set up test accounts or upload your application as a unpublished draft application. Table 1 shows you the conditions under which static responses are signed.
+In some cases, the reserved items may return signed static responses, which lets you test +signature verification in your application. To test signature verification with the special reserved +product IDs, you may need to set up test accounts or +upload your application as a unpublished draft application. Table 1 shows you the conditions under +which static responses are signed.
Table 1. Conditions under which static responses are signed.
@@ -120,68 +167,118 @@ Conditions under which static responses are signed.To make an in-app billing request with a reserved product ID, you simply construct a normal REQUEST_PURCHASE request, but instead of using a real product ID from your application's product list you use one of the reserved product IDs.
To make an in-app billing request with a reserved product ID, you simply construct a normal
+REQUEST_PURCHASE request, but instead of using a real product ID from your
+application's product list you use one of the reserved product IDs.
To test your application using the reserved product IDs, follow these steps:
- Install your application on an Android-powered device.
-
You cannot use the emulator to test in-app billing; you must install your application on a device to test in-app billing.
-To learn how to install an application on a device, see Running on a device.
+You cannot use the emulator to test in-app billing; you must install your application on a + device to test in-app billing.
+To learn how to install an application on a device, see Running on a + device.
- Sign in to your device with your developer account.
-
You do not need to use a test account if you are testing only with the reserved product IDs.
+You do not need to use a test account if you are testing only with the reserved product + IDs.
- - Verify that your device is running a supported version of the Android Market application or the MyApps application.
-
If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing requires version 2.3.4 (or higher) of the Android Market application. To learn how to check the version of the Android Market application, see Updating Android Market.
+ - Verify that your device is running a supported version of the Android Market
+ application or the MyApps application.
+
If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of + the MyApps application. If your device is running any other version of Android, in-app billing + requires version 2.3.4 (or higher) of the Android Market application. To learn how to check the + version of the Android Market application, see Updating Android + Market.
- Run your application and purchase the reserved product IDs.
Note: Making in-app billing requests with the reserved product IDs overrides the usual Android Market production system. When you send an in-app billing request for a reserved product ID, the quality of service will not be comparable to the production environment.
+Note: Making in-app billing requests with the reserved product IDs +overrides the usual Android Market production system. When you send an in-app billing request for a +reserved product ID, the quality of service will not be comparable to the production +environment.
Testing In-app Purchases Using Your Own Product IDs
-After you finish your static response testing, and you verify that signature verification is working in your application, you can test your in-app billing implementation by making actual in-app purchases. Testing real in-app purchases enables you to test the end-to-end in-app billing experience, including the actual responses from Android Market and the actual checkout flow that users will experience in your application.
+After you finish your static response testing, and you verify that signature verification is +working in your application, you can test your in-app billing implementation by making actual in-app +purchases. Testing real in-app purchases enables you to test the end-to-end in-app billing +experience, including the actual responses from Android Market and the actual checkout flow that +users will experience in your application.
-Note: You do not need to publish your application to do end-to-end testing. You only need to upload your draft application to perform end-to-end testing.
+Note: You do not need to publish your application to do end-to-end +testing. You only need to upload your draft application to perform end-to-end testing.
-To test your in-app billing implementation with actual in-app purchases, you will need to register at least one test account on the Android Market publisher site. You cannot use your developer account to test the complete in-app purchase process because Google Checkout does not let you buy items from yourself. If you have not set up test accounts before, see Setting up test accounts.
+To test your in-app billing implementation with actual in-app purchases, you will need to +register at least one test account on the Android Market publisher site. You cannot use your +developer account to test the complete in-app purchase process because Google Checkout does not let +you buy items from yourself. If you have not set up test accounts before, see Setting up test +accounts.
-Also, a test account can purchase an item in your product list only if the item is published. The application does not need to be published, but the item does need to be published.
+Also, a test account can purchase an item in your product list only if the item is published. The +application does not need to be published, but the item does need to be published.
-When you use a test account to purchase items, the test account is billed through Google Checkout and your Google Checkout Merchant account receives a payout for the purchase. Therefore, you may want to refund purchases that are made with test accounts, otherwise the purchases will show up as actual payouts to your merchant account.
+When you use a test account to purchase items, the test account is billed through Google Checkout +and your Google Checkout Merchant account receives a payout for the purchase. Therefore, you may +want to refund purchases that are made with test accounts, otherwise the purchases will show up as +actual payouts to your merchant account.
To test your in-app billing implementation with actual purchases, follow these steps:
- Upload your application as a draft application to the publisher site.
-
You do not need to publish your application to perform end-to-end testing with real product IDs. To learn how to upload an application to Android Market, see Uploading applications.
+You do not need to publish your application to perform end-to-end testing with real product + IDs. To learn how to upload an application to Android Market, see Uploading + applications.
- Add items to the application's product list.
-
Make sure that you publish the items (the application can remain unpublished). See Creating a product list to learn how to do this.
+Make sure that you publish the items (the application can remain unpublished). See Creating a product + list to learn how to do this.
- Install your application on an Android-powered device.
-
You cannot use the emulator to test in-app billing; you must install your application on a device to test in-app billing.
-To learn how to install an application on a device, see Running on a device.
+You cannot use the emulator to test in-app billing; you must install your application on a + device to test in-app billing.
+To learn how to install an application on a device, see Running on a + device.
- Make one of your test accounts the primary account on your device.
-
To perform end-to-end testing of in-app billing, the primary account on your device must be one of the test accounts that you registered on the Android Market site. If the primary account on your device is not a test account, you must do a factory reset of the device and then sign in with one of your test accounts. To perform a factory reset, do the following:
+To perform end-to-end testing of in-app billing, the primary account on your device must be + one of the test accounts + that you registered on the Android Market site. If the primary account on your device is not a + test account, you must do a factory reset of the device and then sign in with one of your test + accounts. To perform a factory reset, do the following:
- Open Settings on your device.
- Touch Privacy.
- Touch Factory data reset.
- Touch Reset phone. -
- After the phone resets, be sure to sign in with one of your test accounts during the device setup process. +
- After the phone resets, be sure to sign in with one of your test accounts during the + device setup process.
- - Verify that your device is running a supported version of the Android Market application or the MyApps application.
-
If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing requires version 2.3.4 (or higher) of the Android Market application. To learn how to check the version of the Android Market application, see Updating Android Market.
+ - Verify that your device is running a supported version of the Android Market
+ application or the MyApps application.
+
If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of + the MyApps application. If your device is running any other version of Android, in-app billing + requires version 2.3.4 (or higher) of the Android Market application. To learn how to check the + version of the Android Market application, see Updating Android + Market.
- Make in-app purchases in your application.
Note: The only way to change the primary account on a device is to do a factory reset, making sure you log on with your primary account first.
+Note: The only way to change the primary account on a device is to +do a factory reset, making sure you log on with your primary account first.
When you are finished testing your in-app billing implementation, you are ready to
publish your application on Android Market. You can follow the normal steps for Topics
Android Market In-app Billing is an Android Market service that lets you sell digital content in your applications. You can use the service to sell a wide range of content, including downloadable content such as media files or photos, and virtual content such as game levels or potions. Android Market In-app Billing is an Android Market service that lets you sell digital content in
+your applications. You can use the service to sell a wide range of content, including downloadable
+content such as media files or photos, and virtual content such as game levels or potions. When you use Android Market's in-app billing service to sell an item, Android Market handles all checkout details so your application never has to directly process any financial transactions. Android Market uses the same checkout service that is used for application purchases, so your users experience a consistent and familiar purchase flow (see figure 1). Also, the transaction fee for in-app purchases is the same as the transaction fee for application purchases (30%). When you use Android Market's in-app billing service to sell an item, Android Market handles all
+checkout details so your application never has to directly process any financial transactions.
+Android Market uses the same checkout service that is used for application purchases, so your users
+experience a consistent and familiar purchase flow (see figure 1). Also, the transaction fee for
+in-app purchases is the same as the transaction fee for application purchases (30%). Any application that you publish through Android Market can implement in-app billing. No special account or registration is required other than an Android Market publisher account and a Google Checkout Merchant account. Also, because the service uses no dedicated framework APIs, you can add in-app billing to any application that uses a minimum API level of 4 or higher. Any application that you publish through Android Market can implement in-app billing. No special
+account or registration is required other than an Android Market publisher account and a Google
+Checkout Merchant account. Also, because the service uses no dedicated framework APIs, you can add
+in-app billing to any application that uses a minimum API level of 4 or higher. To help you integrate in-app billing into your application, the Android SDK provides a sample application that demonstrates a simple implementation of in-app billing. The sample application contains examples of billing-related classes you can use to implement in-app billing in your application. It also contains examples of the database, user interface, and business logic you might use to implement in-app billing. To help you integrate in-app billing into your application, the Android SDK provides a sample
+application that demonstrates a simple implementation of in-app billing. The sample application
+contains examples of billing-related classes you can use to implement in-app billing in your
+application. It also contains examples of the database, user interface, and business logic you might
+use to implement in-app billing. Important: Although the sample application is a working example of how you can implement in-app billing, we strongly recommend that you modify and obfuscate the sample code before you use it in a production application. For more information, see Security and Design. Important: Although the sample application is a working example
+of how you can implement in-app billing, we strongly recommend that you modify and
+obfuscate the sample code before you use it in a production application. For more information, see
+Security and Design.
- Figure 1. Applications initiate in-app billing requests through their own UI (first screen). Android Market responds to the request by providing the checkout user interface (middle screen). When checkout is complete, the application resumes.
+ Figure 1. Applications initiate in-app billing requests through their own UI
+ (first screen). Android Market responds to the request by providing the checkout user interface
+ (middle screen). When checkout is complete, the application resumes.
To learn more about Android Market's in-app billing service and start integrating it into your applications, read the following documents: To learn more about Android Market's in-app billing service and start integrating it into your
+applications, read the following documents:
-
Reference
Downloads
-
-