Doc change: Fixes to IAB purchase state docs.
Change-Id: I7ae5db84c3783085e2c3fbbf3b43fab68e6e89e9
diff --git a/docs/html/guide/google/play/billing/billing_overview.jd b/docs/html/guide/google/play/billing/billing_overview.jd
index 05139b4..82f6cf4 100755
--- a/docs/html/guide/google/play/billing/billing_overview.jd
+++ b/docs/html/guide/google/play/billing/billing_overview.jd
@@ -353,8 +353,9 @@
<p>The <code>RESTORE_TRANSACTIONS</code> request type also triggers a
<code>PURCHASE_STATE_CHANGED</code> 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 <code>CONFIRM_NOTIFICATIONS</code> message.</p>
+information that is sent during a purchase request. Unlike with a purchase request, however, the transactions
+are given without any associated notification IDs, so you do not need to respond to this
+intent with a <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
diff --git a/docs/html/guide/google/play/billing/billing_reference.jd b/docs/html/guide/google/play/billing/billing_reference.jd
index f8c6967..c5541fa 100755
--- a/docs/html/guide/google/play/billing/billing_reference.jd
+++ b/docs/html/guide/google/play/billing/billing_reference.jd
@@ -450,9 +450,7 @@
<p>The In-app Billing API is versioned, with each version offering
additional features to your app. At run time, your app can query the Google Play app to determine
what version of the API it supports and what features are available. Typically, the Google Play app
-will be updated and will support the latest version of the API. For a summary of versions see
-<a href="{@docRoot}guide/google/play/billing/billing_reference.html#billing-versions">In-app Billing
-API Versions</a>.</p>
+will be updated and will support the latest version of the API.
<p>The sections below list the supported versions of the In-app Billing API.
Versions are specified in the <code>API_VERSION</code> key of the Bundle object
diff --git a/docs/html/guide/google/play/billing/billing_subscriptions.jd b/docs/html/guide/google/play/billing/billing_subscriptions.jd
index 3cf9777..ae12951 100755
--- a/docs/html/guide/google/play/billing/billing_subscriptions.jd
+++ b/docs/html/guide/google/play/billing/billing_subscriptions.jd
@@ -241,9 +241,10 @@
it to validate or cancel the subscription remotely using the <a
href="#play-dev-api">Google Play Android Developer API</a>.</p>
-<p>In the case of billing errors, such as could happen if the customer’s credit
-card becomes invalid, Google Play notifies your app of the change in purchase
-state.</p>
+<p>If a recurring payment fails, such as could happen if the customer’s credit
+card has become invalid, the subscription does not renew. Google Play notifies your
+app at the end of the active cycle that the purchase state of the subscription is now "Expired".
+Your app does not need to grant the user further access to the subscription content.</p>
<p>As a best practice, we recommend that your app includes business logic to
notify your backend servers of subscription purchases, tokens, and any billing
@@ -626,13 +627,13 @@
content.</p>
<p>With In-app Billing, you validate a subscription by keeping track of its
-purchase state, such as purchased or cancelled, and then checking the state
-whenever needed. Google Play provides two ways to let you know when the purchase
+purchase state and then checking the state whenever needed. Google Play
+provides two ways to let you know when the purchase
state of a subscription changes:</p>
<ul>
<li><em>In-app Billing Notifications</em>. Google Play pushes a notification
- to your app whenever the purchase state of a subscription changes. Your app can
+ to your app to indicate a change in the purchase state of a subscription. Your app can
store the most recent purchase state for a given purchase token and then check
that state at run time, as needed.</li>
<li><em>Google Play Android Developer API</em>. You can use this HTTP-based
@@ -689,7 +690,8 @@
<td>Purchased successfully</td><td><code>0</code></td><td>Sent at original purchase only (not at recurring billing cycles).</td></tr>
<td>Cancelled</td><td><code>1</code></td><td>Sent at original purchase only if the purchase has failed for some reason. </td></tr>
<td>Refunded</td><td><code>2</code></td><td>The purchase was refunded.</code></td></tr>
-<td>Subscription expired</td><td><code>3</code></td><td>Sent if a subscription expires because of non-payment or user cancelation.</td></tr>
+<td>Subscription expired</td><td><code>3</code></td><td>Sent at the end of a billing cycle to indicate that the subscription expired without renewal because of non-payment or user-cancellation. Your app does not need to grant continued access to the subscription content.
+</td></tr>
</table>
@@ -718,7 +720,7 @@
<p>For more information, see
<a href="{@docRoot}distribute/googleplay/promote/linking.html">Linking to Your Products</a>.</p>
-<h3 id="purchase-state-changes">Recurring billing and changes in purchase state</h3>
+<h3 id="purchase-state-changes">Recurring billing, cancellation, and changes in purchase state</h3>
<p>Google Play notifies your app when the user completes the purchase of a
subscription, but the purchase state does not change over time, provided that
@@ -730,6 +732,19 @@
recurring billing events — those are all handled by Google Play and they
are transparent to your application if billing is successful.</p>
+<p>When the user cancels a subscription during an active billing cycle, Google
+Play <em>does not</em> notify your app immediately of the change in purchase
+state. Instead, it waits until the end of the active billing cycle and then
+notifies your app that the purchase state has changed to "Expired". </p>
+
+<p>Similarly, if payment for the next billing cycle fails, Google Play waits
+until the end of the active billing cycle and then notifies your app at that time that the
+purchase state has changed to "Expired".</p>
+
+<p>Your app can handle user cancellation and non-payment in the same way, since both cause
+a change to the same "Expired" purchase state. Once the purchase state has become "Expired",
+your app does not need to grant further access to the subscription content.</p>
+
<h3 id="modifying">Modifying your app for subscriptions</h3>
<p>For subscriptions, you make the same types of modifications to your app as
diff --git a/docs/html/tools/index.jd b/docs/html/tools/index.jd
index 3fc9bfe..04e0d3b 100644
--- a/docs/html/tools/index.jd
+++ b/docs/html/tools/index.jd
@@ -34,7 +34,7 @@
<ul>
<li>Build rich Android UI with drag and drop.
- <li>Vsualize your UI on tablets, phones, and other devices. Switch themes, locales, even plaform versions instantly, without building.</li>
+ <li>Visualize your UI on tablets, phones, and other devices. Switch themes, locales, even platform versions instantly, without building.</li>
<li>Visual refactoring lets you extracts layout for inclusion, convert layouts, extract styles</li>
<li>Editor support for working with custom UI components</li>
</ul>
