In-app Billing バージョン3

In-app Billing バージョン3APIはあなたの開発したアプリケーションにIn-app Billingを組み込むことをさらに容易にしている。このバージョンの特徴は改善された同期決済フローを組み込んでいる点だ。APIは消費アイテムやin-app決済データのローカルキャッシュの所有権を追尾することを容易にする。

商品タイプ

あなたは自分の商品をGoogle Play Developer Consoleを使用することで定義を行う。商品には商品タイプ、SKU、価格、商品説明などが含まれる。さらなる情報はIn-app Billingの管理を参照。バージョン3APIはマネージドのin-app商品と定期購入をサポートしている。

マネージドIn-app商品

マネージドin-app商品はGoogle Playによって所有権情報が追尾され、管理されるアイテムのことを指す。ユーザーがマネージドin-appアイテムを購入するとき、Google Playはユーザーごとの各アイテムに対する決済情報を保存する。これは特定のユーザーが決済を行ったアイテムの状態を復元するために、あなたがあとでいつでもGoogle Playに問い合わせができるようにする。例えユーザーがアプリをアンインストールしたりデバイスを変えたとしても、この情報はGoogle Playサーバーに永続化される。

もしあなたがバージョン3APIを使っているならば、あなたは開発したアプリの中でマネージドアイテムも消費することができる。あなたは何回も消費できるような(ゲーム内通貨、燃料、魔法の呪文など)アイテムの消費に対する一般的な実装をするだろう。一度決済がされると、Google Playに消費リクエストを送ることによりあなたがそのアイテムを消費するまでは、マネージドアイテムはは再び購入することはできない。さらにin-app商品消費に関して学びたければ消費アイテムを参照。

定期購入

定期購入はIn-app Billingで提供されている商品タイプだ。この商品タイプはあなたの開発したアプリ内で、あなたがコンテンツ、サービス、機能を月ごと、または年ごとに売ることができるようにするものだ。あなたは定期購入をほぼあらゆるタイプのデジタルコンテンツをあらゆるタイプのアプリやゲームから定期販売することができる。どのように定期購入が機能するか理解したい場合はIn-app Billing定期購入を参照。

バージョン3APIで、定期購入販売や定期決済情報の回収に際し、あなたはin-app商品と同じ決済フローを使うことができる。コーディング例を見たい方は定期購入実装を参照。

重要：in-app商品と違い、定期購入は消費することができない。

決済アイテム

バージョン3APIに関する典型的な決済フローは以下のとおり。

1.あなたのアプリケーションはisBillingSupportedリクエストをGoogle Playに送る。それはあなたの使っているIn-app Billing APIのバージョンがサポートされているのかを確認するために行う。

2.あなたのアプリケーションの開始時、もしくはユーザーのログイン時にユーザーがどんなアイテムを所持しているのかを決定するために、Google Playに確認をするのは良い対処法である。ユーザーのin-app決済を問い合わせるためには、getPurchasesリクエストを送ればよい。もしリクエストが成功した場合はGoogle PlayはBundleを返す。Bundleには決済アイテムの商品ID一覧、個別の商品詳細一覧、それら決済のsignature一覧が含まれる。

3.大抵の場合、あなたは決済可能な商品をユーザーに知らせたいはずだ。あなたがGoogle Playで定義したin-app商品の詳細を問い合わせるには、あなたのアプリケーションはgetSkuDetailsリクエストを送れば良い。あなたは問い合わせリクエストの中で商品ID一覧を記載しなければならない。もしリクエストが成功した場合、Google PlayはBundleを返す。このBundleは商品価格、タイトル、詳細説明、決済タイプを含んだ商品詳細が含まれている。

4.もしin-app商品をユーザーが所持していない場合、あなたはin-app商品の決済を開始することができる。決済リクエストを開始するには、あなたのアプリケーションはgetBuyIntentリクエストを送る。そこには他のパラメーターに加え、決済アイテムの商品IDも規定する。あなたはDeveloper Consoleで新たなin-app商品を作る場合には商品IDを記録しておいたほうがよい。

a.Google PlayはPendingIntentを含んだBundleを返す。PendingIntentは決済の精算UIを開始する際にあなたのアプリケーションが使用するものである。

b.あなたのアプリケーションはstartIntentSenderForResultメソッドを呼び出すことで、未決済の目的を始める。

c.精算フローが完了した際には(これはユーザーがアイテムの決済に成功したか、もしくは決済をキャンセルした場合)、Google PlayはあなたのonActivityResultメソッドに対してIntentレスポンスを送る。onActivityResultの結果コードは決済が成功したのかキャンセルされたのかを示す。Intentレスポンスは決済アイテムに関する情報を含んでいる。この決済アイテムは、決済トランザクションを一意に規定するためにGoogle Playによって生成されたpurchaseToken文字列を含んでいる。Intentはあなたのprivate developer keyでサインされた決済signatureも含んでいる。

バージョン3APIコールとサーバーレスポンスに関してより知りたい方はIn-app Billing レファレンスを参照。

In-app商品の消費

あなたはin-app商品のユーザー所有権を追尾するための消費メカニズムを使うことができる。

バージョン3では、すべてのin-app商品はマネージドである。このマネージドの意味はすべてのin-appアイテム決済のユーザー所有権はGoogle Playによって管理され、あなたのアプリは必要なときにユーザー決済情報の問い合せができるという意味である。ユーザーがin-app商品の決済に成功したときは、その決済はGoogle Playに記録される。一度in-app商品が決済されると、"owned(所有している)"とみなされる。owned状態のin-app商品はGoogle Playで決済することができない。あなたはownedのin-app商品に対して消費リクエストを送らなければならない。そうすればGoogle Playはその商品を再び決済可能にすることができる。in-app商品を消費すると、"unowned(非所有)"状態に変わり、前の決済データは廃棄される。

ユーザーによって所有された商品リストを取り出すためにはあなたのアプリケーションはgetPurchasesコールをGoogle Playに送る。あなたのアプリケーションはconsumePurchaseコールを送ることによって消費リクエストを生成することができる。リクエストの引数には、あなたはin-app商品にユニークなpurchaseToken文字列を入れなければならない。この文字列は決済された時にGoogle Playから得られるものだ。Google Playは消費が正しく記録されたかどうかを示すステータスコードを返す。

非消費と消費in-app商品

あなたが自分のin-app商品を非消費アイテムとして扱うか消費アイテムとして扱うかを決めるのはあなた次第だ。

非消費アイテム
基本的にあなたはin-app商品に関する消費の実装をしなくてよい。この商品はあなたのアプリケーション内で一度だけ決済ができる、永久的に便益を提供する。一度決済されたら、これらのアイテムは永久的にそのユーザーのGoogleアカウントに紐づく。非消費in-appアイテムの例はプレミアムアップグレードやレベルパックだ。

消費アイテム
対照的に、あなたは複数回消費ができるようにアイテムに関する実装を行う。基本的にこれらのアイテムはある一時的な効果をもたらす。例えば、ユーザーのゲーム内キャラクターがライフポイントやゲーム内商品のコインを得ることが該当する。あなたのアプリ内で決済したアイテムの便益や効果を消費することをin-app商品のプロビジョニングと呼ぶ。あなたはin-app商品がどのようにユーザーにプロビジョンされたかを追跡し、管理を行う責任がある。

重要：あなたのアプリ内で消費可能なin-app商品をプロビジョニング剃る前に、あなたはGoogle Playに消費リクエストを送らなければならない。また、消費が記録されたことを示す成功レスポンスを受け取らなければならない。

あなたのアプリケーション内で消費可能な商品を管理する

ここでは消費可能なin-app商品の決済に関する基本フローに関して記載をする。

1.getBuyIntentコールで決済フローを立ち上げる
2.Google Playから決済が成功したかどうかを示すレスポンスBundleを受け取る
3.もし決済が成功していたら、consumePurchaseコールを生成することで決済を消費する
4.消費が成功したかどうかを示すGoogle Playからのレスポンスコードを受け取る
5.もし消費が成功していたら、あなたのアプリ内で商品をプロビジョニングする

その後、ユーザーがあなたのアプリを始める、もしくはログインした際に、あなたはユーザーが未処理の消費可能なin-app商品を所有していないかどうかをチェックする必要がある。もし未処理のものがあった場合、それらのアイテムの消費とプロビジョニングを確実にすること。以下があなたが自分のアプリ内で消費可能なin-app商品を実装した際の、推奨されるアプリケーション開始フローである。

1.ユーザーが所有しているin-app商品を問い合わせるために、getPurchaseリクエストを送る
2.もし消費可能なin-app商品があった場合、consumePurchaseコールを送り、アイテムを消費する。このステップは必須である。なぜなら、アプリケーションが消費可能アイテムに関する決済オーダーを完了させたが、アプリケーションが消費リクエストを送る前にアプリが停まるか接続が切れてしまうことがあるからだ。
3.消費が成功したかどうかを示すGoogle Playからのレスポンスコードを受け取る
4.消費が成功した場合、商品のプロビジョニングをアプリ内で行う

ローカルキャッシング

Google Playクライアントは現在、デバイス内でIn-app Billing情報をキャッシュしているので、あなたはバージョン3APIをこれらの情報をより頻繁に問い合わせるために使用することができる。例えばgetPurchasesコールを通してなど。前のバージョンのAPIとは違い、多くのバージョン3APIコールはGoogle Playへのネットワーク接続を通す代わりにキャッシュ参照を通してサービスを行う。このことで、APIの応答時間は劇的に向上している。

In-app Billing Version 3

Topics

Reference

In-app Billing Reference (V3)

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.

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

Figure 1. The basic sequence for a purchase request.

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

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

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

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

Launch a purchase flow with a getBuyIntent call
Get a response Bundlefrom Google Play indicating if the purchase completed successfully.
If the purchase was successful, consume the purchase by making a consumePurchase call.
Get a response code from Google Play indicating if the consumption completed successfully.
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:

Send a getPurchases request to query the owned in-app products for the user.
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.
Get a response code from Google Play indicating if the consumption completed successfully.
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 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.

システム・プログラム関連メモ

2013年5月29日水曜日

Google Play In-app Billingを訳してみる「In-app Billing Version 3」