2014/08/22

Android:In-app Billing Version3

Introduction

AndroidではGoogle Playサービスを利用してアプリ内課金を比較的容易に導入できます.
本稿ではビジネス戦略の1つ”アプリ内課金”にフォーカスしたAndroid Developers | In-app Billing Version 3を翻訳し, In-app Billing Ver.3 APIについて学びます.

In-app Billing Version 3

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.

In-app Billing Ver.3 APIを使うことでアプリ内課金の仕組みをアプリに組み込めます.
このバージョンでは, 過去Verから更に改善された購入フロー, 商品所有情報を追跡するAPI, アプリ内課金情報のローカルキャッシュ機能が含まれる.

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.

Google Play Developer Consoleで定義した商品には, 商品種別, SKU, 価格等が含まれる.
より詳細な情報はAdministering In-app Billingを参照.
Ver.3 APIはアプリ内商品の管理と定期購読をサポートする.

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.

Google Playはユーザが購入した商品の所有情報を追跡する.
商品を購入すると, ユーザ毎の購入情報が記録される.
これにより, 特定ユーザの購入履歴から商品の所有状態をいつでも復元できる.
この情報はGoogle Playサーバに保管されており, アプリのアンインストールや端末変更でも引き続き利用(復元)できる.

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

Ver.3 APIを使用すると, 商品の消費についても管理できる.
商品の消費は複数回購入できる商品(ゲーム内通貨, ポーション, 魔法の書など)で実装されるのが一般的.
一度商品を購入すると, Google Playに消費リクエストを送信して商品を消費するまで同じ商品は購入できなくなる.
商品の消費についてより詳細な情報は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.

定期購読はアプリ内のコンテンツ, サービス, または機能を毎月or毎年定期的に購読(課金)させる支払い形態の一種である.
アプリやゲームからデジタルコンテンツを定期購読販売できる.

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.

Ver.3 APIでは定期購読の購入に同じ支払いフローを使用し, アプリ内商品と同じように定期購読の購入履歴から復元できる.
コードのサンプルはImplementing Subscriptionsを参照.

Important: Google Playで管理されない商品や定期購読は対象外.

Purchasing Items

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

Ver.3 APIを使用した購入フロー:

The basic sequence for a purchase request.
[The basic sequence for a purchase request.]

  1. Your application sends a isBillingSupported request to Google Play to determine that the target version of the In-app Billing API that you are using is supported.
  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 getPurchases request. If the request is successful, Google Play returns a 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. 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 getSkuDetails request. You must specify a list of product IDs in the query request. If the request is successful, Google Play returns a Bundle containing product details including the product’s price, title, description, and the purchase type.
  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 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 Bundle that contains a PendingIntent which you application uses to start the checkout UI for the purchase.
    2. Your application launches the pending intent by calling the startIntentSenderForResult method.
    3. When the checkout flow finishes (that is, the user successfully purchases the item or cancels the purchase), Google Play sends a response Intent to your onActivityResult method. The result code of the onActivityResult has a result code that indicates whether the purchase was successful or canceled. The response Intent contains information about the purchased item, including a purchaseToken String that is generated by Google Play to uniquely identify this purchase transaction. The Intent also contains the signature of the purchase, signed with your private developer key.

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

  1. 使用するIn-app Billing APIのバージョンがサポートされているかGoogle Playに問い合わせる(isBillingSupported)
  2. ユーザの購入情報を取得(getPurchases)する.
    購入情報はBundleに詰めて返され, 商品ID, 購入詳細, 購入署名それぞれがリストで返される.
    購入情報を取得するタイミングとしてアプリ起動時やログイン時を推奨する.
  3. ユーザに商品を訴求するために商品詳細を取得(getSkuDetails)する.
    取得リクエストには商品IDを指定する.
    商品詳細はBundleに詰めて返され, 商品価格, タイトル, 説明, 購入種別が含まれる.
  4. ユーザが商品を所有していない場合に購入フローを開始(getBuyIntent)できる. パラメータには商品IDを指定する. Developer Consoleで作成した商品のIDは記録しておくこと.
    1. getBuyIntentで返却されるBundleには購入手続きを開始するためのPendingIntentが含まれている.
    2. アプリはstartIntentSenderForResultメソッドを呼び出してIntent起動する.
    3. 支払いフローが完了(購入完了 or 購入キャンセル)するとGoogle Playは購入結果をIntentに詰めてonActivityResultメソッドを呼ぶ.
      onActivityResultの結果コードは購入の成功/失敗を示す. Intentには購入情報(商品情報や購入トランザクションを一意に識別するpurchaseTokenの文字列)が含まれる.
      Intentには開発者の秘密鍵で署名された購入証明書も含まれる.

Ver.3 APIとサーバレスポンスについてのより詳細な情報は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.

ユーザの商品所持状態を追跡するために, 消費メカニズムを使用する.

Ver.3ではGoogle Playによって全ての商品や購入情報が管理されており, 必要に応じてこれらの情報を問い合わせることができる. ユーザの購入情報はGoogle Playに記録される.
一度商品を購入し”所持状態”になると, 消費リクエストをGoogle Playに送信するまで同じ商品を購入することはできない. 商品が消費されると”未所持状態”に戻り, 以前の購入データは破棄される.

The basic sequence for a consumption request.
[The basic sequence for a consumption request.]

To retrieve the list of product’s owned by the user, your application sends a getPurchases call to Google Play. Your application can make a consumption request by sending a consumePurchase call. In the request argument, you must specify the in-app product’s unique 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.

ユーザが所持する商品リストを取得するにはgetPurchasesメソッドを, 商品を消費するにはconsumePurchaseメソッドを呼び出す. メソッド引数には商品の購入完了時にGoogle Playから払い出される商品の識別文字列purchaseTokenを指定する.

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 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.
非消費系の商品
非消費系の商品は, 一度購入すれば永続的に効果が持続するため通常選択されない.
一度購入された非消費系の商品は購入ユーザのGoogleアカウントに紐づく. 実装されるケースとしてはアプリのプレミアムアップグレードやレベルパックのような商品に適用できる.
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.
消費系の商品
非消費系の商品とは対照的に, 消費系の商品は同じ商品を複数回購入できるように消費を実装します.
消費系商品の効果は通常一時的なものになる. 例えば, ゲームのポーションや課金によるゲーム内通貨の追加など.
購入商品の利益や効果を分配することを商品の供給と呼ぶ. 開発者は商品がユーザに供給されているかを追跡し制御する責務を負う.
Important: アプリで消費系商品を供給する前に, 必ず消費リクエストをGoogle Playに投げて消費リクエストの成功(消費が正しく記録されたことも意味する)を受け取ること.

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 getBuyIntent call
  2. Get a response Bundle from Google Play indicating if the purchase completed successfully.
  3. If the purchase was successful, consume the purchase by making a consumePurchase call.
  4. Get a response code from Google Play indicating if the consumption completed successfully.
  5. If the consumption was successful, provision the product in your application.

消費系商品を購入する基本フロー:

  1. getBuyIntentを呼び出し, 購入基本フローを開始する
  2. 購入が成功するとGoogle Playからレスポンスを受け取りBundleを取得する
  3. 購入が完了したらconsumePurchaseで商品を消費する
  4. 消費が完了したかどうかを示すレスポンスコードを取得する
  5. 消費が成功したならば, 商品を供給する

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 getPurchases request to query the owned in-app products for the user.
  2. If there are any consumable in-app products, consume the items by calling 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. 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.
  1. getPurchasesリクエストを送り, ユーザが所有する商品を問い合わせる
  2. 消費系の商品があったならば, consumePurchaseで商品を消費する. このステップは商品を購入したにも関わらず消費処理が未完了となっている可能性に備えて必要となる.
  3. Google Playから消費リクエストの成功レスポンスを受け取る
  4. 消費リクエストが成功していたならば商品の共有を行う

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

Ver.3 APIを使用している場合, Google Playクライアントはアプリ内課金の情報をデバイスローカルにキャッシュしている. これにより, getPurchasesなど情報の問い合わせ速度がネットワーク接続を必要としないため, 過去APIバージョンより格段に応答速度が改善し, 問い合わせの頻度を多くすることを可能とする.

License:
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.