diff --git a/docs/html/google/google_toc.cs b/docs/html/google/google_toc.cs index 8b09fe62d5c50..81982a130e65e 100644 --- a/docs/html/google/google_toc.cs +++ b/docs/html/google/google_toc.cs @@ -80,6 +80,9 @@ Reference +
  • + Subscriptions +
  • Security and Design
    • diff --git a/docs/html/google/play/billing/api.jd b/docs/html/google/play/billing/api.jd index 9091f511469a1..3d467150991f6 100644 --- a/docs/html/google/play/billing/api.jd +++ b/docs/html/google/play/billing/api.jd @@ -11,12 +11,13 @@ parent.link=index.html
  • Product Types
    1. Managed In-app Products
    2. +
    3. Subscriptions
  • Purchasing Items
    • -
  • Consuming Items +
  • Consuming In-app Products
      -
    1. Non-consumable and Consumable Items
    2. +
    3. Non-consumable and Consumable In-app Products
    5. Managing Consumable Purchases
    • @@ -40,11 +41,22 @@ parent.link=index.html

    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 only supports the managed in-app product type.

    +href="{@docRoot}google/play/billing/billing_admin.html">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

    +

    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.

    Purchasing Items

    @@ -72,29 +84,38 @@ href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Bil

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

    -

    Consuming Items

    -

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

    +

    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.

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

    +

    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 Items

    +

    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.

    Non-consumable Items
    -
    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.
    +
    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 item in your application, you must send a consumption request to Google Play and receive a successful response indicating that the consumption was recorded.

    +

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

    +

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

    1. Launch a purchase flow with a {@code getBuyIntent} call
    2. Get a response {@code Bundle}from Google Play indicating if the purchase completed successfully.
      3. @@ -102,10 +123,10 @@ href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Bil
    3. Get a response code from Google Play indicating if the consumption completed successfully.
    4. 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 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:

    +

    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 items for the user.
      2. -
    2. 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.
      3. +
    3. Send a {@code getPurchases} request to query the owned in-app products for the user.
      4. +
    4. 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.
    5. Get a response code from Google Play indicating if the consumption completed successfully.
    6. If the consumption was successful, provision the product in your application.
    diff --git a/docs/html/google/play/billing/billing_integrate.jd b/docs/html/google/play/billing/billing_integrate.jd index 315befa51cfdc..297e90604db17 100755 --- a/docs/html/google/play/billing/billing_integrate.jd +++ b/docs/html/google/play/billing/billing_integrate.jd @@ -16,6 +16,7 @@ parent.link=index.html
  • Purchasing an Item
  • Querying Purchased Items
  • Consuming a Purchase
  • +
  • Implementing Subscriptions
    • @@ -176,7 +177,7 @@ 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”), 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(),
@@ -238,7 +239,7 @@ 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.
    
 
 
    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”).
    
+
    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);
 
    
@@ -273,8 +274,26 @@ if (response == 0) {

    Consuming a Purchase

    -

    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 from Google Play. 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 equipment). You would typically not want to implement consumption for 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);
    @@ -282,6 +301,33 @@ int response = mService.consumePurchase(3, getPackageName(), token);

    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);
+
+PendingIntent pendingIntent = bundle.getParcelable(RESPONSE_BUY_INTENT);
+if (bundle.getInt(RESPONSE_CODE) == BILLING_RESPONSE_RESULT_OK) {
+   // Start purchase flow (this brings up the Google Play UI).
+   // Result will be delivered through onActivityResult().
+   startIntentSenderForResult(pendingIntent, RC_BUY, new Intent(),
+       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}.

    diff --git a/docs/html/google/play/billing/billing_overview.jd b/docs/html/google/play/billing/billing_overview.jd index aa48fc8195f7c..bda9237774baa 100755 --- a/docs/html/google/play/billing/billing_overview.jd +++ b/docs/html/google/play/billing/billing_overview.jd @@ -7,9 +7,12 @@ parent.link=index.html

    Quickview

    In this document

      @@ -21,14 +24,12 @@ parent.link=index.html
    1. Google Play Developer Console
    2. Google Play Purchase Flow
      3. -
    3. Sample Apps
      4. +
    4. Sample App
    5. Migration Considerations

    Related Samples

    1. Sample Application (V3)
      2. -
    2. Sample - Application (V2)
    @@ -51,10 +52,12 @@ the Google Play server.

    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.

    -

    Currently, Google Play supports two versions of the In-app Billing API. -To determine which version you should use, see Migration -Considerations.

    -

    Version 3 (recommended)

    +

    In-app billing Version 3 is the latest version, and maintains 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 (a vast majority of active devices).

    + +

    Version 3 features

    -

    Version 2

    - -

    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 -Version Notes for -more details.

    +

    For details about other versions of In-app Billing, see the +Version Notes.

    In-app Products

    In-app products are the digital goods that you offer for sale from inside your @@ -102,12 +94,9 @@ published for another app, even if they are from the same developer.

    how you monetize your application. In all cases, you define your products using the Google Play Developer Console.

    You can specify these types of products for your In-app Billing application -— managed in-app products, subscriptions, and unmanaged -in-app products. 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.

    -

    To learn more about the product types supported by the different API versions, -see the related documentation for Version 2 and Version 3.

    +— managed in-app products and subscriptions. Google Play +handles and tracks ownership for in-app products and subscriptions on your +application on a per user account basis. Learn more about the product types supported by In-app Billing Version 3.

    Google Play Developer Console

    The Developer Console is where you can publish your @@ -148,70 +137,31 @@ providing the checkout user interface (middle screen). When checkout is complete, the application resumes.

    -

    Sample Applications

    +

    Sample Application

    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 +provides a sample application that demonstrates how to sell in-app products and subscriptions from inside an app.

    -
    -
    TrivialDrive sample for the Version 3 API
    -
    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.
    +

    The TrivialDrive sample for the Version 3 API sample shows how to use the In-app Billing Version 3 API +to implement in-app product and subscription 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.

    -
    Dungeons sample for the Version 2 API
    -
    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.
    -
    -

    Important: It's strongly recommended -that you obfuscate the code in your application before you publish it. For -more information, see +

    Recommendation: Make sure to obfuscate the +code in your application before you publish it. For more information, see Security and Design.

    Migration Considerations

    -

    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 Version 2 or -earlier API to the Version 3 API.

    -

    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.

    -

    You can use the following table to decide which version of the API to use, -depending on the needs of your application.

    -

    - Table 1. Selecting the In-app Billing API Version for Your -Project

    +

    If you have an existing In-app Billing implementation that uses Version 2 or +earlier, it is strongly recommended that you migrate to In-app Billing Version 3 at your earliest convenience.

    - - - - - - - - - -
    Choose Version 3 if ...Choose Version 2 if ...
    -
      -
    • You want to sell in-app products only (and not subscriptions)
      • -
    • You need synchronous order confirmations when purchases complete
      • -
    • You need to synchronously restore a user's current purchases
      • -
    -    		 -
      -
    • You want to sell subscriptions in your app
      • -
    -

    If you have published apps selling in-app products, note that:

    In-app Billing version 3

    -

    December 2012

    +

    February 2013

    In-app Billing version 2

    diff --git a/docs/html/images/in-app-billing/v3/billing_subscription_v3.png b/docs/html/images/in-app-billing/v3/billing_subscription_v3.png new file mode 100644 index 0000000000000..0ba472e91d068 Binary files /dev/null and b/docs/html/images/in-app-billing/v3/billing_subscription_v3.png differ