diff --git a/docs/html/google/google_toc.cs b/docs/html/google/google_toc.cs index b6e26e35333e0..b2051d15074ba 100644 --- a/docs/html/google/google_toc.cs +++ b/docs/html/google/google_toc.cs @@ -45,32 +45,47 @@ +
  • Google Play In-app Billing
    • @@ -86,11 +101,9 @@
  • Multiple APK Support
    • -
  • APK Expansion Files
    • -
  • Application Licensing diff --git a/docs/html/google/play/billing/api.jd b/docs/html/google/play/billing/api.jd new file mode 100644 index 0000000000000..9091f511469a1 --- /dev/null +++ b/docs/html/google/play/billing/api.jd @@ -0,0 +1,116 @@ +page.title=In-app Billing Version 3 +parent.title=In-app Billing +parent.link=index.html +@jd:body + + + +

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

    +

    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

    + + +

    Purchasing Items

    + +
    + +

    + Figure 1. The basic sequence for a purchase request. +

    +
    + +

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

    +

    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.

    +
    + +

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

    + +

    Non-consumable and 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 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.
    +
    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.

    +
    +
    +

    Managing consumable purchases in your application

    +

    Here is the basic flow for purchasing a consumable item:

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

    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:

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

    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.

    + + diff --git a/docs/html/google/play/billing/billing_about.html b/docs/html/google/play/billing/billing_about.html deleted file mode 100644 index 38616e6119f2e..0000000000000 --- a/docs/html/google/play/billing/billing_about.html +++ /dev/null @@ -1,12 +0,0 @@ - - - -Redirecting... - - -

    You should be redirected. Please click -here.

    - - \ No newline at end of file diff --git a/docs/html/google/play/billing/billing_admin.jd b/docs/html/google/play/billing/billing_admin.jd index c0f46d0663a4a..cfa7a3074e320 100755 --- a/docs/html/google/play/billing/billing_admin.jd +++ b/docs/html/google/play/billing/billing_admin.jd @@ -8,78 +8,66 @@ parent.link=index.html

    In this document

    1. Creating a Product List
      2. -
    2. Choosing a Purchase Type
      3. +
    3. Choosing a Product Type
    4. Setting up Test Accounts
    5. Handling Refunds
    6. Working with Order Numbers
    7. Where to Get Support
    -

    Downloads

    -
      -
    1. Sample - Application
      2. +

    See also

    1. Overview of In-app Billing
      2. -
    2. Implementing In-app - Billing
      3. -
    3. Security and - Design
      4. -
    4. Testing In-app - Billing
      5. -
    5. In-app Billing - Reference

    In-app billing frees you from processing financial transactions, but you still need to perform a -few administrative tasks, including setting up and maintaining your product list on the publisher -site, registering test accounts, and handling refunds when necessary.

    +few administrative tasks, including setting up and maintaining your product list on the Google Play +Developer Console, registering test accounts, and handling refunds when necessary.

    You must have a Google Play publisher account to register test accounts. And you must have a Google Checkout merchant account to create a product list and issue refunds to your users. If you already have a publisher account on Google Play, you can use your existing account. You do not -need to register for a new account to support in-app billing. If you do not have a publisher -account, you can register as a Google Play developer and set up a publisher account at the -Google Play publisher site. If you do not have a -Google Checkout merchant account, you can register for one at the + +

    If you do not have a publisher account, you can register as a Google Play +developer and set up a publisher account at the Google Play Developer Console. If you do not +have a Google Checkout merchant account, you can register for one at the Google Checkout site.

    Creating a Product List

    -

    The Google Play publisher site provides a product list for each of your published +

    The Google Play Developer Console provides a product list for each of your published applications. You can sell an item using Google Play's in-app billing feature only if the item is listed on an application's product list. Each application has its own product list; you cannot sell items that are listed in another application's product list.

    You can access an application's product list by clicking the In-App Products -link that appears under each of the applications that are listed for your publisher account (see +link in applications listed in your developer account (see figure 1). The In-App Products link appears only if you have a Google Checkout -merchant account and an application's manifest includes the com.android.vending.BILLING +merchant account and the application's manifest includes the com.android.vending.BILLING permission.

    - -

    - Figure 1. You can access an application's product list by clicking the - In-App Products link. -

    -

    A product list specifies items you are selling in an application — in-app products, subscriptions, or a combination of both. For each item, the product list contains information such as a product id, -product description, and price (see figure 2). The product list stores only metadata about the items +product description, and price. The product list stores only metadata about the items you are selling in your application. It does not store any digital content. You are responsible for storing and delivering the digital content that you sell in your applications.

    - -

    - Figure 2. An application's product list. +

    + +

    + Figure 1. You can access an application's product list by clicking the + In-App Products link in the main Apps navigation.

    +

    You can create a product list for any published application or any draft application that's been -uploaded and saved to the Google Play site. However, you must have a Google Checkout merchant +uploaded and saved to the Developer Console. However, you must have a Google Checkout merchant account and the application's manifest must include the com.android.vending.BILLING permission. If an application's manifest does not include this permission, you will be able to edit existing items in the product list but you will not be able to add new items to the list. For more @@ -95,8 +83,8 @@ associated with the application listing. You cannot create individual product li you are using the multiple APK feature.

    You can add items to a product list two ways: you can add items one at a time by using the In-app -Products UI (see figure 3), or you can add a batch of items by importing the items from a -comma-separated values (CSV) file (see figure 2). Adding items one at a time is useful if your +Products UI (see figure 2), or you can add a batch of items by importing the items from a +comma-separated values (CSV) file. Adding items one at a time is useful if your application has only a few in-app items or you are adding only a few items to a product list for testing purposes. The CSV file method is useful if your application has a large number of in-app items.

    @@ -111,16 +99,17 @@ number of in-app items.

  • Log in to your publisher account.
  • In the All Google Play listings panel, under the application name, click In-app Products.
    • -
  • On the In-app Products List page, click Add in-app product.
    • -
  • On the Create New In-app Product page (see figure 3), provide details about the item you are +
  • Click Add new product (see figure 2) and provide details about the item you are selling and then click Save or Publish.
    • - -

    - Figure 3. The Create New In-app Product page lets you add items to an +

    + +

    + Figure 2. The Add New Product page lets you add items to an application's product list.

    +

    You must enter the following information for each item in a product list:

    - -

    - Figure 4. Specifying additional currencies and additional languages for the - item title and description. + +

    + +

    + Figure 3. Specifying additional currencies for an in-app product.

    +

    For more information about product IDs and product lists, see Creating In-App Product +href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1072599">Creating In-App Product IDs. For more information about pricing, see In-App Billing +href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1153485">In-App Billing Pricing.

    Note: Be sure to plan your product ID namespace. You cannot reuse @@ -231,7 +222,7 @@ example, the syntax for the CSV file is as follows:

    published or unpublished.

  • purchase_type -

    This is equivalent to the Purchase Type setting in the In-app Products UI. Can be +

    This is equivalent to the Product Type setting in the In-app Products UI. Can be managed_by_android, which is equivalent to Managed per user account in the In-app Products UI, or managed_by_publisher, which is equivalent to Unmanaged in the In-app Products UI.

    @@ -393,41 +384,18 @@ file. on the In-app Product List page. This is useful if you have manually added items to a product list and you want to start managing the product list through a CSV file.

    -

    Choosing a Purchase Type

    +

    Choosing a Product Type

    -

    An item's purchase type controls how Google Play manages the purchase of the item. There are -two purchase types: "managed per user account" and "unmanaged."

    +

    An item's product type controls how Google Play manages the purchase of the item. There are +several product types, including "managed per user account", "unmanaged," and "subscription." However, +note that the product types supported vary +across In-app Billing Version, so you should always choose a product type that's valid for the +version of In-app BIlling that your app uses.

    -

    Items that are managed per user account can be purchased only once per user account. When an item -is managed per user account, Google Play permanently stores the transaction information for each -item on a per-user basis. This enables you to query Google Play with the -RESTORE_TRANSACTIONS request and restore the state of the items a specific user has -purchased.

    - -

    If a user attempts to purchase a managed item that has already been purchased, Google Play -displays an "Item already purchased" error. This occurs during checkout, when Google Play -displays the price and description information on the checkout page. When the user dismisses the -error message, the checkout page disappears and the user returns to your user interface. As a best -practice, your application should prevent the user from seeing this error. The sample application -demonstrates how you can do this by keeping track of items that are managed and already purchased -and not allowing users to select those items from the list. Your application should do something -similar—either graying out the item or hiding it so that it cannot be selected.

    - -

    The "manage by user account" purchase type is useful if you are selling items such as game levels -or application features. These items are not transient and usually need to be restored whenever a -user reinstalls your application, wipes the data on their device, or installs your application on a -new device.

    - -

    Items that are unmanaged do not have their transaction information stored on Google Play, -which means you cannot query Google Play to retrieve transaction information for items whose -purchase type is listed as unmanaged. You are responsible for managing the transaction information -of unmanaged items. Also, unmanaged items can be purchased multiple times as far as Google Play -is concerned, so it's also up to you to control how many times an unmanaged item can be -purchased.

    - -

    The "unmanaged" purchase type is useful if you are selling consumable items, such as fuel or -magic spells. These items are consumed within your application and are usually purchased multiple -times.

    +

    For details, refer to the documentation for In-app Billing Version +3 or In-app +Billing Version 2.

    Handling Refunds

    @@ -436,13 +404,13 @@ in-app purchases must be directed to you (the application developer). You can th refund through your Google Checkout merchant account. When you do this, Google Play receives a refund notification from Google Checkout, and Google Play sends a refund message to your application. For more information, see Handling +href="{@docRoot}google/play/billing/v2/api.html#billing-action-notify">Handling IN_APP_NOTIFY messages and In-app Billing +href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1153485">In-app Billing Pricing.

    Important: You cannot use the Google Checkout API to issue -refunds or cancel in-app billing transactions. You must do this manually through your Google +refunds or cancel In-app Billing transactions. You must do this manually through your Google Checkout merchant account. However, you can use the Google Checkout API to retrieve order information.

    @@ -478,13 +446,13 @@ Google Order Number:

    Setting Up Test Accounts

    -

    The Google Play publisher site lets you set up one or more test accounts. A test account is a -regular Google account that you register on the publisher site as a test account. Test accounts are +

    The Google Play Developer Console lets you set up one or more test accounts. A test account is a +regular Google account that you register on the Developer Console as a test account. Test accounts are authorized to make in-app purchases from applications that you have uploaded to the Google Play -site but have not yet published.

    +Developer Console but have not yet published.

    You can use any Google account as a test account. Test accounts are useful if you want to let -multiple people test in-app billing on applications without giving them access to your publisher +multiple people test In-app Billing on applications without giving them access to your publisher account's sign-in credentials. If you want to own and control the test accounts, you can create the accounts yourself and distribute the credentials to your developers or testers.

    @@ -503,28 +471,39 @@ accounts yourself and distribute the credentials to your developers or testers.<
    1. Log in to your publisher account.
      2. -
    2. On the upper left part of the page, under your name, click Edit profile.
      3. -
    3. On the Edit Profile page, scroll down to the Licensing & In-app Billing panel (see figure - 5).
      4. -
    4. In Test Accounts, add the email addresses for the test accounts you want to register, +
    5. Click the Settings icon. (If you are using the old Developer Console UI, click + Edit profile in the upper left part of the page, under your name,)
      6. +
    6. Locate the License Testing panel. (In the old UI, scroll down to the Licensing & In-app Billing panel.)
      7. +
    7. Add the email addresses for the test accounts you want to register, separating each account with a comma.
    8. Click Save to save your profile changes.
    - -

    - Figure 5. The Licensing and In-app Billing panel of your account's Edit Profile - page lets you register test accounts. +

    Getting an app's license key

    + +

    The Google Play Developer Console provides a public licensing key for each app. To get the key for an app, +load the app's publishing details in the Developer Console and click the Settings icon. The key +for the app is available for copy/paste in License Key for this Application field, as shown in the figure below.

    + +

    Previously, the Developer Console provided a single public key per developer account. To transition apps to the +new per-app public key, the Developer Console set the app-specific key as the former developer key. This ensures +compatibility for apps that depend on the (former) developer key.

    + +
    + +

    + Figure 4. You can find the license key for each app in the Services & APIs panel.

    +

    Where to Get Support

    -

    If you have questions or encounter problems while implementing in-app billing, contact the +

    If you have questions or encounter problems while implementing In-app Billing, contact the support resources listed in the following table (see table 2). By directing your queries to the correct forum, you can get the support you need more quickly.

    Table 2. Developer support resources -for Google Play in-app billing.

    +for Google Play In-app Billing.

    @@ -549,7 +528,7 @@ android - +
    Billing issue tracker Billing project issue trackerBug and issue reports related specifically to in-app billing sample code.Bug and issue reports related specifically to In-app Billing sample code.
    diff --git a/docs/html/google/play/billing/billing_best_practices.jd b/docs/html/google/play/billing/billing_best_practices.jd index dbf10574a2cf9..015e7c3d63c25 100755 --- a/docs/html/google/play/billing/billing_best_practices.jd +++ b/docs/html/google/play/billing/billing_best_practices.jd @@ -7,42 +7,40 @@ parent.link=index.html -

    As you design your in-app billing implementation, be sure to follow the security and design +

    As you design your In-app Billing implementation, be sure to follow the security and design guidelines that are discussed in this document. These guidelines are recommended best practices for -anyone who is using Google Play's in-app billing service.

    +anyone who is using Google Play's In-app Billing service.

    Security Best Practices

    -

    Perform signature verification tasks on a server

    +

    Perform signature verification tasks on a server

    If practical, you should perform signature verification on a remote server and not on a device. Implementing the verification process on a server makes it difficult for attackers to break the verification process by reverse engineering your .apk file. If you do offload security processing to a remote server, be sure that the device-server handshake is secure.

    -

    Protect your unlocked content

    +

    Protect your unlocked content

    To prevent malicious users from redistributing your unlocked content, do not bundle it in your .apk file. Instead, do one of the following: