In-app Billingバージョン2は取って代わられている。都合がつく限り早く、バージョン3に移行してください。
In-app Billingバージョン2はGoogle Play In-app Billingの旧バージョンである。バージョン3のようにこのバージョンはあなたにGoogle Play決済フローと相互作用をさせ、決済システムを非直接的に行い、IPCを使うことでデバイスがインストールされたPlay Storeアプリと相互作用をするようになっている。
バージョン3と違うのは、バージョン2のAPIは非同期で、送信目的として送られたサービスメッセージを使用している点である。だからバージョン3よりも込み入っている。
バージョン2は非マネージドもマネージド商品もサポートしている。これは定期購入のサポートも同様である。この点に関して、バージョン3はまだ定期購入に対してサポートを提供していない。もしあなたがアプリ内で定期購入を売りたい場合、あなたはバージョン3よりもむしろIn-app Billingバージョン2を実装するべきである。
もしあなたが定期購入を売る必要がない場合は、あなたはIn-app Billingバージョン3を代わりに実装するべきである。
商品タイプ
In-app Billing バージョンは3つの異なる商品タイプをサポートしている。これはあなたにアプリを監視する方法に関して柔軟性を与えるためである。すべてのケースにおいて、あなたはGoogle Playデベロッパーコンソールを使って商品を定義する。定義には商品タイプ、SKU、価格、詳細説明などが含まれている。より詳細を知りたい人はAdministering in-app Billingを参照。
・ユーザーアカウントごとのマネージ-アイテムはGoogle Play上のユーザーアカウントごとに一度のみ決済される。"managed per user account"商品タイプを使用しているアイテムをユーザーが決済する際、Google Playはユーザーごとの各々のアイテムのトランザクション情報を永久的に保存する。これはあなたがあとでGoogle Playに対して特定のユーザーが決済したアイテムの情報を回復するための問い合わせを行うことを可能にする。もしユーザーが既に決済したマネージドアイテムを決済しようとした場合、Google Playはそのユーザーが再びアイテムを購入することを防ぐことができ、"Item already puchased"エラーを表示する。
あなたがゲームレベルやアプリ機能などのアイテムを売る際に、"managed"商品タイプは便利である。これらのアイテムは一時的なものではなく、通常アプリを再インストールする際、デバイスからデータを消去する際、そして新たなデバイスにあなたのアプリをインストールする際には保存しておく必要があるからである。
・非マネージド-Google Play上でトランザクション情報を保存していないアイテムのことである。この意味は、これらのアイテムに対するトランザクション情報を取り出すためにGoogle Playに問い合わせをあとで行うことができないということである。"unmanaged"決済に対しては、あなたはトランザクション情報を管理する責任がある。その上、もし"unmanaged"商品タイプを使った場合、Google Playはユーザーが複数回商品の購入をすることを防ごうとはしない。非マネージドアイテムが何回決済されたかを管理するのはあなた次第である。
あなたが燃料や魔法の呪文などのような消費アイテムを売りたい場合、"unmanaged"商品タイプは便利である。これらのアイテムはあなたのアプリ内で消費され、通常何度も購入する。
・定期購入-デベロッパーが定義した決済間隔ごとに販売をするアイテムである。ユーザーが定期購入決済を行った場合、Google Playとその決済処理は特定の間隔と金額でユーザーアカウントに対して請求がされる。元となる決済メソッドに対し金額を請求しながらそれは行われる。一度ユーザーが定期購入の決済を行うと、Google Playはアカウントに対し無期限に請求をし続ける。ユーザーからの承認やアクションを要求することなしに。ユーザーは定期購入をいつでも取りやめることができる。
定期購入は"managed per user account"決済タイプを使用することによってのみ販売することができる。in-app商品と同様、一度ユーザーがin-app商品を購入すると払い戻しウィンドウは表示されない。払い戻しを希望するユーザーはデベロッパーと直接連絡をしなければならない。定期購入やあなたのアプリでこの商品をどうやって売ればよいかに関する詳細を知りたい方はSubscriptionsドキュメントを参照。
サービス設計
あなたのアプリはAPIを用いることでIn-app Billingサービスにアクセスする。そのAPIはデバイス上でインストールされたGoogle Playアプリによって露出しているものである。Google PlayアプリはあなたのアプリとGoogle Playサーバー間の決済リクエストとレスポンスを通信するために非同期のメッセージループを用いる。実際にはあなたのアプリはGoogle Playサーバーと直にやり取りは決して行わない(図1参照)。その代わり、あなたのアプリは精算リクエストをプロセス間通信(IPC)を通じてGoogle Playアプリに対して送り、Google Playアプリから非同期ブロードキャスト目的の形で決済レスポンスを受け取る。あなたのアプリはアプリ自身とGoogle Playサーバー間のネットワーク接続を管理しないせず、アンドロイドプラットフォームからの特別なAPI群を使用する。
いくつかのin-app精算実装はコンテントを届けたり、トランザクションをバリデートするためにプライベートリモートサーバーを使用するかもしれない。しかし、リモートサーバーはin-appの実装の際に必要ではない。もしあなたがメディアファイルや画像のようなユーザーデバイスに届ける必要があるデジタルコンテンツを得る場合にはリモートサーバーは有用である。署名のバリデーションのような様々なin-app精算のセキュリティタスクに対して何か実施をしたり、ユーザーのトランザクション履歴を保存するためにもリモートサーバーを使うかもしれない。あなたがアプリ内ですべてのセキュリティ関連のタスクをコントロールしたとしても、これらのタスクをリモートサーバー上で行うことが推奨される。なぜならリモートサーバー上でセキュリティタスクを行うことで、あなたのアプリに対するセキュリティ攻撃に対する脆弱性を弱めることができるからである。
基本的なin-app精算実装は3つのコンポーネントに頼っている。
・Service(サンプルアプリでBillingServiceと名付けられている)、これはアプリからの決済メッセージを処理し、Google Play in-app精算サービスに精算リクエストを送る
・BroadcastReceiver(サンプルアプリでBillingReceiverと名付けられている)、これはGoogle Playアプリケーションからのすべての非同期精算レスポンスを受け取る
・セキュリティコンポーネント(サンプルアプリでSecurityと名付けられている)、これは署名照合やnonce生成などのセキュリティ関連タスクを実行する
あなたはin-app精算をサポートする2つの他のコンポーネントも組み込みたいかも知れない
・レスポンスHandler(サンプルアプリでResponseHandlerと名付けられている)、これは決済の通知、エラー、その他のステータスメッセージのアプリ固有の処理を提供する
これらのコンポーネントに加え、あなたのアプリケーションはユーザーの決済情報を保存する方法と、決済アイテムをユーザーに選択させるためのある種のユーザーインターフェースを提供しなければならない。あなたは精算インターフェースを提供する必要はない。ユーザーがin-app決済を初期化させたとき、Google Playアプリケーションがユーザーに精算インターフェースを提供するからである。ユーザーが精算プロセスを完了した際には、あなたのアプリが再開される。
In-app精算メッセージ
ユーザーが決済を初期化した際に、あなたのアプリはGoogle Playのin-app精算サービス(MarketBillingServiceと名付けられている)に対してシンプルなIPCメソッドコールを利用した精算メッセージを送る。Google Playアプリケーションはすべての精算リクエストを同期的にステータス通知やその他の情報をアプリに提供しながら反応をする。Google Playアプリケーションはいくつかの精算リクエストに関しては非同期的に反応をしている。あなたのアプリに対してエラーメッセージや詳細トランザクション情報を提供しながら。後続のセクションは基本的なレスポンスメッセージについて記載をしている。そのメッセージはあなたのアプリとGoogle Playアプリ間で起きるものである。
In-app 精算リクエスト
あなたのアプリはシングルIPCメソッド(sendBillingRequest())を呼び出すことでin-app精算リクエストを送っている。このメソッドはMarketBillingServiceインターフェースによって露出されている。このインターフェースはアンドロイドインターフェース定義言語ファイル(IMarketBillingService.aidl)内で定義されている。あなたはこのAIDLファイルをin-app精算サンプルアプリとともにダウンロードできる。
sendBillingRequestメソッドは単体バンドルパラメーターを持っている。あなたが送るバンドルはいくつかのkey-valueペアを含まなければならない。このペアはリクエストの様々なパラメーターで規定される。例えばあなたが生成した精算リクエストタイプ、決済したアイテムやそのタイプ、リクエストを作成したアプリケーションなどである。リクエストとともに送られるバンドルキーに関するさらなる情報を知りたい場合は、in-app Billing Service Interfaceを参照。
すべてのリクエストバンドルが持たなければならない最も重要なキーの一つはBILLING_REQUESTキーである。このキーはあなたに自分の作った精算リクエストタイプを規定させている。Google Playのin-app精算サービスは次の5つの生産リクエストタイプをサポートしている。
・CHECK_BILLING_SUPPORTED
このリクエストはGoogle Playアプリケーションがin-app精算をサポートしているかどうかを照合する。あなたのアプリがはじめて立ち上がった際に通常このリクエストは送られる。このリクエストはin-app精算にのみ関連するあるUI機能を有効にしたり、無効にしたりしたいときに有用である。
・REQUEST_PURCHASE
このリクエストはGoogle Playアプリに決済メッセージを送り、in-app精算の土台となっているものである。ユーザーがあなたのアプリ内でアイテムの決済をしたい事を示したいときにあなたはこのリクエストを送る。Google Playは精算インターフェースを表示することによって金銭トランザクションを管理する。
・GET_PURCHASE_INFOMATION
このリクエストは決済状態の変化の詳細を取り出す。リクエストされた決済が精算に成功したり、ユーザーが清算中にトランザクションをキャンセルした時に決済は状態を変える。これは前の決済が返金された時にも起きる。Google Playは決済が状態を変えたとき、あなたのアプリに通知を送る。だからあなたはトランザクション情報が取り出された時にこのリクエストを送ること飲みが必要とされている。
・CONFIRM_NOTIFICATIONS
このリクエストはあなたのアプリが決済状態の変化の詳細を受け取ったことを応答するものである。Google Playは決済状態の変化通知をあなたのアプリに送る。あなたがそれら通知を受け取ったことを確認するまで。
・RESTORE_TRANSACTION
このリクエストはマネージド決済と定期購入に対するユーザーのトランザクション状態を取り出すものである。あなたはユーザーのトランザクション状態を取り出す必要があるときのみこのリクエストを送るべきである。トランザクション状態は通常、あなたのアプリが再インストールされたとき、もしくはデバイスからはじめてインストールされたときのものである。
In-app精算レスポンス
Google Playアプリケーションはin-app精算リクエストに対して、同期的、非同期的両方のレスポンスを返す。同期的レスポンスは次の3つのキーのバンドルである。
・RESPONSE_CODE
このキーはリクエストに対するステータス情報とエラー情報を与える
・PURCHASE_INTENT
このキーはPendingIntentを与える。PendingIntentはあなたが精算処理を始める際に使う。
・REQUEST_ID
このキーはあなたにリクエスト識別子を与える。リクエスト識別子はあなたがリクエストに対する非同期レスポンスと一致しているか確かめるのに使うことができる。
これらのキーのいくつかはすべてのリクエストに関連しているわけではない。さらなる情報を得たい方はこのドキュメントで後述するMessaging sequenceを参照。
非同期レスポンスメッセージは個別のブロードキャスト目的の形で送られ、下記を含んでいる。
・com.android.vending.billing.RESPONSE_CODE
このレスポンスはGoogle Playサーバーレスポンスコードを含んでおり、また、あなたがin-app精算リクエストを作った後に送られる。サーバーレスポンスコードは精算リクエストがGoogle Playに届くのに成功したこと、もしくは、精算リクエストを送る途中で何かエラーが生じたことを示している。このレスポンスは(返金や決済情報などの)なんらかの決済状態の変化をレポートするのには使われない。レスポンスと共に送られるレスポンスコードに関するさらなる情報を知りたい方は、Server Response Codes for In-app Billingを参照。
・com.android.vending.billing.IN_APP_NOTIFY
このレスポンスは決済が状態変化をしたことを示している。決済の状態変化とは、決済が成功した、キャンセルになった、返金になったということを意味している。このレスポンスはひとつ、またあｈそれ以上の通知IDを含んでいる。各々の通知IDは特定のサーバーサイドメッセージと一致しており、各々のメッセージはひとつ、もしくはそれ以上のトランザクションに関する情報を含んでいる。あなたのアプリがIn_APP_NOTIFYブロードキャスト目的を受け取った後、あなたはメッセージ詳細を取り出すための通知IDとともにGET_PURCHASE_INFORMATIONリクエストを送る。
・com.android.vending.billing.PURCHASE_STATE_CHANGED
このレスポンスはひとつ、またはそれ以上のトランザクションに間s塗る詳細情報を含んでいる。トランザクション情報はJSON文字列を含んでいる。JSON文字列は署名されており、署名は(暗号化されていない)JSON文字列とともにあなたのアプリに送られる。あなたのin-app精算メッセージのセキュリティを確かなものにするために、あなたのアプリはJSON文字列の署名をチェックすることができる。
PURCHASE_STATE_CHANGED目的とともに返されるJSON文字列はあなたのアプリに対して、一つ、もしくはそれ以上の精算トランザクションの詳細を与える。定期購入アイテムに対するJSON文字列の一例は下記に示している。
JSON文字列のフィールドに関するより多くの情報を知りたい方は、In-app Billing Broadcast intentsを参照。
メッセージシーケンス
基本的な決済リクエストに対するメッセージシーケンスは図2で示されている。各々のsendBillingRequest()メソッドに対するリクエストタイプは太字で示されており、ブロードキャスト目的はイタリックで示されている。明確にするために、図2はリクエスト毎に送られるRESPONSE_CODEブロードキャスト目的は示さない。
in-app決済リクエストに対する基本的なメッセージシーケンスは以下のとおり。
1.あなたのアプリケーションは決済リクエスト(REQUEST_PURCHASEタイプ)を送り、プロダクトIDやその他のパラメーターを規定する
2.Google Playアプリケーションはあなたのアプリに次のキーと共にバンドルを送る：RESPONSE_CODE,PURCHASE_INTENT,REQUEST_ID。PURCHASE_INTENTキーはPendingIntentを提供する。PendingIntentはあなたのアプリが与えられたプロダクトIDに対して精算UIを始めるために使うものである。
3.あなたのアプリは未決済の目的を始める。未決済の目的(pending intent)とは精算UIを始めるものである。
ノート：あなたは未決済の目的をアプリケーション文脈からではなく、アクティビティ文脈からはじめなければならない
4.精算フローが完了したとき(これはユーザーがアイテムの決済を完了するか、またはキャンセルしたことを意味する)、Google Playはあなたのアプリに通知メッセージ(IN_APP_NOTIFYブロードキャスト目的)を送る。通知メッセージは通知IDを含んでいる。この通知IDはトランザクションを言及している。
5.あなたのアプリはGET_PURCHASE_STATE_CHANGEDリクエストを送ることによってトランザクション情報のリクエストを送り、トランザクションに対する通知IDを規定する。
6.Google PlayアプリケーションはRESPONSE_CODEキーとREQUEST_IDキーをバンドルとともに送信する。
7.Google PlayはPURCHASE_STATE_CHANGEDブロードキャスト目的内であなたのアプリにトランザクション情報を送る
8.与えられた通知IDに対し、確認メッセージ(CONFIRM_NOTIFICATIONSタイプ)を送ることによってトランザクション情報を取り出すことをあなたのアプリが確認をする。そして、受け取ったトランザクション情報に対して通知IDを規定する
9.Google PlayアプリはあなたのアプリにRESPONSE_CODEキー、REQUEST_IDキーとともにバンドルを送る。
Google Playからトランザクション情報を受け取ったとき、あなたは確認を送らなければならないことを覚えておくこと(図2のステップ8)。もしあなたが確認メッセージを送らないと、Google Playはあなたが確認をしなかったトランザクションに対するIN_APP_NOTIFYメッセージを送り続けることになる。ベストプラクティスとしては、あなたがユーザーに対してアイテムを届けている間は、決済アイテムに対するCONFIRM_NOTIFICATIONリクエストを送るべきである。このようにすれば、あなたのアプリがクラッシュ、または何かあなたのアプリに商品の付与ができない状態になっても、あなたのアプリは、商品付与をする必要があることを示しながらGoogle PlayからIN_APP_NOTIFYブロードキャスト目的を受け取ることになるだろう。その上、ベストプラクティスとして、あなたのアプリは複数注文を含むIN_APP_NOTIFYメッセージを管理することができるに違いない。
復元されたトランザクションリクエストに対するメッセージシーケンスは図3に示されている。各々のsendBillingRequest()メソッドに対するリクエストタイプは太字で示されており、ブロードキャスト目的はイタリックで示されている。明確にするために、図3はリクエスト毎に送られるRESPONSE_CODEブロードキャストインテントは表示していない。
このリクエストは3つのレスポンスのトリガーになる。初めのものは、RESPONSE_CODEキーとREQUEST_IDキーと一緒に戻されるバンドルである。次に、Google PlayアプリケーションはRESPONSE_CODEブロードキャスト目的を送る。これはステータス情報、もしくはリクエストに関するエラー情報を提供するものである。常に、RESPONSE_CODEメッセージは特定のリクエストIDに言及しており、だからあなたはどのリクエストがRESPONSE_CODEメッセージに紐づくのかを特定することができる。
RESTORE_TRANSACTIONSリクエストタイプはPURCHASE_STATE_CHANGEDブロードキャスト目的のトリガーにもなる。これは決済リクエスト中に送られたトランザクション情報が同じタイプも含んでいる。決済リクエストとは異なり、トランザクションは関連する通知IDなしで与えられることができ、あなたはCONFIRM_NOTIFICATIONメッセージと一緒にこの目的に対する反応をする必要がない。
ノート：あなたはRESTORE_TRANSACTIONSリクエストタイプを次の場合にのみ使うべきである。あなたのアプリがデバイス上で初めてインストールされた時か、あなたのアプリがデバイスから削除された後に再インストールされた場合。
in-app精算がサポートされているかどうかをチェックするためのメッセージシーケンスは図4で示されている。sendBillingRequest()メソッドに対するリクエストタイプは太字で示されている。
CHECK_BILLING_SUPPORTEDリクエストに対する動機レスポンスはサーバーレスポンスコードとともにバンドルを与える。RESULT_OKレスポンスコードはin-app精算がサポートされていることを示している。RESULT_BILLING_UNAVAILABLEレスポンスコードはin-app精算は使えないことを示している。その理由としてはあなたの規定しているAPIバージョンが認識されていない、もしくはユーザーがin-app決済を行うのに不適格であるからである(例えば、そのユーザーはin-app精算が許可されていない国に駐在しているとか)。SERVER_ERRORも返され、Google Playサーバーに問題があることを示している。
IN_APP_NOTIFY メッセージを操作する
通常あなたのアプリはREQUEST_PURCHASEメッセージに応えて、Google PlayからIN_APP_NOTIFYブロードキャスト目的を受け取る(図2参照)。IN_APP_NOTIFYブロードキャスト目的はあなたのアプリにリクエストした決済の状態が変わったことを知らせる。決済詳細を取り出すために、あなたのアプリはGET_PURCHASE_INFORMATIONリクエストを送る。Google PlayはPURCHASE_STATE_CHANGEDブロードキャスト目的とともにレスポンスを返す。この目的は決済状態の変更詳細を含んでいる。あなたのアプリはその後CONFIRM_NOTIFICATIONSメッセージを送り、Google Playにあなたが決済状態の変更情報を受け取ったことを知らせる。
いくつかの特別なケースでは、あなたは複数のIN_APP_NOTIFYメッセージを受け取るかもしれない。それが例え決済情報のレシートをあなたが確認していたとしても。または、あなたが決済の初期化を決してしていないとしても、決済変更に対するIN_APP_NOTIFYメッセージを受け取るかもしれない。あなたのアプリはこれら特別なケースの両方を操作しなければならない。
複数のIN_APP_NOTIFYメッセージを操作する
受け取ったPURCHASE_STATE_CHANGEDメッセージに対するCONFIRM_NOTIFICATIONSメッセージをGoogle Playが受け取ったとき、通常はPURCHASE_STATE_CHANGEDメッセージに対するIN_APP_NOTIFY目的を送るのをやめる。しかしときどき、Google PlayはPURCHASE_STATE_CHANGEDメッセージに対するIN_APP_NOTIFY目的を繰り返し送ることがある。それがたとえあなたのアプリがCONFIRM_NOTIFICATIONメッセージを送っていたとしてもである。これは、あなたがCONFIRM_NOTIFICATIONSメッセージを送っている間にデバイスのネットワーク接続が切れてしまった時に起きる。このケースではGoogle PlayはあなたのCONFIRM_NOTIFICATIONSメッセージを受け取ることができず、あなたがトランザクションメッセージを受け取ったことを認識する応答を受け取るまで、複数のIN_APP_NOTIFYメッセージが送られる。それ故、後続のIN_APP_NOTIFYメッセージは前に処理したトランザクションに対するものであることを、あなたのアプリは認識できなければならない。あなたはJSON文字列を含むorderIDをチェックすることでこれを行うことができる。なぜならすべてのトランザクションはユニークなorderIdを持っているからである。
refunds(返金)やその他未承諾のIN_APP_NOTIFYメッセージを操作する
あなたのアプリがREQUEST_PURCHASEメッセージを送っていないにもかかわらず、IN_APP_NOTIFYブロードキャスト目的を受け取る場合には2つのケースがある。図5はこれらのケースの両方に対するメッセージシーケンスを表している。それぞれのsendBillingRequest()メソッドに対するリクエストタイプは太字で示され、ブロードキャスト目的はイタリックで示されている。明確にするために図5はリクエスト毎に送られたRESPONSE_CODEブロードキャスト目的は示していない。
まず最初のケースでは、ユーザーがあなたのアプリを2つ以上のデバイスでインストールして、そのデバイスのうちの一つからin-app決済を行った際に、あなたのアプリはIN_APP_NOTIFYブロードキャスト目的を受け取るかもしれない。このケースでは、Google PlayはIN_APP_NOTIFYメッセージを2番めのデバイスに送り、決済状態が変更されたことをアプリケーションに知らせる。あなたのアプリはこのメッセージをアプリ初期化のREQUEST_PURCHASEメッセージからのレスポンスの操作と同じように操作できる。だから最終的に、あなたのアプリはPURCHASE_STATE_CHANGEDブロードキャスト目的メッセージを受け取る。このメッセージは決済されたアイテムに関する情報を含んでいる。これはユーザーアカウント毎にマネージドされたプロダクトタイプを持ったアイテムにのみ適用される。
次のケースでは、Google PlayがGoogleウォレットから返金通知を受け取った時、あなたのアプリがIN_APP_NOTIFYブロードキャスト目的を受け取ることができる。このケースでは、Google PlayはIN_APP_NOTIFYメッセージをあなたのアプリに送る。あなたのアプリは初期化されたREQUEST_PURCHASEメッセージからレスポンスを操作するのと同じやり方で、このメッセージを操作することができる。最終的にあなたのアプリが返金されたアイテムに関する情報を含むPURCHASE_STATE_CHANGEDメッセージを受け取るように。この返金情報はPURCHASE_STATE_CHANGEDブロードキャスト目的に付随するJSON文字列形式の中に含まれている。さらに、JSON文字列のpurchaseState文字列は2がセットされる。
重要：あなたはGoogleウォレットAPIをin-app精算トランザクションの返金やキャンセルを行うために使用することはできない。あなたはGoogleウォレット商人アカウントを通して手動で行わなければならない。しかしオーダー情報を取り出すためにGoogleウォレットAPIを使うことはできる。
セキュリティコントロール
アプリに対して送られたトランザクション情報の整合性を高めるために、Google PlayはPURCHASE_STATE_CHANGEDブロードキャスト目的の中に含まれるJSON文字列に署名をしている。Google Playは署名を作るためにアプリとひもづけられた秘密鍵を使っている。デベロッパーコンソールはそれぞれのアプリに対してRSAキーペアを生成する。あなたはアプリ発行詳細のデベロッパーコンソールの設定の下、ライセンスキーフィールドの中に、このキーペアの公開鍵部分を見つけることができる。
Google Playが精算レスポンスに署名をしたとき、精算レスポンスには署名済みJSON文字列(非暗号化)と署名が含まれている。あなたのアプリがこの署名済みレスポンスを受け取ったとき、署名の妥当性を確認するために、あなたはRSAキーペアの公開鍵部分を使うことができる。署名の妥当性チェックを行うことによって、あなたは改竄やなりすましが行われたレスポンスを見破ることができる。あなたはアプリの中で署名妥当性チェックを行うことができる。しかし、もしあなたのアプリがセキュアなリモートサーバーとつながっているのであれば、我々は署名の妥当性チェックをそのサーバー上で行うことを推奨する。
In-app精算はGoogle Playから返される決済情報の整合性をチェックするためにnonce(ワンタイムなランダム文字列)も使用する。あなたのアプリはnonceを生成し、GET_PURCHASE_INFOMATIONリクエストとRESTORE_TRANSACTIONSリクエストとともにnonceを送らなければならない。Google Playがリクエストを受け取ると、nonceにトランザクション情報を含んだJSON文字列を付加する。JSON文字列はその後署名され、あなたのアプリに返される。あなたのアプリがJSON文字列を受け取ったとき、あなたはJSON文字列の署名と同様、nonceも妥当性チェックを行う必要がある。
セキュリティと設計に対するベストプラクティスに関するより多くの情報を知りたい場合は、Security and Designを参照。
In-app精算要件と制約
in-app精算を始める前に、下記の要件と制約を再検討しておくこと。
・In-app精算はGoogle Playを通して発行されたアプリ内でのみ実装できる。
・あなたはGoogle Play In-app精算を使うためにGoogleウォレット商人アカウントを持たなければならない。
・In-app精算を使うにはAndroidマーケットアプリのバージョン2.3.4(もしくはそれ以上)が必要。定期購入をサポートするためには、Google Playアプリのバージョン3.5かそれ以上が必要。Android3.0でデバイスを動かすには、MyAppsアプリのバージョン5.0.12(もしくはそれ以上)が必要。
・デバイスがAndroid1.6(API level4)かそれ以上で動いている場合、アプリはin-app精算のみ使用することができる。
・あなたはin-app精算をデジタルコンテンツの販売にのみ使用出来る。あなたは物理的商品、個人サービス、そのた物理的な配送が必要になるなにかを売るためにin-app精算を使うことはできない。
・Google Playはコンテンツ付与のフォームは何も提供しない。あなたは自分のアプリ内で売るデジタルコンテンツの付与の責任を負っている。
・あなたはネットワークに接続されることが決してないデバイス上で、in-app精算を実装することはできない。in-app精算リクエストを完了させるには、デバイスはネットワーク越しにGoogle Playサーバーにアクセスできなければならない。
In-app Billing Version 2
In-app Billing Version 2 is superseded. Please migrate to Version 3 at your earliest convenience.
Unlike Version 3, the Version 2 API is asynchronous and uses service messages sent as broadcast intents, so it is more complicated than Version 3.
Version 2 supports both unmanaged and managed products, as well as supports subscriptions, where Version 3 does not yet offer support for subscriptions. If you want to sell subscriptions in your app, you should implement In-app Billing Version 2, rather than Version 3.
If you do not need to sell subscriptions, you should implement In-app Billing Version 3 instead.
Product Types
In-app Billing Version supports three different product types to give you flexibility in how you monetize your app. In all cases, 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.
- Managed per user account — Items that can be purchased only
once per user account on Google Play. When a user purchases an item that uses
the "managed per user account" product type, Google Play permanently stores the
transaction information for each item on a per-user basis. This enables you to
later query Google Play to 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 prevents the user from purchasing the item again and
displays an "Item already purchased" error.
The "managed" product 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.
- Unmanaged — Items that do not have their transaction
information stored on Google Play. This means that you cannot later query Google
Play to retrieve transaction information for those items. For "unmanaged"
purchases, you are responsible for managing the transaction information. Also,
Google Play does not attempt to prevent the user from purchasing an item
multiple times if it uses the "unmanaged" product type. It's up to you to
control how many times an unmanaged item can be purchased.
The "unmanaged" product 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. - Subscriptions — Items that are sold with a developer-specified, recurring billing interval. When a user purchases a subscription, Google Play and its payment processor automatically bill the user's account at the specified interval and price, charging the amount to the original payment method. Once the user purchases a subscription, Google Play continues billing the account indefinitely, without requiring approval or action from the user. The user can cancel the subscription at any time. Subscriptions can only be sold using the "managed per user account" purchase type. As with in-app products, once the user has purchased an in-app product there is no refund window. Users desiring refunds must contact the developer directly. For more information about subscriptions and how to sell them in your apps, see the Subscriptions document.
Service Architecture
Your app accesses the In-app Billing service using an API that is exposed by the Google Play app installed on the device. The Google Play app then uses an asynchronous message loop to convey billing requests and responses between your application and the Google Play server. In practice, your application never directly communicates with the Google Play server (see figure 1). Instead, your application sends billing requests to the Google Play application over interprocess communication (IPC) and receives purchase responses from the Google Play application in the form of asynchronous broadcast intents. Your application does not manage any network connections between itself and the Google Play server or use any special APIs from the Android platform.
Figure 1. Your application sends and receives billing messages through the
Google Play application, which handles all communication with the Google Play server.
A typical in-app billing implementation relies on three components:
- A
Service(namedBillingServicein the sample application), which processes purchase messages from the application and sends billing requests to the Google Play in-app billing service. - A
BroadcastReceiver(namedBillingReceiverin the sample application), which receives all asynchronous billing responses from the Google Play application. - A security component (named
Securityin the sample application), which performs security-related tasks, such as signature verification and nonce generation. For more information about in-app billing security, see Security controls later in this document.
- A response
Handler(namedResponseHandlerin the sample application), which provides application-specific processing of purchase notifications, errors, and other status messages. - An observer (named
PurchaseObserverin the sample application), which is responsible for sending callbacks to your application so you can update your user interface with purchase information and status.
In-app Billing Messages
When the user initiates a purchase, your application sends billing messages to Google Play's in-app billing service (named
MarketBillingService) using simple IPC method calls. The
Google Play application responds to all billing requests synchronously, providing your
application with status notifications and other information. The Google Play application also
responds to some billing requests asynchronously, providing your application with error messages and
detailed transaction information. The following section describes the basic request-response
messaging that takes place between your application and the Google Play application.In-app billing requests
Your application sends in-app billing requests by invoking a single IPC method (sendBillingRequest()), which is exposed by the MarketBillingService
interface. This interface is defined in an Android Interface Definition Language file
(IMarketBillingService.aidl). You can download this AIDL
file with the in-app billing sample application.The
sendBillingRequest() method has a single Bundle parameter.
The Bundle that you deliver must include several key-value pairs that specify various parameters for
the request, such as the type of billing request you are making, the item that is being purchased and
its type, and the application that is making the request. For more information about the Bundle keys
that are sent with a request, see In-app Billing
Service Interface.
One of the most important keys that every request Bundle must have is the
BILLING_REQUEST key. This key lets you specify the type of billing request you are
making. Google Play's in-app billing service supports the following five types of billing
requests:CHECK_BILLING_SUPPORTEDThis request verifies that the Google Play application supports in-app billing. You usually send this request when your application first starts up. This request is useful if you want to enable or disable certain UI features that are relevant only to in-app billing.
REQUEST_PURCHASEThis request sends a purchase message to the Google Play application and is the foundation of in-app billing. You send this request when a user indicates that he or she wants to purchase an item in your application. Google Play then handles the financial transaction by displaying the checkout user interface.
GET_PURCHASE_INFORMATIONThis request retrieves the details of a purchase state change. A purchase changes state when a requested purchase is billed successfully or when a user cancels a transaction during checkout. It can also occur when a previous purchase is refunded. Google Play notifies your application when a purchase changes state, so you only need to send this request when there is transaction information to retrieve.
CONFIRM_NOTIFICATIONSThis request acknowledges that your application received the details of a purchase state change. Google Play sends purchase state change notifications to your application until you confirm that you received them.
RESTORE_TRANSACTIONSThis request retrieves a user's transaction status for managed purchases and subscriptions. You should send this request only when you need to retrieve a user's transaction status, which is usually only when your application is reinstalled or installed for the first time on a device.
In-app Billing Responses
The Google Play application responds to in-app billing requests with both synchronous and asynchronous responses. The synchronous response is aBundle with the following
three keys:RESPONSE_CODEThis key provides status information and error information about a request.
PURCHASE_INTENTThis key provides aPendingIntent, which you use to launch the checkout activity.
REQUEST_IDThis key provides you with a request identifier, which you can use to match asynchronous responses with requests.
The asynchronous response messages are sent in the form of individual broadcast intents and include the following:
com.android.vending.billing.RESPONSE_CODEThis response contains a Google Play server response code, and is sent after you make an in-app billing request. A server response code can indicate that a billing request was successfully sent to Google Play or it can indicate that some error occurred during a billing request. This response is not used to report any purchase state changes (such as refund or purchase information). For more information about the response codes that are sent with this response, see Server Response Codes for In-app Billing.
com.android.vending.billing.IN_APP_NOTIFYThis response indicates that a purchase has changed state, which means a purchase succeeded, was canceled, or was refunded. This response contains one or more notification IDs. Each notification ID corresponds to a specific server-side message, and each messages contains information about one or more transactions. After your application receives anIN_APP_NOTIFYbroadcast intent, you send aGET_PURCHASE_INFORMATIONrequest with the notification IDs to retrieve message details.
com.android.vending.billing.PURCHASE_STATE_CHANGEDThis response contains detailed information about one or more transactions. The transaction information is contained in a JSON string. The JSON string is signed and the signature is sent to your application along with the JSON string (unencrypted). To help ensure the security of your in-app billing messages, your application can verify the signature of this JSON string.
PURCHASE_STATE_CHANGED intent provides
your application with the details of one or more billing transactions. An example of this JSON
string for a subscription item is shown below:{ "nonce" : 1836535032137741465,
"orders" :
[{ "notificationId" : "android.test.purchased",
"orderId" : "transactionId.android.test.purchased",
"packageName" : "com.example.dungeons",
"productId" : "android.test.purchased",
"developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ",
"purchaseTime" : 1290114783411,
"purchaseState" : 0,
"purchaseToken" : "rojeslcdyyiapnqcynkjyyjh" }]
}
For more information about the fields in this JSON string, see In-app Billing
Broadcast Intents.Messaging sequence
The messaging sequence for a typical purchase request is shown in figure 2. Request types for eachsendBillingRequest() method are shown in bold, broadcast intents
are shown in italic. For clarity, figure 2 does not show the RESPONSE_CODE
broadcast intents that are sent for every request.The basic message sequence for an in-app purchase request is as follows:
- Your application sends a purchase request (
REQUEST_PURCHASEtype), specifying a product ID and other parameters. - The Google Play application sends your application a Bundle with the following keys:
RESPONSE_CODE,PURCHASE_INTENT, andREQUEST_ID. ThePURCHASE_INTENTkey provides aPendingIntent, which your application uses to start the checkout UI for the given product ID. - Your application launches the pending intent, which launches the checkout UI.
Note: You must launch the pending intent from an activity context and not an application context.
- When the checkout flow finishes (that is, the user successfully purchases the item or cancels
the purchase), Google Play sends your application a notification message (an
IN_APP_NOTIFYbroadcast intent). The notification message includes a notification ID, which references the transaction. - Your application requests the transaction information by sending a
GET_PURCHASE_STATE_CHANGEDrequest, specifying the notification ID for the transaction. - The Google Play application sends a Bundle with a
RESPONSE_CODEkey and aREQUEST_IDkey. - Google Play sends the transaction information to your application in a
PURCHASE_STATE_CHANGEDbroadcast intent. - Your application confirms that you received the transaction information for the given
notification ID by sending a confirmation message (
CONFIRM_NOTIFICATIONStype), specifying the notification ID for which you received transaction information. - The Google Play application sends your application a Bundle with a
RESPONSE_CODEkey and aREQUEST_IDkey.
Figure 2. Message sequence for a purchase request.
Keep in mind, you must send a confirmation when you receive transaction information from Google
Play (step 8 in figure 2). If you don't send a confirmation message, Google Play will
continue sending IN_APP_NOTIFY messages for the transactions you have not
confirmed. As a best practice, you should not send a CONFIRM_NOTIFICATIONS request for
a purchased item until you have delivered the item to the user. This way, if your application
crashes or something else prevents your application from delivering the product, your application
will still receive an IN_APP_NOTIFY broadcast intent from Google Play indicating
that you need to deliver the product. Also, as a best practice, your application must be able to
handle IN_APP_NOTIFY messages that contain multiple orders.The messaging sequence for a restore transaction request is shown in figure 3. Request types for each
sendBillingRequest() method are shown in bold, broadcast intents
are shown in italic. For clarity, figure 3 does not show the RESPONSE_CODE
broadcast intents that are sent for every request.
Figure 3. Message sequence for a restore transactions request.
Bundle with a
RESPONSE_CODE key and a REQUEST_ID key. Next, the Google Play
application sends a RESPONSE_CODE broadcast intent, which provides status information
or error information about the request. As always, the RESPONSE_CODE message references
a specific request ID, so you can determine which request a RESPONSE_CODE message
pertains to.The
RESTORE_TRANSACTIONS request type also triggers a
PURCHASE_STATE_CHANGED broadcast intent, which contains the same type of transaction
information that is sent during a purchase request. Unlike with a purchase request, however, the transactions
are given without any associated notification IDs, so you do not need to respond to this
intent with a CONFIRM_NOTIFICATIONS message.
Note: You should use the
The messaging sequence for checking whether in-app billing is supported is shown in figure 4. The
request type for the RESTORE_TRANSACTIONS request
type only when your application is installed for the first time on a device or when your
application has been removed from a device and reinstalled.sendBillingRequest() method is shown in bold.
Figure 4. Message sequence for checking whether in-app billing is supported.
CHECK_BILLING_SUPPORTED request provides a Bundle
with a server response code. A RESULT_OK response code indicates that in-app billing
is supported; a RESULT_BILLING_UNAVAILABLE response code indicates that in-app billing
is unavailable because the API version you specified is unrecognized or the user is not eligible to
make in-app purchases (for example, the user resides in a country that does not allow in-app
billing). A SERVER_ERROR can also be returned, indicating that there was a problem with
the Google Play server.Handling IN_APP_NOTIFY messages
Usually, your application receives anIN_APP_NOTIFY broadcast intent from Google
Play in response to a REQUEST_PURCHASE message (see figure 2). The
IN_APP_NOTIFY broadcast intent informs your application that the state of a requested
purchase has changed. To retrieve the details of that purchase, your application sends a
GET_PURCHASE_INFORMATION request. Google Play responds with a
PURCHASE_STATE_CHANGED broadcast intent, which contains the details of the purchase
state change. Your application then sends a CONFIRM_NOTIFICATIONS message, informing
Google Play that you have received the purchase state change information.In some special cases, you may receive multiple
IN_APP_NOTIFY messages even though
you have confirmed receipt of the purchase information, or you may receive
IN_APP_NOTIFY messages for a purchase change even though you never initiated the
purchase. Your application must handle both of these special cases.Handling multiple IN_APP_NOTIFY messages
When Google Play receives aCONFIRM_NOTIFICATIONS message for a given
PURCHASE_STATE_CHANGED message, it usually stops sending IN_APP_NOTIFY
intents for that PURCHASE_STATE_CHANGED message. Sometimes, however, Google
Play may send repeated IN_APP_NOTIFY intents for a
PURCHASE_STATE_CHANGED message even though your application has sent a
CONFIRM_NOTIFICATIONS message. This can occur if a device loses network connectivity
while you are sending the CONFIRM_NOTIFICATIONS message. In this case, Google Play
might not receive your CONFIRM_NOTIFICATIONS message and it could send multiple
IN_APP_NOTIFY messages until it receives acknowledgement that you received the
transaction message. Therefore, your application must be able to recognize that the subsequent
IN_APP_NOTIFY messages are for a previously processed transaction. You can do this by
checking the orderID that's contained in the JSON string because every transaction has
a unique orderId.Handling refunds and other unsolicited IN_APP_NOTIFY messages
There are two cases where your application may receiveIN_APP_NOTIFY broadcast
intents even though your application has not sent a REQUEST_PURCHASE message. Figure 5
shows the messaging sequence for both of these cases. Request types for each
sendBillingRequest() method are shown in bold, broadcast intents are
shown in italic. For clarity, figure 5 does not show the RESPONSE_CODE
broadcast intents that are sent for every request.
Figure 5. Message sequence for refunds and other unsolicited
IN_APP_NOTIFY messages.
IN_APP_NOTIFY broadcast intent
when a user has your application installed on two (or more) devices and the user makes an in-app
purchase from one of the devices. In this case, Google Play sends an IN_APP_NOTIFY
message to the second device, informing the application that there is a purchase state change. Your
application can handle this message the same way it handles the response from an
application-initiated REQUEST_PURCHASE message, so that ultimately your application
receives a PURCHASE_STATE_CHANGED broadcast intent message that includes information
about the item that has been purchased. This applies only to items that have their product type
set to "managed per user account."In the second case, your application can receive an
IN_APP_NOTIFY broadcast intent
when Google Play receives a refund notification from Google Wallet. In this case, Google
Play sends an IN_APP_NOTIFY message to your application. Your application can handle
this message the same way it handles responses from an application-initiated
REQUEST_PURCHASE message so that ultimately your application receives a
PURCHASE_STATE_CHANGED message that includes information about the item that has been
refunded. The refund information is included in the JSON string that accompanies the
PURCHASE_STATE_CHANGED broadcast intent. Also, the purchaseState field in
the JSON string is set to 2.
Important: You cannot use the Google Wallet API to
issue refunds or cancel in-app billing transactions. You must do this manually through your
Google Wallet merchant account. However, you can use the Google Wallet API to retrieve order
information.
Security Controls
To help ensure the integrity of the transaction information that is sent to your application, Google Play signs the JSON string that is contained in the
PURCHASE_STATE_CHANGED
broadcast intent. Google Play uses the private key that is associated with the app to create
this signature. The Developer Console generates an RSA key pair for each app.
You can find the public key portion of this key pair in the app's publishing details
in the Developer Console, under Settings, in the License Key field.When Google Play signs a billing response, it includes the signed JSON string (unencrypted) and the signature. When your application receives this signed response you can use the public key portion of your RSA key pair to verify the signature. By performing signature verification you can help detect responses that have been tampered with or that have been spoofed. You can perform this signature verification step in your application; however, if your application connects to a secure remote server then we recommend that you perform the signature verification on that server.
In-app billing also uses nonces (a random number used once) to help verify the integrity of the purchase information that's returned from Google Play. Your application must generate a nonce and send it with a
GET_PURCHASE_INFORMATION request and a RESTORE_TRANSACTIONS
request. When Google Play receives the request, it adds the nonce to the JSON string that
contains the transaction information. The JSON string is then signed and returned to your
application. When your application receives the JSON string, you need to verify the nonce as well as
the signature of the JSON string.For more information about best practices for security and design, see Security and Design.
In-app Billing Requirements and Limitations
Before you get started with in-app billing, be sure to review the following requirements and limitations.
- In-app billing can be implemented only in applications that you publish through Google Play.
- You must have a Google Wallet Merchant account to use Google Play In-app Billing.
- In-app billing requires version 2.3.4 (or higher) of the Android Market application. To support subscriptions, version 3.5 or higher of the Google Play app is required. On devices running Android 3.0, version 5.0.12 (or higher) of the MyApps application is required.
- An application can use in-app billing only if the device is running Android 1.6 (API level 4) or higher.
- You can use in-app billing to sell only digital content. You cannot use in-app billing to sell physical goods, personal services, or anything that requires physical delivery.
- Google Play does not provide any form of content delivery. You are responsible for delivering the digital content that you sell in your applications.
- You cannot implement in-app billing on a device that never connects to the network. To complete in-app purchase requests, a device must be able to access the Google Play server over the network.
