Skip to content

Commit d28470e

Browse files
asolovayasolovay
committed
docs: Revised page to include info about new Publisher API.
Also moved the blurb to the "Google Play Distribution" cover page, and adjusted the TOC accordingly. Per DDoughterty@ 's request, moved the "Purchase Verification Strategies" section to billing_subscriptions.jd Page is staged to: http://asolovay.mtv:9543/google/play/billing/gp-purchase-status-api.html http://asolovay.mtv:9543/google/play/billing/billing_subscriptions.html#strategies Change-Id: I884e2f3f25c76fcb055e663058d1a4f4642fb558
1 parent 1c977b3 commit d28470e

File tree

5 files changed

+199
-104
lines changed

5 files changed

+199
-104
lines changed

‎docs/html/google/google_toc.cs‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -138,9 +138,6 @@ DOCS BUILD RULE.
138138
<li><a href="<?cs var:toroot?>google/play/billing/billing_admin.html">
139139
<span class="en">Administering In-app Billing</span></a>
140140
</li>
141-
<li><a href="<?cs var:toroot?>google/play/billing/gp-purchase-status-api.html">
142-
<span class="en">Purchase Status API</span></a>
143-
</li>
144141
<li><a href="<?cs var:toroot?>google/play/billing/versions.html">
145142
<span class="en">Version Notes</span></a>
146143
</li>
@@ -205,7 +202,9 @@ DOCS BUILD RULE.
205202
<li><a href="<?cs var:toroot ?>google/play/filters.html">
206203
<span class="en">Filters on Google Play</span></a>
207204
</li>
208-
205+
<li><a href="<?cs var:toroot?>google/play/billing/gp-purchase-status-api.html">
206+
<span class="en">Google Play Developer API</span></a>
207+
</li>
209208
<li><a href="<?cs var:toroot ?>google/play/publishing/multiple-apks.html">
210209
<span class="en">Multiple APK Support</span></a>
211210
</li>

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

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ directly from Google Play.</li>
2424
<li><a href="#administering">Configuring Subscriptions Items</a></li>
2525
<li><a href="#cancellation">Cancellation</a></li>
2626
<li><a href="#payment">Payment Processing</a></li>
27+
<li><a href="#strategies">Purchase Verification Strategies</a></li>
2728
</ol>
2829
<h2>See also</h2>
2930
<ol>
@@ -325,6 +326,21 @@ each recurring transaction by appending an integer as follows: </p>
325326
{@code orderId} field of the {@code INAPP_PURCHASE_DATA} JSON field (in V3)
326327
or the {@code PURCHASE_STATE_CHANGED} intent (in V2).</p>
327328

329+
<h2 id="strategies">Purchase Verification Strategies</h2>
330+
331+
<p>In a typical scenario, your app verifies the order status for new purchases
332+
to ensure that they are valid before granting access to the purchased
333+
content.</p>
334+
335+
<p>To verify a purchase, the app passes the purchase token and other details up
336+
to your backend servers, which verifies them directly with Google Play using the
337+
Purchase Status API. If the backend server determines that the purchase is
338+
valid, it notifies the app and grants access to the content.</p>
339+
340+
<p>Keep in mind that users will want the ability to use your app at any time,
341+
including when there may be no network connection available. Make sure that your
342+
approach to purchase verification accounts for the offline use-case.</p>
343+
328344
<h2 id="play-dev-api">Google Play Android Developer API</h2>
329345

330346
<p>Google Play offers an HTTP-based API that lets you remotely query the
@@ -333,4 +349,4 @@ API is designed to be used from your backend servers as a way of securely
333349
managing subscriptions, as well as extending and integrating subscriptions with
334350
other services.</p>
335351

336-
<p>For complete information, see <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a>.</p>
352+
<p>For complete information, see <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a>.</p>

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

Lines changed: 165 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,140 +1,199 @@
1-
page.title=Purchase Status API
2-
page.tags="In-app Billing", "Google Play", "inapp billing", "in app billing", "iab", "billing"
1+
page.title=Google Play Developer API
2+
page.tags="In-app Billing", "Google Play", "inapp billing", "in app billing", "iab", "billing", "publishing"
33

44
@jd:body
55

66
<div id="qv-wrapper">
77
<div id="qv">
88
<h2>In this document</h2>
9+
<!-- TODO: Update TOC -->
910
<ol>
10-
<li><a href="#overview">Overview</a></li>
11-
<li><a href="#using">Using the API</a></li>
12-
<li><a href="#strategies">Verification Strategies</a></li>
13-
<li><a href="#practices">Using the API Efficiently</a></li>
11+
<li><a href="#publishing_api_overview">Publishing API</a>
12+
<li><a href="#subscriptions_api_overview">Subscriptions and In-App
13+
Purchases API</a></li>
14+
<li><a href="#using">Using the API</a>
15+
<li><a href="#edits">Staged Edits</a></li>
16+
<li><a href="#practices">Using the API Efficiently</a>
17+
<ol>
18+
<li><a href="#quota">Quota</a></li>
19+
</ol>
20+
</li>
1421
</ol>
22+
1523
<h2>See also</h2>
1624
<ol>
17-
<li><a href="https://developers.google.com/android-publisher/v1_1/">Google Play Android Developer API</a></li>
25+
<li><a href="https://developers.google.com/android-publisher/">Google Play
26+
Developer API</a> documentation</li>
27+
<li><a href="https://support.google.com/googleplay/android-developer/answer/6071616">Google
28+
Help Center</a> overview of the Google Play Developer API</li>
1829
</ol>
1930
</div>
2031
</div>
2132

22-
<p>Google Play provides an HTTP-based Purchase Status API that lets
23-
you remotely query the status of a specific in-app product or subscription,
24-
or cancel an active subscription. The API is designed to be used from your
25-
backend servers as a way of securely managing in-app products and
26-
subscriptions, as well as extending and integrating them with other services.</p>
33+
<p>The Google Play Developer API is a REST-based web service that allows you to perform publishing
34+
and app-management tasks. You can use this API to integrate your publishing
35+
operations with your release-management process.</p>
36+
37+
<p>Not all developers will need to use these APIs&mdash;in most cases you will
38+
continue to manage your apps directly using the Google Play Developer Console.
39+
However, if you have a large number of APKs to manage, or have to track user
40+
purchases and subscriptions, you may find this API very useful.</p>
41+
42+
<p>Using the Google Play Developer API, you can automate a variety of
43+
app-management tasks, including:</p>
44+
45+
<ul>
46+
<li>Uploading and releasing new versions of your app</li>
47+
<li>Editing your app Google Play Store listings, including localized text and
48+
graphics</li>
49+
<li>Managing your in-app product catalog, your products purchase status and your
50+
app subscriptions</li>
51+
</li>
52+
</ul>
53+
2754

28-
<h2 id="overview">Overview</h2>
2955

30-
<p>With the Purchase Status API you can quickly retrieve the details of any
31-
purchase using a standard GET request. In the request you supply information
32-
about the purchase &mdash; app package name, purchase or subscription ID,
33-
and the purchase token. The server responds with a JSON object describing
34-
the associated purchase details, order status, developer payload, and other
35-
information.</p>
56+
<p>The Google Play Developer API lets you focus on designing and developing your
57+
app, while spending less time and effort managing your releases, even as you
58+
grow to new markets.</p>
59+
60+
<p>The Google Play Developer API includes two components:</p>
61+
62+
<ul>
63+
<li>The <a href="#publishing_api_overview">Publishing API</a> lets you upload and publish
64+
apps, and perform other publishing-related tasks.</li>
65+
<li>The <a href="#subscriptions_api_overview">Subscriptions and In-App Purchases
66+
API</a> lets you manage in-app purchases and subscriptions. (This was
67+
previously known as the "Purchase Status API".)</li>
68+
</ul>
69+
70+
<h2 id="publishing_api_overview">Publishing API</h2>
71+
72+
<p>
73+
The Google Play Developer Publishing API allows you to automate frequent tasks
74+
having to do with app distribution. This provides functions
75+
similar to those available to a developer through the Google Play
76+
Developer Console, such
77+
as:
78+
</p>
79+
80+
<ul><li>Uploading new versions of an app</li>
81+
<li>Releasing apps, by assigning APKs to various <em>Tracks</em> (alpha, beta,
82+
staged rollout, or production)</li>
83+
<li>Creating and modifying Google Play Store listings, including localized text
84+
and graphics and multi-device screenshots</li></ul>
85+
86+
<p>Those tasks are performed using the
87+
<a href="#edits">edits</a>
88+
functionality, which takes a transactional approach to making changes &mdash;
89+
you bundle several changes into a single draft edit, then commit the changes all
90+
at once. (None of the changes take effect until the edit is committed.)</p>
91+
92+
<p class="note"><strong>Note:</strong> Not all developers will need to use this
93+
API. All the functionality provided by the API is also available through the
94+
Google Play
95+
Developer Console. However, this API lets you integrate your app and listing
96+
update process with your existing tools, which will be very useful for some
97+
developers. In particular, if you have a large number of APKs to manage, or
98+
localized listings in many different locales, you may find this API invaluable.
99+
</p>
100+
101+
<h2 id="subscriptions_api_overview">Subscriptions and In-App Purchases API</h2>
102+
103+
<p>The API allows you to manage your app's catalog of in-app products and
104+
subscriptions. In addition, with the Subscriptions and In-App Purchases API you
105+
can quickly retrieve the
106+
details of any purchase using a standard GET request. In the request you supply
107+
information about the purchase &mdash; app package name, purchase or
108+
subscription ID, and the purchase token. The server responds with a JSON object
109+
describing the associated purchase details, order status, developer payload, and
110+
other information.</p>
36111

37112
<p>You can use the Purchase Status API in several ways, such as for reporting
38113
and reconciliation of individual orders and for verifying purchases and
39114
subscription expirations. You can also use the API to learn about cancelled
40115
orders and confirm whether in-app products have been consumed, including
41116
whether they were consumed before being cancelled.</p>
42117

43-
<p>For subscriptions, in addition to querying for order status and expiration,
44-
you can use the Purchase Status API to remotely cancel a subscription. This is a
45-
convenient way to manage cancellations on behalf of customers, without
46-
requiring them to manage the cancellation themselves on their Android devices.</p>
47-
48-
<p>If you plan to use the Purchase Status API, keep in mind that:</p>
49-
<ul><li>You can use the API to check the status of individual items only
50-
&mdash; bulk requests for order status are not supported at this time.</li>
51-
<li>You can query for the details of orders placed on or after 12 June 2013,
52-
but not for orders placed earlier.</li>
53-
<li>You can query purchases of any item type made with the In-app
54-
Billing v3 API, or purchases of managed items made with In-app Billing v1 and
55-
v2. You can not use the Purchase Status API to query purchases of unmanaged items
56-
made with In-app Billing v1 or v2.</li>
57-
</ul>
118+
<p class="note"><strong>Note:</strong> The Subscriptions and In-App
119+
Purchases API does not use the new, transactional "edits" functionality used by
120+
the <a href="#publishing_api_overview">Publishing API</a>. Methods for the
121+
<a href="https://developers.google.com/android-publisher/api-ref/inappproducts">Inappproducts</a>,
122+
<a href="https://developers.google.com/android-publisher/api-ref/purchases/products">Purchases.products</a>,
123+
and <a href="https://developers.google.com/android-publisher/api-ref/purchases/subscriptions">Purchases.subscriptions</a>
124+
resources take effect immediately. Each resource's API reference page notes
125+
specifically whether the methods for that resource use the "edits"
126+
model.</p>
58127

59128
<p>The Purchase Status API is part of the <a
60-
href="https://developers.google.com/android-publisher/v1_1/">Google Play Android
61-
Developer API v1.1</a>, available through the Google Developers Console. The new version
62-
of the API supersedes the v1 API, which is deprecated. If you are using the v1
63-
API, please migrate your operations to the v1.1 API as soon as possible.</p>
64-
129+
href="https://developers.google.com/android-publisher/">Google Play Developer
130+
API</a> v. 2.0, available through the Google Developers Console.</p>
65131

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

68-
<p>To use the API, you must first register a project at the <a
69-
href="https://cloud.google.com/console">Google Developers Console</a> and receive
70-
a Client ID and shared secret that your app will present when calling the
71-
API. All calls are authenticated with OAuth 2.0.</p>
134+
<p>To start making API calls, you’ll set up and manage the Google Play Developer
135+
API directly from the <a href="https://play.google.com/apps/publish/">Google
136+
Play Developer Console</a>. The API can only be managed by the owner of your
137+
Google Play Developer account.</p>
72138

73-
<p>Once your app is registered, you can access the API directly, using standard
74-
HTTP methods to retrieve and manipulate resources. The API is built on a RESTful
75-
design that uses HTTP and JSON. so any standard web stack can send requests and
76-
parse the responses. However, if you don’t want to send HTTP requests and parse
77-
responses manually, you can access the API using the Google APIs Client
78-
Libraries, which provide better language integration, improved security,
79-
and support for making calls that require user authorization.</p>
139+
<p>To access the API, you'll need to:</p>
80140

81-
<p>For more information about the API and how to access it through the Google
82-
APIs Client Libraries, see the documentation at:</p>
83-
84-
<p style="margin-left:1.5em;"><a
85-
href="https://developers.google.com/android-publisher/v1_1/">https://developers.
86-
google.com/android-publisher/v1_1/</a></p>
87-
88-
<h3 id="quota">Quota</h3>
89-
90-
<p>Applications using the Google Play Android Developer API are limited to an
91-
initial courtesy usage quota of <strong>200,000 requests per day</strong> (per
92-
application). This should provide enough access for normal
93-
subscription-validation needs, assuming that you follow the recommendation in
94-
this section.</p>
95-
96-
<p>If you need to request a higher limit for your application, see the
97-
instructions in the <a
98-
href="https://developers.google.com/console/help/new/#trafficcontrols">Google Developers
99-
Console Help</a>.
100-
Also, please read the section below on design best practices for minimizing your
101-
use of the API.</p>
141+
<ol><li>Set up a new or existing API project</li>
142+
<li>Set up one or more authorized clients, which can be either:
143+
<ul>
144+
<li><a href="https://developers.google.com/accounts/docs/OAuth2">OAuth
145+
clients</a></li>
146+
<li><a href="https://developers.google.com/accounts/docs/OAuth2ServiceAccount">
147+
service account</a></li>
148+
</ul></li></ol>
102149

103-
<h3 id="auth">Authorization</h3>
150+
<p>For full details, see the Google Play Developer API
151+
<a href="https://developers.google.com/android-publisher/getting_started">Getting
152+
Started</a> page.</p>
104153

105-
<p>Calls to the Google Play Android Developer API require authorization. Google
106-
uses the OAuth 2.0 protocol to allow authorized applications to access user
107-
data. To learn more, see <a
108-
href="https://developers.google.com/android-publisher/authorization">Authorization</a>
109-
in the Google Play Android Developer API documentation.</p>
154+
<h2 id="edits">Staged Edits</h2>
110155

111-
<h2 id="strategies">Purchase Verification Strategies</h2>
156+
<p>The Google Play Developer Publishing API Edits methods allow you to prepare
157+
and commit changes to your Google Play apps. Once your update is ready to go,
158+
you can deploy it with a single operation. The changes you can make include:</p>
112159

113-
<p>In a typical scenario, your app verifies the order status for new purchases
114-
to ensure that they are valid before granting access to the purchased content.</p>
160+
<ul>
161+
<li>Uploading one or more APKs</li>
162+
<li>Assigning different APKs to different “tracks”: alpha, beta, staged
163+
rollout, and production</li>
164+
<li>Creating and modifying localized store listings for the app</li>
165+
<li>Uploading screenshots and other images for the app’s store listings</li>
166+
</ul>
115167

116-
<p>To verify a purchase, the app passes the purchase token and other details up
117-
to your backend servers, which verifies them directly with Google Play using the
118-
Purchase Status API. For security reasons, the app should not normally attempt to verify
119-
the purchase itself using the Purchase Status API.</p>
168+
<p>Once all the desired changes have been staged, they are all committed with a
169+
single operation.</p>
120170

121-
<p>If the backend server determines that the purchase is valid, it notifies the
122-
app and grants access to the content. For improved performance, the backend servers
123-
should store the purchase details and order status in a local database, updated at
124-
intervals or as-needed.</p>
171+
<p>For full details on staged edits, see the Google Play Developer API
172+
<a href="https://developers.google.com/android-publisher/edits/">Edits</a>
173+
page.</p>
125174

126-
<p>Keep in mind that users will want the ability to use your app at any time, including
127-
when there may be no network connection available. Make sure that your approach to
128-
purchase verification accounts for the offline use-case.</p>
175+
<p class="note"><strong>Note:</strong> The new, transactional "edits"
176+
functionality is only used by the <a href="#publishing_api_overview">Publishing
177+
API</a>. Methods for the <a href="#subscriptions_api_overview">Subscriptions and
178+
In-App Purchases API</a> take effect immediately. Each resource's API reference
179+
page notes specifically whether the methods for that resource use the "edits"
180+
model.</p>
129181

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

132-
<p>Access to the Google Play Android Developer API is regulated to help ensure a
133-
high-performance environment for all applications that use it. While you can
184+
<p>Access to the Google Play Developer API is regulated to help ensure a
185+
high-performance environment for all applications that use it (as described in
186+
<a href="#quota">Quota</a>). While you can
134187
request a higher daily quota for your application, we highly recommend that you
135-
minimize your access using the techniques below. </p>
188+
minimize your access using these techniques: </p>
136189

137190
<ul>
191+
<li><em>Limit the number of app updates</em> &mdash; Do not publish alpha or beta
192+
updates more frequently than once a day. (Production apps should be updated
193+
even less frequently than that.) Every update costs your users time and
194+
possibly money. If you update too frequently, users will start ignoring
195+
updates, or even uninstall the product. (Of course, if there's a major problem
196+
with your app, go ahead and fix it.)</li>
138197
<li><em>Query the Purchase Status API for new purchases only</em> &mdash; At
139198
purchase, your app can pass the purchase token and other details to your backend
140199
servers, which can use the Purchase Status API to verify the purchase.</li>
@@ -163,6 +222,15 @@ minimize your access using the techniques below. </p>
163222
</ul>
164223

165224
<p>By following those general guidelines, your implementation will offer the
166-
best possible performance for users and minimize use of the <a
167-
href="https://developers.google.com/android-publisher/v1_1/">Google Play Android
168-
Developer API</a>.</p>
225+
best possible performance for users.</p>
226+
227+
<h3 id="quota">Quota</h3>
228+
229+
<p>Applications using the Google Play Developer API are limited to an
230+
initial courtesy usage quota of <strong>200,000 requests per day</strong> (per
231+
application). This should provide enough access for publishing activities and
232+
normal subscription-validation needs.</p>
233+
234+
<p>If you need to request a higher limit for your application, use the "Request
235+
more" link on the <strong>Quotas</strong>
236+
pane of the Google Developers Console.</p>

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,11 @@ and features, and more. You can use In-app Billing to sell products as</p>
1414
<div class="sidebox">
1515
<h2><strong>New in In-App Billing</strong></h2>
1616
<ul>
17-
<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>
17+
<li><strong>Google Play Developer API</strong>&mdash;The
18+
<a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google
19+
Play Developer API</a> allows you to perform a number of publishing and
20+
app-management tasks. It includes the functionality previously known as the
21+
<em>Purchase Status API.</em> </li>
1822
<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>
1923
<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>
2024
<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>

0 commit comments

Comments
 (0)