Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 47050d35: am 768dba6d: docs: Merged commits for final release of IABv3 docs.

Browse Source 
* commit '47050d3578986febcc4b28f901effd6b4b9ae41a':
  docs: Merged commits for final release of IABv3 docs.
This commit is contained in:
Quddus Chong
2012-12-09 18:51:35 -08:00
committed by Android Git Automerger
parent 2588648b52 47050d3578
commit 3aecb61beb
40 changed files with 6460 additions and 2284 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/html/google/google_toc.cs
View File

@@ -45,32 +45,47 @@
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header"><a href="<?cs var:toroot ?>google/play/billing/index.html">
<span class="en">Google Play In-app Billing</span></a>
</div>
<ul>
<li><a href="<?cs var:toroot?>google/play/billing/billing_overview.html">
<span class="en">In-app Billing Overview</span></a>
</li>
<li><a href="<?cs var:toroot?>google/play/billing/billing_integrate.html">
<span class="en">Implementing In-app Billing</span></a>
</li>
<li><a href="<?cs var:toroot?>google/play/billing/billing_subscriptions.html">
<span class="en">Subscriptions</span></a>
</li>
<li><a href="<?cs var:toroot?>google/play/billing/billing_best_practices.html">
<li><a href="<?cs var:toroot?>google/play/billing/billing_overview.html">
<span class="en">Overview</span></a>
</li>
<li class="nav-section"><div class="nav-section-header"><a href="<?cs var:toroot?>google/play/billing/api.html">
<span class="en">Version 3 API</span></a></div>
<ul>
<li><a href="<?cs var:toroot?>google/play/billing/billing_integrate.html">
<span class="en">Implementing the API</span></a></li>
<li><a href="<?cs var:toroot?>google/play/billing/billing_reference.html">
<span class="en">Reference</span></a></li>
</ul>
</li>
<li class="nav-section"><div class="nav-section-header"><a href="<?cs var:toroot?>google/play/billing/v2/api.html">
<span class="en">Version 2 API</span></a></div>
<ul>
<li><a href="<?cs var:toroot?>google/play/billing/v2/billing_integrate.html">
<span class="en">Implementing the API</span></a></li>
<li><a href="<?cs var:toroot?>google/play/billing/v2/billing_subscriptions.html">
<span class="en">Subscriptions</span></a></li>
<li><a href="<?cs var:toroot?>google/play/billing/v2/billing_reference.html">
<span class="en">Reference</span></a></li>
</ul>
</li>
<li><a href="<?cs var:toroot?>google/play/billing/billing_best_practices.html">
<span class="en">Security and Design</span></a>
</li>
<li><a href="<?cs var:toroot?>google/play/billing/billing_testing.html">
</li>
<li><a href="<?cs var:toroot?>google/play/billing/billing_testing.html">
<span class="en">Testing In-app Billing</span></a>
</li>
<li><a href="<?cs var:toroot?>google/play/billing/billing_admin.html">
</li>
<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/billing_reference.html">
<span class="en">Reference</span></a>
</li>
</li>
<li><a href="<?cs var:toroot?>google/play/billing/versions.html">
<span class="en">Version Notes</span></a>
</li>
</ul>
</li>
@@ -86,11 +101,9 @@
<li><a href="<?cs var:toroot ?>google/play/publishing/multiple-apks.html">
<span class="en">Multiple APK Support</span></a>
</li>
<li><a href="<?cs var:toroot ?>google/play/expansion-files.html">
<span class="en">APK Expansion Files</span></a>
</li>
<li class="nav-section">
<div class="nav-section-header"><a href="<?cs var:toroot ?>google/play/licensing/index.html">
<span class="en">Application Licensing</span></a>

116
docs/html/google/play/billing/api.jd Normal file
View File

@@ -0,0 +1,116 @@
page.title=In-app Billing Version 3
parent.title=In-app Billing
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Topics</h2>
<ol>
<li><a href="#producttypes">Product Types</a>
<ol>
<li><a href="#managed">Managed In-app Products</a><li>
</ol>
</li>
<li><a href="#purchase">Purchasing Items</a></li>
<li><a href="#consume">Consuming Items</a>
<ol>
<li><a href="#consumetypes">Non-consumable and Consumable Items</a><li>
<li><a href="#managingconsumables">Managing Consumable Purchases</a><li>
</ol>
</li>
<li><a href="#caching">Local Caching</a></li>
</ol>
<h2>Reference</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing
Reference (V3)</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}training/in-app-billing/index.html">Selling In-app Products</a></li>
</ol>
</div>
</div>
<p>The In-app Billing Version 3 API makes it easier for you to integrate In-app Billing into your applications. The features in this version include improved synchronous purchase flow, APIs to let you easily track ownership of consumable goods, and local caching of in-app purchase data.</p>
<h2 id="producttypes">Product Types</h2>
<p>You define your products using the Google Play Developer Console, including product type, SKU, price, description, and so on. For more information, see <a
href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Billing</a>. The Version 3 API only supports the managed in-app product type.</p>
<h3 id="managed">Managed In-app Products</h3>
<p>Managed in-app products are items that have their ownership information tracked and managed by Google Play. When a user purchases a managed in-app item, Google Play stores the purchase information for each item on a per-user basis. This enables you to later query Google Play at any time to restore the state of the items a specific user has purchased. This information is persistent on the Google Play servers even if the user uninstalls the application or if they change devices.</p>
<p>If you are using the Version 3 API, you can also consume managed items within your application. You would typically implement consumption for items that can be purchased multiple times (such as in-game currency, fuel, or magic spells). Once purchased, a managed item cannot be purchased again until you consume the item, by sending a consumption request to Google Play. To learn more about in-app product consumption, see <a href="#consume">Consuming Items</a></p>
<h2 id="purchase">Purchasing Items</h2>
<div class="figure" style="width:430px">
<img src="{@docRoot}images/in-app-billing/v3/iab_v3_purchase_flow.png" id="figure1" height="530"/>
<p class="img-caption">
<strong>Figure 1.</strong> The basic sequence for a purchase request.
</p>
</div>
<p>A typical purchase flow with the Version 3 API is as follows:
<ol>
<li>Your application sends a {@code isBillingSupported} request to Google Play to determine that the target version of the In-app Billing API that you are using is supported. </li>
<li>When your application starts or user logs in, it's good practice to check with Google Play to determine what items are owned by the user. To query the user's in-app purchases, send a {@code getPurchases} request. If the request is successful, Google Play returns a {@code Bundle} containing a list of product IDs of the purchased items, a list of the individual purchase details, and a list of the signatures for the purchases.</li>
<li>Usually, you'll want to inform the user of the products that are available for purchase. To query the details of the in-app products that you defined in Google Play, your application can send a {@code getSkuDetails} request. You must specify a list of product IDs in the query request. If the request is successful, Google Play returns a {@code Bundle} containing product details including the product’s price, title, description, and the purchase type.
</li>
<li>If an in-app product is not owned by the user, you can initiate a purchase for it. To start a purchase request, your application sends a {@code getBuyIntent} request, specifying the product ID of the item to purchase, along with other parameters. You should record the product ID when you create a new in-app product in the Developer Console.
<ol type="a">
<li>Google Play returns a {@code Bundle} that contains a {@code PendingIntent} which you application uses to start the checkout UI for the purchase.</li>
<li>Your application launches the pending intent by calling the {@code startIntentSenderForResult} method.</li>
<li>When the checkout flow finishes (that is, the user successfully purchases the item or cancels the purchase), Google Play sends a response {@code Intent} to your {@code onActivityResult} method. The result code of the {@code onActivityResult} has a result code that indicates whether the purchase was successful or canceled. The response {@code Intent} contains information about the purchased item, including a {@code purchaseToken} String that is generated by Google Play to uniquely identify this purchase transaction. The {@code Intent} also contains the signature of the purchase, signed with your private developer key.</li>
</ol>
</li>
</ol>
</p>
<p>To learn more about the Version 3 API calls and server responses, see <a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing Reference</a>.</p>
<h2 id="consume">Consuming Items</h2>
<p>You can use the consumption mechanism to track the user's ownership of in-app products.</p>
<p>In Version 3, all in-app products are managed. This means that the user's ownership of all in-app item purchases is maintained by Google Play, and your application can query the user's purchase information when needed. When the user successfully purchases an item, that purchase is recorded in Google Play. Once an item is purchased, it is considered to be "owned". Items in the "owned" state cannot be purchased from Google Play. You must send a consumption request for the "owned" item before Google Play makes it available for purchase again. Consuming the item reverts it to the "unowned" state, and discards the previous purchase data.</p>
<div class="figure" style="width:420px">
<img src="{@docRoot}images/in-app-billing/v3/iab_v3_consumption_flow.png" id="figure2" height="300"/>
<p class="img-caption">
<strong>Figure 2.</strong> The basic sequence for a consumption request.
</p>
</div>
<p>To retrieve the list of product's owned by the user, your application sends a {@code getPurchases} call to Google Play. Your application can make a consumption request by sending a {@code consumePurchase} call. In the request argument, you must specify the item's unique {@code purchaseToken} String that you obtained from Google Play when it was purchased. Google Play returns a status code indicating if the consumption was recorded successfully.</p>
<h3 id="consumetypes">Non-consumable and Consumable Items</h3>
<p>It's up to you to decide if you want to handle your in-app products as non-consumable or consumable items.</p>
<dl>
<dt>Non-consumable Items</dt>
<dd>Typically, you would not implement consumption for items that can only be purchased once in your application and provide a permanent benefit. Once purchased, these items will be permanently associated to the user's Google account. An example of a non-consumable item is a premium upgrade or a level pack.</dd>
<dt>Consumable items</dt>
<dd>In contrast, you can implement consumption for items that can be made available for purchase multiple times. Typically, these items provide certain temporary effects. For example, the user's in-game character might gain life points or gain extra gold coins in their inventory. Dispensing the benefits or effects of the purchased item in your application is called <em>provisioning</em> the in-app product. You are responsible for controlling and tracking how in-app products are provisioned to the users.
<p class="note"><strong>Important:</strong> Before provisioning the consumable item in your application, you must send a consumption request to Google Play and receive a successful response indicating that the consumption was recorded.</p>
</dd>
</dl>
<h3 id="managingconsumables">Managing consumable purchases in your application</h3>
<p>Here is the basic flow for purchasing a consumable item:</p>
<ol>
<li>Launch a purchase flow with a {@code getBuyIntent} call</li>
<li>Get a response {@code Bundle}from Google Play indicating if the purchase completed successfully.</li>
<li>If the purchase was successful, consume the purchase by making a {@code consumePurchase} call.</li>
<li>Get a response code from Google Play indicating if the consumption completed successfully.</li>
<li>If the consumption was successful, provision the product in your application.</li>
</ol>
<p>Subsequently, when the user starts up or logs in to your application, you should check if the user owns any outstanding consumable items; if so, make sure to consume and provision those items. Here's the recommended application startup flow if you implement consumable items in your application:</p>
<ol>
<li>Send a {@code getPurchases} request to query the owned items for the user.</li>
<li>If there are any consumable items, consume the items by calling {@code consumePurchase}. This step is necessary because the application might have completed the purchase order for the consumable item, but stopped or got disconnected before the application had the chance to send a consumption request.</li>
<li>Get a response code from Google Play indicating if the consumption completed successfully.</li>
<li>If the consumption was successful, provision the product in your application.</li>
</ol>
<h2 id="caching">Local Caching</h2>
<p>Because the Google Play client now caches In-app Billing information locally on the device, you can use the Version 3 API to query for this information more frequently, for example through a {@code getPurchases} call. Unlike with previous versions of the API, many Version 3 API calls will be serviced through cache lookups instead of through a network connection to Google Play, which significantly speeds up the API's response time. </p>

12
docs/html/google/play/billing/billing_about.html
View File

@@ -1,12 +0,0 @@
<html>
<head>
<meta http-equiv="refresh"
content="0;url=http://developer.android.com/google/play/billing/index.html">
<title>Redirecting...</title>
</head>
<body>
<p>You should be redirected. Please <a
href="http://developer.android.com/google/play/billing/index.html">click
here</a>.</p>
</body>
</html>

201
docs/html/google/play/billing/billing_admin.jd
View File

@@ -8,78 +8,66 @@ parent.link=index.html
<h2>In this document</h2>
<ol>
<li><a href="#billing-list-setup">Creating a Product List</a></li>
<li><a href="#billing-purchase-type">Choosing a Purchase Type</a></li>
<li><a href="#billing-purchase-type">Choosing a Product 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>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">Sample
Application</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">Overview of In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html">Implementing In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_best_practices.html">Security and
Design</a></li>
<li><a href="{@docRoot}google/play/billing/billing_testing.html">Testing In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing
Reference</a></li>
</ol>
</div>
</div>
<p>In-app billing frees you from processing financial transactions, but you still need to perform a
few administrative tasks, including setting up and maintaining your product list on the publisher
site, registering test accounts, and handling refunds when necessary.</p>
few administrative tasks, including setting up and maintaining your product list on the Google Play
Developer Console, 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 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 Checkout merchant account, you can register for one at the <a
need to register for a new account to support in-app billing.</p>
<p>If you do not have a publisher account, you can register as a Google Play
developer and set up a publisher account at the <a
href="http://play.google.com/apps/publish">Google Play Developer Console</a>. If you do not
have a 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>
<p>The Google Play publisher site provides a product list for each of your published
<p>The Google Play Developer Console provides a product list for each of your published
applications. You can sell an item using Google Play's in-app billing feature only if the item is
listed on an application's product list. Each application has its own product list; you cannot sell
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
link in applications listed in your developer account (see
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>
merchant account and the application's manifest includes the <code>com.android.vending.BILLING</code>
permission.</p>
<img src="{@docRoot}images/billing_product_list_entry.png" height="548" id="figure1" />
<p class="img-caption">
<strong>Figure 1.</strong> You can access an application's product list by clicking the
<strong>In-App Products</strong> link.
</p>
<p>A product list specifies items you are selling in an application &mdash; in-app products,
subscriptions, or a combination of both. For each item, the product list contains information such as a product id,
product description, and price (see figure 2). The product list stores only metadata about the items
product description, and price. The product list stores only metadata about the items
you are selling in your application. It does not store any digital content. You are responsible for
storing and delivering the digital content that you sell in your applications.</p>
<img src="{@docRoot}images/billing_product_list.png" height="658" id="figure2" />
<p class="img-caption">
<strong>Figure 2.</strong> An application's product list.
<div style="margin:1em;">
<img style="border:1px solid #ddd;padding-bottom:.5em" src="{@docRoot}images/in-app-billing/billing_product_list.png" xheight="548" id="figure1" />
<p class="img-caption" style="padding-left:.5em;">
<strong>Figure 1.</strong> You can access an application's product list by clicking the
<strong>In-App Products</strong> link in the main Apps navigation.
</p>
</div>
<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 Checkout merchant
uploaded and saved to the Developer Console. 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
@@ -95,8 +83,8 @@ associated with the application listing. You cannot create individual product li
you are using the multiple APK feature.</p>
<p>You can add items to a product list two ways: you can add items one at a time by using the In-app
Products UI (see figure 3), or you can add a batch of items by importing the items from a
comma-separated values (CSV) file (see figure 2). Adding items one at a time is useful if your
Products UI (see figure 2), or you can add a batch of items by importing the items from a
comma-separated values (CSV) file. Adding items one at a time is useful if your
application has only a few in-app items or you are adding only a few items to a
product list for testing purposes. The CSV file method is useful if your application has a large
number of in-app items.</p>
@@ -111,16 +99,17 @@ number of in-app items.</p>
<li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li>
<li>In the <strong>All Google Play listings</strong> panel, under the application name, click
<strong>In-app Products</strong>.</li>
<li>On the In-app Products List page, click <strong>Add in-app product</strong>.</li>
<li>On the Create New In-app Product page (see figure 3), provide details about the item you are
<li>Click <strong>Add new product</strong> (see figure 2) and provide details about the item you are
selling and then click <strong>Save</strong> or <strong>Publish</strong>.</li>
</ol>
<img src="{@docRoot}images/billing_list_form.png" height="840" id="figure3" />
<p class="img-caption">
<strong>Figure 3.</strong> The Create New In-app Product page lets you add items to an
<div style="margin:1em;">
<img style="border:1px solid #ddd;padding-bottom:.5em;" src="{@docRoot}images/in-app-billing/billing_add.png" height="300" id="figure2" />
<p class="img-caption" style="padding-left:.5em;">
<strong>Figure 2.</strong> The Add New Product page lets you add items to an
application's product list.
</p>
</div>
<p>You must enter the following information for each item in a product list:</p>
<ul>
@@ -132,10 +121,10 @@ number of in-app items.</p>
<p>In addition, you cannot modify an item's product ID after it is created, and you cannot reuse
a product ID.</p>
</li>
<li><strong>Purchase Type</strong>
<p>The purchase type can be <strong>Managed per user account</strong>, <strong>Unmanaged</strong>,
or <strong>Subscription</strong>. You can never change an item's purchase type after you set it. For more
information, see <a href="#billing-purchase-type">Choosing a purchase type</a> later in this
<li><strong>Product Type</strong>
<p>The product type can be <strong>Managed per user account</strong>, <strong>Unmanaged</strong>,
or <strong>Subscription</strong>. You can never change an item's product type after you set it. For more
information, see <a href="#billing-purchase-type">Choosing a product type</a> later in this
document.</p>
</li>
<li><strong>Publishing State</strong>
@@ -147,14 +136,14 @@ number of in-app items.</p>
href="{@docRoot}google/play/billing/billing_testing.html#billing-testing-real">Testing In-app
Billing</a> for more information.</p>
</li>
<li><strong>Language</strong>
<p>The language setting determines which languages are used to display the item title and
item description during checkout. A product list inherits its default language from the
parent application. You can add more languages by clicking <strong>add language</strong>. You
can also choose to have the title and description automatically translated from the default
language by selecting the <strong>Fill fields with auto translation</strong> checkbox (see
figure 4). If you do not use the auto translation feature, you must provide the translated
versions of the title and description.</p>
<li><strong>Languages and Translations</strong>
<p>You can provide localized titles and descriptions for your in-app
products using the Add Translations button. If you want Google Play to translate
your title and description for you, based on the title and description in the
default language, just click the languages that you want to offer. If you want
to provide custom translations in specific languages, you can also do that. By
default, an in-app product inherits its default language from the parent
application.</p>
</li>
<li><strong>Title</strong>
<p>The title is a short descriptor for the item. For example, "Sleeping potion." Titles must be
@@ -174,20 +163,22 @@ number of in-app items.</p>
page in the Google Play developer console.</p>
<p>To specify prices in other currencies, you can manually enter the price for each
currency or you can click <strong>Auto Fill</strong> and let Google Play do a one-time
conversion from your home currency to the currencies you are targeting (see figure 4).</p>
conversion from your home currency to the currencies you are targeting (see figure 3).</p>
<p>For subscription items, note that you can not change the item's price once you have published it. </p>
</li>
</ul>
<img src="{@docRoot}images/billing_list_form_2.png" height="1226" id="figure4" />
<p class="img-caption">
<strong>Figure 4.</strong> Specifying additional currencies and additional languages for the
item title and description.
<div style="margin:1em;">
<img style="border:1px solid #ddd;padding-bottom:.5em" src="{@docRoot}images/in-app-billing/billing_list_form_2.png" xheight="1226" id="figure3" />
<p class="img-caption" style="padding-left:.5em;">
<strong>Figure 3.</strong> Specifying additional currencies for an in-app product.
</p>
</div>
<p>For more information about product IDs and product lists, see <a
href="http://market.android.com/support/bin/answer.py?answer=1072599">Creating In-App Product
href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1072599">Creating In-App Product
IDs</a>. For more information about pricing, see <a
href="http://market.android.com/support/bin/answer.py?answer=1153485">In-App Billing
href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1153485">In-App Billing
Pricing</a>.</p>
<p class="note"><strong>Note</strong>: Be sure to plan your product ID namespace. You cannot reuse
@@ -231,7 +222,7 @@ example, the syntax for the CSV file is as follows:</p>
published</code> or <code>unpublished</code>.</p>
</li>
<li><em>purchase_type</em>
<p>This is equivalent to the Purchase Type setting in the In-app Products UI. Can be <code>
<p>This is equivalent to the Product Type setting in the In-app Products UI. Can be <code>
managed_by_android</code>, which is equivalent to <strong>Managed per user account
</strong> in the In-app Products UI, or <code>managed_by_publisher</code>, which is equivalent
to <strong>Unmanaged</strong> in the In-app Products UI.</p>
@@ -393,41 +384,18 @@ file.
</strong> on the In-app Product List page. This is useful if you have manually added items to
a product list and you want to start managing the product list through a CSV file.</p>
<h3 id="billing-purchase-type">Choosing a Purchase Type</h3>
<h3 id="billing-purchase-type">Choosing a Product Type</h3>
<p>An item's purchase type controls how Google Play manages the purchase of the item. There are
two purchase types: "managed per user account" and "unmanaged."</p>
<p>An item's product type controls how Google Play manages the purchase of the item. There are
several product types, including "managed per user account", "unmanaged," and "subscription." However,
note that the product types supported vary
across In-app Billing Version, so you should always choose a product type that's valid for the
version of In-app BIlling that your app uses. </p>
<p>Items that are managed per user account can be purchased only once per user account. When an item
is managed per user account, Google Play permanently stores the transaction information for each
item on a per-user basis. This enables you to query Google Play with the
<code>RESTORE_TRANSACTIONS</code> request and restore the state of the items a specific user has
purchased.</p>
<p>If a user attempts to purchase a managed item that has already been purchased, Google Play
displays an "Item already purchased" error. This occurs during checkout, when Google Play
displays the price and description information on the checkout page. When the user dismisses the
error message, the checkout page disappears and the user returns to your user interface. As a best
practice, your application should prevent the user from seeing this error. The sample application
demonstrates how you can do this by keeping track of items that are managed and already purchased
and not allowing users to select those items from the list. Your application should do something
similar&mdash;either graying out the item or hiding it so that it cannot be selected.</p>
<p>The "manage by user account" purchase type is useful if you are selling items such as game levels
or application features. These items are not transient and usually need to be restored whenever a
user reinstalls your application, wipes the data on their device, or installs your application on a
new device.</p>
<p>Items that are unmanaged do not have their transaction information stored on Google Play,
which means you cannot query Google Play to retrieve transaction information for items whose
purchase type is listed as unmanaged. You are responsible for managing the transaction information
of unmanaged items. Also, unmanaged items can be purchased multiple times as far as Google Play
is concerned, so it's also up to you to control how many times an unmanaged item can be
purchased.</p>
<p>The "unmanaged" purchase type is useful if you are selling consumable items, such as fuel or
magic spells. These items are consumed within your application and are usually purchased multiple
times.</p>
<p>For details, refer to the documentation for <a
href="{@docRoot}google/play/billing/api.html#producttype">In-app Billing Version
3</a> or <a href="{@docRoot}google/play/billing/v2/api.html#producttype">In-app
Billing Version 2</a>.
<h2 id="billing-refunds">Handling Refunds</h2>
@@ -436,13 +404,13 @@ in-app purchases must be directed to you (the application developer). You can th
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
href="{@docRoot}google/play/billing/v2/api.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
href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&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
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>
@@ -478,13 +446,13 @@ Google Order Number:</p>
<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
regular Google account that you register on the publisher site as a test account. Test accounts are
<p>The Google Play Developer Console lets you set up one or more test accounts. A test account is a
regular Google account that you register on the Developer Console as a test account. Test accounts are
authorized to make in-app purchases from applications that you have uploaded to the Google Play
site but have not yet published.</p>
Developer Console but have not yet published.</p>
<p>You can use any Google account as a test account. Test accounts are useful if you want to let
multiple people test in-app billing on applications without giving them access to your publisher
multiple people test In-app Billing on applications without giving them access to your publisher
account's sign-in credentials. If you want to own and control the test accounts, you can create the
accounts yourself and distribute the credentials to your developers or testers.</p>
@@ -503,28 +471,39 @@ accounts yourself and distribute the credentials to your developers or testers.<
<ol>
<li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li>
<li>On the upper left part of the page, under your name, click <strong>Edit profile</strong>.</li>
<li>On the Edit Profile page, scroll down to the Licensing &amp; In-app Billing panel (see figure
5).</li>
<li>In Test Accounts, add the email addresses for the test accounts you want to register,
<li>Click the <strong>Settings</strong> icon. (If you are using the old Developer Console UI, click
<strong>Edit profile</strong> in the upper left part of the page, under your name,)</li>
<li>Locate the License Testing panel. (In the old UI, scroll down to the Licensing &amp; In-app Billing panel.)</li>
<li>Add the email addresses for the test accounts you want to register,
separating each account with a comma.</li>
<li>Click <strong>Save</strong> to save your profile changes.</li>
</ol>
<img src="{@docRoot}images/billing_public_key.png" height="510" id="figure5" />
<p class="img-caption">
<strong>Figure 5.</strong> The Licensing and In-app Billing panel of your account's Edit Profile
page lets you register test accounts.
<h3 id="license_key">Getting an app's license key</h3>
<p>The Google Play Developer Console provides a public licensing key for each app. To get the key for an app,
load the app's publishing details in the Developer Console and click the <strong>Settings</strong> icon. The key
for the app is available for copy/paste in License Key for this Application field, as shown in the figure below.</p>
<p>Previously, the Developer Console provided a single public key per developer account. To transition apps to the
new per-app public key, the Developer Console set the app-specific key as the former developer key. This ensures
compatibility for apps that depend on the (former) developer key. </p>
<div style="margin:1em;">
<img style="border:1px solid #ddd;padding-bottom:.5em" src="{@docRoot}images/in-app-billing/billing_app_key.png" xheight="510" id="figure4" />
<p class="img-caption" style="padding-left:.5em;">
<strong>Figure 4.</strong> You can find the license key for each app in the <strong>Services & APIs</strong> panel.
</p>
</div>
<h2 id="billing-support">Where to Get Support</h2>
<p>If you have questions or encounter problems while implementing in-app billing, contact the
<p>If you have questions or encounter problems while implementing In-app Billing, contact the
support resources listed in the following table (see table 2). By directing your queries to the
correct forum, you can get the support you need more quickly.</p>
<p class="table-caption" id="support-table"><strong>Table 2.</strong> Developer support resources
for Google Play in-app billing.</p>
for Google Play In-app Billing.</p>
<table>
@@ -549,7 +528,7 @@ android</a></td>
<td>Billing issue tracker</td>
<td><a href="http://code.google.com/p/marketbilling/issues/">Billing
project issue tracker</a></td>
<td>Bug and issue reports related specifically to in-app billing sample code.</td>
<td>Bug and issue reports related specifically to In-app Billing sample code.</td>
</tr>
</table>

62
docs/html/google/play/billing/billing_best_practices.jd
View File

@@ -7,42 +7,40 @@ parent.link=index.html
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#billing-security">Security Best Practices</a></li>
</ol>
<h2>Downloads</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">Sample
Application</a></li>
<li><a href="#billing-security">Security Best Practices</a>
<ol>
<li><a href="#unlocked">Protect Unlocked Content</a></li>
<li><a href="#obfuscate">Obfuscate Your Code</a></li>
<li><a href="#sample">Modify Sample Code</a></li>
<li><a href="#nonce">Use Secure Random Nonces</a></li>
<li><a href="#payload">Set the Developer Payload String</a></li>
<li><a href="#trademark">Report Trademark and Copyright Infringement</a></li>
<li><a href="#revocable">Implement a Revocability scheme</a></li>
<li><a href="#key">Protect Your Public Key</a></li>
</ol>
</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">Overview of In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html">Implementing In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_testing.html">Testing In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing
Reference</a></li>
</ol>
</div>
</div>
<p>As you design your in-app billing implementation, be sure to follow the security and design
<p>As you design your In-app Billing implementation, be sure to follow the security and design
guidelines that are discussed in this document. These guidelines are recommended best practices for
anyone who is using Google Play's in-app billing service.</p>
anyone who is using Google Play's In-app Billing service.</p>
<h2>Security Best Practices</h2>
<h4>Perform signature verification tasks on a server</h4>
<h3 id="sign">Perform signature verification tasks on a server</h3>
<p>If practical, you should perform signature verification on a remote server and not on a device.
Implementing the verification process on a server makes it difficult for attackers to break the
verification process by reverse engineering your .apk file. If you do offload security processing to
a remote server, be sure that the device-server handshake is secure.</p>
<h4>Protect your unlocked content</h4>
<h3 id="unlocked">Protect your unlocked content</h3>
<p>To prevent malicious users from redistributing your unlocked content, do not bundle it in your
.apk file. Instead, do one of the following:</p>
<ul>
@@ -54,29 +52,29 @@ a remote server, be sure that the device-server handshake is secure.</p>
content in device memory or store it on the device's SD card. If you store content on an SD card, be
sure to encrypt the content and use a device-specific encryption key.</p>
<h4>Obfuscate your code</h4>
<p>You should obfuscate your in-app billing code so it is difficult for an attacker to reverse
<h3 id="obfuscate">Obfuscate your code</h3>
<p>You should obfuscate your In-app Billing code so it is difficult for an attacker to reverse
engineer security protocols and other application components. At a minimum, we recommend that you
run an obfuscation tool like <a
href="{@docRoot}tools/help/proguard.html">Proguard</a> on your
code.</p>
<p>In addition to running an obfuscation program, we recommend that you use the following techniques
to obfuscate your in-app billing code.</p>
to obfuscate your In-app Billing code.</p>
<ul>
<li>Inline methods into other methods.</li>
<li>Construct strings on the fly instead of defining them as constants.</li>
<li>Use Java reflection to call methods.</li>
</ul>
<p>Using these techniques can help reduce the attack surface of your application and help minimize
attacks that can compromise your in-app billing implementation.</p>
attacks that can compromise your In-app Billing implementation.</p>
<div class="note">
<p><strong>Note:</strong> If you use Proguard to obfuscate your code, you must add the following
line to your Proguard configuration file:</p>
<p><code>-keep class com.android.vending.billing.**</code></p>
</div>
<h4>Modify all sample application code</h4>
<p>The in-app billing sample application is publicly distributed and can be downloaded by anyone,
<h3 id="sample">Modify all sample application code</h3>
<p>The In-app Billing sample application is publicly distributed and can be downloaded by anyone,
which means it is relatively easy for an attacker to reverse engineer your application if you use
the sample code exactly as it is published. The sample application is intended to be used only as an
example. If you use any part of the sample application, you must modify it before you publish it or
@@ -84,25 +82,31 @@ release it as part of a production application.</p>
<p>In particular, attackers look for known entry points and exit points in an application, so it is
important that you modify these parts of your code that are identical to the sample application.</p>
<h4>Use secure random nonces</h4>
<h3 id="nonce">Use secure random nonces</h3>
<p>Nonces must not be predictable or reused. Always use a cryptographically secure random number
generator (like {@link java.security.SecureRandom}) when you generate nonces. This can help reduce
replay attacks.</p>
<p>Also, if you are performing nonce verification on a server, make sure that you generate the
nonces on the server.</p>
<h4>Take action against trademark and copyright infringement</h4>
<h3 id="payload">Set the developer payload string when making purchase requests</h3>
<p>With the In-app Billing Version 3 API, you can include a 'developer payload' string token when sending your purchase request to Google Play. Typically, this is used to pass in a string token that uniquely identifies this purchase request. If you specify a string value, Google Play returns this string along with the purchase response. Subsequently, when you make queries about this purchase, Google Play returns this string together with the purchase details.</p>
<p>You should pass in a string token that helps your application to identify the user who made the purchase, so that you can later verify that this is a legitimate purchase by that user. For consumable items, you can use a randomly generated string, but for non-consumable items you should use a string that uniquely identifies the user.</p>
<p>When you get back the response from Google Play, make sure to verify that the developer payload string matches the token that you sent previously with the purchase request. As a further security precaution, you should perform the verification on your own secure server.</p>
<h3 id="trademark">Take action against trademark and copyright infringement</h3>
<p>If you see your content being redistributed on Google Play, act quickly and decisively. File a
<a href="http://market.android.com/support/bin/answer.py?hl=en&amp;answer=141511">trademark notice
<a href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=141511">trademark notice
of infringement</a> or a <a href="http://www.google.com/android_dmca.html">copyright notice of
infringement</a>.</p>
<h4>Implement a revocability scheme for unlocked content</h4>
<h3 id="revocable">Implement a revocability scheme for unlocked content</h3>
<p>If you are using a remote server to deliver or manage content, have your application verify the
purchase state of the unlocked content whenever a user accesses the content. This allows you to
revoke use when necessary and minimize piracy.</p>
<h4>Protect your Google Play public key</h4>
<h3 id="key">Protect your Google Play public key</h3>
<p>To keep your public key safe from malicious users and hackers, do not embed it in any code as a
literal string. Instead, construct the string at runtime from pieces or use bit manipulation (for
example, XOR with some other string) to hide the actual key. The key itself is not secret

1276
docs/html/google/play/billing/billing_integrate.jd
View File

File diff suppressed because it is too large Load Diff

695
docs/html/google/play/billing/billing_overview.jd
View File

@@ -5,504 +5,223 @@ parent.link=index.html
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>Use In-app Billing to sell digital goods, including one-time items and recurring subscriptions.</li>
<li>Supported for any app published on Google Play. You only need a Google Play publisher account and a Google Checkout Merchant account.</li>
<li>Checkout processing is automatically handled by Google Play, with the same look-and-feel as for app purchases.</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#billing-types">Product and Purchase Types</a></li>
<li><a href="#billing-arch">In-app Billing Architecture</a></li>
<li><a href="#billing-msgs">In-app Billing Messages</a></li>
<ol>
<li><a href="#billing-request">Request messages</a></li>
<li><a href="#billing-response">Broadcast intents</a></li>
<li><a href="#billing-message-sequence">Messaging sequence</a></li>
<li><a href="#billing-action-notify">Handling IN_APP_NOTIFY messages</a></li>
</ol>
<li><a href="#billing-security">Security Controls</a></li>
<li><a href="#billing-limitations">Requirements and Limitations</a></li>
<li><a href="#api">In-app Billing API</a></li>
<li><a href="#products">In-app Products</a>
<ol>
<li><a href="#prodtypes">Product Types</a>
</ol>
</li>
<li><a href="#console">Google Play Developer Console</a></li>
<li><a href="#checkout">Google Play Purchase Flow</a></li>
<li><a href="#samples">Sample Apps</a></li>
<li><a href="#migration">Migration Considerations</a></li>
</ol>
<h2>Downloads</h2>
<h2>Related Samples</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">Sample
Application</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html">Implementing In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_best_practices.html">Security and
Design</a></li>
<li><a href="{@docRoot}google/play/billing/billing_testing.html">Testing In-app Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing
Reference</a></li>
</ol>
<li><a href="{@docRoot}training/in-app-billing/preparing-iab-app.html#GetSample">Sample Application (V3)</a></li>
<li><a href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">Sample
Application (V2)</a></li>
</ol>
</div>
</div>
<p>In-app Billing is a Google Play service that provides checkout processing for
in-app purchases. To use the service, your application sends a billing request for a specific in-app
product. The service then handles all of the checkout details for the transaction, including
requesting and validating the form of payment and processing the financial transaction. When the
checkout process is complete, the service sends your application the purchase details, such as the
order number, the order date and time, and the price paid. At no point does your application have to
handle any financial transactions; that role is provided by Google Play's in-app billing
service.</p>
<p>This documentation describes the fundamental In-app Billing components and
features that you need to understand in order to implement your own In-app
Billing application.</p>
<h2 id="billing-types">Product and Purchase Types</h2>
<p>In-app Billing supports different product types and purchase types to give you flexibility in how you monetize your app. In all cases, you define your products using the Google Play Developer Console, including product type, purchase type, SKU, price, description, and so on. For more information, see <a href="billing_admin.html">Administering In-app Billing</a>.</p>
<h3 id="producttypes">Product Types</h3>
<p>With In-app Billing, you can sell two types of products &mdash; <em>in-app products</em> and <em>subscriptions</em>. The billing characteristics of the two types are very different, but the In-app Billing API lets you handle the two product types in your app using the same communication model, data structures, and user interactions, as described later in this document.</p>
<ul>
<li><em>In-app products</em> &mdash; Items that a user would purchase one-at-a-time. For example, typical in-app products would let users purchase digital content, unlock functionality in an app, pay for one-time charges, or add almost anything to the application experience. Unlike with priced applications, once the user has purchased an in-app product there is no refund window. Users desiring refunds must contact the developer directly.
<p>In-app products can be sold using either the "managed per user account" or "unmanaged" purchase type. In-app products are always explicitly associated with one and only one app. That is, one app cannot purchase an in-app product published for another app, even if they are from the same developer. In-app products are supported in all versions of In-app Billing.</p></li>
<li><em>Subscriptions</em> &mdash; Items that are sold with a developer-specified, recurring billing interval. When a user purchases a subscription, Google Play and its payment processor automatically bill the user's account at the specified interval and price, charging the amount to the original payment method. Once the user purchases a subscription, Google Play continues billing the account indefinitely, without requiring approval or action from the user. The user can cancel the subscription at any time.
<p>Subscriptions can only be sold using the "managed per user account" purchase type. As with in-app products, once the user has purchased an in-app product there is no refund window. Users desiring refunds must contact the developer directly. For more information about subscriptions and how to sell them in your apps, see the <a href="billing_subscriptions.html">Subscriptions</a> document.</p></li>
</ul>
<h3 id="purchasetypes">Purchase Types</h3>
<p>In-app Billing offers two purchase types that you can use when selling in-app products, "managed per user account" and "unmanaged". The purchase type controls how Google Play handles and tracks purchases for the products. </p>
<ul>
<li><em>Managed per user account</em> &mdash; Items that can be purchased only once per user account on Google Play. When a user purchases an item that uses the "managed per user account" purchase type, Google Play permanently stores the transaction information for each item on a per-user basis. This enables you to later query Google Play to restore the state of the items a specific user has purchased. If a user attempts to purchase a managed item that has already been purchased, Google Play prevents the user from purchasing the item again and displays an "Item already purchased" error.
<p>The "managed per user account" purchase type is useful if you are selling items such as game levels or application features. These items are not transient and usually need to be restored whenever a user reinstalls your application, wipes the data on their device, or installs your application on a new device.</p>
<li><em>Unmanaged</em> &mdash; Items that do not have their transaction information stored on Google Play. This means that you cannot later query Google Play to retrieve transaction information for those items. For "unmanaged" purchases, you are responsible for managing the transaction information. Also, Google Play does not attempt to prevent the user from purchasing an item multiple times if it uses the "unmanaged" purchase type. It's up to you to control how many times an unmanaged item can be purchased.</p>
<p>The "unmanaged" purchase type is useful if you are selling consumable items, such as fuel or magic spells. These items are consumed within your application and are usually purchased multiple times.</p></li>
</ul>
<h2 id="billing-arch">In-app Billing Architecture</h2>
<p>Your app accesses the In-app Billing service using an API that is exposed by
the Google Play app installed on the device. The Google Play app then uses an
asynchronous message loop to convey billing requests and responses between your
application and the Google Play server. In practice, your application never
directly communicates with the Google Play server (see figure 1). Instead, your
application sends billing requests to the Google Play application over
interprocess communication (IPC) and receives purchase responses from the Google
Play application in the form of asynchronous broadcast intents. Your application
does not manage any network connections between itself and the Google Play
server or use any special APIs from the Android platform.</p>
<div class="figure" style="width:440px">
<img src="{@docRoot}images/billing_arch.png" alt="" height="582" />
<p class="img-caption">
<strong>Figure 1.</strong> Your application sends and receives billing messages through the
Google Play application, which handles all communication with the Google Play server.</p>
</div>
<p>Some in-app billing implementations may also use a private remote server to deliver content or
validate transactions, but a remote server is not required to implement in-app billing. A remote
server can be useful if you are selling digital content that needs to be delivered to a user's
device, such as media files or photos. You might also use a remote server to store users'
transaction history or perform various in-app billing security tasks, such as signature
verification. Although you can handle all security-related tasks in your application, performing
those tasks on a remote server is recommended because it helps make your application less vulnerable
to security attacks.</p>
<p>A typical in-app billing implementation relies on three components:</p>
<ul>
<li>A {@link android.app.Service} (named <code>BillingService</code> in the sample application),
which processes purchase messages from the application and sends billing requests to the Google
Play in-app billing service.</li>
<li>A {@link android.content.BroadcastReceiver} (named <code>BillingReceiver</code> in the sample
application), which receives all asynchronous billing responses from the Google Play
application.</li>
<li>A security component (named <code>Security</code> in the sample application), which performs
security-related tasks, such as signature verification and nonce generation. For more information
about in-app billing security, see <a href="#billing-security">Security controls</a> later in this
document.</li>
</ul>
<p>You may also want to incorporate two other components to support in-app billing:</p>
<ul>
<li>A response {@link android.os.Handler} (named <code>ResponseHandler</code> in the sample
application), which provides application-specific processing of purchase notifications, errors,
and other status messages.</li>
<li>An observer (named <code>PurchaseObserver</code> in the sample application), which is
responsible for sending callbacks to your application so you can update your user interface with
purchase information and status.</li>
</ul>
<p>In addition to these components, your application must provide a way to store information about
users' purchases and some sort of user interface that lets users select items to purchase. You do
not need to provide a checkout user interface. When a user initiates an in-app purchase, the Google
Play application presents the checkout user interface to your user. When the user completes the
checkout process, your application resumes.</p>
<h2 id="billing-msgs">In-app Billing Messages</h2>
<p>When the user initiates a purchase, your application sends billing messages to Google Play's
in-app billing service (named <code>MarketBillingService</code>) using simple IPC method calls. The
Google Play application responds to all billing requests synchronously, providing your
application with status notifications and other information. The Google Play application also
responds to some billing requests asynchronously, providing your application with error messages and
detailed transaction information. The following section describes the basic request-response
messaging that takes place between your application and the Google Play application.</p>
<h3 id="billing-request">In-app billing requests</h3>
<p>Your application sends in-app billing requests by invoking a single IPC method
(<code>sendBillingRequest()</code>), which is exposed by the <code>MarketBillingService</code>
interface. This interface is defined in an <a
href="{@docRoot}guide/components/aidl.html">Android Interface Definition Language</a> file
(<code>IMarketBillingService.aidl</code>). You can <a
href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">download</a> this AIDL
file with the in-app billing sample application.</p>
<p>The <code>sendBillingRequest()</code> method has a single {@link android.os.Bundle} parameter.
The Bundle that you deliver must include several key-value pairs that specify various parameters for
the request, such as the type of billing request you are making, the item that is being purchased and
its type, and the application that is making the request. For more information about the Bundle keys
that are sent with a request, see <a
href="{@docRoot}google/play/billing/billing_reference.html#billing-interface">In-app Billing
Service Interface</a>.
<p>One of the most important keys that every request Bundle must have is the
<code>BILLING_REQUEST</code> key. This key lets you specify the type of billing request you are
making. Google Play's in-app billing service supports the following five types of billing
requests:</p>
<ul>
<li><code>CHECK_BILLING_SUPPORTED</code>
<p>This request verifies that the Google Play application supports in-app billing. You
usually send this request when your application first starts up. This request is useful if you
want to enable or disable certain UI features that are relevant only to in-app billing.</p>
</li>
<li><code>REQUEST_PURCHASE</code>
<p>This request sends a purchase message to the Google Play application and is the foundation
of in-app billing. You send this request when a user indicates that he or she wants to purchase
an item in your application. Google Play then handles the financial transaction by displaying
the checkout user interface.</p>
</li>
<li><code>GET_PURCHASE_INFORMATION</code>
<p>This request retrieves the details of a purchase state change. A purchase changes state when
a requested purchase is billed successfully or when a user cancels a transaction during
checkout. It can also occur when a previous purchase is refunded. Google Play notifies your
application when a purchase changes state, so you only need to send this request when there is
transaction information to retrieve.</p>
</li>
<li><code>CONFIRM_NOTIFICATIONS</code>
<p>This request acknowledges that your application received the details of a purchase state
change. Google Play sends purchase state change notifications to your application until you
confirm that you received them.</p>
</li>
<li><code>RESTORE_TRANSACTIONS</code>
<p>This request retrieves a user's transaction status for <a
href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">managed
purchases</a> and <a
href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">subscriptions</a>.
You should send this request only when you need to retrieve a user's transaction
status, which is usually only when your application is reinstalled or installed for the first
time on a device.</p>
</li>
</ul>
<h3 id="billing-response">In-app Billing Responses</h3>
<p>The Google Play application responds to in-app billing requests with both synchronous and
asynchronous responses. The synchronous response is a {@link android.os.Bundle} with the following
three keys:</p>
<ul>
<li><code>RESPONSE_CODE</code>
<p>This key provides status information and error information about a request.</p>
</li>
<li><code>PURCHASE_INTENT</code>
<p>This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout
activity.</p>
</li>
<li><code>REQUEST_ID</code>
<p>This key provides you with a request identifier, which you can use to match asynchronous
responses with requests.</p>
</li>
</ul>
<p>Some of these keys are not relevant to every request. For more information, see <a
href="#billing-message-sequence">Messaging sequence</a> later in this document.</p>
<p>The asynchronous response messages are sent in the form of individual broadcast intents and
include the following:</p>
<ul>
<li><code>com.android.vending.billing.RESPONSE_CODE</code>
<p>This response contains a Google Play server response code, and is sent after you make an
in-app billing request. A server response code can indicate that a billing request was
successfully sent to Google Play or it can indicate that some error occurred during a billing
request. This response is <em>not</em> used to report any purchase state changes (such as refund
or purchase information). For more information about the response codes that are sent with this
response, see <a
href="{@docRoot}google/play/billing/billing_reference.html#billing-codes">Server Response Codes
for In-app Billing</a>.</p>
</li>
<li><code>com.android.vending.billing.IN_APP_NOTIFY</code>
<p>This response indicates that a purchase has changed state, which means a purchase succeeded,
was canceled, or was refunded. This response contains one or more notification IDs. Each
notification ID corresponds to a specific server-side message, and each messages contains
information about one or more transactions. After your application receives an
<code>IN_APP_NOTIFY</code> broadcast intent, you send a <code>GET_PURCHASE_INFORMATION</code>
request with the notification IDs to retrieve message details.</p>
</li>
<li><code>com.android.vending.billing.PURCHASE_STATE_CHANGED</code>
<p>This response contains detailed information about one or more transactions. The transaction
information is contained in a JSON string. The JSON string is signed and the signature is sent
to your application along with the JSON string (unencrypted). To help ensure the security of
your in-app billing messages, your application can verify the signature of this JSON string.</p>
</li>
</ul>
<p>The JSON string that is returned with the <code>PURCHASE_STATE_CHANGED</code> intent provides
your application with the details of one or more billing transactions. An example of this JSON
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" : "12999556515565155651.5565135565155651",
"packageName" : "com.example.dungeons",
"productId" : "android.test.purchased",
"developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ",
"purchaseTime" : 1290114783411,
"purchaseState" : 0,
"purchaseToken" : "rojeslcdyyiapnqcynkjyyjh" }]
}
</pre>
<p>For more information about the fields in this JSON string, see <a
href="{@docRoot}google/play/billing/billing_reference.html#billing-intents">In-app Billing
Broadcast Intents</a>.</p>
<h3 id="billing-message-sequence">Messaging sequence</h3>
<p>The messaging sequence for a typical purchase request is shown in figure 2. 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 2 does not show the <code>RESPONSE_CODE</code>
broadcast intents that are sent for every request.</p>
<p>The basic message sequence for an in-app purchase request is as follows:</p>
<ol>
<li>Your application sends a purchase request (<code>REQUEST_PURCHASE</code> type), specifying a
product ID and other parameters.</li>
<li>The Google Play application sends your application a Bundle with the following keys:
<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.
<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), Google Play sends your application a notification message (an
<code>IN_APP_NOTIFY</code> broadcast intent). The notification message includes a notification ID,
which references the transaction.</li>
<li>Your application requests the transaction information by sending a
<code>GET_PURCHASE_STATE_CHANGED</code> request, specifying the notification ID for the
transaction.</li>
<li>The Google Play application sends a Bundle with a <code>RESPONSE_CODE</code> key and a
<code>REQUEST_ID</code> key.
<li>Google Play sends the transaction information to your application in a
<code>PURCHASE_STATE_CHANGED</code> broadcast intent.</li>
<li>Your application confirms that you received the transaction information for the given
notification ID by sending a confirmation message (<code>CONFIRM_NOTIFICATIONS</code> type),
specifying the notification ID for which you received transaction information.</li>
<li>The Google Play application sends your application a Bundle with a
<code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key.</li>
</ol>
<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 Google
Play (step 8 in figure 2). If you don't send a confirmation message, Google Play 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 Google Play 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>
broadcast intents that are sent for every request.</p>
<div class="figure" style="width:490px">
<img src="{@docRoot}images/billing_restore_transactions.png" alt="" height="168" />
<p class="img-caption">
<strong>Figure 3.</strong> Message sequence for a restore transactions request.
</p>
</div>
<p>The request triggers three responses. The first is a {@link android.os.Bundle} with a
<code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key. Next, the Google Play
application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides status information
or error information about the request. As always, the <code>RESPONSE_CODE</code> message references
a specific request ID, so you can determine which request a <code>RESPONSE_CODE</code> message
pertains to.</p>
<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. 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
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>
<div class="figure" style="width:454px">
<img src="{@docRoot}images/billing_check_supported.png" alt="" height="168" />
<p class="img-caption">
<strong>Figure 4.</strong> Message sequence for checking whether in-app billing is supported.
</p>
</div>
<p>The synchronous response for a <code>CHECK_BILLING_SUPPORTED</code> request provides a Bundle
with a server response code. A <code>RESULT_OK</code> response code indicates that in-app billing
is supported; a <code>RESULT_BILLING_UNAVAILABLE</code> response code indicates that in-app billing
is unavailable because the API version you specified is unrecognized or the user is not eligible to
make in-app purchases (for example, the user resides in a country that does not allow in-app
billing). A <code>SERVER_ERROR</code> can also be returned, indicating that there was a problem with
<h2 id="api">In-app Billing API</h2>
<p>Your application accesses the In-app Billing service using an API that is
exposed by the Google Play app that is installed on the device. The Google Play
app then conveys billing requests and responses between your
application and the Google Play server. In practice, your application never
directly communicates with the Google Play server. Instead, your application
sends billing requests to the Google Play application over interprocess
communication (IPC) and receives responses from the Google Play app.
Your application does not manage any network connections between itself and
the Google Play server.</p>
<p>In-app Billing can be implemented only in applications that you publish
through Google Play. To complete in-app purchase requests, the Google Play app
must be able to access the Google Play server over the network.</p>
<h3 id="billing-action-notify">Handling IN_APP_NOTIFY messages</h3>
<p>Usually, your application receives an <code>IN_APP_NOTIFY</code> broadcast intent from Google
Play in response to a <code>REQUEST_PURCHASE</code> message (see figure 2). The
<code>IN_APP_NOTIFY</code> broadcast intent informs your application that the state of a requested
purchase has changed. To retrieve the details of that purchase, your application sends a
<code>GET_PURCHASE_INFORMATION</code> request. Google Play 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
Google Play that you have received the purchase state change information.</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>
<h4>Handling multiple IN_APP_NOTIFY messages</h4>
<p>When Google Play 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, Google
Play 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, Google Play
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
shown in <em>italic</em>. For clarity, figure 5 does not show the <code>RESPONSE_CODE</code>
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>
</div>
<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, Google Play sends an <code>IN_APP_NOTIFY</code>
message to the second device, informing the application that there is a purchase state change. Your
application can handle this message the same way it handles the response from an
application-initiated <code>REQUEST_PURCHASE</code> message, so that ultimately your application
receives a <code>PURCHASE_STATE_CHANGED</code> broadcast intent message that includes information
about the item that has been purchased. This applies only to items that have their <a
href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">purchase type</a> set
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 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
<code>PURCHASE_STATE_CHANGED</code> message that includes information about the item that has been
refunded. The refund information is included in the JSON string that accompanies the
<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,
Google Play signs the JSON string that is contained in the <code>PURCHASE_STATE_CHANGED</code>
broadcast intent. Google Play uses the private key that is associated with your publisher account
to create this signature. The publisher site generates an RSA key pair for each publisher account.
You can find the public key portion of this key pair on your account's profile page. It is the same
public key that is used with Google Play licensing.</p>
<p>When Google Play signs a billing response, it includes the signed JSON string (unencrypted)
and the signature. When your application receives this signed response you can use the public key
portion of your RSA key pair to verify the signature. By performing signature verification you can
help detect responses that have been tampered with or that have been spoofed. You can perform this
signature verification step in your application; however, if your application connects to a secure
remote server then we recommend that you perform the signature verification on that server.</p>
<p>In-app billing also uses nonces (a random number used once) to help verify the integrity of the
purchase information that's returned from Google Play. Your application must generate a nonce and
send it with a <code>GET_PURCHASE_INFORMATION</code> request and a <code>RESTORE_TRANSACTIONS</code>
request. When Google Play receives the request, it adds the nonce to the JSON string that
contains the transaction information. The JSON string is then signed and returned to your
application. When your application receives the JSON string, you need to verify the nonce as well as
the signature of the JSON string.</p>
<p>For more information about best practices for security and design, see <a
href="{@docRoot}google/play/billing/billing_best_practices.html">Security and Design</a>.</p>
<h2 id="billing-limitations">In-app Billing Requirements and Limitations</h2>
<p>Before you get started with in-app billing, be sure to review the following requirements and
limitations.</p>
<p>Currently, Google Play supports two versions of the In-app Billing API.
To determine which version you should use, see <a href="#migration">Migration
Considerations</a>.</p>
<h4><a href="{@docRoot}google/play/billing/api.html">Version 3</a> (recommended)</h4>
<ul>
<li>In-app billing can be implemented only in applications that you publish through Google
Play.</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>
<li>An application can use in-app billing only if the device is running Android 1.6 (API level 4)
or higher.</li>
<li>You can use in-app billing to sell only digital content. You cannot use in-app billing to sell
physical goods, personal services, or anything that requires physical delivery.</li>
<li>Google Play does not provide any form of content delivery. You are responsible for
delivering the digital content that you sell in your applications.</li>
<li>You cannot implement in-app billing on a device that never connects to the network. To
complete in-app purchase requests, a device must be able to access the Google Play server over
the network. </li>
<li>Requests are sent through a streamlined API that allows you to easily request
product details from Google Play, order in-app products, and quickly restore
items based on users' product ownership</li>
<li>Order information is synchronously propagated to the device on purchase
completion</li>
<li>All purchases are “managed” (that is, Google Play keeps track of the user's
ownership of in-app products). The user cannot own multiple copies of an in-app
item; only one copy can be owned at any point in time</li>
<li>Purchased items can be consumed. When consumed, the item reverts to the
"unowned" state and can be purchased again from Google Play</li>
</ul>
<h4><a href="{@docRoot}google/play/billing/v2/api.html">Version 2</a></h4>
<ul>
<li>Requests are sent via a single API interface ({@code sendBillingRequest})</li>
<li>Responses from Google Play are asynchronous, in the form of broadcast intents</li>
<li>No consumption model provided. You have to implement your own solution</li>
<li>Provides support for subscriptions and unmanaged in-app purchase items,
as well as managed in-app products</li>
</ul>
<p>Both versions offer very broad compatibility across the range of Android
devices. In-app Billing Version 3 is supported on devices running Android 2.2 or
higher that have the latest version of the Google Play store installed
(over 90% of active devices). Version 2 offers similar compatibility. See
<a href="{@docRoot}google/play/billing/versions.html">Version Notes</a> for
more details.</p>
<h2 id="products">In-app Products</h2>
<p>In-app products are the digital goods that you offer for sale from inside your
application to users. Examples of digital goods includes in-game currency,
application feature upgrades that enhance the user experience, and new content
for your application.</p>
<p>You can use In-app Billing to sell only digital content.
You cannot use In-app Billing to sell physical goods, personal services, or
anything that requires physical delivery. Unlike with priced applications, once
the user has purchased an in-app product there is no refund window.</p>
<p>Google Play does not provide any form of content delivery. You are
responsible for delivering the digital content that you sell in your
applications. In-app products are always explicitly associated with one and
only one app. That is, one application cannot purchase an in-app product
published for another app, even if they are from the same developer.</p>
<h3 id="prodtypes">Product types</h3>
<p>In-app Billing supports different product types to give you flexibility in
how you monetize your application. In all cases, you define your products using
the Google Play Developer Console.</p>
<p>You can specify these types of products for your In-app Billing application
— <em>managed in-app products</em>, <em>subscriptions</em>, and <em>unmanaged
in-app products</em>. The term “managed” indicates that Google Play handles and
tracks ownership for in-app products on your application on a per user account
basis, while “unmanaged” indicates that you will manage the ownership information yourself.</p>
<p>To learn more about the product types supported by the different API versions,
see the related documentation for <a href="{@docRoot}google/play/billing/v2/api.html#billing-types">Version 2</a> and <a href="{@docRoot}google/play/billing/api.html#producttypes">Version 3</a>.</p>
<h2 id="console">Google Play Developer Console</h2>
<p>The Developer Console is where you can publish your
In-app Billing application, and manage the various in-app products that are
available for purchase from your application.</p>
<p>You can create a product list of
digital goods that are associated with your application, including items for
one-time purchase and recurring subscriptions. For each item, you can define
information such as the item’s unique product ID (also called its SKU), product
type, pricing, description, and how Google Play should handle and track
purchases for that product.</p>
<p>You can also create test accounts to authorize
access for testing applications that are unpublished.</p>
<p>To learn how to use the Developer Console to configure your in-app
products and product list, see
<a href="{@docRoot}google/play/billing/billing_admin.html">Administering
In-app Billing</a>.</p>
<h2 id="checkout">Google Play Purchase Flow</h2>
<p>Google Play uses the same checkout backend service as is used for application
purchases, so your users experience a consistent and familiar purchase flow.</p>
<p class="note"><strong>Important:</strong> You must have a Google Checkout
Merchant account to use the In-app Billing service on Google Play.</p>
<p>To initiate a purchase, your application sends a billing request for a
specific in-app product. Google Play then handles all of the checkout details for
the transaction, including requesting and validating the form of payment and
processing the financial transaction.</p>
<p>When the checkout process is complete,
Google Play sends your application the purchase details, such as the order
number, the order date and time, and the price paid. At no point does your
application have to handle any financial transactions; that role is provided by
Google Play.</p>
<img src="{@docRoot}images/in-app-billing/v3/iab_v3_checkout_flow.png" height="382" id="figure1" />
<p class="img-caption">
<strong>Figure 1.</strong> Applications initiate In-app Billing requests
through their own UI (first screen). Google Play responds to the request by
providing the checkout user interface (middle screen). When checkout is
complete, the application resumes.
</p>
<h2>The Sample Applications</h2>
<p>To help you integrate In-app Billing into your application, the Android SDK
provides two sample applications that demonstrate how to sell in-app products
from inside an app.</p>
<dl>
<dt><a href="{@docRoot}training/in-app-billing/preparing-iab-app.html#GetSample">TrivialDrive sample for the Version 3 API</a></dt>
<dd>This sample shows how to use the In-app Billing Version 3 API to implement
in-app product purchases for a driving game. The application demonstrates how to
send In-app Billing requests, and handle synchronous responses from Google Play.
The application also shows how to record item consumption with the API. The
Version 3 sample includes convenience classes for processing In-app Billing
operations as well as perform automatic signature verification.</dd>
<dt><a href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">Dungeons sample for the Version 2 API</a></dt>
<dd>This sample demonstrates how to use the In-app Billing Version 2 API to sell
standard in-app products and subscriptions for an adventuring game. It also
contains examples of the database, user interface, and business logic you might
use to implement In-app Billing.</dd>
</dl>
<p class="caution"><strong>Important</strong>: It's <em>strongly recommended</em>
that you obfuscate the code in your application before you publish it. For
more information, see
<a href="{@docRoot}google/play/billing/billing_best_practices.html">Security
and Design</a>.</p>
<h2 id="migration">Migration Considerations</h2>
<p>The following considerations may be applicable if you are planning to create a new
in-app biling application, or migrate your existing In-app Billing implementation
from the <a href="{@docRoot}google/play/billing/v2/api.html">Version 2</a> or
earlier API to the <a href="{@docRoot}google/play/billing/api.html">Version 3</a> API.</p>
<p>Google Play will continue to support both the Version 2 and Version 3 APIs for
some time, so you can plan to migrate to Version 3 at your own pace. The Google
Play team will give advance notice of any upcoming changes to the support
status of In-app Billing Version 2.</p>
<p>You can use the following table to decide which version of the API to use,
depending on the needs of your application.</p>
<p class="table-caption" id="table1">
<strong>Table 1.</strong> Selecting the In-app Billing API Version for Your
Project</p>
<table>
<tr>
<th scope="col">Choose Version 3 if ...</th>
<th scope="col">Choose Version 2 if ...</th>
</tr>
<tr>
<td>
<ul>
<li>You want to sell in-app products only (and not subscriptions)</li>
<li>You need synchronous order confirmations when purchases complete</li>
<li>You need to synchronously restore a user's current purchases</li>
</ul>
</td>
<td>
<ul>
<li>You want to sell subscriptions in your app</li>
</ul>
</td>
</tr>
</table>
<p>If you have published apps selling in-app products, note that:</p>
<ul>
<li>Managed items that you have previously defined in the Developer Console will
work with Version 3 as before.</li>
<li>Unmanaged items that you have defined for existing applications will be
treated as managed products if you make a purchase request for these items using
the Version 3 API. You do not need to create a new product entry in Developer
Console for these items, and you can use the same product IDs to purchase these
items. They will still continue to be treated as unmanaged items if you make a
purchase request for them using the Version 2 or earlier API.
</ul>
<p>For more information about in-app billing requirements, see <a
href="https://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1153481">In-App
Billing Availability and Policies</a>.</p>

638
docs/html/google/play/billing/billing_reference.jd
View File

@@ -1,4 +1,4 @@
page.title=In-app Billing Reference
page.title=In-app Billing Reference <span style="font-size:16px;">(IAB Version 3)</span>
parent.title=In-app Billing
parent.link=index.html
@jd:body
@@ -7,485 +7,213 @@ parent.link=index.html
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#billing-codes">Server Response Codes for In-app Billing</a></li>
<li><a href="#billing-interface">In-app Billing Service Interface</a></li>
<li><a href="#billing-intents">In-app Billing Broadcast Intents</a></li>
<li><a href="#other-intents">Other Broadcast Intents</a></li>
<li><a href="#billing-versions">In-app Billing API Versions</a></li>
<li><a href="#billing-codes">Server Response Codes</a></li>
<li><a href="#billing-interface">API Reference</a>
<ol>
<li><a href="#getSkuDetails">getSkuDetails()</a></li>
<li><a href="#getBuyIntent">getBuyIntent()</a></li>
<li><a href="#getPurchases">getPurchases()</a></li>
</ol>
</li>
</ol>
<h2>Downloads</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">Sample
Application</a></li>
Application (V3)</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">Overview of In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html">Implementing In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_best_practices.html">Security and
Design</a></li>
<li><a href="{@docRoot}google/play/billing/billing_testing.html">Testing In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/api.html">In-app Billing Version 3</a></li>
<li><a href="{@docRoot}training/in-app-billing/index.html">Selling In-app Products</a></li>
</ol>
</div>
</div>
<p>This documentation provides technical reference information for using the In-app Billing Version 3 API. </p>
<p>The following document provides technical reference information for the following:</p>
<ul>
<li><a href="#billing-codes">Google Play Server Response Codes for In-app Billing</a></li>
<li><a href="#billing-interface">In-app Billing Interface Parameters</a></li>
<li><a href="#billing-intents">In-app Billing Broadcast Intents</a></li>
<li><a href="#other-intents">Other Intents</a></li>
<li><a href="#billing-versions">In-app Billing API Versions</a></li>
</ul>
<h2 id="billing-codes">Server Response Codes for In-app Billing</h2>
<p>The following table lists all of the server response codes that are sent from Google Play to
your application. Google Play sends these response codes asynchronously as
<code>response_code</code> extras in the <code>com.android.vending.billing.RESPONSE_CODE</code>
broadcast intent. Your application must handle all of these response codes.</p>
<p class="table-caption" id="response-codes-table"><strong>Table 1.</strong> Summary of response
codes returned by Google Play.</p>
<h2 id="billing-codes">Server Response Codes</h2>
<p>The following table lists all of the server response codes that are sent from Google Play to your application. Google Play sends the response code synchronously as an integer mapped to the {@code RESPONSE_CODE} key in the response {@code Bundle}. Your application must handle all of these response codes.</p>
<p class="table-caption" id="response-codes-table">
<strong>Table 1.</strong> Summary of response codes for In-app Billing Version 3 API calls.</p>
<table>
<tr>
<th>Response Code</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td><code>RESULT_OK</code></td>
<td>0</td>
<td>Indicates that the request was sent to the server successfully. When this code is returned in
response to a <code>CHECK_BILLING_SUPPORTED</code> request, indicates that billing is
supported.</td>
</tr>
<tr>
<td><code>RESULT_USER_CANCELED</code></td>
<td>1</td>
<td>Indicates that the user pressed the back button on the checkout page instead of buying the
item.</td>
</tr>
<tr>
<td><code>RESULT_SERVICE_UNAVAILABLE</code></td>
<td>2</td>
<td>Indicates that the network connection is down.</td>
</tr>
<tr>
<td><code>RESULT_BILLING_UNAVAILABLE</code></td>
<td>3</td>
<td>Indicates that in-app billing is not available because the <code>API_VERSION</code> that you
specified is not recognized by the Google Play application or the user is ineligible for in-app
billing (for example, the user resides in a country that prohibits in-app purchases).</td>
</tr>
<tr>
<td><code>RESULT_ITEM_UNAVAILABLE</code></td>
<td>4</td>
<td>Indicates that Google Play cannot find the requested item in the application's product
list. This can happen if the product ID is misspelled in your <code>REQUEST_PURCHASE</code>
request or if an item is unpublished in the application's product list.</td>
</tr>
<tr>
<td><code>RESULT_DEVELOPER_ERROR</code></td>
<td>5</td>
<td>Indicates that an application is trying to make an in-app billing request but the application
has not declared the com.android.vending.BILLING permission in its manifest. Can also indicate
that an application is not properly signed, or that you sent a malformed request, such as a
request with missing Bundle keys or a request that uses an unrecognized request type.</td>
</tr>
<tr>
<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 Checkout.</td>
</tr>
<tr>
<th scope="col">Response Code</th>
<th scope="col">Value</th>
<th scope="col">Description</th>
</tr>
<tr>
<td>{@code BILLING_RESPONSE_RESULT_OK}</td>
<td>0</td>
<td>Success</td>
</tr>
<tr>
<td>{@code BILLING_RESPONSE_RESULT_USER_CANCELED}</td>
<td>1</td>
<td>User pressed back or canceled a dialog</td>
</tr>
<tr>
<td>{@code BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE}</td>
<td>3</td>
<td>Billing API version is not supported for the type requested</td>
</tr>
<tr>
<td>{@code BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE}</td>
<td>4</td>
<td>Requested product is not available for purchase</td>
</tr>
<tr>
<td>{@code BILLING_RESPONSE_RESULT_DEVELOPER_ERROR}</td>
<td>5</td>
<td>Invalid arguments provided to the API. This error can also indicate that the application was not correctly signed or properly set up for In-app Billing in Google Play, or does not have the necessary permissions in its manifest</td>
</tr>
<tr>
<td>{@code BILLING_RESPONSE_RESULT_ERROR}</td>
<td>6</td>
<td>Fatal error during the API action</td>
</tr>
<tr>
<td>{@code BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED}</td>
<td>7</td>
<td>Failure to purchase since item is already owned</td>
</tr>
<tr>
<td>{@code BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED}</td>
<td>8</td>
<td>Failure to consume since item is not owned</td>
</tr>
</table>
<h2 id="billing-interface">In-app Billing Service Interface</h2>
<h2 id="billing-interface">API Reference</h2>
<p>The In-app Billing Version 3 API is defined in the {@code IInAppBillingService.aidl} file, which is included with the Version 3 <a href="{@docRoot}training/in-app-billing/preparing-iab-app.html#GetSample">sample application</a>.</p>
<p>The following section describes the interface for Google Play's in-app billing service. The
interface is defined in the <code>IMarketBillingService.aidl</code> file, which is included with the
in-app billing <a
href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">sample
application</a>.</p>
<p>The interface consists of a single request method <code>sendBillingRequest()</code>. This method
takes a single {@link android.os.Bundle} parameter. The Bundle parameter includes several key-value
pairs, which are summarized in table 2.</p>
<p class="table-caption"><strong>Table 2.</strong> Description of Bundle keys passed in a
<code>sendBillingRequest()</code> request.</p>
<h3 id="getSkuDetails">The getSkuDetails() method</h3>
<p>This method returns product details for a list of product IDs. In the response {@code Bundle} sent by Google Play, the query results are stored in a String {@code ArrayList} mapped to the {@code DETAILS_LIST} key. Each String in the details list contains product details for a single product in JSON format. The fields in the JSON string with the product details are summarized in table 2.</p>
<p class="table-caption" id="product-details-table">
<strong>Table 2.</strong> Description of JSON fields with product item details returned from a {@code getSkuDetails} request.</p>
<table>
<tr>
<th>Key</th>
<th>Type</th>
<th>Possible Values</th>
<th>Required?</th>
<th>Description</th>
</tr>
<tr>
<td><code>BILLING_REQUEST</code></td>
<td><code>String</code></td>
<td><code>CHECK_BILLING_SUPPORTED</code>, <code>REQUEST_PURCHASE</code>,
<code>GET_PURCHASE_INFORMATION</code>, <code>CONFIRM_NOTIFICATIONS</code>, or
<code>RESTORE_TRANSACTIONS</code></td>
<td>Yes</td>
<td>The type of billing request you are making with the <code>sendBillingRequest()</code> request.
The possible values are discussed more below this table.</td>
</tr>
<tr>
<td><code>API_VERSION</code></td>
<td><code>int</code></td>
<td> <ul>
<li><code>"2"</code> [<a href="#version_2">details</a>]</li>
<li><code>"1"</code> [<a href="#version_1">details</a>]</li>
</ul></td>
<td>Yes</td>
<td>The version of Google Play's in-app billing service you want to use. The current version is
2.</td>
</tr>
<tr>
<td><code>PACKAGE_NAME</code></td>
<td><code>String</code></td>
<td>A valid package name.</td>
<td>Yes</td>
<td>The name of the application that is making the request.</td>
</tr>
<tr>
<td><code>ITEM_ID</code></td>
<td><code>String</code></td>
<td>Any valid product identifier.</td>
<td>Required for <code>REQUEST_PURCHASE</code> requests.</td>
<td>The product ID of the item you are making a billing request for. Every in-app item that you
sell using Google Play's in-app billing service must have a unique product ID, which you
specify on the Google Play publisher site.</td>
</tr>
<tr>
<td><code>NONCE</code></td>
<td><code>long</code></td>
<td>Any valid <code>long</code> value.</td>
<td>Required for <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code>
requests.</td>
<td>A number used once. Your application must generate and send a nonce with each
<code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> request. The nonce is
returned with the <code>PURCHASE_STATE_CHANGED</code> broadcast intent, so you can use this value
to verify the integrity of transaction responses form Google Play.</td>
</tr>
<tr>
<td><code>NOTIFY_IDS</code></td>
<td>Array of <code>long</code> values</td>
<td>Any valid array of <code>long</code> values</td>
<td>Required for <code>GET_PURCHASE_INFORMATION</code> and <code>CONFIRM_NOTIFICATIONS</code>
requests.</td>
<td>An array of notification identifiers. A notification ID is sent to your application in an
<code>IN_APP_NOTIFY</code> broadcast intent every time a purchase changes state. You use the
notification to retrieve the details of the purchase state change.</td>
</tr>
<tr>
<td><code>DEVELOPER_PAYLOAD</code></td>
<td><code>String</code></td>
<td>Any valid <code>String</code> less than 256 characters long.</td>
<td>No</td>
<td>A developer-specified string that can be specified when you make a
<code>REQUEST_PURCHASE</code> request. This field is returned in the JSON string that contains
transaction information for an order. You can use this key to send supplemental information with
an order. For example, you can use this key to send index keys with an order, which is useful if
you are using a database to store purchase information. We recommend that you do not use this key
to send data or content.</td>
</tr>
<tr>
<th scope="col">Key</th>
<th scope="col">Description</th>
</tr>
<tr>
<td>{@code productId}</td>
<td>The product ID for the product.</td>
</tr>
<tr>
<td>{@code type}</td>
<td>Value must be “inapp” for an in-app purchase type.</td>
</tr>
<tr>
<td>{@code price}</td>
<td>Formatted price of the item, including its currency sign. The price does not include tax.</td>
</tr>
<tr>
<td>{@code title}</td>
<td>Title of the product.</td>
</tr>
<tr>
<td>{@code description}</td>
<td>Description of the product.</td>
</tr>
</table>
</p>
<p>The <code>BILLING_REQUEST</code> key can have the following values:</p>
<ul>
<li><code>CHECK_BILLING_SUPPORTED</code>
<p>This request verifies that the Google Play application supports in-app billing. You
usually send this request when your application first starts up. This request is useful if you
want to enable or disable certain UI features that are relevant only to in-app billing.</p>
</li>
<li><code>REQUEST_PURCHASE</code>
<p>This request sends a purchase message to the Google Play application and is the foundation
of in-app billing. You send this request when a user indicates that he or she wants to purchase
an item in your application. Google Play then handles the financial transaction by displaying
the checkout user interface.</p>
</li>
<li><code>GET_PURCHASE_INFORMATION</code>
<p>This request retrieves the details of a purchase state change. A purchase state change can
occur when a purchase request is billed successfully or when a user cancels a transaction during
checkout. It can also occur when a previous purchase is refunded. Google Play notifies your
application when a purchase changes state, so you only need to send this request when there is
transaction information to retrieve.</p>
</li>
<li><code>CONFIRM_NOTIFICATIONS</code>
<p>This request acknowledges that your application received the details of a purchase state
change. That is, this message confirms that you sent a <code>GET_PURCHASE_INFORMATION</code>
request for a given notification and that you received the purchase information for the
notification.</p>
</li>
<li><code>RESTORE_TRANSACTIONS</code>
<p>This request retrieves a user's transaction status for managed purchases (see <a
href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">Choosing a
Purchase Type</a> for more information). You should send this message only when you need to
retrieve a user's transaction status, which is usually only when your application is reinstalled
or installed for the first time on a device.</p>
</li>
</ul>
<p>Every in-app billing request generates a synchronous response. The response is a {@link
android.os.Bundle} and can include one or more of the following keys:</p>
<ul>
<li><code>RESPONSE_CODE</code>
<p>This key provides status information and error information about a request.</p>
</li>
<li><code>PURCHASE_INTENT</code>
<p>This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout
activity.</p>
</li>
<li><code>REQUEST_ID</code>
<p>This key provides you with a request identifier, which you can use to match asynchronous
responses with requests.</p>
</li>
</ul>
<p>Some of these keys are not relevant to certain types of requests. Table 3 shows which keys are
returned for each request type.</p>
<p class="table-caption"><strong>Table 3.</strong> Description of Bundle keys that are returned with
each in-app billing request type.</p>
<h3 id="getBuyIntent">The getBuyIntent() method</h3>
<p>This method returns a response code integer mapped to the {@code RESPONSE_CODE} key, and a {@code PendingIntent} to launch the puchase flow for the in-app item mapped to the {@code BUY_INTENT} key. When it receives the {@code PendingIntent}, Google Play sends a response {@code Intent} with the data for that purchase order. The data that is returned in the response {@code Intent} is summarized in table 3.</p>
<p class="table-caption" id="purchase-pendingintent-response-table">
<strong>Table 3.</strong> Response data from an In-app Billing Version 3 purchase request.</p>
<table>
<tr>
<th>Request Type</th>
<th>Keys Returned</th>
<th>Possible Response Codes</th>
</tr>
<tr>
<td><code>CHECK_BILLING_SUPPORTED</code></td>
<td><code>RESPONSE_CODE</code></td>
<td><code>RESULT_OK</code>, <code>RESULT_BILLING_UNAVAILABLE</code>, <code>RESULT_ERROR</code>,
<code>RESULT_DEVELOPER_ERROR</code></td>
</tr>
<tr>
<td><code>REQUEST_PURCHASE</code></td>
<td><code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, <code>REQUEST_ID</code></td>
<td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
</tr>
<tr>
<td><code>GET_PURCHASE_INFORMATION</code></td>
<td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td>
<td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
</tr>
<tr>
<td><code>CONFIRM_NOTIFICATIONS</code></td>
<td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td>
<td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
</tr>
<tr>
<td><code>RESTORE_TRANSACTIONS</code></td>
<td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td>
<td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
</tr>
<tr>
<th scope="col">Key</th>
<th scope="col">Description</th>
</tr>
<tr>
<td>{@code RESPONSE_CODE}</td>
<td>0 if the purchase was success, error otherwise.</td>
</tr>
<tr>
<td>{@code INAPP_PURCHASE_DATA}</td>
<td>
A String in JSON format that contains details about the purchase order. See table 4 for a description of the JSON fields.
</td>
</tr>
<tr>
<td>{@code INAPP_DATA_SIGNATURE}</td>
<td>String containing the signature of the purchase data that was signed with the private key of the developer.</td>
</tr>
</table>
</p>
<h2 id="billing-intents">In-app Billing Broadcast Intents</h2>
<p>The following section describes the in-app billing broadcast intents that are sent by the Google
Play application. These broadcast intents inform your application about in-app billing actions
that have occurred. Your application must implement a {@link android.content.BroadcastReceiver} to
receive these broadcast intents, such as the <code>BillingReceiver</code> that's shown in the in-app
billing <a href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">sample
application</a>.</p>
<h4>com.android.vending.billing.RESPONSE_CODE</h4>
<p>This broadcast intent contains a Google Play response code, and is sent after you make an
in-app billing request. A server response code can indicate that a billing request was successfully
sent to Google Play or it can indicate that some error occurred during a billing request. This
intent is not used to report any purchase state changes (such as refund or purchase information).
For more information about the response codes that are sent with this response, see <a
href="#billing-codes">Google Play Response Codes for In-app Billing</a>. The sample application
assigns this broadcast intent to a constant named <code>ACTION_RESPONSE_CODE</code>.</p>
<h5>Extras</h5>
<ul type="none">
<li><code>request_id</code>&mdash;a <code>long</code> representing a request ID. A request ID
identifies a specific billing request and is returned by Google Play at the time a request is
made.</li>
<li><code>response_code</code>&mdash;an <code>int</code> representing the Google Play server
response code.</li>
</ul>
<h4>com.android.vending.billing.IN_APP_NOTIFY</h4>
<p>This response indicates that a purchase has changed state, which means a purchase succeeded, was
canceled, or was refunded. This response contains one or more notification IDs. Each notification ID
corresponds to a specific server-side message, and each messages contains information about one or
more transactions. After your application receives an <code>IN_APP_NOTIFY</code> broadcast intent,
you send a <code>GET_PURCHASE_INFORMATION</code> request with the notification IDs to retrieve the
message details. The sample application assigns this broadcast intent to a constant named
<code>ACTION_NOTIFY</code>.</p>
<h5>Extras</h5>
<ul type="none">
<li><code>notification_id</code>&mdash;a <code>String</code> representing the notification ID for
a given purchase state change. Google Play notifies you when there is a purchase state change
and the notification includes a unique notification ID. To get the details of the purchase state
change, you send the notification ID with the <code>GET_PURCHASE_INFORMATION</code> request.</li>
</ul>
<h4>com.android.vending.billing.PURCHASE_STATE_CHANGED</h4>
<p>This broadcast intent contains detailed information about one or more transactions. The
transaction information is contained in a JSON string. The JSON string is signed and the signature
is sent to your application along with the JSON string (unencrypted). To help ensure the security of
your in-app billing messages, your application can verify the signature of this JSON string. The
sample application assigns this broadcast intent to a constant named
<code>ACTION_PURCHASE_STATE_CHANGED</code>.</p>
<h5>Extras</h5>
<ul type="none">
<li><code>inapp_signed_data</code>&mdash;a <code>String</code> representing the signed JSON
string.</li>
<li><code>inapp_signature</code>&mdash;a <code>String</code> representing the signature.</li>
</ul>
<p class="note"><strong>Note:</strong> Your application should map the broadcast intents and extras
to constants that are unique to your application. See the <code>Consts.java</code> file in the
sample application to see how this is done.</p>
<p>The fields in the JSON string are described in the following table (see table 4):</p>
<p class="table-caption"><strong>Table 4.</strong> Description of JSON fields that are returned with
a <code>PURCHASE_STATE_CHANGED</code> intent.</p>
<p>Table 4 describes the JSON fields that are returned in the response data for a purchase order.</p>
<p class="table-caption" id="purchase-data-table">
<strong>Table 4.</strong> Descriptions of the JSON fields for {@code INAPP_PURCHASE_DATA}.</p>
<table>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
<tr>
<td>nonce</td>
<td>A number used once. Your application generates the nonce and sends it with the
<code>GET_PURCHASE_INFORMATION</code> request. Google Play sends the nonce back as part of the
JSON string so you can verify the integrity of the message.</td>
</tr>
<tr>
<td>notificationId</td>
<td>A unique identifier that is sent with an <code>IN_APP_NOTIFY</code> broadcast intent. Each
<code>notificationId</code> corresponds to a specify message that is waiting to be retrieved on
the Google Play server. Your application sends back the <code>notificationId</code> with the
<code>GET_PURCHASE_INFORMATION</code> message so Google Play can determine which messages you
are retrieving.</td>
</tr>
<tr>
<td>orderId</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>
<td>The application package from which the purchase originated.</td>
</tr>
<tr>
<td>productId</td>
<td>The item's product identifier. Every item has a product ID, which you must specify in the
application's product list on the Google Play publisher site.</td>
</tr>
<tr>
<td>purchaseTime</td>
<td>The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).</td>
</tr>
<tr>
<td>purchaseState</td>
<td>The purchase state of the order. Possible values are 0 (purchased), 1 (canceled), 2
(refunded), or 3 (expired, for subscription purchases only).</td>
</tr>
<tr>
<td>purchaseToken</td>
<td>A token that uniquely identifies a subscription purchase for a given item and user pair.
You can use the token to specify the subscription when querying for subscription validity.
<p><br><em>Supported only in In-app Billing API version 2 and higher.</em></p></td>
</tr>
<tr>
<td>developerPayload</td>
<td>A developer-specified string that contains supplemental information about an order. You can
specify a value for this field when you make a <code>REQUEST_PURCHASE</code> request.</td>
</tr>
<tr>
<th scope="col">Field</th>
<th scope="col">Description</th>
</tr>
<tr>
<td>{@code orderId}</td>
<td>A unique order identifier for the transaction. This corresponds to the Google Wallet Order ID.</td>
</tr>
<tr>
<td>{@code packageName}</td>
<td>The application package from which the purchase originated.</td>
</tr>
<tr>
<td>{@code productId}</td>
<td>The item's product identifier. Every item has a product ID, which you must specify in the application's product list on the Google Play publisher site.</td>
</tr>
<tr>
<td>{@code purchaseTime}</td>
<td>The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).</td>
</tr>
<tr>
<td>{@code purchaseState}</td>
<td>The purchase state of the order. Possible values are 0 (purchased), 1 (canceled), or 2 (refunded).</td>
</tr>
<tr>
<td>{@code developerPayload}</td>
<td>A developer-specified string that contains supplemental information about an order. You can specify a value for this field when you make a {@code getBuyIntent} request.</td>
</tr>
<tr>
<td>{@code purchaseToken}</td>
<td>A token that uniquely identifies a purchase for a given item and user pair. </td>
</tr>
</table>
</p>
<!--<h2 id="other-intents">Other Intents</h2>
<p>The following Intents related to In-app Billing may be useful in your
implemention. </p> -->
<h2 id="http-api">HTTP API for verification and cancelation</h2>
<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/billing_subscriptions.html#play-dev-api">
Google Play Android Developer API</a> for more information.</p>
<h2 id="billing-versions">In-app Billing API Versions</h2>
<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.
<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
passed in the <code>sendBillingRequest()</code>, which is defined in the defined
in the <code>IMarketBillingService.aidl</code> file, which is included with the
in-app billing <a
href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">
sample application</a>. For more information, see <a
href="#billing-interface">In-app Billing Service Interface</a>.</p>
<h3 id="version_2">In-app Billing version 2</h3>
<p><em>May 2012</em></p>
<ul>
<li>Adds support for subscriptions.
<ul>
<li>Adds a new supported string value, "2", for the <code>API_VERSION</code> key
of the Bundle object passed in the <code>sendBillingRequest()</code>.</li>
<li>Adds a new JSON field, <code>purchaseToken</code>, to the
<code>orders</code> list returned in a <code>PURCHASE_STATE_CHANGED</code>
intent. </li>
<li>Adds a new <code>purchaseState</code> value, <code>3</code> (expired), to the
<code>orders</code> list returned in a <code>PURCHASE_STATE_CHANGED</code>
intent. The value indicates that a subscription has expired and is no longer valid.</li>
<li>Requires Google Play (Play Store) version 3.5 or higher.</li>
</ul>
<h3 id="version_1">In-app Billing version 1</h3>
<p><em>March 2011</em></p>
<ul>
<li>Initial release.</li>
<li>Requires Google Play/Android Market 2.3.4 or higher.</li>
</ul>
<h3 id="getPurchases">The getPurchases() method</h3>
<p>This method returns the current un-consumed products owned by the user. Table 5 lists the response data that is returned in the {@code Bundle}.</p>
<p class="table-caption" id="getpurchases-response-table">
<strong>Table 5.</strong> Response data from a {@code getPurchases} request.</p>
<table>
<tr>
<th scope="col">Key</th>
<th scope="col">Description</th>
</tr>
<tr>
<td>{@code RESPONSE_CODE}</td>
<td>0 if the request was successful, error otherwise.</td>
</tr>
<tr>
<td>{@code INAPP_PURCHASE_ITEM_LIST}</td>
<td>{@code StringArrayList} containing the list of productIds of purchases from this app.</td>
</tr>
<tr>
<td>{@code INAPP_PURCHASE_DATA_LIST}</td>
<td>{@code StringArrayList} containing the details for purchases from this app. See table 4 for the list of detail information stored in each {@code INAPP_PURCHASE_DATA} item in the list.</td>
</tr>
<tr>
<td>{@code INAPP_DATA_SIGNATURE_LIST}</td>
<td>{@code StringArrayList} containing the signatures of purchases from this app.</td>
</tr>
<tr>
<td>{@code INAPP_CONTINUATION_TOKEN}</td>
<td>String containing a continuation token to retrieve the next set of in-app products owned by the user. This is only set by the Google Play service if the number of products owned by the user is very large. When a continuation token is present in the response, you must make another call to {@code getPurchases} and pass in the continuation token that you received. The subsequent {@code getPurchases} call returns more purchases and possibly another continuation token.</td>
</tr>
</table>
</p>

86
docs/html/google/play/billing/billing_testing.jd
View File

@@ -9,53 +9,39 @@ parent.link=index.html
<ol>
<li><a href="#billing-testing-static">Testing in-app purchases with static responses</a></li>
<li><a href="#billing-testing-real">Testing in-app purchases using your own product IDs</a></li>
</ol>
<h2>Downloads</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">Sample
Application</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">Overview of In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html">Implementing In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_best_practices.html">Security and
Design</a></li>
<li><a href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing
Reference</a></li>
</ol>
<ol>
</div>
</div>
<p>The Google Play publisher site provides several tools that help you test your in-app billing
<p>The Google Play publisher site provides several tools that help you test your In-app Billing
implementation before it is published. You can use these tools to create test accounts and purchase
special reserved items that send static billing responses to your application.</p>
<p>To test in-app billing in an application you must install the application on an Android-powered
device. You cannot use the Android emulator to test in-app billing. The device you use for testing
<p>To test In-app Billing in an application you must install the application on an Android-powered
device. You cannot use the Android emulator to test In-app Billing. The device you use for testing
must run a standard version of the Android 1.6 or later platform (API level 4 or higher), and have
the most current version of the Google Play application installed. If a device is not running the
most current Google Play application, your application won't be able to send in-app billing
most current Google Play application, your application won't be able to send In-app Billing
requests to Google Play. For general information about how to set up a device for use in
developing Android applications, see <a href="{@docRoot}tools/device.html">Using Hardware
Devices</a>.</p>
<p>The following section shows you how to set up and use the in-app billing test tools.</p>
<p>The following section shows you how to set up and use the In-app Billing test tools.</p>
<h2 id="billing-testing-static">Testing in-app purchases with static responses</h2>
<p>We recommend that you first test your in-app billing implementation using static responses from
<p>We recommend that you first test your In-app Billing implementation using static responses from
Google Play. This enables you to verify that your application is handling the primary Google
Play responses correctly and that your application is able to verify signatures correctly.</p>
<p>To test your implementation with static responses, you make an in-app billing request using a
<p>To test your implementation with static responses, you make an In-app Billing request using a
special item that has a reserved product ID. Each reserved product ID returns a specific static
response from Google Play. No money is transferred when you make in-app billing requests with the
response from Google Play. No money is transferred when you make In-app Billing requests with the
reserved product IDs. Also, you cannot specify the form of payment when you make a billing request
with a reserved product ID. Figure 1 shows the checkout flow for the reserved item that has the
product ID android.test.purchased.</p>
@@ -71,36 +57,34 @@ the publisher site to perform static response tests with the reserved product ID
install your application on a device, log into the device, and make billing requests using the
reserved product IDs.</p>
<p>There are four reserved product IDs for testing static in-app billing responses:</p>
<p>There are four reserved product IDs for testing static In-app Billing responses:</p>
<ul>
<li><strong>android.test.purchased</strong>
<p>When you make an in-app billing request with this product ID, Google Play responds as
<p>When you make an In-app Billing request with this product ID, Google Play responds as
though you successfully purchased an item. The response includes a JSON string, which contains
fake purchase information (for example, a fake order ID). In some cases, the JSON string is
signed and the response includes the signature so you can test your signature verification
implementation using these responses.</p>
</li>
<li><strong>android.test.canceled</strong>
<p>When you make an in-app billing request with this product ID Google Play responds as
<p>When you make an In-app Billing request with this product ID Google Play responds as
though the purchase was canceled. This can occur when an error is encountered in the order
process, such as an invalid credit card, or when you cancel a user's order before it is
charged.</p>
</li>
<li><strong>android.test.refunded</strong>
<p>When you make an in-app billing request with this product ID, Google Play responds as
<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 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
href="http://www.google.com/support/androidmarket/bin/answer.py?answer=1153485">In-app Billing
Pricing</a>.</p>
a refund has been made. For more information about refunds, see <a href="{@docRoot}google/play/billing/v2/api.html#billing-action-notify">Handling
IN_APP_NOTIFY messages</a> and <a href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1153485">In-app Billing
Pricing</a>.</p>
</li>
<li><strong>android.test.item_unavailable</strong>
<p>When you make an in-app billing request with this product ID, Google Play responds as
<p>When you make an In-app Billing request with this product ID, Google Play responds as
though the item being purchased was not listed in your application's product list.</p>
</li>
</ul>
@@ -167,7 +151,7 @@ Conditions under which static responses are signed.</p>
</table>
<p>To make an in-app billing request with a reserved product ID, you simply construct a normal
<p>To make an In-app Billing request with a reserved product ID, you simply construct a normal
<code>REQUEST_PURCHASE</code> request, but instead of using a real product ID from your
application's product list you use one of the reserved product IDs.</p>
@@ -175,8 +159,8 @@ application's product list you use one of the reserved product IDs.</p>
<ol>
<li><strong>Install your application on an Android-powered device.</strong>
<p>You cannot use the emulator to test in-app billing; you must install your application on a
device to test in-app billing.</p>
<p>You cannot use the emulator to test In-app Billing; you must install your application on a
device to test In-app Billing.</p>
<p>To learn how to install an application on a device, see <a
href="{@docRoot}tools/building/building-cmdline.html#RunningOnDevice">Running on a
device</a>.</p>
@@ -187,8 +171,8 @@ application's product list you use one of the reserved product IDs.</p>
</li>
<li><strong>Verify that your device is running a supported version of the Google Play
application or the MyApps application.</strong>
<p>If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of
the MyApps application. If your device is running any other version of Android, in-app billing
<p>If your device is running Android 3.0, In-app Billing requires version 5.0.12 (or higher) of
the MyApps application. If your device is running any other version of Android, In-app Billing
requires version 2.3.4 (or higher) of the Google Play application. To learn how to check the
version of the Google Play application, see <a
href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Google
@@ -197,16 +181,16 @@ application's product list you use one of the reserved product IDs.</p>
<li><strong>Run your application and purchase the reserved product IDs.</strong></li>
</ol>
<p class="note"><strong>Note</strong>: Making in-app billing requests with the reserved product IDs
overrides the usual Google Play production system. When you send an in-app billing request for a
<p class="note"><strong>Note</strong>: Making In-app Billing requests with the reserved product IDs
overrides the usual Google Play production system. When you send an In-app Billing request for a
reserved product ID, the quality of service will not be comparable to the production
environment.</p>
<h2 id="billing-testing-real">Testing In-app Purchases Using Your Own Product IDs</h2>
<p>After you finish your static response testing, and you verify that signature verification is
working in your application, you can test your in-app billing implementation by making actual in-app
purchases. Testing real in-app purchases enables you to test the end-to-end in-app billing
working in your application, you can test your In-app Billing implementation by making actual in-app
purchases. Testing real in-app purchases enables you to test the end-to-end In-app Billing
experience, including the actual responses from Google Play and the actual checkout flow that
users will experience in your application.</p>
@@ -214,7 +198,7 @@ users will experience in your application.</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
<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 Checkout does not let
you buy items from yourself. If you have not set up test accounts before, see <a
@@ -229,7 +213,7 @@ and your Google Checkout Merchant account receives a payout for the purchase. Th
want to refund purchases that are made with test accounts, otherwise the purchases will show up as
actual payouts to your merchant account.</p>
<p>To test your in-app billing implementation with actual purchases, follow these steps:</p>
<p>To test your In-app Billing implementation with actual purchases, follow these steps:</p>
<ol>
<li><strong>Upload your application as a draft application to the publisher site.</strong>
@@ -238,7 +222,7 @@ actual payouts to your merchant account.</p>
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 Google Play, see
<a href="http://market.android.com/support/bin/answer.py?answer=113469">Uploading
<a href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=113469">Uploading
applications</a>.</p>
</li>
<li><strong>Add items to the application's product list.</strong>
@@ -247,14 +231,14 @@ actual payouts to your merchant account.</p>
list</a> to learn how to do this.</p>
</li>
<li><strong>Install your application on an Android-powered device.</strong>
<p>You cannot use the emulator to test in-app billing; you must install your application on a
device to test in-app billing.</p>
<p>You cannot use the emulator to test In-app Billing; you must install your application on a
device to test In-app Billing.</p>
<p>To learn how to install an application on a device, see <a
href="{@docRoot}tools/building/building-cmdline.html#RunningOnDevice">Running on a
device</a>.</p>
</li>
<li><strong>Make one of your test accounts the primary account on your device.</strong>
<p>To perform end-to-end testing of in-app billing, the primary account on your device must be
<p>To perform end-to-end testing of In-app Billing, the primary account on your device must be
one of the <a
href="{@docRoot}google/play/billing/billing_admin.html#billing-testing-setup">test accounts</a>
that you registered on the Google Play site. If the primary account on your device is not a
@@ -271,8 +255,8 @@ actual payouts to your merchant account.</p>
</li>
<li><strong>Verify that your device is running a supported version of the Google Play
application or the MyApps application.</strong>
<p>If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of
the MyApps application. If your device is running any other version of Android, in-app billing
<p>If your device is running Android 3.0, In-app Billing requires version 5.0.12 (or higher) of
the MyApps application. If your device is running any other version of Android, In-app Billing
requires version 2.3.4 (or higher) of the Google Play application. To learn how to check the
version of the Google Play application, see <a
href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Google
@@ -284,7 +268,7 @@ actual payouts to your merchant account.</p>
<p class="note"><strong>Note:</strong> The only way to change the primary account on a device is to
do a factory reset, making sure you log on with your primary account first.</p>
<p>When you are finished testing your in-app billing implementation, you are ready to
<p>When you are finished testing your In-app Billing implementation, you are ready to
publish your application on Google Play. You can follow the normal steps for <a
href="{@docRoot}tools/publishing/preparing.html">preparing</a>, <a
href="{@docRoot}tools/publishing/app-signing.html">signing</a>, and <a

58
docs/html/google/play/billing/index.jd
View File

@@ -10,8 +10,9 @@ 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>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>
<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 products and purchases more effectively.</li>
<li><strong>New order number format</strong>&mdash;Starting 5 December, orders are reported in Merchant Order Number format. See <a href="/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/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>
</ul>
</div>
</div>
@@ -26,62 +27,35 @@ whether it's an in-app product or a subscription, Google Play
handles all checkout details so your application never has to directly process
any financial transactions. Google Play uses the same checkout backend service as
is used for application purchases, so your users experience a consistent and
familiar purchase flow (see figure 1). Also, the transaction fee for in-app
purchases is the same as the transaction fee for application purchases
(30%).</p>
familiar purchase flow.</p>
<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
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>
Checkout merchant account.</p>
<p>To help you integrate in-app billing into your application, the Android SDK
provides a sample application that demonstrates how to sell standard in-app
products and subscriptions from inside an app. The sample contains examples of
billing-related classes you can use to implement in-app billing in your
application. It also contains examples of the database, user interface, and
business logic you might use to implement in-app billing.</p>
products and subscriptions from inside an app.</p>
<p class="caution"><strong>Important</strong>: Although the sample application is a working example
of how you can implement in-app billing, we <em>strongly recommend</em> that you modify and
obfuscate the sample code before you use it in a production application. For more information, see
<a href="{@docRoot}google/play/billing/billing_best_practices.html">Security and Design</a>.</p>
<img src="{@docRoot}images/billing_checkout_flow.png" height="382" id="figure1" />
<p class="img-caption">
<strong>Figure 1.</strong> Applications initiate in-app billing requests through their own UI
(first screen). Google Play responds to the request by providing the checkout user interface
(middle screen). When checkout is complete, the application resumes.
</p>
<p>To learn more about Google Play's in-app billing service and start integrating it into your
applications, read the following documents:</p>
<p>To get started, read the documents below or take the <a href="{@docRoot}training/in-app-billing/index.html">Selling
In-app Products</a> training class.</p>
</div>
</div>
<dl>
<dt><strong><a href="{@docRoot}google/play/billing/billing_overview.html">In-app
Billing Overview</a></strong></dt>
<dd>Learn how the service works and what a typical in-app billing implementation looks
like.</dd>
<dt><strong><a href="{@docRoot}google/play/billing/billing_integrate.html">Implementing
In-app Billing</a></strong></dt>
<dd>Use this step-by-step guide to start incorporating in-app billing into your
application. The instructions apply to both one-time and subscription purchases.</dd>
<dt><strong><a href="{@docRoot}google/play/billing/billing_subscriptions.html">Subscriptions</a></strong></dt>
<dd>Learn how subscriptions work and how to implement support for them in your app.</dd>
<dt><strong><a href="{@docRoot}google/play/billing/billing_overview.html">Overview</a></strong></dt>
<dd>Read this document for a description of the underlying concepts in In-app Billing.</dd>
<dt><strong><a href="{@docRoot}google/play/billing/api.html">Version 3 API</a></strong></dt>
<dd>Read the documents in this section for an overview of the latest version of In-app Billing, as well as implementation details and API reference.</dd>
<dt><strong><a href="{@docRoot}google/play/billing/billing_best_practices.html">Security
and Design</a></strong></dt>
<dd>Review these best practices to help ensure that your in-app billing implementation is
<dd>Review these best practices to help ensure that your In-app Billing implementation is
secure and well designed.</dd>
<dt><strong><a href="{@docRoot}google/play/billing/billing_testing.html">Testing In-app
Billing</a></strong></dt>
<dd>Understand how the in-app billing test tools work and learn how to test your in-app billing
<dd>Understand how the In-app Billing test tools work and learn how to test your In-app Billing
implementation.</dd>
<dt><strong><a href="{@docRoot}google/play/billing/billing_admin.html">Administering
In-app Billing</a></strong></dt>
<dd>Learn how to set up your product list, register test accounts, and handle refunds.</dd>
<dt><strong><a href="{@docRoot}google/play/billing/billing_reference.html">Reference</a></strong></dt>
<dd>Get detailed information about Google Play response codes and the in-app billing
interface.</dd>
</dl>

523
docs/html/google/play/billing/v2/api.jd Normal file
View File

@@ -0,0 +1,523 @@
page.title=In-app Billing Version 2
@jd:body
<div style="background-color:#fffdeb;width:100%;margin-bottom:1em;padding:.5em;">In-app Billing Version 2 is superseded. Please <a href="{@docRoot}google/play/billing/billing_overview.html#migration">migrate to Version 3</a> at your earliest convenience.</div>
<div id="qv-wrapper" style="margin-top:0;">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#billing-types">Product and Purchase Types</a></li>
<li><a href="#billing-arch">Service Architecture</a></li>
<li><a href="#billing-msgs">Service Messages</a></li>
<ol>
<li><a href="#billing-request">Request messages</a></li>
<li><a href="#billing-response">Broadcast intents</a></li>
<li><a href="#billing-message-sequence">Messaging sequence</a></li>
<li><a href="#billing-action-notify">Handling IN_APP_NOTIFY messages</a></li>
</ol>
<li><a href="#billing-security">Security Controls</a></li>
<li><a href="#billing-limitations">Requirements and Limitations</a></li>
</ol>
</div>
</div>
<p>In-app Billing version 2 is the legacy version of the Google Play In-app
Billing. Like Version 3, it lets you interact with the Google Play purchase flow
and payments system indirectly, by means of IPC communication with the Play
Store app installed on the device. </p>
<p>Unlike Version 3, the Version 2 API is
asynchronous and uses service messages sent as broadcast intents, so
it is more complicated than Version 3. </p>
<p>Version 2 supports both unmanaged and managed products, as well as supports
subscriptions, where Version 3 does not yet offer support for subscriptions. If
you want to sell subscriptions in your app, you should implement In-app Billing
Version 2, rather than Version 3. </p>
<p>If you do not need to sell subscriptions, you
should implement In-app Billing Version 3 instead.</p>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>New in In-app Billing V2</h2>
<p><strong>Free trials</strong>—You can now offer users a configurable free trial period for
your in-app subscriptions. You can set up trials with a simple change in the Developer
Console—no change to your app code is needed.</p>
</div>
</div>
<h2 id="billing-types">Product Types</h2>
<p>In-app Billing Version supports three different product types
to give you flexibility in how you monetize your app. In all cases, you define
your products using the Google Play Developer Console, including product type,
SKU, price, description, and so on. For more information, see <a
href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Billing</a>.</p>
<ul>
<li><em>Managed per user account</em> &mdash; Items that can be purchased only
once per user account on Google Play. When a user purchases an item that uses
the "managed per user account" product type, Google Play permanently stores the
transaction information for each item on a per-user basis. This enables you to
later query Google Play to restore the state of the items a specific user has
purchased. If a user attempts to purchase a managed item that has already been
purchased, Google Play prevents the user from purchasing the item again and
displays an "Item already purchased" error.
<p>The "managed" product type is useful if you are selling
items such as game levels or application features. These items are not transient
and usually need to be restored whenever a user reinstalls your application,
wipes the data on their device, or installs your application on a new
device.</p>
<li><em>Unmanaged</em> &mdash; Items that do not have their transaction
information stored on Google Play. This means that you cannot later query Google
Play to retrieve transaction information for those items. For "unmanaged"
purchases, you are responsible for managing the transaction information. Also,
Google Play does not attempt to prevent the user from purchasing an item
multiple times if it uses the "unmanaged" product type. It's up to you to
control how many times an unmanaged item can be purchased.</p>
<p>The "unmanaged" product type is useful if you are selling consumable items,
such as fuel or magic spells. These items are consumed within your application
and are usually purchased multiple times.</p></li>
<li><em>Subscriptions</em> &mdash; Items that are sold with a
developer-specified, recurring billing interval. When a user purchases a
subscription, Google Play and its payment processor automatically bill the
user's account at the specified interval and price, charging the amount to the
original payment method. Once the user purchases a subscription, Google Play
continues billing the account indefinitely, without requiring approval or action
from the user. The user can cancel the subscription at any time.
<p>Subscriptions can only be sold using the "managed per user account" purchase
type. As with in-app products, once the user has purchased an in-app product
there is no refund window. Users desiring refunds must contact the developer
directly. For more information about subscriptions and how to sell them in your
apps, see the <a href="{@docRoot}google/play/billing/v2/billing_subscriptions.html">Subscriptions</a>
document.</p></li>
</ul>
<h2 id="billing-arch">Service Architecture</h2>
<p>Your app accesses the In-app Billing service using an API that is exposed by
the Google Play app installed on the device. The Google Play app then uses an
asynchronous message loop to convey billing requests and responses between your
application and the Google Play server. In practice, your application never
directly communicates with the Google Play server (see figure 1). Instead, your
application sends billing requests to the Google Play application over
interprocess communication (IPC) and receives purchase responses from the Google
Play application in the form of asynchronous broadcast intents. Your application
does not manage any network connections between itself and the Google Play
server or use any special APIs from the Android platform.</p>
<div class="figure" style="width:440px">
<img src="/images/billing_arch.png" alt="" height="582" />
<p class="img-caption">
<strong>Figure 1.</strong> Your application sends and receives billing messages through the
Google Play application, which handles all communication with the Google Play server.</p>
</div>
<p>Some in-app billing implementations may also use a private remote server to deliver content or
validate transactions, but a remote server is not required to implement in-app billing. A remote
server can be useful if you are selling digital content that needs to be delivered to a user's
device, such as media files or photos. You might also use a remote server to store users'
transaction history or perform various in-app billing security tasks, such as signature
verification. Although you can handle all security-related tasks in your application, performing
those tasks on a remote server is recommended because it helps make your application less vulnerable
to security attacks.</p>
<p>A typical in-app billing implementation relies on three components:</p>
<ul>
<li>A {@link android.app.Service Service} (named <code>BillingService</code> in the sample application),
which processes purchase messages from the application and sends billing requests to the Google
Play in-app billing service.</li>
<li>A {@link android.content.BroadcastReceiver BroadcastReceiver} (named <code>BillingReceiver</code> in the sample
application), which receives all asynchronous billing responses from the Google Play
application.</li>
<li>A security component (named <code>Security</code> in the sample application), which performs
security-related tasks, such as signature verification and nonce generation. For more information
about in-app billing security, see <a href="#billing-security">Security controls</a> later in this
document.</li>
</ul>
<p>You may also want to incorporate two other components to support in-app billing:</p>
<ul>
<li>A response {@link android.os.Handler Handler} (named <code>ResponseHandler</code> in the sample
application), which provides application-specific processing of purchase notifications, errors,
and other status messages.</li>
<li>An observer (named <code>PurchaseObserver</code> in the sample application), which is
responsible for sending callbacks to your application so you can update your user interface with
purchase information and status.</li>
</ul>
<p>In addition to these components, your application must provide a way to store information about
users' purchases and some sort of user interface that lets users select items to purchase. You do
not need to provide a checkout user interface. When a user initiates an in-app purchase, the Google
Play application presents the checkout user interface to your user. When the user completes the
checkout process, your application resumes.</p>
<h2 id="billing-msgs">In-app Billing Messages</h2>
<p>When the user initiates a purchase, your application sends billing messages to Google Play's
in-app billing service (named <code>MarketBillingService</code>) using simple IPC method calls. The
Google Play application responds to all billing requests synchronously, providing your
application with status notifications and other information. The Google Play application also
responds to some billing requests asynchronously, providing your application with error messages and
detailed transaction information. The following section describes the basic request-response
messaging that takes place between your application and the Google Play application.</p>
<h3 id="billing-request">In-app billing requests</h3>
<p>Your application sends in-app billing requests by invoking a single IPC method
(<code>sendBillingRequest()</code>), which is exposed by the <code>MarketBillingService</code>
interface. This interface is defined in an <a
href="{@docRoot}guide/components/aidl.html">Android Interface Definition Language</a> file
(<code>IMarketBillingService.aidl</code>). You can <a
href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">download</a> this AIDL
file with the in-app billing sample application.</p>
<p>The <code>sendBillingRequest()</code> method has a single {@link android.os.Bundle Bundle} parameter.
The Bundle that you deliver must include several key-value pairs that specify various parameters for
the request, such as the type of billing request you are making, the item that is being purchased and
its type, and the application that is making the request. For more information about the Bundle keys
that are sent with a request, see <a
href="{@docRoot}google/play/billing/v2/billing_reference.html#billing-interface">In-app Billing
Service Interface</a>.
<p>One of the most important keys that every request Bundle must have is the
<code>BILLING_REQUEST</code> key. This key lets you specify the type of billing request you are
making. Google Play's in-app billing service supports the following five types of billing
requests:</p>
<ul>
<li><code>CHECK_BILLING_SUPPORTED</code>
<p>This request verifies that the Google Play application supports in-app billing. You
usually send this request when your application first starts up. This request is useful if you
want to enable or disable certain UI features that are relevant only to in-app billing.</p>
</li>
<li><code>REQUEST_PURCHASE</code>
<p>This request sends a purchase message to the Google Play application and is the foundation
of in-app billing. You send this request when a user indicates that he or she wants to purchase
an item in your application. Google Play then handles the financial transaction by displaying
the checkout user interface.</p>
</li>
<li><code>GET_PURCHASE_INFORMATION</code>
<p>This request retrieves the details of a purchase state change. A purchase changes state when
a requested purchase is billed successfully or when a user cancels a transaction during
checkout. It can also occur when a previous purchase is refunded. Google Play notifies your
application when a purchase changes state, so you only need to send this request when there is
transaction information to retrieve.</p>
</li>
<li><code>CONFIRM_NOTIFICATIONS</code>
<p>This request acknowledges that your application received the details of a purchase state
change. Google Play sends purchase state change notifications to your application until you
confirm that you received them.</p>
</li>
<li><code>RESTORE_TRANSACTIONS</code>
<p>This request retrieves a user's transaction status for <a
href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">managed
purchases</a> and <a
href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">subscriptions</a>.
You should send this request only when you need to retrieve a user's transaction
status, which is usually only when your application is reinstalled or installed for the first
time on a device.</p>
</li>
</ul>
<h3 id="billing-response">In-app Billing Responses</h3>
<p>The Google Play application responds to in-app billing requests with both synchronous and
asynchronous responses. The synchronous response is a {@link android.os.Bundle Bundle} with the following
three keys:</p>
<ul>
<li><code>RESPONSE_CODE</code>
<p>This key provides status information and error information about a request.</p>
</li>
<li><code>PURCHASE_INTENT</code>
<p>This key provides a {@link android.app.PendingIntent PendingIntent}, which you use to launch the checkout
activity.</p>
</li>
<li><code>REQUEST_ID</code>
<p>This key provides you with a request identifier, which you can use to match asynchronous
responses with requests.</p>
</li>
</ul>
<p>Some of these keys are not relevant to every request. For more information, see <a
href="#billing-message-sequence">Messaging sequence</a> later in this document.</p>
<p>The asynchronous response messages are sent in the form of individual broadcast intents and
include the following:</p>
<ul>
<li><code>com.android.vending.billing.RESPONSE_CODE</code>
<p>This response contains a Google Play server response code, and is sent after you make an
in-app billing request. A server response code can indicate that a billing request was
successfully sent to Google Play or it can indicate that some error occurred during a billing
request. This response is <em>not</em> used to report any purchase state changes (such as refund
or purchase information). For more information about the response codes that are sent with this
response, see <a
href="{@docRoot}google/play/billing/v2/billing_reference.html#billing-codes">Server Response Codes
for In-app Billing</a>.</p>
</li>
<li><code>com.android.vending.billing.IN_APP_NOTIFY</code>
<p>This response indicates that a purchase has changed state, which means a purchase succeeded,
was canceled, or was refunded. This response contains one or more notification IDs. Each
notification ID corresponds to a specific server-side message, and each messages contains
information about one or more transactions. After your application receives an
<code>IN_APP_NOTIFY</code> broadcast intent, you send a <code>GET_PURCHASE_INFORMATION</code>
request with the notification IDs to retrieve message details.</p>
</li>
<li><code>com.android.vending.billing.PURCHASE_STATE_CHANGED</code>
<p>This response contains detailed information about one or more transactions. The transaction
information is contained in a JSON string. The JSON string is signed and the signature is sent
to your application along with the JSON string (unencrypted). To help ensure the security of
your in-app billing messages, your application can verify the signature of this JSON string.</p>
</li>
</ul>
<p>The JSON string that is returned with the <code>PURCHASE_STATE_CHANGED</code> intent provides
your application with the details of one or more billing transactions. An example of this JSON
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",
"packageName" : "com.example.dungeons",
"productId" : "android.test.purchased",
"developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ",
"purchaseTime" : 1290114783411,
"purchaseState" : 0,
"purchaseToken" : "rojeslcdyyiapnqcynkjyyjh" }]
}
</pre>
<p>For more information about the fields in this JSON string, see <a
href="{@docRoot}google/play/billing/v2/billing_reference.html#billing-intents">In-app Billing
Broadcast Intents</a>.</p>
<h3 id="billing-message-sequence">Messaging sequence</h3>
<p>The messaging sequence for a typical purchase request is shown in figure 2. 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 2 does not show the <code>RESPONSE_CODE</code>
broadcast intents that are sent for every request.</p>
<p>The basic message sequence for an in-app purchase request is as follows:</p>
<ol>
<li>Your application sends a purchase request (<code>REQUEST_PURCHASE</code> type), specifying a
product ID and other parameters.</li>
<li>The Google Play application sends your application a Bundle with the following keys:
<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 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.
<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), Google Play sends your application a notification message (an
<code>IN_APP_NOTIFY</code> broadcast intent). The notification message includes a notification ID,
which references the transaction.</li>
<li>Your application requests the transaction information by sending a
<code>GET_PURCHASE_STATE_CHANGED</code> request, specifying the notification ID for the
transaction.</li>
<li>The Google Play application sends a Bundle with a <code>RESPONSE_CODE</code> key and a
<code>REQUEST_ID</code> key.
<li>Google Play sends the transaction information to your application in a
<code>PURCHASE_STATE_CHANGED</code> broadcast intent.</li>
<li>Your application confirms that you received the transaction information for the given
notification ID by sending a confirmation message (<code>CONFIRM_NOTIFICATIONS</code> type),
specifying the notification ID for which you received transaction information.</li>
<li>The Google Play application sends your application a Bundle with a
<code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key.</li>
</ol>
<img src="/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 Google
Play (step 8 in figure 2). If you don't send a confirmation message, Google Play 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 Google Play 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>
broadcast intents that are sent for every request.</p>
<div class="figure" style="width:490px">
<img src="/images/billing_restore_transactions.png" alt="" height="168" />
<p class="img-caption">
<strong>Figure 3.</strong> Message sequence for a restore transactions request.
</p>
</div>
<p>The request triggers three responses. The first is a {@link android.os.Bundle Bundle} with a
<code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key. Next, the Google Play
application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides status information
or error information about the request. As always, the <code>RESPONSE_CODE</code> message references
a specific request ID, so you can determine which request a <code>RESPONSE_CODE</code> message
pertains to.</p>
<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. 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
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>
<div class="figure" style="width:454px">
<img src="/images/billing_check_supported.png" alt="" height="168" />
<p class="img-caption">
<strong>Figure 4.</strong> Message sequence for checking whether in-app billing is supported.
</p>
</div>
<p>The synchronous response for a <code>CHECK_BILLING_SUPPORTED</code> request provides a Bundle
with a server response code. A <code>RESULT_OK</code> response code indicates that in-app billing
is supported; a <code>RESULT_BILLING_UNAVAILABLE</code> response code indicates that in-app billing
is unavailable because the API version you specified is unrecognized or the user is not eligible to
make in-app purchases (for example, the user resides in a country that does not allow in-app
billing). A <code>SERVER_ERROR</code> can also be returned, indicating that there was a problem with
the Google Play server.</p>
<h3 id="billing-action-notify">Handling IN_APP_NOTIFY messages</h3>
<p>Usually, your application receives an <code>IN_APP_NOTIFY</code> broadcast intent from Google
Play in response to a <code>REQUEST_PURCHASE</code> message (see figure 2). The
<code>IN_APP_NOTIFY</code> broadcast intent informs your application that the state of a requested
purchase has changed. To retrieve the details of that purchase, your application sends a
<code>GET_PURCHASE_INFORMATION</code> request. Google Play 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
Google Play that you have received the purchase state change information.</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>
<h4>Handling multiple IN_APP_NOTIFY messages</h4>
<p>When Google Play 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, Google
Play 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, Google Play
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
shown in <em>italic</em>. For clarity, figure 5 does not show the <code>RESPONSE_CODE</code>
broadcast intents that are sent for every request.</p>
<div class="figure" style="width:481px">
<img src="/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>
</div>
<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, Google Play sends an <code>IN_APP_NOTIFY</code>
message to the second device, informing the application that there is a purchase state change. Your
application can handle this message the same way it handles the response from an
application-initiated <code>REQUEST_PURCHASE</code> message, so that ultimately your application
receives a <code>PURCHASE_STATE_CHANGED</code> broadcast intent message that includes information
about the item that has been purchased. This applies only to items that have their product type
set 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
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
<code>PURCHASE_STATE_CHANGED</code> message that includes information about the item that has been
refunded. The refund information is included in the JSON string that accompanies the
<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
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
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,
Google Play signs the JSON string that is contained in the <code>PURCHASE_STATE_CHANGED</code>
broadcast intent. Google Play uses the private key that is associated with the app to create
this signature. The Developer Console generates an RSA key pair for each app.
You can find the public key portion of this key pair in the app's publishing details
in the Developer Console, under <strong>Settings</strong>, in the License Key field.</p>
<p>When Google Play signs a billing response, it includes the signed JSON string (unencrypted)
and the signature. When your application receives this signed response you can use the public key
portion of your RSA key pair to verify the signature. By performing signature verification you can
help detect responses that have been tampered with or that have been spoofed. You can perform this
signature verification step in your application; however, if your application connects to a secure
remote server then we recommend that you perform the signature verification on that server.</p>
<p>In-app billing also uses nonces (a random number used once) to help verify the integrity of the
purchase information that's returned from Google Play. Your application must generate a nonce and
send it with a <code>GET_PURCHASE_INFORMATION</code> request and a <code>RESTORE_TRANSACTIONS</code>
request. When Google Play receives the request, it adds the nonce to the JSON string that
contains the transaction information. The JSON string is then signed and returned to your
application. When your application receives the JSON string, you need to verify the nonce as well as
the signature of the JSON string.</p>
<p>For more information about best practices for security and design, see <a
href="{@docRoot}google/play/billing/billing_best_practices.html">Security and Design</a>.</p>
<h2 id="billing-limitations">In-app Billing Requirements and Limitations</h2>
<p>Before you get started with in-app billing, be sure to review the following requirements and
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>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>
<li>An application can use in-app billing only if the device is running Android 1.6 (API level 4)
or higher.</li>
<li>You can use in-app billing to sell only digital content. You cannot use in-app billing to sell
physical goods, personal services, or anything that requires physical delivery.</li>
<li>Google Play does not provide any form of content delivery. You are responsible for
delivering the digital content that you sell in your applications.</li>
<li>You cannot implement in-app billing on a device that never connects to the network. To
complete in-app purchase requests, a device must be able to access the Google Play server over
the network. </li>
</ul>

1111
docs/html/google/play/billing/v2/billing_integrate.jd Executable file
View File

File diff suppressed because it is too large Load Diff

415
docs/html/google/play/billing/v2/billing_reference.jd Normal file
View File

@@ -0,0 +1,415 @@
page.title=In-app Billing Reference <span style="font-size:16px;">(IAB Version 2)</span>
@jd:body
<div style="background-color:#fffdeb;width:100%;margin-bottom:1em;padding:.5em;">In-app Billing Version 2 is superseded. Please <a href="{@docRoot}google/play/billing/billing_overview.html#migration">migrate to Version 3</a> at your earliest convenience.</div>
<div id="qv-wrapper" style="margin-top:0;">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#billing-codes">Server Response Codes</a></li>
<li><a href="#billing-interface">API Reference</a></li>
<li><a href="#billing-intents">Broadcast Intents</a></li>
<li><a href="#http-api">REST API for Subscriptions</a></li>
</ol>
<h2>Related Samples</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">Sample
Application (V2)</a></li>
</ol>
</div>
</div>
<p>This documentation provides technical reference information for using the In-app Billing Version 2 API. </p>
<h2 id="billing-codes">Server Response Codes</h2>
<p>The following table lists all of the server response codes that are sent from Google Play to
your application. Google Play sends these response codes asynchronously as
<code>response_code</code> extras in the <code>com.android.vending.billing.RESPONSE_CODE</code>
broadcast intent. Your application must handle all of these response codes.</p>
<p class="table-caption" id="response-codes-table"><strong>Table 6.</strong> Summary of response
codes returned by Google Play.</p>
<table>
<tr>
<th>Response Code</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td><code>RESULT_OK</code></td>
<td>0</td>
<td>Indicates that the request was sent to the server successfully. When this code is returned in
response to a <code>CHECK_BILLING_SUPPORTED</code> request, indicates that billing is
supported.</td>
</tr>
<tr>
<td><code>RESULT_USER_CANCELED</code></td>
<td>1</td>
<td>Indicates that the user pressed the back button on the checkout page instead of buying the
item.</td>
</tr>
<tr>
<td><code>RESULT_SERVICE_UNAVAILABLE</code></td>
<td>2</td>
<td>Indicates that the network connection is down.</td>
</tr>
<tr>
<td><code>RESULT_BILLING_UNAVAILABLE</code></td>
<td>3</td>
<td>Indicates that In-app Billing is not available because the <code>API_VERSION</code> that you
specified is not recognized by the Google Play application or the user is ineligible for in-app
billing (for example, the user resides in a country that prohibits in-app purchases).</td>
</tr>
<tr>
<td><code>RESULT_ITEM_UNAVAILABLE</code></td>
<td>4</td>
<td>Indicates that Google Play cannot find the requested item in the application's product
list. This can happen if the product ID is misspelled in your <code>REQUEST_PURCHASE</code>
request or if an item is unpublished in the application's product list.</td>
</tr>
<tr>
<td><code>RESULT_DEVELOPER_ERROR</code></td>
<td>5</td>
<td>Indicates that an application is trying to make an In-app Billing request but the application
has not declared the com.android.vending.BILLING permission in its manifest. Can also indicate
that an application is not properly signed, or that you sent a malformed request, such as a
request with missing Bundle keys or a request that uses an unrecognized request type.</td>
</tr>
<tr>
<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>
</tr>
</table>
</p>
<h3 id="billing-interface">In-app billing Version 2 API reference</h3>
<p>The following section describes the interface for Google Play's In-app Billing service. The
interface is defined in the <code>IMarketBillingService.aidl</code> file, which is included with the
In-app Billing <a
href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">sample
application</a>.</p>
<p>The interface consists of a single request method <code>sendBillingRequest()</code>. This method
takes a single {@link android.os.Bundle} parameter. The Bundle parameter includes several key-value
pairs, which are summarized in table 7.</p>
<p class="table-caption"><strong>Table 7.</strong> Description of Bundle keys passed in a
<code>sendBillingRequest()</code> request.</p>
<table>
<tr>
<th>Key</th>
<th>Type</th>
<th>Possible Values</th>
<th>Required?</th>
<th>Description</th>
</tr>
<tr>
<td><code>BILLING_REQUEST</code></td>
<td><code>String</code></td>
<td><code>CHECK_BILLING_SUPPORTED</code>, <code>REQUEST_PURCHASE</code>,
<code>GET_PURCHASE_INFORMATION</code>, <code>CONFIRM_NOTIFICATIONS</code>, or
<code>RESTORE_TRANSACTIONS</code></td>
<td>Yes</td>
<td>The type of billing request you are making with the <code>sendBillingRequest()</code> request.
The possible values are discussed more below this table.</td>
</tr>
<tr>
<td><code>API_VERSION</code></td>
<td><code>int</code></td>
<td> <ul>
<li><code>"2"</code> [<a href="#version_2">details</a>]</li>
<li><code>"1"</code> [<a href="#version_1">details</a>]</li>
</ul></td>
<td>Yes</td>
<td>The version of Google Play's In-app Billing service you want to use.</td>
</tr>
<tr>
<td><code>PACKAGE_NAME</code></td>
<td><code>String</code></td>
<td>A valid package name.</td>
<td>Yes</td>
<td>The name of the application that is making the request.</td>
</tr>
<tr>
<td><code>ITEM_ID</code></td>
<td><code>String</code></td>
<td>Any valid product identifier.</td>
<td>Required for <code>REQUEST_PURCHASE</code> requests.</td>
<td>The product ID of the item you are making a billing request for. Every in-app item that you
sell using Google Play's In-app Billing service must have a unique product ID, which you
specify on the Google Play publisher site.</td>
</tr>
<tr>
<td><code>NONCE</code></td>
<td><code>long</code></td>
<td>Any valid <code>long</code> value.</td>
<td>Required for <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code>
requests.</td>
<td>A number used once. Your application must generate and send a nonce with each
<code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> request. The nonce is
returned with the <code>PURCHASE_STATE_CHANGED</code> broadcast intent, so you can use this value
to verify the integrity of transaction responses form Google Play.</td>
</tr>
<tr>
<td><code>NOTIFY_IDS</code></td>
<td>Array of <code>long</code> values</td>
<td>Any valid array of <code>long</code> values</td>
<td>Required for <code>GET_PURCHASE_INFORMATION</code> and <code>CONFIRM_NOTIFICATIONS</code>
requests.</td>
<td>An array of notification identifiers. A notification ID is sent to your application in an
<code>IN_APP_NOTIFY</code> broadcast intent every time a purchase changes state. You use the
notification to retrieve the details of the purchase state change.</td>
</tr>
<tr>
<td><code>DEVELOPER_PAYLOAD</code></td>
<td><code>String</code></td>
<td>Any valid <code>String</code> less than 256 characters long.</td>
<td>No</td>
<td>A developer-specified string that can be specified when you make a
<code>REQUEST_PURCHASE</code> request. This field is returned in the JSON string that contains
transaction information for an order. You can use this key to send supplemental information with
an order. For example, you can use this key to send index keys with an order, which is useful if
you are using a database to store purchase information. We recommend that you do not use this key
to send data or content.</td>
</tr>
</table>
<p>The <code>BILLING_REQUEST</code> key can have the following values:</p>
<ul>
<li><code>CHECK_BILLING_SUPPORTED</code>
<p>This request verifies that the Google Play application supports In-app Billing. You
usually send this request when your application first starts up. This request is useful if you
want to enable or disable certain UI features that are relevant only to In-app Billing.</p>
</li>
<li><code>REQUEST_PURCHASE</code>
<p>This request sends a purchase message to the Google Play application and is the foundation
of In-app Billing. You send this request when a user indicates that he or she wants to purchase
an item in your application. Google Play then handles the financial transaction by displaying
the checkout user interface.</p>
</li>
<li><code>GET_PURCHASE_INFORMATION</code>
<p>This request retrieves the details of a purchase state change. A purchase state change can
occur when a purchase request is billed successfully or when a user cancels a transaction during
checkout. It can also occur when a previous purchase is refunded. Google Play notifies your
application when a purchase changes state, so you only need to send this request when there is
transaction information to retrieve.</p>
</li>
<li><code>CONFIRM_NOTIFICATIONS</code>
<p>This request acknowledges that your application received the details of a purchase state
change. That is, this message confirms that you sent a <code>GET_PURCHASE_INFORMATION</code>
request for a given notification and that you received the purchase information for the
notification.</p>
</li>
<li><code>RESTORE_TRANSACTIONS</code>
<p>This request retrieves a user's transaction status for managed purchases (see <a
href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">Choosing a
Purchase Type</a> for more information). You should send this message only when you need to
retrieve a user's transaction status, which is usually only when your application is reinstalled
or installed for the first time on a device.</p>
</li>
</ul>
<p>Every In-app Billing request generates a synchronous response. The response is a {@link
android.os.Bundle} and can include one or more of the following keys:</p>
<ul>
<li><code>RESPONSE_CODE</code>
<p>This key provides status information and error information about a request.</p>
</li>
<li><code>PURCHASE_INTENT</code>
<p>This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout
activity.</p>
</li>
<li><code>REQUEST_ID</code>
<p>This key provides you with a request identifier, which you can use to match asynchronous
responses with requests.</p>
</li>
</ul>
<p>Some of these keys are not relevant to certain types of requests. Table 8 shows which keys are
returned for each request type.</p>
<p class="table-caption"><strong>Table 8.</strong> Description of Bundle keys that are returned with
each In-app Billing request type.</p>
<table>
<tr>
<th>Request Type</th>
<th>Keys Returned</th>
<th>Possible Response Codes</th>
</tr>
<tr>
<td><code>CHECK_BILLING_SUPPORTED</code></td>
<td><code>RESPONSE_CODE</code></td>
<td><code>RESULT_OK</code>, <code>RESULT_BILLING_UNAVAILABLE</code>, <code>RESULT_ERROR</code>,
<code>RESULT_DEVELOPER_ERROR</code></td>
</tr>
<tr>
<td><code>REQUEST_PURCHASE</code></td>
<td><code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, <code>REQUEST_ID</code></td>
<td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
</tr>
<tr>
<td><code>GET_PURCHASE_INFORMATION</code></td>
<td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td>
<td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
</tr>
<tr>
<td><code>CONFIRM_NOTIFICATIONS</code></td>
<td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td>
<td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
</tr>
<tr>
<td><code>RESTORE_TRANSACTIONS</code></td>
<td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td>
<td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
</tr>
</table>
<h3 id="billing-intents">In-app billing broadcast intents</h3>
<p>The following section describes the In-app Billing broadcast intents that are sent by the Google
Play application. These broadcast intents inform your application about In-app Billing actions
that have occurred. Your application must implement a {@link android.content.BroadcastReceiver} to
receive these broadcast intents, such as the <code>BillingReceiver</code> that's shown in the in-app
billing <a href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">sample
application</a>.</p>
<h4>com.android.vending.billing.RESPONSE_CODE</h4>
<p>This broadcast intent contains a Google Play response code, and is sent after you make an
In-app Billing request. A server response code can indicate that a billing request was successfully
sent to Google Play or it can indicate that some error occurred during a billing request. This
intent is not used to report any purchase state changes (such as refund or purchase information).
For more information about the response codes that are sent with this response, see <a
href="#billing-codes">Google Play Response Codes for In-app Billing</a>. The sample application
assigns this broadcast intent to a constant named <code>ACTION_RESPONSE_CODE</code>.</p>
<h5>Extras</h5>
<ul type="none">
<li><code>request_id</code>&mdash;a <code>long</code> representing a request ID. A request ID
identifies a specific billing request and is returned by Google Play at the time a request is
made.</li>
<li><code>response_code</code>&mdash;an <code>int</code> representing the Google Play server
response code.</li>
</ul>
<h4>com.android.vending.billing.IN_APP_NOTIFY</h4>
<p>This response indicates that a purchase has changed state, which means a purchase succeeded, was
canceled, or was refunded. This response contains one or more notification IDs. Each notification ID
corresponds to a specific server-side message, and each messages contains information about one or
more transactions. After your application receives an <code>IN_APP_NOTIFY</code> broadcast intent,
you send a <code>GET_PURCHASE_INFORMATION</code> request with the notification IDs to retrieve the
message details. The sample application assigns this broadcast intent to a constant named
<code>ACTION_NOTIFY</code>.</p>
<h5>Extras</h5>
<ul type="none">
<li><code>notification_id</code>&mdash;a <code>String</code> representing the notification ID for
a given purchase state change. Google Play notifies you when there is a purchase state change
and the notification includes a unique notification ID. To get the details of the purchase state
change, you send the notification ID with the <code>GET_PURCHASE_INFORMATION</code> request.</li>
</ul>
<h4>com.android.vending.billing.PURCHASE_STATE_CHANGED</h4>
<p>This broadcast intent contains detailed information about one or more transactions. The
transaction information is contained in a JSON string. The JSON string is signed and the signature
is sent to your application along with the JSON string (unencrypted). To help ensure the security of
your In-app Billing messages, your application can verify the signature of this JSON string. The
sample application assigns this broadcast intent to a constant named
<code>ACTION_PURCHASE_STATE_CHANGED</code>.</p>
<h5>Extras</h5>
<ul type="none">
<li><code>inapp_signed_data</code>&mdash;a <code>String</code> representing the signed JSON
string.</li>
<li><code>inapp_signature</code>&mdash;a <code>String</code> representing the signature.</li>
</ul>
<p class="note"><strong>Note:</strong> Your application should map the broadcast intents and extras
to constants that are unique to your application. See the <code>Consts.java</code> file in the
sample application to see how this is done.</p>
<p>The fields in the JSON string are described in the following table (see table 9):</p>
<p class="table-caption"><strong>Table 9.</strong> Description of JSON fields that are returned with
a <code>PURCHASE_STATE_CHANGED</code> intent.</p>
<table>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
<tr>
<td>nonce</td>
<td>A number used once. Your application generates the nonce and sends it with the
<code>GET_PURCHASE_INFORMATION</code> request. Google Play sends the nonce back as part of the
JSON string so you can verify the integrity of the message.</td>
</tr>
<tr>
<td>notificationId</td>
<td>A unique identifier that is sent with an <code>IN_APP_NOTIFY</code> broadcast intent. Each
<code>notificationId</code> corresponds to a specify message that is waiting to be retrieved on
the Google Play server. Your application sends back the <code>notificationId</code> with the
<code>GET_PURCHASE_INFORMATION</code> message so Google Play can determine which messages you
are retrieving.</td>
</tr>
<tr>
<td>orderId</td>
<td>A unique order identifier for the transaction. This corresponds to the Google Wallet Order
ID.</td>
</tr>
<tr>
<td>packageName</td>
<td>The application package from which the purchase originated.</td>
</tr>
<tr>
<td>productId</td>
<td>The item's product identifier. Every item has a product ID, which you must specify in the
application's product list on the Google Play publisher site.</td>
</tr>
<tr>
<td>purchaseTime</td>
<td>The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).</td>
</tr>
<tr>
<td>purchaseState</td>
<td>The purchase state of the order. Possible values are 0 (purchased), 1 (canceled), 2
(refunded), or 3 (expired, for subscription purchases only).</td>
</tr>
<tr>
<td>purchaseToken</td>
<td>A token that uniquely identifies a subscription purchase for a given item and user pair.
You can use the token to specify the subscription when querying for subscription validity.
<p><br><em>Supported only in In-app Billing API Version 2 and higher.</em></p></td>
</tr>
<tr>
<td>developerPayload</td>
<td>A developer-specified string that contains supplemental information about an order. You can
specify a value for this field when you make a <code>REQUEST_PURCHASE</code> request.</td>
</tr>
</table>
<!--<h2 id="other-intents">Other Intents</h2>
<p>The following Intents related to In-app Billing may be useful in your
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>

52
docs/html/google/play/billing/billing_subscriptions.jd → docs/html/google/play/billing/v2/billing_subscriptions.jd
View File

@@ -1,9 +1,8 @@
page.title=Subscriptions
parent.title=In-app Billing
parent.link=index.html
page.title=Subscriptions <span style="font-size:16px;">(IAB Version 2)</span>
@jd:body
<div id="qv-wrapper">
<div style="background-color:#fffdeb;width:100%;margin-bottom:1em;padding:.5em;">In-app Billing Version 2 is superseded. Please <a href="{@docRoot}google/play/billing/billing_overview.html#migration">migrate to Version 3</a> at your earliest convenience.</div>
<div id="qv-wrapper" style="margin-top:0;">
<div id="qv">
<h2>In this document</h2>
<ol>
@@ -46,26 +45,11 @@ parent.link=index.html
</ol> -->
</li>
</ol>
<h2>Downloads</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">Sample Application</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">Overview of In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_best_practices.html">Security and
Design</a></li>
<li><a href="{@docRoot}google/play/billing/billing_testing.html">Testing In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app
Billing</a></li>
<li><a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing
Reference</a></li>
</ol>
</div>
</div>
<p class="note"><strong>Important:</strong> This documentation describes how to implement subscriptions with the Version 2 API. Subscription support for the in-app billing <a href="{@docRoot}google/play/billing/api.html">Version 3 API</a> is coming soon.</p></li>
<p>Subscriptions let you sell content, services, or features in your app with
automated, recurring billing. Adding support for subscriptions is
straightforward and you can easily adapt an existing In-app Billing
@@ -78,13 +62,15 @@ subscriptions using the standard communication model, data structures, and user
interactions as for other in-app products.subscriptions. Because the
implementation of subscriptions follows the same path as for other in-app
products, details are provided outside of this document, starting with the <a
href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing
href="{@docRoot}google/play/billing/v2/api.html">In-app Billing
Overview</a>. </p>
<p>This document is focused on highlighting implementation details that are
specific to subscriptions, along with some strategies for the associated billing
and business models.</p>
<p class="note"><strong>Note:</strong> Subscriptions are supported in In-app Billing Version 2 only. Support for subscriptions will be added to Version 3 in the weeks ahead.</p>
<h2 id="overview">Overview of Subscriptions</h2>
<p>A <em>subscription</em> is a new product type offered in In-app Billing that lets you
@@ -379,7 +365,7 @@ these minimum requirements:</p>
<ul>
<li>Must run Android 2.2 or higher</li>
<li>Google Play Store app, version 3.5 or higher, must be installed</li>
<li>Google Play Store app, Version 3.5 or higher, must be installed</li>
</ul>
<p>Google Play 3.5 and later versions include support for the In-app Billing
@@ -411,7 +397,7 @@ other in-app products.subscriptions. </p>
<p>The full implementation details for In-app Billing are provided outside of
this document, starting with the <a
href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing
href="{@docRoot}google/play/billing/v2/api.html">In-app Billing
Overview</a>. This document is focused on highlighting implementation details
that are specific to subscriptions, along with some strategies for the
associated billing and business models.</p>
@@ -420,10 +406,10 @@ associated billing and business models.</p>
<h3 id="sample">Sample application</h3>
<p>To help you get started with your In-app Billing implementation and
subscriptions, an updated version of the In-app Billing sample app is available.
subscriptions, an updated Version of the In-app Billing sample app is available.
You can download the sample app from the Android SDK repository using the
Android SDK Manager. For details, see <a
href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">
href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">
Downloading the Sample Application</a>.</p>
<h3 id="model">Application model</h3>
@@ -442,7 +428,7 @@ Play. Also recommended are a response Handler for processing notifications,
errors, and status messages, and an observer for sending callbacks to your
application as needed. All of these components and their interactions are
described in full in the <a
href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing
href="{@docRoot}google/play/billing/v2/api.html">In-app Billing
Overview</a> and related documents.</p>
<p>To initiate different types of billing communication with Google Play, your
@@ -494,7 +480,7 @@ data.</p>
<p>Subscriptions support is available only in versions of Google Play that
support the In-app Billing v2 API (Google Play 3.5 and higher). For your app,
an essential first step at launch is to check whether the version of Google Play
an essential first step at launch is to check whether the Version of Google Play
installed on the device supports the In-app Billing v2 API and
subscriptions.</p>
@@ -571,7 +557,7 @@ indicates that subscriptions are supported.</p>
<h3 id="purchase">Requesting a subscription purchase</h3>
<p>Once you’ve checked the API version as described above and determined that
<p>Once you’ve checked the API Version as described above and determined that
subscriptions are supported, you can present subscription products to the user
for purchase. When the user has selected a subscription product and initiated a
purchase, your app handles the purchase just as it would for other in-app
@@ -581,7 +567,7 @@ transaction..
<p>The REQUEST_PURCHASE includes a Bundle containing the item details, as
described in the <a
href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing
href="{@docRoot}google/play/billing/v2/api.html">In-app Billing
Overview</a>. For a subscription, the Bundle must also specify:</p>
<ul>
@@ -597,7 +583,7 @@ Overview</a>. For a subscription, the Bundle must also specify:</p>
<code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, and
<code>REQUEST_ID</code>. Your app uses the <code>PURCHASE_INTENT</code> to
launch the checkout UI and the message flow proceeds exactly as described in <a
href="{@docRoot}google/play/billing/billing_overview.html#billing-message-
href="{@docRoot}google/play/billing/v2/api.html#billing-message-
sequence">Messaging sequence</a>.</p>
<p>Here’s how the sample app initiates a purchase for a subscription, where
@@ -654,7 +640,7 @@ the subscriptions that the user has purchased.</p>
<p>The process for restoring subscriptions transactions is the same as described
in <a
href="{@docRoot}google/play/billing/billing_overview.html#billing-message-
href="{@docRoot}google/play/billing/v2/api.html#billing-message-
sequence">Messaging sequence</a>. Your app sends a
<code>RESTORE_TRANSACTIONS</code> request to Google Play. Google Play sends two
broadcast intents as asynchronous responses &mdash; a <code>RESPONSE_CODE</code>
@@ -804,7 +790,7 @@ your app does not need to grant further access to the subscription content.</p>
<p>For subscriptions, you make the same types of modifications to your app as
are described in <a
href="{@docRoot}google/play/billing/billing_integrate.html#billing-implement">
href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-implement">
Modifying your Application Code</a>.</p>
<p>Note that, in your UI that lets users view and select subscriptions for

50
docs/html/google/play/billing/versions.jd Normal file
View File

@@ -0,0 +1,50 @@
page.title=In-app Billing Version Notes
@jd:body
<p>The In-app Billing API is versioned, with each version offering additional features to your app. API support is provided by the Google Play Store app. On most devices, the Google Play Store app is updated automatically to support newer versions of the API.
<p>The sections below list the supported versions of the In-app Billing API.</p>
<p id="api_check"><strong><em>How to check for In-app Billing version</em></strong></p>
<p>At run time, your app can query the Google Play Store app to determine what version of the API it supports and what features are available. </p>
<ul>
<li>If you are using in-app billing version 3, the version information is not directly returned the Google Play. Instead, you can check if Google Play supports the version of the In-app Billing API that you are using by sending a {@code isBillingSupported} request.</li>
<li>If the In-app Billing API version that you are using is earlier than version 3, the version information is returned in the <code>API_VERSION</code> key of the Bundle object passed in the {@code sendBillingRequest} method. For more information, see <a href="{@docRoot}google/play/billing/v2/billing_reference.html#billing-interface-v2">In-app Billing Service Interface</a>.</li>
</ul>
<h3 id="version_3">In-app Billing version 3</h3>
<p><em>December 2012</em></p>
<ul>
<li>Requires Google Play client version 3.9.16 or higher.
<li>Provides a new Android Interface Definition Language (AIDL) file named {@code IInAppBillingService.aidl}. The new interface offers these features:
<ul>
<li>Provides a new API to get details of in-app items published for the app including price, type, title and description.</li>
<li>The purchase flow is synchronous and purchase information is available immediately after it completes.</li>
<li>Purchase information of in-app purchases is maintained within the Google Play system till the purchase is consumed.</li>
<li>An API to consume a purchase of an inapp item. All purchases of one-time in-app items are consumable and thereafter can be purchased again.</li>
<li>An API to get current purchases of the user immediately. This list will not contain any consumed purchases.</li>
</ul>
</li>
<li>Subscriptions are not yet supported in this version of the API.</li>
</ul>
<h3 id="version_2">In-app Billing version 2</h3>
<p><em>May 2012</em></p>
<ul>
<li>Adds support for subscriptions, including free trial period.</li>
<li>Adds a new supported string value, "2", for the <code>API_VERSION</code> key of the Bundle object passed in the <code>sendBillingRequest()</code>.</li>
<li>Adds a new JSON field, <code>purchaseToken</code>, to the <code>orders</code> list returned in a <code>PURCHASE_STATE_CHANGED</code> intent. </li>
<li>Adds a new <code>purchaseState</code> value, <code>3</code> (expired), to the <code>orders</code> list returned in a <code>PURCHASE_STATE_CHANGED</code> intent. The value indicates that a subscription has expired and is no longer valid.</li>
<li>Requires Google Play (Play Store) version 3.5 or higher.</li>
</ul>
<h3 id="version_1">In-app Billing version 1</h3>
<p><em>March 2011</em></p>
<ul>
<li>Initial release.</li>
<li>Requires Google Play/Android Market 2.3.4 or higher.</li>
</ul>

BIN
docs/html/images/billing_arch.png Executable file → Normal file
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 63 KiB

After

Width:  |  Height:  |  Size: 63 KiB

BIN
docs/html/images/in-app-billing/billing_add.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
docs/html/images/in-app-billing/billing_app_key.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 KiB

BIN
docs/html/images/in-app-billing/billing_list_form_2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

BIN
docs/html/images/in-app-billing/billing_product_list.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

BIN
docs/html/images/in-app-billing/v3/iab_v3_checkout_flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 66 KiB

BIN
docs/html/images/in-app-billing/v3/iab_v3_consumption_flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
docs/html/images/in-app-billing/v3/iab_v3_flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 72 KiB

BIN
docs/html/images/in-app-billing/v3/iab_v3_purchase_flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 66 KiB

46
docs/html/training/in-app-billing/index.jd Normal file
View File

@@ -0,0 +1,46 @@
page.title=Selling In-app Products
trainingnavtop=true
startpage=true
next.title=Preparing Your In-app Billing Application
next.link=preparing-iab-app.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
<h2>Dependencies and prerequisites</h2>
<ul>
<li>Android 2.2 or higher</li>
</ul>
<h2>You Should Also Read</h2>
<ul>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing
Overview</a></li>
</ul>
</div>
</div>
<p>In this class, you'll learn how to perform common In-app Billing operations from Android applications.</p>
<p>In-app billing is a service hosted on Google Play that lets you charge for digital content or for upgrades in your app. The In-app Billing API makes it easy for you to integrate In-app Billing into your applications. You can request product details from Google Play, issue orders for in-app products, and quickly retrieve ownership information based on users' purchase history. You can also query the Google Play service for details about in-app products, such as local pricing and availability. Google Play provides a checkout interface that makes user interactions with the In-app Billing service seamless, and provides a more intuitive experience to your users.</p>
<p>This class describes how to get started with the Version 3 API. To learn how to use the version 2 API, see <a href="{@docRoot}google/play/billing/v2/billing_integrate.html">Implementing In-App Billing (V2)</a>.</p>
<h2>Lessons</h2>
<!-- Create a list of the lessons in this class along with a short description of each lesson.
These should be short and to the point. It should be clear from reading the summary whether someone
will want to jump to a lesson or not.-->
<dl>
<dt><b><a href="preparing-iab-app.html">Preparing Your In-app Billing Application</a></b></dt>
<dd>In this lesson, you will learn how to prepare your application to use the In-app Billing API and communicate with Google Play. You will also learn how to establish a connection to communicate with Google Play and verify that the In-app Billing API version that you are using is supported.</dd>
<dt><b><a href="list-iab-products.html">Establishing In-app Billing Products for Sale</a></b></dt>
<dd>In this lesson, you will learn how to specify the In-app Billing products for your app in Google Play and query the product details.</dd>
<dt><b><a href="purchase-iab-products.html">Purchase In-app Billing Products</a></b></dt>
<dd>In this lesson, you will learn how to purchase In-app Billing products, track consumption of purchased items, and query for details of purchased items.</dd>
<dt><b><a href="test-iab-app.html">Testing Your In-app Billing Application</a></b></dt>
<dd>In this lesson, you will learn how to test your application to ensure that In-app Billing is functioning correctly.</dd>
</dl>

91
docs/html/training/in-app-billing/list-iab-products.jd Normal file
View File

@@ -0,0 +1,91 @@
page.title=Establishing In-app Billing Products for Sale
parent.title=Selling In-app Products
parent.link=index.html
trainingnavtop=true
previous.title=Preparing Your In-app Billing Application
previous.link=preparing-iab-app.html
next.title=Purchasing In-app Billing Products
next.link=purchase-iab-products.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#DefineProducts">Specify In-app Products in Google Play</a></li>
<li><a href="#QueryDetails">Query In-app Product Details</a></li>
</ol>
<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing
Overview</a></li>
</ul>
</div>
</div>
<p>Before publishing your In-app Billing application, you'll need to define the product list of digital goods available for purchase in the <a href="https://play.google.com/apps/publish/">Google Play Developer Console</a>. </p>
<h2 id="DefineProducts">Specify In-app Products in Google Play</h2>
<p>From the Developer Console, you can define product information for in-app products and associate the product list with your application.</p>
<p>To add new in-app products to your product list:</p>
<ol>
<li>Build a signed APK file for your In-app Billing application. To learn how to build and sign your APK, see <a href="{@docRoot}tools/publishing/preparing.html#publishing-build">Building Your Application for Release</a>. Make sure that you are using your final (not debug) certificate and private key to sign your application.
</li>
<li>In the Developer Console, open the application entry that you created earlier.</li>
<li>Click on the APK tab then click on Upload new APK. Upload the signed APK file to the Developer Console. Don’t publish the app yet!</li>
<li>Navigate to the uploaded app listing, and click on <strong>In-app Products</strong>.
<li>Click on the option to add a new product, then complete the form to specify the product information such as the item’s unique product ID (also called its <em>SKU</em>), description, price, and country availability. Note down the product ID since you might need this information to query purchase details in your application later. <p class="note"><strong>Important:</strong> The In-app Billing Version 3 service only supports managed in-app products, so make sure that you specify that the purchase type is 'Managed' when you add new items to your product list in the Developer Console.</p></li>
<li>Once you have completed the form, activate the product so that your application can purchase it. <p class="note"><strong>Warning:</strong> It may take up to 2-3 hours after uploading the APK for Google Play to recognize your updated APK version. If you try to test your application before your uploaded APK is recognized by Google Play, your application will receive a ‘purchase cancelled’ response with an error message “This version of the application is not enabled for In-app Billing.”</p></li>
</ol>
<h2 id="QueryDetails">Query Items Available for Purchase</h2>
<p>You can query Google Play to programmatically retrieve details of the in-app products that are associated with your application (such as the product’s price, title, description, and type). This is useful, for example, when you want to display a listing of unowned items that are still available for purchase to users.</p>
<p class="note"><strong>Note:</strong> When making the query, you will need to specify the product IDs for the products explicitly. You can manually find the product IDs from the Developer Console by opening the <strong>In-app Products</strong> tab for your application. The product IDs are listed under the column labeled <strong>Name/ID</strong>.</p>
<p>To retrieve the product details, call {@code queryInventoryAsync(boolean, List, QueryInventoryFinishedListener)} on your IabHelper instance.
<ul>
<li>The first input argument indicates whether product details should be retrieved (should be set to {@code true}).</li>
<li>The {@code List} argument consists of one or more product IDs (also called SKUs) for the products that you want to query.</li>
<li>Finally, the {@code QueryInventoryFinishedListener} argument specifies a listener is notified when the query operation has completed and handles the query response.</li>
</ul>
If you use the the convenience classes provided in the sample, the classes will handle background thread management for In-app Billing requests, so you can safely make queries from the main thread of your application.
</p>
<p>The following code shows how you can retrieve the details for two products with IDs {@code SKU_APPLE} and {@code SKU_BANANA} that you previously defined in the Developer Console.</p>
<pre>
List<String> additionalSkuList = new List<String>();
additionalSkuList.add(SKU_APPLE);
additionalSkuList.add(SKU_BANANA);
mHelper.queryInventoryAsync(true, additionalSkuList,
mQueryFinishedListener);
</pre>
<p>If the query is successful, the query results are stored in an {@code Inventory} object that is passed back to the listener.</p>
<p>The following code shows how you can retrieve the item prices from the result set.</p>
<pre>
IabHelper.QueryInventoryFinishedListener
mQueryFinishedListener = new IabHelper.QueryInventoryFinishedListener() {
public void onQueryInventoryFinished(IabResult result, Inventory inventory)
{
if (result.isFailure()) {
// handle error
return;
}
String applePrice =
inventory.getSkuDetails(SKU_APPLE).getPrice();
String bananaPrice =
inventory.getSkuDetails(SKU_BANANA).getPrice();
// update the UI
}
}
</pre>

144
docs/html/training/in-app-billing/preparing-iab-app.jd Normal file
View File

@@ -0,0 +1,144 @@
page.title=Preparing Your In-app Billing Application
parent.title=Selling In-app Products
parent.link=index.html
trainingnavtop=true
next.title=Establishing In-app Billing Products for Sale
next.link=list-iab-products.html
@jd:body
<!-- This is the training bar -->
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#GetSample">Download the Sample App</a></li>
<li><a href="#AddToDevConsole">Add Your App to the Developer Console</a></li>
<li><a href="#AddLibrary">Add the In-app Billing Library</a></li>
<li><a href="#SetPermission">Set the Billing Permission</a></li>
<li><a href="#Connect">Initiate a Connection with Google Play</a></li>
</ol>
<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing
Overview</a></li>
</ul>
</div>
</div>
<p>Before you can start using the In-app Billing service, you'll need to add the library that contains the In-app Billing Version 3 API to your Android project. You also need to setting the permissions for your application to communicate with Google Play. In addition, you'll need to establish a connection between your application and Google Play. You should also verify that the In-app Billing API version that you are using in your application is supported by Google Play.</p>
<h2 id="GetSample">Download the Sample Application</h2>
<p>In this training class, you will use a reference implementation for the In-app Billing Version 3 API called the {@code TrivialDrive} sample application. The sample includes convenience classes to quickly set up the In-app Billing service, marshal and unmarshal data types, and handle In-app Billing requests from the main thread of your application. </p>
<p>To download the sample application:</p>
<ol>
<li>Open the <a href="{@docRoot}tools/help/sdk-manager.html">Android SDK Manager</a>.</li>
<li>In the SDK Manager, expand the {@code Extras} section.</li>
<li>Select <strong>Google Play Billing Library</strong>. Make sure to select the download for In-app Billing Version 3 or above.</li>
<li>Click <strong>Install</strong> to complete the download.</li>
</ol>
<p>The sample files will be installed to {@code /your/sdk/location/extras/google/play_billing/in-app-billing-v03}.</p>
<h2 id="AddToDevConsole">Add Your Application to the Developer Console</h2>
<p>The Google Play Developer Console is where you publish your In-app Billing application and manage the various digital goods that are available for purchase from your application. When you create a new application entry in the Developer Console, it automatically generates a public license key for your application. You will need this key to establish a trusted connection from your application to the Google Play servers. You only need to generate this key once per application, and don’t need to repeat these steps when you update the APK file for your application.</p>
<p>To add your application to the Developer Console:</p>
<ol>
<li>Go to the <a href="http://play.google.com/apps/publish">Google Play Developer Console</a> site and log in. You will need to register for a new developer account, if you have not registered previously. To sell in-app items, you also need to have a <a href="http://www.google.com/wallet/merchants.html">Google Checkout Merchant</a> account.</li>
<li>Click on <strong>Try the new design</strong> to access the preview version of the Developer Console, if you are not already logged on to that version. </li>
<li>In the <strong>All Applications</strong> tab, add a new application entry.
<ol type="a">
<li>Click <strong>Add new application</strong>.</li>
<li>Enter a name for your new In-app Billing application.</li>
<li>Click <strong>Prepare Store Listing</strong>.</li>
</ol>
</li>
<li>In the <strong>Services & APIs</strong> tab, find and make a note of the public license key that Google Play generated for your application. This is a Base64 string that you will need to include in your application code later.</li>
</ol>
<p>Your application should now appear in the list of applications in Developer Console.</p>
<h2 id="AddLibrary">Add the In-app Billing Library</h2>
<p>To use the In-app Billing Version 3 features, you must add the {@code IInAppBillingService.aidl} file to your Android project. This Android Interface Definition Language (AIDL) file defines the interface to the Google Play service.</p>
<p>You can find the {@code IInAppBillingService.aidl} file in the provided sample app. Depending on whether you are creating a new application or modifying an existing application, follow the instructions below to add the In-app Billing Library to your project.</p>
<h3>New Project</h3>
<p>To add the In-app Billing Version 3 library to your new In-app Billing project:</p>
<ol>
<li>Copy the {@code TrivialDrive} sample files into your Android project.</li>
<li>Modify the package name in the files you copied to use the package name for your project. In Eclipse, you can use this shortcut: right-click the package name, then select <strong>Refactor</strong> > <strong>Rename</strong>.</li>
<li>Open the {@code AndroidManifest.xml} file and update the package attribute value to use the package name for your project.</li>
<li>Fix import statements as needed so that your project compiles correctly. In Eclipse, you can use this shortcut: press <strong>Ctrl+Shift+O</strong> in each file showing errors.</li>
<li>Modify the sample to create your own application. Remember to copy the Base64 public license key for your application from the Developer Console over to your {@code MainActivity.java}.</li>
</ol>
<h3>Existing Project</h3>
<p>To add the In-app Billing Version 3 library to your existing In-app Billing project:</p>
<ol>
<li>Copy the {@code IInAppBillingService.aidl} file to your Android project.
<ul>
<li>If you are using Eclipse: Import the {@code IInAppBillingService.aidl} file into your {@code /src} directory.</li>
<li>If you are developing in a non-Eclipse environment: Create the following directory {@code /src/com/android/vending/billing} and copy the {@code IInAppBillingService.aidl} file into this directory.</li>
</ul>
</li>
<li>Build your application. You should see a generated file named {@code IInAppBillingService.java} in the {@code /gen} directory of your project.</li>
<li>Add the helper classes from the {@code /util} directory of the {@code TrivialDrive} sample to your project. Remember to change the package name declarations in those files accordingly so that your project compiles correctly.</li>
</ol>
<p>Your project should now contain the In-app Billing Version 3 library.</p>
<h2 id="SetPermission">Set the Billing Permission</h2>
<p>Your app needs to have permission to communicate request and response messages to the Google Play’s billing service. To give your app the necessary permission, add this line in your {@code AndroidManifest.xml} manifest file:</p>
<pre>
&lt;uses-permission android:name="com.android.vending.BILLING" /&gt;
</pre>
<h2 id="Connect">Initiate a Connection with Google Play</h2>
<p>You must bind your Activity to Google Play’s In-app Billing service to send In-app Billing requests to Google Play from your application. The convenience classes provided in the sample handles the binding to the In-app Billing service, so you don’t have to manage the network connection directly.</p>
<p>To set up synchronous communication with Google Play, create an {@code IabHelper} instance in your activity's {@code onCreate} method. In the constructor, pass in the {@code Context} for the activity, along with a string containing the public license key that was generated earlier by the Google Play Developer Console. </p>
<p class="note"><strong>Security Recommendation:</strong> It is highly recommended that you do not hard-code the exact public license key string value as provided by Google Play. Instead, you can construct the whole public license key string at runtime from substrings, or retrieve it from an encrypted store, before passing it to the constructor. This approach makes it more difficult for malicious third-parties to modify the public license key string in your APK file.</p>
<pre>
IabHelper mHelper;
&#64;Override
public void onCreate(Bundle savedInstanceState) {
// ...
String base64EncodedPublicKey;
// compute your public key and store it in base64EncodedPublicKey
mHelper = new IabHelper(this, base64EncodedPublicKey);
}
</pre>
<p>Next, perform the service binding by calling the {@code startSetup} method on the {@code IabHelper} instance that you created. Pass the method an {@code OnIabSetupFinishedListener} instance, which is called once the {@code IabHelper} completes the asynchronous setup operation. As part of the setup process, the {@code IabHelper} also checks if the In-app Billing Version 3 API is supported by Google Play. If the API version is not supported, or if an error occured while establishing the service binding, the listener is notified and passed an {@code IabResult} object with the error message.</p>
<pre>
mHelper.startSetup(new IabHelper.OnIabSetupFinishedListener() {
public void onIabSetupFinished(IabResult result) {
if (!result.isSuccess()) {
// Oh noes, there was a problem.
Log.d(TAG, "Problem setting up In-app Billing: " + result);
}
// Hooray, IAB is fully set up!
}
});
</pre>
<p>If the setup completed successfully, you can now use the {@code mHelper} reference to communicate with the Google Play service. When your application is launched, it is a good practice to query Google Play to find out what in-app items are owned by a user. This is covered further in the <a href="{@docRoot}training/in-app-billing/purchase-iab-products.html#QueryPurchases">Query Purchased Items</a> section.</p>
<p class="note"><strong>Important:</strong> Remember to unbind from the In-app Billing service when you are done with your activity. If you don’t unbind, the open service connection could cause your device’s performance to degrade. To unbind and free your system resources, call the {@code IabHelper}'s {@code dispose} method when your {@code Activity} gets destroyed.</p>
<pre>
&#64;Override
public void onDestroy() {
if (mHelper != null) mHelper.dispose();
mHelper = null;
}
</pre>

138
docs/html/training/in-app-billing/purchase-iab-products.jd Normal file
View File

@@ -0,0 +1,138 @@
page.title=Purchasing In-app Billing Products
parent.title=Selling In-app Products
parent.link=index.html
trainingnavtop=true
previous.title=Establishing In-app Billing Products for Sale
previous.link=list-iab-products.html
next.title=Testing Your In-app Billing Application
next.link=test-iab-app.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#Purchase">Purchase an Item</a></li>
<li><a href="#QueryPurchases">Query Purchased Items</a></li>
<li><a href="#Consume">Consume a Purchase</a></li>
</ol>
<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing
Overview</a></li>
</ul>
</div>
</div>
<p>Once your application is connected to Google Play, you can initiate purchase requests for in-app products. Google Play provides a checkout interface for users to enter their payment method, so your application does not need to handle payment transactions directly.</p>
<p>When an item is purchased, Google Play recognizes that the user has ownership of that item and prevents the user from purchasing another item with the same product ID until it is consumed. You can control how the item is consumed in your application, and notify Google Play to make the item available for purchase again.</p>
<p>You can also query Google Play to quickly retrieve the list of purchases that were made by the user. This is useful, for example, when you want to restore the user's purchases when your user launches your app.</p>
<h2 id="Purchase">Purchase an Item</h2>
<p>To start a purchase request from your app, call {@code launchPurchaseFlow(Activity, String, int, OnIabPurchaseFinishedListener, String)} on your {@code IabHelper} instance. You must make this call from the main thread of your {@code Activity}. Here’s an explaination of the {@code launchPurchaseFlow} method parameters:</p>
<ul>
<li>The first argument is the calling {@code Activity}.</li>
<li>The second argument is the product ID (also called its SKU) of the item to purchase. Make sure that you are providing the ID and not the product name. You must have previously defined and activated the item in the Developer Console, otherwise it won’t be recognized. </li>
<li>The third argument is a request code value. This value can be any positive integer. Google Play reurns this request code to the calling {@code Activity}’s {@code onActivityResult} along with the purchase response.</li>
<li>The fourth argument is a listener that is notified when the purchase operation has completed and handles the purchase response from Google Play.</li>
<li>The fifth argument contains a ‘developer payload’ string that you can use to send supplemental information about an order (it can be an empty string). Typically, this is used to pass in a string token that uniquely identifies this purchase request. If you specify a string value, Google Play returns this string along with the purchase response. Subsequently, when you make queries about this purchase, Google Play returns this string together with the purchase details. <p class="note"><strong>Security Recommendation:</strong> It’s good practice to pass in a string that helps your application to identify the user who made the purchase, so that you can later verify that this is a legitimate purchase by that user. For consumable items, you can use a randomly generated string, but for non-consumable items you should use a string that uniquely identifies the user.</p></li>
</ul>
<p>The following example shows how you can make a purchase request for a product with ID {@code SKU_GAS}, using an arbitrary value of 10001 for the request code, and an encoded developer payload string.</p>
<pre>
mHelper.launchPurchaseFlow(this, SKU_GAS, 10001,
mPurchaseFinishedListener, "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ");
</pre>
<p>If the purchase order is successful, the response data from Google Play is stored in an {@code Purchase} object that is passed back to the listener.</p>
<p>The following example shows how you can handle the purchase response in the listener, depending on whether the purchase order was completed successfully, and whether the user purchased gas or a premium upgrade. In this example, gas is an in-app product that can be purchased multiple times, so you should consume the purchase to allow the user to buy it again. To learn how to consume purchases, see the <a href="{@docRoot}training/in-app-billing/purchase-iab-products.html#Consume">Consuming Products</a> section. The premium upgrade is a one-time purchase so you don’t need to consume it. It is good practice to update the UI immediately so that your users can see their newly purchased items.</p>
<pre>
IabHelper.OnIabPurchaseFinishedListener mPurchaseFinishedListener
= new IabHelper.OnIabPurchaseFinishedListener() {
public void onIabPurchaseFinished(IabResult result, Purchase purchase)
{
if (result.isFailure()) {
Log.d(TAG, "Error purchasing: " + result);
return;
}
else if (purchase.getSku().equals(SKU_GAS)) {
// consume the gas and update the UI
}
else (purchase.getSku().equals(SKU_PREMIUM)) {
// give user access to premium content and update the UI
}
}
};
</pre>
<p class="note"><strong>Security Recommendation:</strong> When you receive the purchase response from Google Play, make sure to check the returned data signature, the {@code orderId}, and the {@code developerPayload} string in the {@code Purchase} object to make sure that you are getting the expected values. You should verify that the {@code orderId} is a unique value that you have not previously processed, and the {@code developerPayload} string matches the token that you sent previously with the purchase request. As a further security precaution, you should perform the verification on your own secure server. </p>
<h2 id="QueryPurchases">Query Purchased Items</h2>
<p>Upon a successful purchase, the user’s purchase data is cached locally by Google Play’s In-app Billing service. It is good practice to frequently query the In-app Billing service for the user’s purchases, for example whenever the app starts up or resumes, so that the user’s current in-app product ownership information is always reflected in your app.</p>
<p>To retrieve the user’s purchases from your app, call {@code queryInventoryAsync(QueryInventoryFinishedListener)} on your {@code IabHelper} instance. The {@code QueryInventoryFinishedListener} argument specifies a listener that is notified when the query operation has completed and handles the query response. It is safe to make this call fom your main thread.</p>
<pre>
mHelper.queryInventoryAsync(mGotInventoryListener);
</pre>
<p>If the query is successful, the query results are stored in an {@code Inventory} object that is passed back to the listener. The In-app Billing service returns only the purchases made by the user account that is currently logged in to the device.</p>
<pre>
IabHelper.QueryInventoryFinishedListener mGotInventoryListener
= new IabHelper.QueryInventoryFinishedListener() {
public void onQueryInventoryFinished(IabResult result,
Inventory inventory) {
if (result.isFailure()) {
// handle error here
}
else {
// does the user have the premium upgrade?
mIsPremium = inventory.hasPurchase(SKU_PREMIUM);
// update UI accordingly
}
}
};
</pre>
<h2 id="Consume">Consume a Purchase</h2>
<p>You can use the In-app Billing Version 3 API to track the ownership of purchased items in Google Play. Once an item is purchased, it is considered to be "owned" and cannot be purchased again from Google Play while in that state. You must send a consumption request for the item before Google Play makes it available for purchase again. All managed in-app products are consumable. How you use the consumption mechanism in your app is up to you. Typically, you would implement consumption for products with temporary benefits that users may want to purchase multiple times (for example, in-game currency or replensihable game tokens). You would typically not want to implement consumption for products that are purchased once and provide a permanent effect (for example, a premium upgrade).</p>
<p>It's your responsibility to control and track how the in-app product is provisioned to the user. For example, if the user purchased in-game currency, you should update the player's inventory with the amount of currency purchased.</p>
<p class="note"><strong>Security Recommendation:</strong> You must send a consumption request before provisioning the benefit of the consumable in-app purchase to the user. Make sure that you have received a successful consumption response from Google Play before you provision the item.</p>
<p>To record a purchase consumption, call {@code consumeAsync(Purchase, OnConsumeFinishedListener)} on your {@code IabHelper} instance. The first argument that the method takes is the {@code Purchase} object representing the item to consume. The second argument is a {@code OnConsumeFinishedListener} that is notified when the consumption operation has completed and handles the consumption response from Google Play. It is safe to make this call fom your main thread.</p>
<p>In this example, you want to consume the gas item that the user has previously purchased in your app.</p>
<pre>
mHelper.consumeAsync(inventory.getPurchase(SKU_GAS),
mConsumeFinishedListener);
</pre>
<p>The following example shows how to implement the {@code OnConsumeFinishedListener}.</p>
<pre>
IabHelper.OnConsumeFinishedListener mConsumeFinishedListener =
new IabHelper.OnConsumeFinishedListener() {
public void onConsumeFinished(Purchase purchase, IabResult result) {
if (result.isSuccess()) {
// provision the in-app purchase to the user
// (for example, credit 50 gold coins to player's character)
}
else {
// handle error
}
}
};
</pre>
<h3>Check for Consumable Items on Startup</h3>
<p>It’s important to check for consumable items when the user starts up your application. Typically, you would first query the In-app Billing service for the items purchased by the user (via {@code queryInventoryAsync}), then get the consumable {@code Purchase} objects from the Inventory. If your application detects that are any consumable items that are owned by the user, you should send a consumption request to Google Play immediately and provision the item to the user. See the {@code TrivialDrive} sample for an example of how to implement this checking at startup.</p>

56
docs/html/training/in-app-billing/test-iab-app.jd Normal file
View File

@@ -0,0 +1,56 @@
page.title=Testing Your In-app Billing Application
parent.title=Selling In-app Products
parent.link=index.html
trainingnavtop=true
previous.title=Purchasing In-app Billing Products
previous.link=purchase-iab-products.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#StaticTest">Test with Static Responses</a></li>
<li><a href="#PlayItemTest">Test with Your Own Product IDs</a></li>
</ol>
<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing
Overview</a></li>
</ul>
</div>
</div>
<p>To ensure that In-app Billing is functioning correctly in your application, you should test the test the application before you publish it on Google Play. Early testing also helps to ensure that the user flow for purchasing in-app items is not confusing or slow, and that users can see their newly purchased items in a timely way.</p>
<h2 id="StaticTest">Test with Static Responses</h2>
Test your In-app Billing application with static responses by using Google Play’s reserved product IDs.By using reserved product IDs instead of actual product IDs, you can test the purchase flow without specifying an actual payment method or transferring money. To learn more about the reserved product IDs, see <a href="{@docRoot}google/play/billing/billing_testing.html">Testing In-app Billing</a>.
<h2 id="PlayItemTest">Test with Your Own Product IDs</h2>
<p>Because Google Play does not allow you to use your developer account to directly purchase in-app products that you have created yourself, you'll need to create test acccounts under your developer account profile. To create a test account, simply enter a valid Google email address. Users with these test accounts will then be able to make in-app-billing purchases from uploaded, unpublished applications that you manage.</p>
<p>To test your In-app Billing Version 3 application using your own product IDs:
<ol>
<li>In the Developer Console, add one or more tester accounts to the developer account that you are using to publish your application.
<ol type="a">
<li>Login to the <a href="https://play.google.com/apps/publish/" target="_blank">Developer Console</a> with your developer account.</li>
<li>Click <strong>Settings</strong> > <strong>Account</strong> details, then in the <strong>License Testing</strong> section, add the Google email addresses for your tester accounts.</li>
</ol>
<li>Build a signed APK file for your In-app Billing application. To learn how to build and sign your APK, see <a href="{@docRoot}tools/publishing/preparing.html#publishing-build">Building Your Application for Release</a>. Make sure that you are using your final (not debug) certificate and private key to sign your application.
</li>
<li>Make sure that you have uploaded the signed APK for your application to the Developer Console, and associated one or more in-app products with your application. You don't need to publish the application on Google Play to test it. <p class="note"><strong>Warning:</strong> It may take up to 2-3 hours after uploading the APK for Google Play to recognize your updated APK version. If you try to test your application before your uploaded APK is recognized by Google Play, your application will receive a ‘purchase cancelled’ response with an error message “This version of the application is not enabled for In-app Billing.”</p></li>
<li>Install the APK file to your physical test device by using the {@code adb} tool. To learn how to install the application, see <a href="{@docRoot}tools/building/building-cmdline.html#RunningOnDevice">Running on a Device</a>. Make sure that:
<ul>
<li>Your test device is running on Android SDK Version 2.2 (API level 8) or higher, and is installed with Google Play client Version 3.9.16 or higher.</li>
<li>The {@code android:versionCode} and {@code android:versionName} attributes values in the {@code AndroidManifest.xml} of the application that you are installing matches the values of your APK in the Developer Console.</li>
<li>Your application is signed with the same certificate that you used for the APK that you uploaded to the Developer Console, before installing it on your device.</li>
</ul>
</li>
<li>Login to the test device by using a tester account. Test your In-app Billing application by purchasing a few items, and fix any issues that you encounter. Remember to refund the purchases if you don’t want your testers to be actually charged!</li>
</ol>
</p>

24
docs/html/training/training_toc.cs
View File

@@ -954,6 +954,30 @@
</a>
</div>
<ul>
<li class="nav-section">
<div class="nav-section-header"><a href="<?cs var:toroot ?>training/in-app-billing/index.html"
description="How to sell in-app products from your application using In-app Billing.">
Selling In-app Products
</a></div>
<ul>
<li><a href="<?cs var:toroot ?>training/in-app-billing/preparing-iab-app.html">
<span class="en">Preparing Your App</span>
</a>
</li>
<li><a href="<?cs var:toroot ?>training/in-app-billing/list-iab-products.html">
<span class="en">Establishing Products for Sale</span>
</a>
</li>
<li><a href="<?cs var:toroot ?>training/in-app-billing/purchase-iab-products.html">
<span class="en">Purchasing Products</span>
</a>
</li>
<li><a href="<?cs var:toroot ?>training/in-app-billing/test-iab-app.html">
<span class="en">Testing Your App</span>
</a>
</li>
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header">

BIN
docs/image_sources/in-app-billing/v2/billing_arch.graffle Normal file
View File

Binary file not shown.

BIN
docs/image_sources/in-app-billing/v2/billing_check_supported.graffle Normal file
View File

Binary file not shown.

BIN
docs/image_sources/in-app-billing/v2/billing_checkout_flow.graffle Normal file
View File

Binary file not shown.

BIN
docs/image_sources/in-app-billing/v2/billing_refund.graffle Normal file
View File

Binary file not shown.

BIN
docs/image_sources/in-app-billing/v2/billing_request_purchase.graffle Normal file
View File

Binary file not shown.

BIN
docs/image_sources/in-app-billing/v2/billing_restore_transactions.graffle Normal file
View File

Binary file not shown.

BIN
docs/image_sources/in-app-billing/v2/billing_test_flow.graffle Normal file
View File

Binary file not shown.

BIN
docs/image_sources/in-app-billing/v3/iab_v3_checkout_flow.graffle Normal file
View File

Binary file not shown.

1018
docs/image_sources/in-app-billing/v3/iab_v3_consumption_flow.graffle Normal file
View File

File diff suppressed because it is too large Load Diff

1879
docs/image_sources/in-app-billing/v3/iab_v3_purchase_flow.graffle Normal file
View File

File diff suppressed because it is too large Load Diff