From 32db3fc25b1067accff8d4671d7a0a1428d4b546 Mon Sep 17 00:00:00 2001
From: Bill Gruber <billg@google.com>
Date: Wed, 29 Jun 2011 10:17:19 -0700
Subject: [PATCH] Cherry pick from Honeycomb-mr2 Change ID 
 I6ba2dca8606cdd4608d42f219b115536facf099f IAB docs: fixes and updates

Change-Id: I0a9d782a83ca16b27c3e90f7bfc19bb9bca5e908
---
 docs/html/guide/guide_toc.cs                  |  3 -
 .../guide/market/billing/billing_about.html   | 12 ++++
 .../guide/market/billing/billing_about.jd     | 30 --------
 .../guide/market/billing/billing_admin.jd     |  5 ++
 .../guide/market/billing/billing_integrate.jd | 27 +++++--
 .../guide/market/billing/billing_overview.jd  | 70 +++++++++++++------
 .../guide/market/billing/billing_testing.jd   | 10 ++-
 7 files changed, 95 insertions(+), 62 deletions(-)
 create mode 100644 docs/html/guide/market/billing/billing_about.html
 delete mode 100755 docs/html/guide/market/billing/billing_about.jd
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index f7dbe30f41d69..ddfeb6181fd68 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -383,9 +383,6 @@
             <span class="en">In-app Billing</span></a>
         </div>
         <ul>
-          <li><a href="<?cs var:toroot?>guide/market/billing/billing_about.html">
-              <span class="en">About this Release</span></a>
-          </li>
           <li><a href="<?cs var:toroot?>guide/market/billing/billing_overview.html">
               <span class="en">In-app Billing Overview</span></a>
           </li>
diff --git a/docs/html/guide/market/billing/billing_about.html b/docs/html/guide/market/billing/billing_about.html
new file mode 100644
index 0000000000000..d8395df3bb670
--- /dev/null
+++ b/docs/html/guide/market/billing/billing_about.html
@@ -0,0 +1,12 @@
+<html>
+<head>
+<meta http-equiv="refresh"
+content="0;url=http://developer.android.com/guide/market/billing/index.html">
+<title>Redirecting...</title>
+</head>
+<body>
+<p>You should be redirected. Please <a
+href="http://developer.android.com/guide/market/billing/index.html">click
+here</a>.</p>
+</body>
+</html>
\ No newline at end of file
diff --git a/docs/html/guide/market/billing/billing_about.jd b/docs/html/guide/market/billing/billing_about.jd
deleted file mode 100755
index 5924170bb8339..0000000000000
--- a/docs/html/guide/market/billing/billing_about.jd
+++ /dev/null
@@ -1,30 +0,0 @@
-page.title=About this Release
-parent.title=In-app Billing
-parent.link=index.html
-@jd:body
-
-<div id="qv-wrapper">
-<div id="qv">
-  <h2>In this document</h2>
-  <ol>
-    <li><a href="#billing-about">About this Release</a></li>
-  </ol>
-  <h2>Downloads</h2>
-  <ol>
-    <li><a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">Sample Application</a></li>
-  </ol>
-  <h2>See also</h2>
-  <ol>
-    <li><a href="{@docRoot}guide/market/billing/billing_overview.html">Overview of In-app Billing</a></li>
-    <li><a href="{@docRoot}guide/market/billing/billing_integrate.html">Implementing In-app Billing</a></li>
-    <li><a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a></li>
-    <li><a href="{@docRoot}guide/market/billing/billing_testing.html">Testing In-app Billing</a></li>
-    <li><a href="{@docRoot}guide/market/billing/billing_admin.html">Administering In-app Billing</a></li>
-    <li><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></li>
-  </ol>
-</div>
-</div>
-
-<p>Android Market In-app Billing has reached the final launch milestone and is now available to developers and users. You can now publish applications that use Android Market's in-app billing service, and users can make in-app purchases. To find out how to implement in-app billing in your applications, see the  <a href="{@docRoot}guide/market/billing/index.html">documentation</a> and the <a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">sample application</a>.</p>
-
-
diff --git a/docs/html/guide/market/billing/billing_admin.jd b/docs/html/guide/market/billing/billing_admin.jd
index 939bbaa03e680..cbb4b29cfc475 100755
--- a/docs/html/guide/market/billing/billing_admin.jd
+++ b/docs/html/guide/market/billing/billing_admin.jd
@@ -202,6 +202,11 @@ IN_APP_NOTIFY messages</a> and <a
 href="http://www.google.com/support/androidmarket/bin/answer.py?answer=1153485">In-app Billing
 Pricing</a>.</p>
 
+<p class="caution"><strong>Important:</strong> You cannot use the Google Checkout API to issue
+refunds or cancel in-app billing transactions. You must do this manually through your Google
+Checkout merchant account. However, you can use the Google Checkout API to retrieve order
+information.</p>
+
 <h2 id="billing-testing-setup">Setting Up Test Accounts</h2>
 
 <p>The Android Market publisher site lets you set up one or more test accounts. A test account is a
diff --git a/docs/html/guide/market/billing/billing_integrate.jd b/docs/html/guide/market/billing/billing_integrate.jd
index 1a1f02a346887..3eebd595a492d 100755
--- a/docs/html/guide/market/billing/billing_integrate.jd
+++ b/docs/html/guide/market/billing/billing_integrate.jd
@@ -783,11 +783,17 @@ request identifier for the request.</p>
 <code>RESPONSE_CODE</code> broadcast intent. This broadcast intent provides status and error
 information about the request.</p>
 
-<p class="note"><strong>Note:</strong> As a best practice, you should not send a
-<code>CONFIRM_NOTIFICATIONS</code> 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 <code>IN_APP_NOTIFY</code> broadcast
-intent from Android Market indicating that you need to deliver the product.</p>
+<p>You must send a confirmation when you receive transaction information from Android Market. If you
+don't send a confirmation message, Android Market will continue sending
+<code>IN_APP_NOTIFY</code> messages for the transactions you have not confirmed. Also,
+your application must be able to handle <code>IN_APP_NOTIFY</code> messages that contain multiple
+orders.</p>
+
+<p>In addition, as a best practice, you should not send a <code>CONFIRM_NOTIFICATIONS</code> 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 <code>IN_APP_NOTIFY</code> broadcast intent from Android Market indicating
+that you need to deliver the product.</p>
 
 <h4>Restoring transaction information (RESTORE_TRANSACTIONS)</h4>
 
@@ -828,6 +834,10 @@ message contains the detailed transaction information. The transaction informati
 signed JSON string (unencrypted). The message includes the signature so you can verify the integrity
 of the signed string.</p>
 
+<p class="note"><strong>Note:</strong> You should use the <code>RESTORE_TRANSACTIONS</code>
+request type only when your application is installed for the first time on a device or when your
+application has been removed from a device and reinstalled.</p>
+
 <h3>Other service tasks</h3>
 
 <p>You may also want your {@link android.app.Service} to receive intent messages from your {@link
@@ -1061,7 +1071,12 @@ practices, see <a href="{@docRoot}guide/market/billing/billing_best_practices.ht
 Design</a>.</p>
 
 <p class="note"><strong>Note</strong>: If you store any purchase information on a device, be sure to
-encrypt the data and use a device-specific encryption key.</p>
+encrypt the data and use a device-specific encryption key. Also, if the purchase type for any of
+your items is "unmanaged," we recommend that you back up the purchase information for these items to
+a remote server or use Android's <a href="{@docRoot}guide/topics/data/backup.html">data
+backup</a> framework to back up the purchase information. Backing up purchase information for
+unmanaged items is important because unmanaged items cannot be restored by using the
+<code>RESTORE_TRANSACTIONS</code> request type.</p>
 
 <h3>Creating a user interface for selecting items</h3>
 
diff --git a/docs/html/guide/market/billing/billing_overview.jd b/docs/html/guide/market/billing/billing_overview.jd
index a42b772a2d57c..8f9fd4c616ccb 100755
--- a/docs/html/guide/market/billing/billing_overview.jd
+++ b/docs/html/guide/market/billing/billing_overview.jd
@@ -257,7 +257,10 @@ broadcast intents that are sent for every request.</p>
   <code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, and <code>REQUEST_ID</code>. The
   <code>PURCHASE_INTENT</code> key provides a {@link android.app.PendingIntent}, which your
   application uses to start the checkout UI for the given product ID.</li>
-  <li>Your application launches the pending intent, which launches the checkout UI.</li>
+  <li>Your application launches the pending intent, which launches the checkout UI.
+    <p class="note"><strong>Note:</strong> You must launch the pending intent from an activity
+    context and not an application context.</p>
+  </li>
   <li>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
   <code>IN_APP_NOTIFY</code> broadcast intent). The notification message includes a notification ID,
@@ -276,14 +279,21 @@ broadcast intents that are sent for every request.</p>
   <code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key.</li>
 </ol>
 
-<p class="note"><strong>Note:</strong> You must launch the pending intent from an activity context
-and not an application context.</p>
-
 <img src="{@docRoot}images/billing_request_purchase.png" height="231" id="figure2" />
 <p class="img-caption">
   <strong>Figure 2.</strong> Message sequence for a purchase request.
 </p>
 
+<p>Keep in mind, you must send a confirmation when you receive transaction information from Android
+Market (step 8 in figure 2). If you don't send a confirmation message, Android Market will
+continue sending <code>IN_APP_NOTIFY</code> messages for the transactions you have not
+confirmed. As a best practice, you should not send a <code>CONFIRM_NOTIFICATIONS</code> 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 <code>IN_APP_NOTIFY</code> broadcast intent from Android Market indicating
+that you need to deliver the product. Also, as a best practice, your application must be able to
+handle <code>IN_APP_NOTIFY</code> messages that contain multiple orders.</p>
+
 <p>The messaging sequence for a restore transaction request is shown in figure 3. Request types for
 each <code>sendBillingRequest()</code> method are shown in <strong>bold</strong>, broadcast intents
 are shown in <em>italic</em>. For clarity, figure 3 does not show the <code>RESPONSE_CODE</code>
@@ -308,6 +318,10 @@ pertains to.</p>
 information that is sent during a purchase request, although you do not need to respond to this
 intent with a <code>CONFIRM_NOTIFICATIONS</code> message.</p>
 
+<p class="note"><strong>Note:</strong> You should use the <code>RESTORE_TRANSACTIONS</code> request
+type only when your application is installed for the first time on a device or when your
+application has been removed from a device and reinstalled.</p>
+
 <p>The messaging sequence for checking whether in-app billing is supported is shown in figure 4. The
 request type for the <code>sendBillingRequest()</code> method is shown in <strong>bold</strong>.</p>
 
@@ -335,21 +349,32 @@ purchase has changed. To retrieve the details of that purchase, your application
 <code>GET_PURCHASE_INFORMATION</code> request. Android Market responds with a
 <code>PURCHASE_STATE_CHANGED</code> broadcast intent, which contains the details of the purchase
 state change. Your application then sends a <code>CONFIRM_NOTIFICATIONS</code> message, informing
-Android Market that you've received the purchase state change information.</p>
+Android Market that you have received the purchase state change information.</p>
 
-<p>When Android Market receives a <code>CONFIRM_NOTIFICATIONS</code> message for a given message, it
-usually stops sending <code>IN_APP_NOTIFY</code> intents for that message. However, there are some
-cases where Android Market may send repeated <code>IN_APP_NOTIFY</code> intents for a message even
-though your application has sent a <code>CONFIRM_NOTIFICATIONS</code> message. This can occur if a
-device loses network connectivity while you are sending the <code>CONFIRM_NOTIFICATIONS</code>
-message. In this case, Android Market might not receive your <code>CONFIRM_NOTIFICATIONS</code>
-message and it could send multiple <code>IN_APP_NOTIFY</code> messages until it receives
-acknowledgement that you received the message. Therefore, your application must be able to recognize
-that the subsequent <code>IN_APP_NOTIFY</code> messages are for a previously processed transaction.
-You can do this by checking the <code>orderID</code> that's contained in the JSON string because
-every transaction has a unique <code>orderId</code>.</p>
+<p>In some special cases, you may receive multiple <code>IN_APP_NOTIFY</code> messages even though
+you have confirmed receipt of the purchase information, or you may receive
+<code>IN_APP_NOTIFY</code> messages for a purchase change even though you never initiated the
+purchase. Your application must handle both of these special cases.</p>
 
-<p>There are two cases where your application may also receive <code>IN_APP_NOTIFY</code> broadcast
+<h4>Handling multiple IN_APP_NOTIFY messages</h4>
+
+<p>When Android Market receives a <code>CONFIRM_NOTIFICATIONS</code> message for a given
+<code>PURCHASE_STATE_CHANGED</code> message, it usually stops sending <code>IN_APP_NOTIFY</code>
+intents for that <code>PURCHASE_STATE_CHANGED</code> message. Sometimes, however, Android
+Market may send repeated <code>IN_APP_NOTIFY</code> intents for a
+<code>PURCHASE_STATE_CHANGED</code> message even though your application has sent a
+<code>CONFIRM_NOTIFICATIONS</code> message. This can occur if a device loses network connectivity
+while you are sending the <code>CONFIRM_NOTIFICATIONS</code> message. In this case, Android Market
+might not receive your <code>CONFIRM_NOTIFICATIONS</code> message and it could send multiple
+<code>IN_APP_NOTIFY</code> messages until it receives acknowledgement that you received the
+transaction message. Therefore, your application must be able to recognize that the subsequent
+<code>IN_APP_NOTIFY</code> messages are for a previously processed transaction. You can do this by
+checking the <code>orderID</code> that's contained in the JSON string because every transaction has
+a unique <code>orderId</code>.</p>
+
+<h4>Handling refunds and other unsolicited IN_APP_NOTIFY messages</h4>
+
+<p>There are two cases where your application may receive <code>IN_APP_NOTIFY</code> broadcast
 intents even though your application has not sent a <code>REQUEST_PURCHASE</code> message. Figure 5
 shows the messaging sequence for both of these cases. Request types for each
 <code>sendBillingRequest()</code> method are shown in <strong>bold</strong>, broadcast intents are
@@ -359,11 +384,11 @@ broadcast intents that are sent for every request.</p>
 <div class="figure" style="width:481px">
 <img src="{@docRoot}images/billing_refund.png" alt="" height="189" />
 <p class="img-caption">
-  <strong>Figure 5.</strong> Message sequence for refunds and other unsolicited IN_APP_NOTIFY messages.
-</p>
+  <strong>Figure 5.</strong> Message sequence for refunds and other unsolicited
+IN_APP_NOTIFY messages.</p>
 </div>
 
-<p>In the first case, your application can receive an <code>IN_APP_NOTIFY</code> broadcast intent
+<p>In the first case, your application may receive an <code>IN_APP_NOTIFY</code> 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 <code>IN_APP_NOTIFY</code>
 message to the second device, informing the application that there is a purchase state change. Your
@@ -384,6 +409,11 @@ refunded. The refund information is included in the JSON string that accompanies
 <code>PURCHASE_STATE_CHANGED</code> broadcast intent. Also, the <code>purchaseState</code> field in
 the JSON string is set to 2.</p>
 
+<p class="caution"><strong>Important:</strong> You cannot use the Google Checkout API to
+issue refunds or cancel in-app billing transactions. You must do this manually through your
+Google Checkout merchant account. However, you can use the Google Checkout API to retrieve order
+information.</p>
+
 <h2 id="billing-security">Security Controls</h2>
 
 <p>To help ensure the integrity of the transaction information that is sent to your application,
diff --git a/docs/html/guide/market/billing/billing_testing.jd b/docs/html/guide/market/billing/billing_testing.jd
index 84d25b2eb1dfd..5453047d96a83 100755
--- a/docs/html/guide/market/billing/billing_testing.jd
+++ b/docs/html/guide/market/billing/billing_testing.jd
@@ -211,7 +211,8 @@ experience, including the actual responses from Android Market and the actual ch
 users will experience in your application.</p>
 
 <p class="note"><strong>Note</strong>: 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.</p>
+testing. You only need to upload your application as a draft application to perform end-to-end
+testing.</p>
 
 <p>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
@@ -233,8 +234,11 @@ actual payouts to your merchant account.</p>
 <ol>
   <li><strong>Upload your application as a draft application to the publisher site.</strong>
     <p>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 <a
-    href="http://market.android.com/support/bin/answer.py?answer=113469">Uploading
+    IDs; you only need to upload your application as a draft application. However, you must sign
+    your application with your release key before you upload it as a draft application. Also, the
+    version number of the uploaded application must match the version number of the application you
+    load to your device for testing. To learn how to upload an application to Android Market, see
+    <a href="http://market.android.com/support/bin/answer.py?answer=113469">Uploading
     applications</a>.</p>
   </li>
   <li><strong>Add items to the application's product list.</strong>
