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

Commit 7e86ae85 authored by Andrew Solovay's avatar Andrew Solovay
Browse files

docs: IAB formatting fixes (no content changes) 

Saw a problem with the files' TOCs that was causing formatting
problems. While I had the files open, I fixed other formatting
issues--mostly just whitespace (paragraphs that were on one line
instead of broken at 100 chars) and a couple of other typos or HTML
errors. No substantive changes to the documentation.

Change-Id: I5f89ae616489d19dd683fd24e11e3482cce99477
parent 85ac0dd2

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

+244 −67
Original line number Diff line number Diff line
@@ -11,15 +11,15 @@ page.tags="billing, inapp, iap" 
  <ol>

    <li><a href="#producttypes">Product Types</a>

       <ol>

       <li><a href="#managed">Managed In-app Products</a><li>

       <li><a href="#subs">Subscriptions</a><li>

       <li><a href="#managed">Managed In-app Products</a></li>

       <li><a href="#subs">Subscriptions</a></li>

       </ol>

    </li>

    <li><a href="#purchase">Purchasing Items</a></li>

    <li><a href="#consume">Consuming In-app Products</a>

       <ol>

       <li><a href="#consumetypes">Non-consumable and Consumable In-app Products</a><li>

       <li><a href="#managingconsumables">Managing Consumable Purchases</a><li>

       <li><a href="#consumetypes">Non-consumable and Consumable In-app Products</a></li>

       <li><a href="#managingconsumables">Managing Consumable Purchases</a></li>

       </ol>

    </li>

    <li><a href="#caching">Local Caching</a></li>
@@ -38,26 +38,69 @@ page.tags="billing, inapp, iap" 
</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>

<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 supports managed in-app products and subscriptions.</p>



<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 supports managed in-app products and

  subscriptions.

</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>



<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>



<h3 id="subs">Subscriptions</h3>

<p>A subscription is a product type offered in In-app Billing that lets you sell 



<p>

  A subscription is a product type offered in In-app Billing that lets you sell

  content, services, or features to users from inside your app with recurring

  monthly or annual billing. You can sell subscriptions to almost any type of

  digital content, from any type of app or game. To understand how

subscriptions work, see <a href="{@docRoot}google/play/billing/billing_subscriptions.html">In-app Billing Subscriptions</a>.</p>

<p>With the Version 3 API, you can use the same purchase flow for buying 

  subscriptions work, see <a href=

  "{@docRoot}google/play/billing/billing_subscriptions.html">In-app Billing

  Subscriptions</a>.

</p>



<p>

  With the Version 3 API, you can use the same purchase flow for buying

  subscriptions and retrieving subscription purchase information as with in-app

products. For a code example, see <a href="{@docRoot}google/play/billing/billing_integrate.html#Subs">Implementing Subscriptions</a>.</p>

<p class="caution"><strong>Important</strong>: Unlike in-app products, 

subscriptions cannot be consumed.</p>

  products. For a code example, see <a href=

  "{@docRoot}google/play/billing/billing_integrate.html#Subs">Implementing

  Subscriptions</a>.

</p>



<p class="caution">

  <strong>Important</strong>: Unlike in-app products, subscriptions cannot be

  consumed.

</p>



<h2 id="purchase">Purchasing Items</h2>
@@ -68,71 +111,205 @@ subscriptions cannot be consumed.</p> 
</p>

</div>



<p>A typical purchase flow with the Version 3 API is as follows:

<p>A typical purchase flow with the Version 3 API is as follows:</p>



<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>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.



  <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 your 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> 

      <li>Google Play returns a {@code Bundle} that contains a {@code

      PendingIntent} which your 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>

  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>

<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 In-app Products</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 



<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 in-app product, that purchase is recorded in Google 

Play. Once an in-app product is purchased, it is considered to be "owned". 

In-app products in the "owned" state cannot be purchased from Google Play. You 

must send a consumption request for the "owned" in-app product before Google 

Play makes it available for purchase again. Consuming the in-app product reverts 

it to the "unowned" state, and discards the previous purchase data.</p>

  application can query the user's purchase information when needed. When the

  user successfully purchases an in-app product, that purchase is recorded in

  Google Play. Once an in-app product is purchased, it is considered to be

  "owned". In-app products in the "owned" state cannot be purchased from Google

  Play. You must send a consumption request for the "owned" in-app product

  before Google Play makes it available for purchase again. Consuming the

  in-app product 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"/>

<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 in-app product'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>



<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 in-app product'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 In-app Products</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>



<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 in-app products 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 in-app product 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 in-app product in your application, you must send a consumption request to Google Play and receive a successful response indicating that the consumption was recorded.</p>

  <dt>

    Non-consumable Items

  </dt>



  <dd>

    Typically, you would not implement consumption for in-app products 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 in-app product 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 in-app

      product 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 in-app product:</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>

  <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 in-app products; if so, make sure to consume and provision those items. Here's the recommended application startup flow if you implement consumable in-app products in your application:</p>



<p>

  Subsequently, when the user starts up or logs in to your application, you

  should check if the user owns any outstanding consumable in-app products; if

  so, make sure to consume and provision those items. Here's the recommended

  application startup flow if you implement consumable in-app products in your

  application:

</p>



<ol>

<li>Send a {@code getPurchases} request to query the owned in-app products for the user.</li>

<li>If there are any consumable in-app products, 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>

  <li>Send a {@code getPurchases} request to query the owned in-app products

  for the user.

  </li>



  <li>If there are any consumable in-app products, 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>





<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>

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

+354 −106

File changed.

Preview size limit exceeded, changes collapsed.