From 0369cf98743e72d052eb5542125f58d1ad2f7f61 Mon Sep 17 00:00:00 2001 From: Bill Gruber Date: Wed, 27 Apr 2011 11:20:54 -0700 Subject: Cherry pick from Honeycomb Change ID I8d57d12828afab700d76f9b19195817a0adfe080 IAB docs: adds best practices for pending transaction UI Change-Id: I9e27f3421e57b20c5b5961fc680fe89e3d5e865b --- .../html/guide/market/billing/billing_integrate.jd | 62 ++++++++++++++++++---- 1 file changed, 53 insertions(+), 9 deletions(-) (limited to 'docs/html/guide') diff --git a/docs/html/guide/market/billing/billing_integrate.jd b/docs/html/guide/market/billing/billing_integrate.jd index 59344ba..1a1f02a 100755 --- a/docs/html/guide/market/billing/billing_integrate.jd +++ b/docs/html/guide/market/billing/billing_integrate.jd @@ -299,7 +299,9 @@ onto a device to run it. To run the sample application, do the following:

purchases will show up as actual payouts to your merchant account.

-

Note: Debug log messages are turned off by default in the sample application. You can turn them on by setting the variable DEBUG to true in the Consts.java file.

+

Note: Debug log messages are turned off by default in the +sample application. You can turn them on by setting the variable DEBUG +to true in the Consts.java file.

Adding the AIDL file to your project

@@ -598,7 +600,7 @@ to the Bundle prior to invoking the sendBillingRequest() method.

PURCHASE_INTENT key provides you with a {@link android.app.PendingIntent}, which you can use to launch the checkout UI.

-
Launching the pending intent
+
Using 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 @@ -649,16 +651,58 @@ application.

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 RESPONSE_CODE broadcast intent returns RESULT_OK, which +indicates that the request was successfully sent. (To be clear, a RESULT_OK response +does not indicate that the requested purchase was successful; it indicates that the request was sent +successfully to Android Market.)

+ +

Next, when the requested transaction changes state (for example, the purchase is successfully +charged to a credit card or the user cancels the purchase), 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.

+ +

Note: The Android Market application also sends +an IN_APP_NOTIFY for refunds. For more information, see Handling IN_APP_NOTIFY messages.

+

Because the purchase process is not instantaneous and can take several seconds (or more), you +must assume that a purchase request is pending from the time you receive a RESULT_OK +message until you receive an IN_APP_NOTIFY message for the transaction. While the +transaction is pending, the Android Market checkout UI displays an "Authorizing purchase..." +notification; however, this notification is dismissed after 60 seconds and you should not rely on +this notification as your primary means of conveying transaction status to users. Instead, we +recommend that you do the following:

+ + + +

To use these two UI elements, you could invoke a status bar notification with a ticker-text +message that says "Purchase pending" when your application receives a RESULT_OK +message. Then, when your application receives an IN_APP_NOTIFY message, you could +update the notification with a new message that says "Purchase succeeded" or "Purchase failed." When +a user touches the expanded status bar notification, you could launch the activity that shows the +status of pending and completed in-app purchases.

+ +

If you use some other UI technique to inform users about the state of a pending transaction, +be sure that your pending status UI does not block your application. For example, you should avoid +using a hovering progress wheel to convey the status of a pending transaction because a pending +transaction could last a long time, particularly if a device loses network connectivity and cannot +receive transaction updates from Android Market.

+ +

Important: If a user purchases a managed item, you must prevent +the user from purchasing the item again while the original transaction is pending. If a user +attempts to purchase a managed item twice, and the first transaction is still pending, Android +Market will display an error to the user; however, Android Market will not send an error to your +application notifying you that the second purchase request was canceled. This might cause your +application to get stuck in a pending state while it waits for an IN_APP_NOTIFY message +for the second purchase request.

+

Retrieving transaction information for a purchase or refund (GET_PURCHASE_INFORMATION)

You retrieve transaction information in response to an IN_APP_NOTIFY broadcast -- cgit v1.1