From 7e86ae85cc75e710e0d7d81aa4758d92bac1b869 Mon Sep 17 00:00:00 2001 From: Andrew Solovay Date: Thu, 1 Oct 2015 14:04:25 -0700 Subject: [PATCH] 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 --- docs/html/google/play/billing/api.jd | 311 +++++++++--- .../google/play/billing/billing_integrate.jd | 464 ++++++++++++++---- 2 files changed, 600 insertions(+), 175 deletions(-) diff --git a/docs/html/google/play/billing/api.jd b/docs/html/google/play/billing/api.jd index 9379a6b2e1bdb..6816ff16264f4 100644 --- a/docs/html/google/play/billing/api.jd +++ b/docs/html/google/play/billing/api.jd @@ -11,53 +11,96 @@ page.tags="billing, inapp, iap"
  1. Product Types
      -
    1. Managed In-app Products
    2. -
    3. Subscriptions
    4. +
    5. Managed In-app Products
      6. +
    6. Subscriptions
  2. Purchasing Items
  3. Consuming In-app Products
      -
    1. Non-consumable and Consumable In-app Products
    2. -
    3. Managing Consumable Purchases
    4. +
    5. Non-consumable and Consumable In-app Products
      6. +
    6. Managing Consumable Purchases
  4. Local Caching
- +

Reference

  1. In-app Billing Reference (V3)
- +

See also

  1. Selling In-app Products
    2. -
+ -

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.

+

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

Product Types

-

You define your products using the Google Play Developer Console, including product type, SKU, price, description, and so on. For more information, see Administering In-app Billing. The Version 3 API supports managed in-app products and subscriptions.

+ +

+ You define your products using the Google Play Developer Console, including + product type, SKU, price, description, and so on. For more information, see + Administering + In-app Billing. The Version 3 API supports managed in-app products and + subscriptions. +

+

Managed In-app Products

-

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.

-

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

+ +

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

+ +

+ 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 Consuming + Items. +

Subscriptions

-

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 In-app Billing Subscriptions.

-

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

-

Important: Unlike in-app products, -subscriptions cannot be consumed.

+ +

+ 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 In-app Billing + Subscriptions. +

+ +

+ 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 Implementing + Subscriptions. +

+ +

+ Important: Unlike in-app products, subscriptions cannot be + consumed. +

Purchasing Items

@@ -68,71 +111,205 @@ subscriptions cannot be consumed.

-

A typical purchase flow with the Version 3 API is as follows: +

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

+
    -
  1. 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.
    2. -
  2. 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.
    3. -
  3. 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. -
    4. -
  4. 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. -
      -
    1. Google Play returns a {@code Bundle} that contains a {@code PendingIntent} which your application uses to start the checkout UI for the purchase.
      2. -
    2. Your application launches the pending intent by calling the {@code startIntentSenderForResult} method.
      3. -
    3. 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.
      4. -
    -
    5. +
  5. 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. +
    6. + +
  6. 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. +
    7. + +
  7. 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. +
    8. + +
  8. 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. +
      +
    1. Google Play returns a {@code Bundle} that contains a {@code + PendingIntent} which your application uses to start the checkout UI for + the purchase. +
      2. + +
    2. Your application launches the pending intent by calling the {@code + startIntentSenderForResult} method. +
      3. + +
    3. 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. +
      4. +
    +
+ +

+ To learn more about the Version 3 API calls and server responses, see + In-app Billing + Reference.

-

To learn more about the Version 3 API calls and server responses, see In-app Billing Reference.

Consuming In-app Products

-

You can use the consumption mechanism to track the user's ownership of in-app -products.

-

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.

+ +

+ You can use the consumption mechanism to track the user's ownership of in-app + products. +

+ +

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

+
- +

Figure 2. The basic sequence for a consumption request.

-

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.

+ +

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

Non-consumable and Consumable In-app Products

-

It's up to you to decide if you want to handle your in-app products as non-consumable or consumable items.

+ +

+ It's up to you to decide if you want to handle your in-app products as + non-consumable or consumable items. +

+
-
Non-consumable Items
-
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.
-
Consumable items
-
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 provisioning the in-app product. You are responsible for controlling and tracking how in-app products are provisioned to the users. -

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

-
+
+ Non-consumable Items +
+ +
+ 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. +
+ +
+ Consumable items +
+ +
+ 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 + provisioning the in-app product. You are responsible for + controlling and tracking how in-app products are provisioned to the users. +

+ Important: 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. +

+
+

Managing consumable purchases in your application

Here is the basic flow for purchasing a consumable in-app product:

+
    -
  1. Launch a purchase flow with a {@code getBuyIntent} call
    2. -
  2. Get a response {@code Bundle}from Google Play indicating if the purchase completed successfully.
    3. -
  3. If the purchase was successful, consume the purchase by making a {@code consumePurchase} call.
    4. -
  4. Get a response code from Google Play indicating if the consumption completed successfully.
    5. -
  5. If the consumption was successful, provision the product in your application.
    6. +
  6. Launch a purchase flow with a {@code getBuyIntent} call +
    7. + +
  7. Get a response {@code Bundle}from Google Play indicating if the purchase + completed successfully. +
    8. + +
  8. If the purchase was successful, consume the purchase by making a {@code + consumePurchase} call. +
    9. + +
  9. Get a response code from Google Play indicating if the consumption + completed successfully. +
    10. + +
  10. If the consumption was successful, provision the product in your + application. +
-

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:

+ +

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

+
    -
  1. Send a {@code getPurchases} request to query the owned in-app products for the user.
    2. -
  2. 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.
    3. -
  3. Get a response code from Google Play indicating if the consumption completed successfully.
    4. -
  4. If the consumption was successful, provision the product in your application.
    5. +
  5. Send a {@code getPurchases} request to query the owned in-app products + for the user. +
    6. + +
  6. 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. +
    7. + +
  7. Get a response code from Google Play indicating if the consumption + completed successfully. +
    8. + +
  8. If the consumption was successful, provision the product in your + application. +

Local Caching

-

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.

- +

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

diff --git a/docs/html/google/play/billing/billing_integrate.jd b/docs/html/google/play/billing/billing_integrate.jd index 4ff1c083b3fb4..ce1f50e8d02ae 100644 --- a/docs/html/google/play/billing/billing_integrate.jd +++ b/docs/html/google/play/billing/billing_integrate.jd @@ -16,8 +16,8 @@ page.tags="inapp, billing, iap"
  • Querying Items Available for Purchase
  • Purchasing an Item
  • Querying Purchased Items
    • -
  • Consuming a Purchase
  • -
  • Implementing Subscriptions
  • +
  • Consuming a Purchase
    • +
  • Implementing Subscriptions
  • Securing Your App @@ -38,15 +38,35 @@ page.tags="inapp, billing, iap" -

    In-app Billing on Google Play provides a straightforward, simple interface for sending In-app Billing requests and managing In-app Billing transactions using Google Play. The information below covers the basics of how to make calls from your application to the In-app Billing service using the Version 3 API.

    +

    + In-app Billing on Google Play provides a straightforward, simple interface + for sending In-app Billing requests and managing In-app Billing transactions + using Google Play. The information below covers the basics of how to make + calls from your application to the In-app Billing service using the Version 3 + API. +

    -

    Note: To see a complete implementation and learn how to test your application, see the Selling In-app Products training class. The training class provides a complete sample In-app Billing application, including convenience classes to handle key tasks related to setting up your connection, sending billing requests and processing responses from Google Play, and managing background threading so that you can make In-app Billing calls from your main activity.

    +

    + Note: To see a complete implementation and learn how to test + your application, see the Selling In-app Products + training class. The training class provides a complete sample In-app Billing + application, including convenience classes to handle key tasks related to + setting up your connection, sending billing requests and processing responses + from Google Play, and managing background threading so that you can make + In-app Billing calls from your main activity. +

    -

    Before you start, be sure that you read the In-app Billing Overview to familiarize yourself with -concepts that will make it easier for you to implement In-app Billing.

    +

    + Before you start, be sure that you read the In-app Billing + Overview to familiarize yourself with concepts that will make it easier + for you to implement In-app Billing. +

    To implement In-app Billing in your application, you need to do the following:

    +
    1. Add the In-app Billing library to your project.
    2. Update your {@code AndroidManifest.xml} file.
      3. @@ -73,48 +93,74 @@ method calls.

      The {@code IInAppBillingService.aidl} file will be installed to {@code <sdk>/extras/google/play_billing/}.

      To add the AIDL to your project:

      -
        -
      1. Copy the {@code IInAppBillingService.aidl} file to your Android project. -
          -
        • If you are using Eclipse: -
            -
          1. If you are starting from an existing Android project, open the project -in Eclipse. If you are creating a new Android project from scratch, click -File > New > Android Application -Project, then follow the instructions in the New Android -Application wizard to create a new project in your workspace.
            2. -
          2. In the {@code /src} directory, click File > -New > Package, then create a package named {@code com.android.vending.billing}.
            3. -
          3. Copy the {@code IInAppBillingService.aidl} file from {@code <sdk>/extras/google/play_billing/} and paste it into the {@code src/com.android.vending.billing/} -folder in your workspace.
            4. -
          -
          • -
        • 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. Put the AIDL file -into your project and use the Ant tool to build your project so that the -IInAppBillingService.java file gets generated.
          • -
        -
        2. -
      2. Build your application. You should see a generated file named -{@code IInAppBillingService.java} in the {@code /gen} directory of your -project.
        3. -
      +
        +
      1. Copy the {@code IInAppBillingService.aidl} file to your Android project. +
          +
        • If you are using Eclipse: +
            +
          1. If you are starting from an existing Android project, open the + project in Eclipse. If you are creating a new Android project from + scratch, click File > New > + Android Application Project, then follow the + instructions in the New Android Application wizard + to create a new project in your workspace. +
            2. + +
          2. In the {@code /src} directory, click File > + New > Package, then create a + package named {@code com.android.vending.billing}. +
            3. + +
          3. Copy the {@code IInAppBillingService.aidl} file from {@code + <sdk>/extras/google/play_billing/} and paste it into the {@code + src/com.android.vending.billing/} folder in your workspace. +
            4. +
          +
          • + +
        • 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. Put the AIDL + file into your project and use the Ant tool to build your project so that + the IInAppBillingService.java file gets generated. +
          • +
        +
        2. + +
      2. Build your application. You should see a generated file named {@code + IInAppBillingService.java} in the {@code /gen} directory of your project. +
        3. +

      Updating Your Application's Manifest

      -

      In-app billing relies on the Google Play application, which handles all communication between your application and the Google Play server. To use the Google Play application, your application must request the proper permission. You can do this by adding the {@code com.android.vending.BILLING} permission to your AndroidManifest.xml file. If your application does not declare the In-app Billing permission, but attempts to send billing requests, Google Play will refuse the requests and respond with an error.

      +

      + In-app billing relies on the Google Play application, which handles all + communication between your application and the Google Play server. To use the + Google Play application, your application must request the proper permission. + You can do this by adding the {@code com.android.vending.BILLING} permission + to your AndroidManifest.xml file. If your application does not declare the + In-app Billing permission, but attempts to send billing requests, Google Play + will refuse the requests and respond with an error. +

      + +

      + To give your app the necessary permission, add this line in your {@code + Android.xml} manifest file: +

      -

      To give your app the necessary permission, add this line in your {@code Android.xml} manifest file:

       <uses-permission android:name="com.android.vending.BILLING" />

      Creating a ServiceConnection

      -

      Your application must have a {@link android.content.ServiceConnection} to facilitate messaging between -your application and Google Play. At a minimum, your application must do the following:

      +

      + Your application must have a {@link android.content.ServiceConnection} to + facilitate messaging between your application and Google Play. At a minimum, + your application must do the following: +

      • Bind to {@code IInAppBillingService}. @@ -123,8 +169,18 @@ your application and Google Play. At a minimum, your application must do the fol

      Binding to IInAppBillingService

      -

      To establish a connection with the In-app Billing service on Google Play, implement a {@link android.content.ServiceConnection} to bind your activity to {@code IInAppBillingService}. Override the {@link android.content.ServiceConnection#onServiceDisconnected onServiceDisconnected} and {@link -android.content.ServiceConnection#onServiceConnected onServiceConnected} methods to get a reference to the {@code IInAppBillingService} instance after a connection has been established.

      + +

      + To establish a connection with the In-app Billing service on Google Play, + implement a {@link android.content.ServiceConnection} to bind your activity + to {@code IInAppBillingService}. Override the {@link + android.content.ServiceConnection#onServiceDisconnected + onServiceDisconnected} and {@link + android.content.ServiceConnection#onServiceConnected onServiceConnected} + methods to get a reference to the {@code IInAppBillingService} instance after + a connection has been established. +

      + 
       IInAppBillingService mService;
 
@@ -142,9 +198,25 @@ ServiceConnection mServiceConn = new ServiceConnection() {
 };
      -

      In your activity’s {@link android.app.Activity#onCreate onCreate} method, perform the binding by calling the {@link android.content.Context#bindService bindService} method. Pass the method an {@link android.content.Intent} that references the In-app Billing service and an instance of the {@link android.content.ServiceConnection} that you created, and explicitly set the Intent's target package name to com.android.vending — the package name of Google Play app.

      +

      + In your activity’s {@link android.app.Activity#onCreate onCreate} method, + perform the binding by calling the {@link android.content.Context#bindService + bindService} method. Pass the method an {@link android.content.Intent} that + references the In-app Billing service and an instance of the {@link + android.content.ServiceConnection} that you created, and explicitly set the + Intent's target package name to com.android.vending — the + package name of Google Play app. +

      -

      Caution: To protect the security of billing transactions, always make sure to explicitly set the intent's target package name to com.android.vending, using {@link android.content.Intent#setPackage(java.lang.String) setPackage()} as shown in the example below. Setting the package name explicitly ensures that only the Google Play app can handle billing requests from your app, preventing other apps from intercepting those requests.

      +

      + Caution: To protect the security of billing transactions, + always make sure to explicitly set the intent's target package name to + com.android.vending, using {@link + android.content.Intent#setPackage(java.lang.String) setPackage()} as shown in + the example below. Setting the package name explicitly ensures that + only the Google Play app can handle billing requests from your app, + preventing other apps from intercepting those requests. +

      @Override
 public void onCreate(Bundle savedInstanceState) {
@@ -154,8 +226,22 @@ public void onCreate(Bundle savedInstanceState) {
   serviceIntent.setPackage("com.android.vending");
   bindService(serviceIntent, mServiceConn, Context.BIND_AUTO_CREATE);
      -

      You can now use the mService reference to communicate with the Google Play service.

      -

      Important: Remember to unbind from the In-app Billing service when you are done with your {@link android.app.Activity}. If you don’t unbind, the open service connection could cause your device’s performance to degrade. This example shows how to perform the unbind operation on a service connection to In-app Billing called {@code mServiceConn} by overriding the activity’s {@link android.app.Activity#onDestroy onDestroy} method.

      + +

      + You can now use the mService reference to communicate with the Google Play + service. +

      + +

      + Important: Remember to unbind from the In-app Billing + service when you are done with your {@link android.app.Activity}. If you + don’t unbind, the open service connection could cause your device’s + performance to degrade. This example shows how to perform the unbind + operation on a service connection to In-app Billing called {@code + mServiceConn} by overriding the activity’s {@link + android.app.Activity#onDestroy onDestroy} method. +

      + 
       @Override
 public void onDestroy() {
@@ -166,16 +252,37 @@ public void onDestroy() {
 }
      -

      For a complete implementation of a service connection that binds to the {@code IInAppBillingService}, -see the Selling In-app -Products training class and associated sample.

      - +

      + For a complete implementation of a service connection that binds to the + {@code IInAppBillingService}, see the Selling In-app + Products training class and associated sample. +

      Making In-app Billing Requests

      -

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

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

      Querying for Items Available for Purchase

      -

      In your application, you can query the item details from Google Play using the In-app Billing Version 3 API. To pass a request to the In-app Billing service, first create a {@link android.os.Bundle} that contains a String {@link java.util.ArrayList} of product IDs with key "ITEM_ID_LIST", where each string is a product ID for an purchasable item.

      + +

      + In your application, you can query the item details from Google Play using + the In-app Billing Version 3 API. To pass a request to the In-app Billing + service, first create a {@link android.os.Bundle} that contains a String + {@link java.util.ArrayList} of product IDs with key "ITEM_ID_LIST", where + each string is a product ID for an purchasable item. +

      + 
       ArrayList<String> skuList = new ArrayList<String> ();
 skuList.add("premiumUpgrade");
@@ -183,19 +290,51 @@ skuList.add("gas");
 Bundle querySkus = new Bundle();
 querySkus.putStringArrayList(“ITEM_ID_LIST”, skuList);
      -

      To retrieve this information from Google Play, call the {@code getSkuDetails} method on the In-app Billing Version 3 API, and pass the method the In-app Billing API version (“3”), the package name of your calling app, the purchase type (“inapp”), and the {@link android.os.Bundle} that you created.

      + +

      + To retrieve this information from Google Play, call the {@code getSkuDetails} + method on the In-app Billing Version 3 API, and pass the method the In-app + Billing API version (“3”), the package name of your calling app, the purchase + type (“inapp”), and the {@link android.os.Bundle} that you created. +

      + 
       Bundle skuDetails = mService.getSkuDetails(3,
    getPackageName(), "inapp", querySkus);
      -

      If the request is successful, the returned {@link android.os.Bundle}has a response code of {@code BILLING_RESPONSE_RESULT_OK} (0).

      -

      Warning: Do not call the {@code getSkuDetails} method on the main thread. Calling this method triggers a network request which could block your main thread. Instead, create a separate thread and call the {@code getSkuDetails} method from inside that thread.

      -

      To see all the possible response codes from Google Play, see In-app Billing Reference.

      +

      + If the request is successful, the returned {@link android.os.Bundle}has a + response code of {@code BILLING_RESPONSE_RESULT_OK} (0). +

      -

      The query results are stored in a String ArrayList with key {@code DETAILS_LIST}. The purchase information is stored in the String in JSON format. To see the types of product detail information that are returned, see In-app Billing Reference.

      +

      + Warning: Do not call the {@code getSkuDetails} method on the + main thread. Calling this method triggers a network request which could block + your main thread. Instead, create a separate thread and call the {@code + getSkuDetails} method from inside that thread. +

      + +

      + To see all the possible response codes from Google Play, see In-app + Billing Reference. +

      + +

      + The query results are stored in a String ArrayList with key {@code + DETAILS_LIST}. The purchase information is stored in the String in JSON + format. To see the types of product detail information that are returned, see + In-app + Billing Reference. +

      + +

      + In this example, you are retrieving the prices for your in-app items from the + skuDetails {@link android.os.Bundle} returned from the previous code snippet. +

      -

      In this example, you are retrieving the prices for your in-app items from the skuDetails {@link android.os.Bundle} returned from the previous code snippet.

       int response = skuDetails.getInt("RESPONSE_CODE");
 if (response == 0) {
@@ -213,28 +352,66 @@ if (response == 0) {

      Purchasing an Item

      -

      To start a purchase request from your app, call the {@code getBuyIntent} method on the In-app Billing service. Pass in to the method the In-app Billing API version (“3”), the package name of your calling app, the product ID for the item to purchase, the purchase type (“inapp” or "subs"), and a {@code developerPayload} String. The {@code developerPayload} String is used to specify any additional arguments that you want Google Play to send back along with the purchase information.

      +

      + To start a purchase request from your app, call the {@code getBuyIntent} + method on the In-app Billing service. Pass in to the method the In-app + Billing API version (“3”), the package name of your calling app, the product + ID for the item to purchase, the purchase type (“inapp” or "subs"), and a + {@code developerPayload} String. The {@code developerPayload} String is used + to specify any additional arguments that you want Google Play to send back + along with the purchase information. +

       Bundle buyIntentBundle = mService.getBuyIntent(3, getPackageName(),
    sku, "inapp", "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ");
      +

      -If the request is successful, the returned {@link android.os.Bundle} has a response code of {@code BILLING_RESPONSE_RESULT_OK} (0) and a {@link android.app.PendingIntent} that you can use to start the purchase flow. To see all the possible response codes from Google Play, see In-app Billing Reference. Next, extract a {@link android.app.PendingIntent} from the response {@link android.os.Bundle} with key {@code BUY_INTENT}. + If the request is successful, the returned {@link android.os.Bundle} has a + response code of {@code BILLING_RESPONSE_RESULT_OK} (0) and a {@link + android.app.PendingIntent} that you can use to start the purchase flow. To + see all the possible response codes from Google Play, see In-app + Billing Reference. Next, extract a {@link android.app.PendingIntent} from + the response {@link android.os.Bundle} with key {@code BUY_INTENT}.

      + 
       PendingIntent pendingIntent = buyIntentBundle.getParcelable("BUY_INTENT");
      +

      -To complete the purchase transaction, call the {@link android.app.Activity#startIntentSenderForResult startIntentSenderForResult} method and use the {@link android.app.PendingIntent} that you created. In this example, you are using an arbitrary value of 1001 for the request code.

      + To complete the purchase transaction, call the {@link + android.app.Activity#startIntentSenderForResult startIntentSenderForResult} + method and use the {@link android.app.PendingIntent} that you created. In + this example, you are using an arbitrary value of 1001 for the request code. +

      + 
       startIntentSenderForResult(pendingIntent.getIntentSender(),
    1001, new Intent(), Integer.valueOf(0), Integer.valueOf(0),
    Integer.valueOf(0));
      -

      Google Play sends a response to your {@link android.app.PendingIntent} to the {@link android.app.Activity#onActivityResult onActivityResult} method of your application. The {@link android.app.Activity#onActivityResult onActivityResult} method will have a result code of {@code Activity.RESULT_OK} (1) or {@code Activity.RESULT_CANCELED} (0). To see the types of order information that is returned in the response {@link android.content.Intent}, see In-app Billing Reference.

      -

      The purchase data for the order is a String in JSON format that is mapped to the {@code INAPP_PURCHASE_DATA} key in the response {@link android.content.Intent}, for example: +

      + Google Play sends a response to your {@link android.app.PendingIntent} to the + {@link android.app.Activity#onActivityResult onActivityResult} method of your + application. The {@link android.app.Activity#onActivityResult + onActivityResult} method will have a result code of {@code + Activity.RESULT_OK} (1) or {@code Activity.RESULT_CANCELED} (0). To see the + types of order information that is returned in the response {@link + android.content.Intent}, see In-app + Billing Reference. +

      + +

      + The purchase data for the order is a String in JSON format that is mapped to + the {@code INAPP_PURCHASE_DATA} key in the response {@link + android.content.Intent}, for example: +

      + 
       '{
    "orderId":"GPA.1234-5678-9012-34567",
@@ -246,17 +423,22 @@ startIntentSenderForResult(pendingIntent.getIntentSender(),
    "purchaseToken":"opaque-token-up-to-1000-characters"
  }'
      + +

      + Note: Google Play generates a token for the purchase. This + token is an opaque character sequence that may be up to 1,000 characters + long. Pass this entire token to other methods, such as when you consume the + purchase, as described in Consume + a Purchase. Do not abbreviate or truncate this token; you must save and + return the entire token.

      -

      Note: Google Play generates a token for the -purchase. This token is an opaque character sequence that may be up to 1,000 -characters long. Pass this entire token to other methods, such as when you -consume the purchase, as described in -Consume -a Purchase. Do not abbreviate or truncate this token; you must save and -return the entire token.

      +

      + Continuing from the previous example, you get the response code, purchase + data, and signature from the response {@link android.content.Intent}. +

      -

      Continuing from the previous example, you get the response code, purchase data, and signature from the response {@link android.content.Intent}.

       @Override
 protected void onActivityResult(int requestCode, int resultCode, Intent data) {
@@ -280,16 +462,55 @@ protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    }
 }
      -

      Security Recommendation: When you send a purchase request, create a String token that uniquely identifies this purchase request and include this token in the {@code developerPayload}.You can use a randomly generated string as the token. 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. For added security, you should perform the checking on your own secure server. Make sure to 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.

      + +

      + Security Recommendation: When you send a purchase request, + create a String token that uniquely identifies this purchase request and + include this token in the {@code developerPayload}.You can use a randomly + generated string as the token. 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. For added security, you + should perform the checking on your own secure server. Make sure to 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. +

      Querying for Purchased Items

      -

      To retrieve information about purchases made by a user from your app, call the {@code getPurchases} method on the In-app Billing Version 3 service. Pass in to the method the In-app Billing API version (“3”), the package name of your calling app, and the purchase type (“inapp” or "subs").

      + +

      + To retrieve information about purchases made by a user from your app, call + the {@code getPurchases} method on the In-app Billing Version 3 service. Pass + in to the method the In-app Billing API version (“3”), the package name of + your calling app, and the purchase type (“inapp” or "subs"). +

      + 
       Bundle ownedItems = mService.getPurchases(3, getPackageName(), "inapp", null);
      -

      The Google Play service returns only the purchases made by the user account that is currently logged in to the device. If the request is successful, the returned {@link android.os.Bundle} has a response code of 0. The response {@link android.os.Bundle} also contains a list of the product IDs, a list of the order details for each purchase, and the signatures for each purchase.

      -

      To improve performance, the In-app Billing service returns only up to 700 products that are owned by the user when {@code getPurchase} is first called. If the user owns a large number of products, Google Play includes a String token mapped to the key {@code INAPP_CONTINUATION_TOKEN} in the response {@link android.os.Bundle} to indicate that more products can be retrieved. Your application can then make a subsequent {@code getPurchases} call, and pass in this token as an argument. Google Play continues to return a continuation token in the response {@link android.os.Bundle} until all products that are owned by the user has been sent to your app.

      -

      For more information about the data returned by {@code getPurchases}, see In-app Billing Reference. The following example shows how you can retrieve this data from the response. + +

      + The Google Play service returns only the purchases made by the user account + that is currently logged in to the device. If the request is successful, the + returned {@link android.os.Bundle} has a response code of 0. The response + {@link android.os.Bundle} also contains a list of the product IDs, a list of + the order details for each purchase, and the signatures for each purchase. +

      + +

      + To improve performance, the In-app Billing service returns only up to 700 + products that are owned by the user when {@code getPurchase} is first called. + If the user owns a large number of products, Google Play includes a String + token mapped to the key {@code INAPP_CONTINUATION_TOKEN} in the response + {@link android.os.Bundle} to indicate that more products can be retrieved. + Your application can then make a subsequent {@code getPurchases} call, and + pass in this token as an argument. Google Play continues to return a + continuation token in the response {@link android.os.Bundle} until all + products that are owned by the user has been sent to your app. +

      + +

      For more information about the data returned by {@code getPurchases}, see In-app Billing Reference. The following example shows how you can retrieve this data from the response.

      + 
       int response = ownedItems.getInt("RESPONSE_CODE");
 if (response == 0) {
@@ -302,7 +523,7 @@ if (response == 0) {
    String continuationToken =
       ownedItems.getString("INAPP_CONTINUATION_TOKEN");
 
-   for (int i = 0; i < purchaseDataList.size(); ++i) {
+   for (int i = 0; i < purchaseDataList.size(); ++i) {
       String purchaseData = purchaseDataList.get(i);
       String signature = signatureList.get(i);
       String sku = ownedSkus.get(i);
@@ -314,43 +535,76 @@ if (response == 0) {
    // if continuationToken != null, call getPurchases again
    // and pass in the token to retrieve more items
 }
-
      +

      Consuming a Purchase

      -

      You can use the In-app Billing Version 3 API to track the ownership of -purchased in-app products in Google Play. Once an in-app product is purchased, -it is considered to be "owned" and cannot be purchased from Google Play. You -must send a consumption request for the in-app product before Google Play makes -it available for purchase again.

      -

      Important: Managed in-app products are -consumable, but subscriptions are not.

      -

      How you use the consumption mechanism in your app is up to you. Typically, -you would implement consumption for in-app products with temporary benefits that -users may want to purchase multiple times (for example, in-game currency or -equipment). You would typically not want to implement consumption for in-app -products that are purchased once and provide a permanent effect (for example, -a premium upgrade).

      -

      To record a purchase consumption, send the {@code consumePurchase} method to -the In-app Billing service and pass in the {@code purchaseToken} String value -that identifies the purchase to be removed. The {@code purchaseToken} is part -of the data returned in the {@code INAPP_PURCHASE_DATA} String by the Google -Play service following a successful purchase request. In this example, you are -recording the consumption of a product that is identified with the -{@code purchaseToken} in the {@code token} variable.

      + +

      + You can use the In-app Billing Version 3 API to track the ownership of + purchased in-app products in Google Play. Once an in-app product is + purchased, it is considered to be "owned" and cannot be purchased from Google + Play. You must send a consumption request for the in-app product before + Google Play makes it available for purchase again. +

      + +

      + Important: Managed in-app products are consumable, but + subscriptions are not. +

      + +

      + How you use the consumption mechanism in your app is up to you. Typically, + you would implement consumption for in-app products with temporary benefits + that users may want to purchase multiple times (for example, in-game currency + or equipment). You would typically not want to implement consumption for + in-app products that are purchased once and provide a permanent effect (for + example, a premium upgrade). +

      + +

      + To record a purchase consumption, send the {@code consumePurchase} method to + the In-app Billing service and pass in the {@code purchaseToken} String value + that identifies the purchase to be removed. The {@code purchaseToken} is part + of the data returned in the {@code INAPP_PURCHASE_DATA} String by the Google + Play service following a successful purchase request. In this example, you + are recording the consumption of a product that is identified with the {@code + purchaseToken} in the {@code token} variable. +

      + 
       int response = mService.consumePurchase(3, getPackageName(), token);
      -

      Warning: Do not call the {@code consumePurchase} method on the main thread. Calling this method triggers a network request which could block your main thread. Instead, create a separate thread and call the {@code consumePurchase} method from inside that thread.

      -

      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.

      -

      Security Recommendation: 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.

      + +

      + Warning: Do not call the {@code consumePurchase} method on + the main thread. Calling this method triggers a network request which could + block your main thread. Instead, create a separate thread and call the {@code + consumePurchase} method from inside that thread. +

      + +

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

      + +

      + Security Recommendation: 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. +

      Implementing Subscriptions

      +

      Launching a purchase flow for a subscription is similar to launching the purchase flow for a product, with the exception that the product type must be set to "subs". The purchase result is delivered to your Activity's {@link android.app.Activity#onActivityResult onActivityResult} method, exactly as in the case of in-app products.

      + 
       Bundle bundle = mService.getBuyIntent(3, "com.example.myapp",
    MY_SKU, "subs", developerPayload);
@@ -363,12 +617,15 @@ if (bundle.getInt(RESPONSE_CODE) == BILLING_RESPONSE_RESULT_OK) {
        Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0));
 }
      +

      To query for active subscriptions, use the {@code getPurchases} method, again with the product type parameter set to "subs".

      + 
       Bundle activeSubs = mService.getPurchases(3, "com.example.myapp",
                    "subs", continueToken);
      +

      The call returns a {@code Bundle} with all the active subscriptions owned by the user. Once a subscription expires without renewal, it will no longer appear in the returned {@code Bundle}.

      @@ -383,7 +640,7 @@ Developer Console generates an RSA key pair for each application.

      Note:To find the public key portion of this key pair, open your application's details in the Developer Console, then click on -Services & APIs, and look at the field titled +Services & APIs, and look at the field titled Your License Key for This Application.

      The Base64-encoded RSA public key generated by Google Play is in binary @@ -400,12 +657,3 @@ verification on that server.

      For more information about best practices for security and design, see Security and Design.

      - - - - - - - - -