am 147b01bc: Merge "Doc change: In-app Billing -- add notes about orderId change and subscription orderIds." into jb-mr1-dev

* commit '147b01bc637ad8d184bd0aa2d6bf902e69c92107': Doc change: In-app Billing -- add notes about orderId change and subscription orderIds.
2012-12-04 18:43:25 -08:00
parent 174af19814 147b01bc63
commit 1cb5ad47a1
8 changed files with 101 additions and 42 deletions
--- a/docs/html/google/play-services/setup.jd
+++ b/docs/html/google/play-services/setup.jd
@@ -7,13 +7,20 @@ page.title=Setup
    downloadable package from the <a href="{@docRoot}tools/help/sdk-manager.html">SDK
    Manager</a>. The download includes the client library and code samples.
 </p>
+    
+<p>
+    To develop using the <a href="{@docRoot}reference/gms-packages.html">Google
+    Play services APIs</a>, you must download the Google Play services SDK.
+    Additionally, you must provide a physical <strong>development device</strong> on
+    which you can run and debug your app. You can develop on any compatible Android
+    device that runs Android 2.2 or higher and includes the Google Play Store.
+    Ideally, you would develop and test the app on a variety of devices, including
+    both phones and tablets. 
+</p>

-<p>You must download the Google Play services SDK in order to develop using the
-<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>. However, <strong>you
-cannot use the Android emulator</strong> to test an app that depends on the Google Play services
-APIs&mdash;you must use a real device running Android 2.2 or higher that includes
-Google Play Store.</p>
-
+<p class="note"><strong>Note</strong>: Google Play services is not supported on the
+Android emulator &mdash; to develop using the APIs, you need to provide a development
+device such as an Android phone or tablet.</p>

 <p>To install the Google Play services SDK for development:</p>

--- a/docs/html/google/play/billing/billing_admin.jd
+++ b/docs/html/google/play/billing/billing_admin.jd
@@ -11,6 +11,7 @@ parent.link=index.html
    <li><a href="#billing-purchase-type">Choosing a Purchase Type</a></li>
    <li><a href="#billing-testing-setup">Setting up Test Accounts</a></li>
    <li><a href="#billing-refunds">Handling Refunds</a></li>
+    <li><a href="#billing-refunds">Working with Order Numbers</a></li>
    <li><a href="#billing-support">Where to Get Support</a></li>
  </ol>
  <h2>Downloads</h2>
@@ -39,13 +40,13 @@ few administrative tasks, including setting up and maintaining your product list
 site, registering test accounts, and handling refunds when necessary.</p>

 <p>You must have a Google Play publisher account to register test accounts. And you must have a
-Google Wallet merchant account to create a product list and issue refunds to your users. If you
+Google Checkout merchant account to create a product list and issue refunds to your users. If you
 already have a publisher account on Google Play, you can use your existing account. You do not
 need to register for a new account to support in-app billing. If you do not have a publisher
 account, you can register as a Google Play developer and set up a publisher account at the
 Google Play <a href="http://play.google.com/apps/publish">publisher site</a>. If you do not have a
-Google Wallet merchant account, you can register for one at the <a
-href="http://checkout.google.com">Google Wallet site</a>.</p>
+Google Checkout merchant account, you can register for one at the <a
+href="http://checkout.google.com">Google Checkout site</a>.</p>

 <h2 id="billing-list-setup">Creating a Product List</h2>

@@ -56,7 +57,7 @@ items that are listed in another application's product list.</p>

 <p>You can access an application's product list by clicking the <strong>In-App Products</strong>
 link that appears under each of the applications that are listed for your publisher account (see
-figure 1). The <strong>In-App Products</strong> link appears only if you have a Google Wallet
+figure 1). The <strong>In-App Products</strong> link appears only if you have a Google Checkout
 merchant account and an application's manifest includes the <code>com.android.vending.BILLING</code>
 permission.</p>

@@ -78,7 +79,7 @@ storing and delivering the digital content that you sell in your applications.</
 </p>

 <p>You can create a product list for any published application or any draft application that's been
-uploaded and saved to the Google Play site. However, you must have a Google Wallet merchant
+uploaded and saved to the Google Play site. However, you must have a Google Checkout merchant
 account and the application's manifest must include the <code>com.android.vending.BILLING</code>
 permission. If an application's manifest does not include this permission, you will be able to edit
 existing items in the product list but you will not be able to add new items to the list. For more
@@ -432,19 +433,49 @@ times.</p>

 <p>In-app billing does not allow users to send a refund request to Google Play. Refunds for
 in-app purchases must be directed to you (the application developer). You can then process the
-refund through your Google Wallet merchant account. When you do this, Google Play receives a
-refund notification from Google Wallet, and Google Play sends a refund message to your
+refund through your Google Checkout merchant account. When you do this, Google Play receives a
+refund notification from Google Checkout, and Google Play sends a refund message to your
 application. For more information, see <a
 href="{@docRoot}google/play/billing/billing_overview.html#billing-action-notify">Handling
 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 Wallet API to issue
+<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
-Wallet merchant account. However, you can use the Google Wallet API to retrieve order
+Checkout merchant account. However, you can use the Google Checkout API to retrieve order
 information.</p>

+<h2 id="orderId">Working with Order Numbers</h2>
+
+<p>When a user purchases an in-app item, Google Checkout assigns the transaction
+a unique and permanent order number. Google Play provides that order number to
+you at the conclusion of the purchase flow, as the value of the
+<code>orderId</code> field of the <code>PURCHASE_STATE_CHANGED</code>
+intent.</p>
+
+<p>In your app, you can use the order number as a general-purpose identifier for
+the in-app purchase transaction. After the purchase, you can use the order
+number as a means of tracking the transaction in reconciliation reports and for
+customer support.</p>
+
+<p>The order number itself is a string consisting of numbers only, with a format
+assigned and managed by Google Checkout.</p>
+
+<p>For transactions dated 5 December 2012 or later, Google Checkout assigns a
+Merchant Order Number (rather than a Google Order Number) and reports the Merchant
+Order Number as the value of <code>orderID</code>. Here's an
+example:</p>
+
+<pre>"orderId" : "12999556515565155651.5565135565155651"</pre>
+
+<p>For transactions dated previous to 5 December 2012, Google checkout assigned
+a Google Order Number and reported that number as the value of
+<code>orderID</code>. Here's an example of an <code>orderID</code> holding a
+Google Order Number:</p>
+
+<pre>"orderId" : "556515565155651"</pre>
+
 <h2 id="billing-testing-setup">Setting Up Test Accounts</h2>

 <p>The Google Play publisher site lets you set up one or more test accounts. A test account is a
--- a/docs/html/google/play/billing/billing_integrate.jd
+++ b/docs/html/google/play/billing/billing_integrate.jd
@@ -242,7 +242,7 @@ how to do this.</p>
    List</a>.</p>
    <p class="note"><strong>Note:</strong> You must publish the items in your product
    list (<code>sword_001</code> and <code>potion_001</code>) even though you are not publishing the
-    sample application. Also, you must have a Google Wallet Merchant account to add items to the
+    sample application. Also, you must have a Google Checkout Merchant account to add items to the
    sample application's product list.</p>
  </li>
 </ol>
@@ -255,7 +255,7 @@ onto a device to run it. To run the sample application, do the following:</p>
 <ol>
  <li><strong>Make sure you have at least one test account registered under your Google Play
  publisher account.</strong>
-    <p>You cannot purchase items from yourself (Google Wallet prohibits this), so you need to
+    <p>You cannot purchase items from yourself (Google Checkout prohibits this), so you need to
    create at least one test account that you can use to purchase items in the sample application.
    To learn how to set up a test account, see <a
    href="{@docRoot}google/play/billing/billing_testing.html#billing-testing-setup">Setting up Test
@@ -294,7 +294,7 @@ onto a device to run it. To run the sample application, do the following:</p>
  </li>
  <li><strong>Run the application and purchase the sword or the potion.</strong>
    <p>When you use a test account to purchase items, the test account is billed through Google
-    Wallet and your Google Wallet Merchant account receives a payout for the purchase.
+    Wallet 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.</p>
 </ol>
--- a/docs/html/google/play/billing/billing_overview.jd
+++ b/docs/html/google/play/billing/billing_overview.jd
@@ -265,7 +265,7 @@ string for a subscription item is shown below:</p>
 <pre class="no-pretty-print" style="color:black">{ "nonce" : 1836535032137741465,
  "orders" :
    [{ "notificationId" : "android.test.purchased",
-       "orderId" : "transactionId.android.test.purchased",
+       "orderId" : "12999556515565155651.5565135565155651",
       "packageName" : "com.example.dungeons",
       "productId" : "android.test.purchased",
       "developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ",
@@ -439,7 +439,7 @@ href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">pu
 to "managed per user account."</p>

 <p>In the second case, your application can receive an <code>IN_APP_NOTIFY</code> broadcast intent
-when Google Play receives a refund notification from Google Wallet. In this case, Google
+when Google Play receives a refund notification from Google Checkout. In this case, Google
 Play sends an <code>IN_APP_NOTIFY</code> message to your application. Your application can handle
 this message the same way it handles responses from an application-initiated
 <code>REQUEST_PURCHASE</code> message so that ultimately your application receives a
@@ -448,9 +448,9 @@ 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 Wallet API to
+<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 Wallet merchant account. However, you can use the Google Wallet API to retrieve order
+Google Checkout merchant account. However, you can use the Google Checkout API to retrieve order
 information.</p>

 <h2 id="billing-security">Security Controls</h2>
@@ -488,7 +488,7 @@ limitations.</p>
 <ul>
  <li>In-app billing can be implemented only in applications that you publish through Google
  Play.</li>
-  <li>You must have a Google Wallet Merchant account to use Google Play In-app Billing.</li>
+  <li>You must have a Google Checkout Merchant account to use Google Play In-app Billing.</li>
  <li>In-app billing requires version 2.3.4 (or higher) of the Android Market application.
  To support subscriptions, version 3.5 or higher of the Google Play app is required. On devices
  running Android 3.0, version 5.0.12 (or higher) of the MyApps application is required.</li>
--- a/docs/html/google/play/billing/billing_reference.jd
+++ b/docs/html/google/play/billing/billing_reference.jd
@@ -105,7 +105,7 @@ codes returned by Google Play.</p>
  <td><code>RESULT_ERROR</code></td>
  <td>6</td>
  <td>Indicates an unexpected server error. For example, this error is triggered if you try to
-purchase an item from yourself, which is not allowed by Google Wallet.</td>
+purchase an item from yourself, which is not allowed by Google Checkout.</td>
 </tr>
 </table>

@@ -394,8 +394,10 @@ a <code>PURCHASE_STATE_CHANGED</code> intent.</p>
 </tr>
 <tr>
  <td>orderId</td>
-  <td>A unique order identifier for the transaction. This corresponds to the Google Wallet Order
-  ID.</td>
+  <td>A unique order identifier for the transaction. This corresponds to the transaction's Merchant
+  Order Number. For transactions dated previous to 5 December 2012, the orderID correcponds to the transaction's 
+  Google Order Number. For more information, see <a href="{@docRoot}google/play/billing/billing_admin.html#orderId">Working
+  with order numbers</a>.</td>
 </tr>
 <tr>
  <td>packageName</td>
--- a/docs/html/google/play/billing/billing_subscriptions.jd
+++ b/docs/html/google/play/billing/billing_subscriptions.jd
@@ -107,7 +107,7 @@ other in-app products.</p>
 <p>When users purchase subscriptions in your apps, Google Play handles all
 checkout details so your apps never have to directly process any financial
 transactions. Google Play processes all payments for subscriptions through
-Google Wallet, just as it does for standard in-app products and app purchases.
+Google Checkout, just as it does for standard in-app products and app purchases.
 This ensures a consistent and familiar purchase flow for your users.</p>

 <img src="{@docRoot}images/billing_subscription_flow.png" style="border:4px solid ddd;">
@@ -221,10 +221,10 @@ the new price.</p>
 either of two intervals:</p>

 <ul>
-  <li>Monthly &mdash; Google Play bills the customer’s Google Wallet account at
+  <li>Monthly &mdash; Google Play bills the customer’s Google Checkout account at
  the time of purchase and monthly subsequent to the purchase date (exact billing
  intervals can vary slightly over time)</li>
-  <li>Annually &mdash; Google Play bills the customer's Google Wallet account at
+  <li>Annually &mdash; Google Play bills the customer's Google Checkout account at
  the time of purchase and again on the same date in subsequent years.</li>
 </ul>

@@ -238,7 +238,7 @@ cycles will always match subscription cycles, based on the purchase date.</p>
 Direct Carrier Billing) that was originally used to purchase the
 subscription.</p>

-<p>When the subscription payment is approved by Google Wallet, Google Play
+<p>When the subscription payment is approved by Google Checkout, Google Play
 provides a purchase token back to the purchasing app through the In-app Billing
 API. For details, see <a href="#token">Purchase token</a>, below. Your apps can
 store the token locally or pass it to your backend servers, which can then use
@@ -343,7 +343,7 @@ subscriptions are not available at this time.</p>
 <h3 id="payment">Payment processing and policies</h3>

 <p>In general, the terms of Google Play allow you to sell in-app subscriptions
-only through the standard payment processor, Google Wallet. For purchases of any
+only through the standard payment processor, Google Checkout. For purchases of any
 subscription products, just as for other in-app products and apps, the
 transaction fee for subscriptions, just as for other in-app purchases, is the
 same as the transaction fee for application purchases (30%).</p>
@@ -356,6 +356,22 @@ outside of the app and Google Play (such as to a web site).</p>
 href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies
 document</a>.</p>

+<h3 id="orderId">Subscription Order Numbers</h3>
+
+<p>To help you track transactions relating to a given subscription, Google
+Checkout provides a base Merchant Order Number for all recurrences of the subscription and denotes
+each recurring transaction by appending an integer as follows: </p>
+
+<p><span style="color:#777"><code style="color:#777">12999556515565155651.5565135565155651</code> (base order number)</span><br />
+<code>12999556515565155651.5565135565155651..0</code> (initial purchase orderID)<br />
+<code>12999556515565155651.5565135565155651..1</code> (first recurrence orderID)<br />
+<code>12999556515565155651.5565135565155651..2</code> (second recurrence orderID)<br />
+...<br /></p>
+
+<p>Google Play provides that order number to as the value of the
+<code>orderId</code> field of the <code>PURCHASE_STATE_CHANGED</code>
+intent.</p>
+
 <h3 id="requirements">System requirements for subscriptions</h3>

 <p>In-app purchases of subscriptions are supported only on devices that meet
@@ -440,7 +456,7 @@ responses. Inside the requests and responses are two new fields described below.
 token, a string value that uniquely identifies (and associates) a user ID and a
 subscription ID. Google Play generates the purchase token when the user
 completes the purchase of a subscription product (and payment is approved by
-Google Wallet) and then sends it to the purchasing app on the device through the
+Google Checkout) and then sends it to the purchasing app on the device through the
 In-app Billing API. </p>

 <p>At the conclusion of a <code>PURCHASE_REQUEST</code> message flow, your app
@@ -456,7 +472,7 @@ is shown below. </p>
 <pre class="no-pretty-print" style="color:black">{ "nonce" : 1836535032137741465,
  "orders" :
    [{ "notificationId" : "android.test.purchased",
-       "orderId" : "transactionId.android.test.purchased",
+       "orderId" : "12999556515565155651.5565135565155651"
       "packageName" : "com.example.dungeons",
       "productId" : "android.test.purchased",
       "developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ",
--- a/docs/html/google/play/billing/billing_testing.jd
+++ b/docs/html/google/play/billing/billing_testing.jd
@@ -62,7 +62,7 @@ product ID android.test.purchased.</p>

 <img src="{@docRoot}images/billing_test_flow.png" height="381" id="figure1" />
 <p class="img-caption">
-  <strong>Figure 1.</strong> Wallet flow for the special reserved item android.test.purchased.
+  <strong>Figure 1.</strong>Wallet flow for the special reserved item android.test.purchased.
 </p>

 <p>You do not need to list the reserved products in your application's product list. Google Play
@@ -91,8 +91,8 @@ reserved product IDs.</p>
    <p>When you make an in-app billing request with this product ID, Google Play responds as
    though the purchase was refunded. Refunds cannot be initiated through Google Play's in-app
    billing service. Refunds must be initiated by you (the merchant). After you process a refund
-    request through your Google Wallet account, a refund message is sent to your application by
-    Google Play. This occurs only when Google Play gets notification from Google Wallet that
+    request through your Google Checkout account, a refund message is sent to your application by
+    Google Play. This occurs only when Google Play gets notification from Google Checkout that
    a refund has been made. For more information about refunds, see <a
    href="{@docRoot}google/play/billing/billing_overview.html#billing-action-notify">Handling
    IN_APP_NOTIFY messages</a> and <a
@@ -216,7 +216,7 @@ 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 Google Play publisher site. You cannot use your
-developer account to test the complete in-app purchase process because Google Wallet does not let
+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 <a
 href="{@docRoot}google/play/billing/billing_admin.html#billing-testing-setup">Setting up test
 accounts</a>.</p>
@@ -224,8 +224,8 @@ accounts</a>.</p>
 <p>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.</p>

-<p>When you use a test account to purchase items, the test account is billed through Google Wallet
-and your Google Wallet Merchant account receives a payout for the purchase. Therefore, you may
+<p>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.</p>

--- a/docs/html/google/play/billing/index.jd
+++ b/docs/html/google/play/billing/index.jd
@@ -8,8 +8,11 @@ and features, and more. You can use In-app Billing to sell products as</p>

 <div class="sidebox-wrapper">
 <div class="sidebox">
-  <p><strong>Free trials for subscriptions</strong> <span class="new" style="font-size:.78em;">New!</span></p>
-  <p>You can now offer users a configurable <a href="{@docRoot}google/play/billing/billing_subscriptions.html#trials">free trial period</a> for your in-app subscriptions. You can set up trials with a simple change in the Developer Console&mdash;no change to your app code is needed. 
+  <h2><strong>New in In-App Billing</strong></h2>
+  <ul>
+  <li><strong>New order number format</strong>&mdash; Starting 5 December, orders are reported in Merchant Order Number format. See <a href="{@docRoot}google/play/billing/billing_admin.html#orderId">Working with Order Numbers</a> for an example.</li>
+  <li><strong>Free trials</strong>&mdash;You can now offer users a configurable <a href="/google/play/billing/billing_subscriptions.html#trials">free trial period</a> for your in-app subscriptions. You can set up trials with a simple change in the Developer Console&mdash;no change to your app code is needed.</li>
+ </ul>
 </div>
 </div>

@@ -29,7 +32,7 @@ purchases is the same as the transaction fee for application purchases

 <p>Any application that you publish through Google Play can implement In-app Billing. No special
 account or registration is required other than an Android Market publisher account and a Google
-Wallet Merchant account. Also, because the service uses no dedicated framework APIs, you can add
+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.</p>

 <p>To help you integrate in-app billing into your application, the Android SDK