Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 47f5c410 authored by Dirk Dougherty's avatar Dirk Dougherty Committed by Android Git Automerger
Browse files

am 57bb89f0: Doc change: Add docs for GP Purchase Status API. 

* commit '57bb89f0':
  Doc change: Add docs for GP Purchase Status API.
parents 497584ed 57bb89f0

docs/html/google/google_toc.cs

+3 −0
Original line number Diff line number Diff line
@@ -107,6 +107,9 @@ 
      <li><a href="<?cs var:toroot?>google/play/billing/billing_admin.html">

              <span class="en">Administering In-app Billing</span></a>

      </li>

      <li><a href="<?cs var:toroot?>google/play/billing/gp-purchase-status-api.html">

              <span class="en">Purchase Status API</span></a>

      </li>

      <li><a href="<?cs var:toroot?>google/play/billing/versions.html">

              <span class="en">Version Notes</span></a>

      </li>

docs/html/google/play/billing/billing_subscriptions.jd

+7 −89
Original line number Diff line number Diff line
@@ -20,11 +20,11 @@ directly from Google Play.</li> 
    <li><a href="#administering">Configuring Subscriptions Items</a></li>

    <li><a href="#cancellation">Cancellation</a></li>

    <li><a href="#payment">Payment Processing</a></li>

    <li><a href="#play-dev-api">Google Play Android Developer API</a></li>

  </ol>

  <h2>See also</h2>

  <ol>

    <li><a href="{@docRoot}google/play/billing/billing_integrate.html#Subs">Implementing Subscriptions (V3)</a></li>

    <li><a href="https://developers.google.com/android-publisher/v1_1/">Google Play Android Developer API</a></li>

  </ol>

</div>

</div>
@@ -68,7 +68,7 @@ In-app Billing to provide subscription purchasers with extended access to 
content (for example, from your web site or another service).

The server-side API lets you validate the status of a subscription when users

sign into your other services. For more information about the API, see <a

href="#play-dev-api">Google Play Android Developer API</a>. </p>

href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a>. </p>



<p>You can also build on your existing external subscriber base from inside your

Android apps.</p>
@@ -157,8 +157,9 @@ subscription.</p> 
<p>When the subscription payment is approved by Google Wallet, Google Play

provides a purchase token back to the purchasing app through the In-app Billing

API. Your apps can store the token locally or pass it to your backend servers, 

which can then use it to validate or cancel the subscription remotely using the <a

href="#play-dev-api">Google Play Android Developer API</a>.</p>

which can then use it to validate or cancel the subscription remotely using the

<a

href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a>.</p>



<p>If a recurring payment fails (for example, because the customer’s credit

card has become invalid), the subscription does not renew. How your app is
@@ -322,93 +323,10 @@ or the {@code PURCHASE_STATE_CHANGED} intent (in V2).</p> 


<h2 id="play-dev-api">Google Play Android Developer API</h2>



<p>Google Play offers an HTTP-based API that you can use to remotely query the

<p>Google Play offers an HTTP-based API that lets you remotely query the

validity of a specific subscription at any time or cancel a subscription. The

API is designed to be used from your backend servers as a way of securely

managing subscriptions, as well as extending and integrating subscriptions with

other services.</p>



<h3 id="using">Using the API</h3>



<p>To use the API, you must first register a project at the <a

href="https://code.google.com/apis/console">Google APIs Console</a> and receive

a Client ID and shared secret that  your app will present when calling the

Google Play Android Developer API. All calls to the API are authenticated with

OAuth 2.0.</p>



<p>Once your app is registered, you can access the API directly, using standard

HTTP methods to retrieve and manipulate resources, or you can use the Google

APIs Client Libraries, which are extended to support the API.</p>



<p>The Google Play Android Developer API is built on a RESTful design that uses

HTTP and JSON, so any standard web stack can send requests and parse the

responses. However, if you don’t want to send HTTP requests and parse responses

manually, you can access the API using the client libraries, which provide

better language integration, improved security, and support for making calls

that require user authorization.</p>



<p>For more information about the API and how to access it through the Google

APIs Client Libraries, see the documentation at:</p> 



<p style="margin-left:1.5em;"><a

href="https://developers.google.com/android-publisher/v1/">https://developers.

google.com/android-publisher/v1/</a></p>



<h3 id="quota">Quota</h3>



<p>Applications using the Google Play Android Developer API are limited to an

initial courtesy usage quota of <strong>15000 requests per day</strong> (per

application). This should provide enough access for normal

subscription-validation needs, assuming that you follow the recommendation in

this section.</p>



<p>If you need to request a higher limit for your application, please use the

“Request more” link in the <a

href="https://code.google.com/apis/console/#:quotas">Google APIs Console</a>.

Also, please read the section below on design best practices for minimizing your

use of the API.</p>



<h3 id="auth">Authorization</h3>



<p>Calls to the Google Play Android Developer API require authorization. Google

uses the OAuth 2.0 protocol to allow authorized applications to access user

data. To learn more, see <a

href="https://developers.google.com/android-publisher/authorization">Authorization</a>

in the Google Play Android Developer API documentation.</p>



<h3 id="practices">Using the API efficiently</h3>



<p>Access to the Google Play Android Developer API is regulated to help ensure a

high-performance environment for all applications that use it. While you can

request a higher daily quota for your application, we highly recommend that you

minimize your access using the technique(s) below. </p>



<ul>

  <li><em>Store subscription expiry on your servers</em> &mdash; your servers

  should use the Google Play Android Developer API to query the expiration date

  for new subscription tokens, then store the expiration date locally. This allows

  you to check the status of subscriptions only at or after the expiration (see

  below). </li>

  <li><em>Cache expiration and purchaseState</em> &mdash; If your app contacts

  your backend servers at runtime to verify subscription validity, your server

  should cache the expiration and purchaseState to ensure the fastest possible

  response (and best experience) for the user.</li>

  <li><em>Query for subscription status only at expiration</em> &mdash; Once your

  server has retrieved the expiration date of subscription tokens, it should not

  query the Google Play servers for the subscription status again until the

  subscription is reaching or has passed the expiration date. Typically, your

  servers would run a batch query each day to check the status of

  <em>expiring</em> subscriptions, then update the database. Note that: 

  <ul>

    <li>Your servers should not query all subscriptions every day</li>

    <li>Your servers should never query subscription status dynamically, based on

    individual requests from your Android application. </li>

  </ul>

  </li>

</ul>



<p>By following those general guidelines, your implementation will offer the

best possible performance for users and minimize use of the Google Play Android

Developer API.</p>



<p>For complete information, see <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a>.</p>
 
 No newline at end of file

docs/html/google/play/billing/gp-purchase-status-api.jd

0 → 100644
+166 −0
Original line number Diff line number Diff line 
page.title=Purchase Status API

page.tags="In-app Billing", "Google Play", "inapp billing", "in app billing", "iab", "billing"



@jd:body



<div id="qv-wrapper">

<div id="qv">

  <h2>In this document</h2>

  <ol>

    <li><a href="#overview">Overview</a></li>

    <li><a href="#using">Using the API</a></li>

        <li><a href="#strategies">Verification Strategies</a></li>

            <li><a href="#practices">Using the API Efficiently</a></li>

  </ol>

  <h2>See also</h2>

  <ol>

    <li><a href="https://developers.google.com/android-publisher/v1_1/">Google Play Android Developer API</a></li>

  </ol>

</div>

</div>



<p>Google Play provides an HTTP-based Purchase Status API that lets

you remotely query the status of a specific in-app product or subscription,

or cancel an active subscription. The API is designed to be used from your

backend servers as a way of securely managing in-app products and

subscriptions, as well as extending and integrating them with other services.</p>



<h2 id="overview">Overview</h2>



<p>With the Purchase Status API you can quickly retrieve the details of any

purchase using a standard GET request. In the request you supply information

about the purchase &mdash; app package name, purchase or subscription ID,

and the purchase token. The server responds with a JSON object describing

the associated purchase details, order status, developer payload, and other

information.</p>



<p>You can use the Purchase Status API in several ways, such as for reporting

and reconciliation of individual orders and for verifying purchases and

subscription expirations. You can also use the API to learn about cancelled

orders and confirm whether in-app products have been consumed, including

whether they were consumed before being cancelled.</p>



<p>For subscriptions, in addition to querying for order status and expiration,

you can use the Purchase Status API to remotely cancel a subscription. This is a

convenient way to manage cancellations on behalf of customers, without

requiring them to manage the cancellation themselves on their Android devices.</p>



<p>If you plan to use the Purchase Status API, keep in mind that:</p>

<ul><li>You can use the API to check the status of individual items only

&mdash; bulk requests for order status are not supported at this time.</li>

<li>You can query for the details of orders placed on or after 12 June 2013,

but not for orders placed earlier.</li>

<li>You can query purchases of any item type made with the In-app

Billing v3 API, or purchases of managed items made with In-app Billing v1 and

v2. You can not use the Purchase Status API to query purchases of unmanaged items

made with In-app Billing v1 or v2.</li>

</ul>



<p>The Purchase Status API is part of the <a

href="https://developers.google.com/android-publisher/v1_1/">Google Play Android

Developer API v1.1</a>, available through the Google APIs console. The new version

of the API supersedes the v1 API, which is deprecated. If you are using the v1

API, please migrate your operations to the v1.1 API as soon as possible.</p>





<h2 id="using">Using the API</h2>



<p>To use the API, you must first register a project at the <a

href="https://code.google.com/apis/console">Google APIs Console</a> and receive

a Client ID and shared secret that  your app will present when calling the

API. All calls are authenticated with OAuth 2.0.</p>



<p>Once your app is registered, you can access the API directly, using standard

HTTP methods to retrieve and manipulate resources. The API is built on a RESTful

design that uses HTTP and JSON. so any standard web stack can send requests and

parse the responses. However, if you don’t want to send HTTP requests and parse

responses manually, you can access the API using the Google APIs Client

Libraries, which provide better language integration, improved security,

and support for making calls that require user authorization.</p>



<p>For more information about the API and how to access it through the Google

APIs Client Libraries, see the documentation at:</p> 



<p style="margin-left:1.5em;"><a

href="https://developers.google.com/android-publisher/v1_1/">https://developers.

google.com/android-publisher/v1_1/</a></p>



<h3 id="quota">Quota</h3>



<p>Applications using the Google Play Android Developer API are limited to an

initial courtesy usage quota of <strong>15000 requests per day</strong> (per

application). This should provide enough access for normal

subscription-validation needs, assuming that you follow the recommendation in

this section.</p>



<p>If you need to request a higher limit for your application, please use the

“Request more” link in the <a

href="https://code.google.com/apis/console/#:quotas">Google APIs Console</a>.

Also, please read the section below on design best practices for minimizing your

use of the API.</p>



<h3 id="auth">Authorization</h3>



<p>Calls to the Google Play Android Developer API require authorization. Google

uses the OAuth 2.0 protocol to allow authorized applications to access user

data. To learn more, see <a

href="https://developers.google.com/android-publisher/authorization">Authorization</a>

in the Google Play Android Developer API documentation.</p>



<h2 id="strategies">Purchase Verification Strategies</h2>



<p>In a typical scenario, your app verifies the order status for new purchases

to ensure that they are valid before granting access to the purchased content.</p>



<p>To verify a purchase, the app passes the purchase token and other details up

to your backend servers, which verifies them directly with Google Play using the

Purchase Status API. For security reasons, the app should not normally attempt to verify

the purchase itself using the Purchase Status API.</p>



<p>If the backend server determines that the purchase is valid, it notifies the

app and grant access to the content. For improved performance, the backend servers

should store the purchase details and order status in a local database, updated a

intervals or as-needed.</p>



<p>Keep in mind that users will want to be able to use your app at any time, including

when there may be no network connection available. Make sure that your approach to

purchase verification takes account of the offline use-case.</p>



<h2 id="practices">Using the API Efficiently</h2>



<p>Access to the Google Play Android Developer API is regulated to help ensure a

high-performance environment for all applications that use it. While you can

request a higher daily quota for your application, we highly recommend that you

minimize your access using the techniques below. </p>



<ul>

  <li><em>Query the Purchase Status API for new purchases only</em> &mdash; At

  purchase, your app can pass the purchase token and other details to your backend

  servers, which can use the Purchase Status API to verify the purchase.</li>

  <li><em>Cache purchase details on your servers</em> &mdash; To the extent possible,

  cache the purchase details for in-app products and subscriptions on your backend

  servers. If your app contacts your backend servers at runtime to verify purchase

  validity, your server can verify the purchase based on the cached details, to

  minimize use of the Purchase Status API and to provide the fastest possible response

  (and best experience) for the user.</li>

  <li><em>Store subscription expiry on your servers</em> &mdash; Your servers should

  use the Purchase Status API to query the expiration date for new subscription tokens,

  then store the expiration date locally. This allows you to check the status of

  subscriptions only at or after the expiration (see below).</li>

  <li><em>Query for subscription status only at expiration</em> &mdash; Once your

  server has retrieved the expiration date of subscription tokens, it should not query

  the Google Play servers for the subscription status again until the subscription is

  reaching or has passed the expiration date. Typically, your servers would run a batch

  query each day to check the status of expiring subscriptions, then update the database.

  Note that:

    <ul>

      <li>Your servers should not query all subscriptions every day</li>

      <li>Your servers should never query subscription status dynamically, based on

      individual requests from your Android application.</li>

    </ul>

  </li>

</ul>



<p>By following those general guidelines, your implementation will offer the

best possible performance for users and minimize use of the Google Play Android

Developer API.</p>

docs/html/google/play/billing/index.jd

+1 −0
Original line number Diff line number Diff line
@@ -10,6 +10,7 @@ and features, and more. You can use In-app Billing to sell products as</p> 
<div class="sidebox">

  <h2><strong>New in In-App Billing</strong></h2>

  <ul>

  <li><strong>Purchase Status API</strong>&mdash;The <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a> lets you query the status of in-app product or subscription purchases. </li>

  <li><strong>In-app Billing Version 3</strong>&mdash;The <a href="{@docRoot}google/play/billing/api.html">latest version</a> of In-app Billing features a synchronous API that is easier to implement and lets you manage in-app products and subscriptions more effectively.</li>

  <li><strong>Subscriptions now supported in Version 3</strong>&mdash;You can query and launch purchase flows for subscription items using the V3 API.</li>

  <li><strong>Free trials</strong>&mdash;You can now offer users a configurable <a href="/google/play/billing/v2/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>

docs/html/google/play/billing/v2/billing_reference.jd

+1 −1
Original line number Diff line number Diff line
@@ -413,4 +413,4 @@ a <code>PURCHASE_STATE_CHANGED</code> intent.</p> 
implemention. </p> -->



<h3 id="http-api">REST API for subscriptions</h3>

<p>Google Play offers an HTTP-based API that you can use to remotely query the validity of a specific subscription at any time or cancel a subscription. The API is designed to be used from your backend servers as a way of securely managing subscriptions, as well as extending and integrating subscriptions with other services. See <a href="{@docRoot}google/play/billing/v2/billing_subscriptions.html#play-dev-api"> Google Play Android Developer API</a> for more information.</p>
 
<p>Google Play offers an HTTP-based API that you can use to remotely query the validity of a specific subscription at any time or cancel a subscription. The API is designed to be used from your backend servers as a way of securely managing subscriptions, as well as extending and integrating subscriptions with other services. See <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a> for more information.</p>