このドキュメントでは、In-app Billing Version 3 API の利用に関する技術的なリファレンス情報を記載しています。
サーバー レスポンス コード
以下の表は、Google Play からアプリに送信されるサーバー レスポンス コードの一覧です。
レスポンス コードはレスポンス Bundle 内の RESPONSE_CODE キーにマッピングされた整数で、Google Play から同期的に送信されます。
アプリはこれらのレスポンス コードをすべて処理する必要があります。
表 1. In-app Billing Version 3 API からの呼び出しに対するレスポンス コードの一覧
| レスポンス コード | 値 | 説明 |
|---|---|---|
BILLING_RESPONSE_RESULT_OK | 0 | 成功 |
BILLING_RESPONSE_RESULT_USER_CANCELED | 1 | ユーザーが [戻る] をクリック、またはダイアログをキャンセルした |
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE | 2 | ネットワーク接続がダウンした |
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE | 3 | Billing API のバージョンがリクエストされたタイプをサポートしていない |
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE | 4 | リクエストされた商品が購入できない |
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR | 5 | API に指定した引数が無効。 アプリが正しく署名されていない、Google Play のアプリ内課金用に適切にセットアップされていない、マニフェストに必要なパーミッションがない場合にも、このエラーが返されます。 |
BILLING_RESPONSE_RESULT_ERROR | 6 | API の動作中に致命的なエラーが発生した |
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED | 7 | アイテムがすでに所有されているため、購入できない |
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED | 8 | アイテムを所有していないため、消費できない |
API リファレンス
In-app Billing Version 3 API は Version 3 のサンプル アプリケーション に含まれる IInAppBillingService.aidl ファイル内に定義されています。
getSkuDetails() メソッド
このメソッドは商品 ID リストに対応した商品の詳細情報を返します。Google Play から送信されるレスポンス Bundle 内で、 DETAILS_LIST キーにマッピングされた文字列 ArrayList にクエリの結果が保管されています。
詳細リストにある各文字列には、単一商品の商品詳細が JSON 形式で含まれています。
表 2 は商品詳細情報を含む JSON 文字列のフィールドをまとめたものです。
表 2. getSkuDetails リクエストから返される、商品アイテム詳細情報を含む JSON フィールドの説明
| キー | 説明 |
|---|---|
productId | その商品の商品 ID。 |
type | 値は、アプリ内アイテムの場合は “inapp”、定期購入の場合は "subs" である必要があります。 |
price | 通貨記号付きのフォーマット済みアイテム価格。 価格は税抜き価格です。 |
price_amount_micros | 価格はマイクロ単位です。1,000,000 マイクロ単位が 1 通貨単位に相当します。
たとえば、price が "€7.99" の場合、price_amount_micros は "7990000" です。この値は、ある特定の通貨にローカライズして端数を丸めた価格を表します。 |
price_currency_code | price の ISO 4217 通貨記号 です。
たとえば、price にイギリス ポンドが指定された場合、price_currency_code は "GBP" です。 |
title | 商品タイトル。 |
description | 商品説明。 |
getBuyIntent() メソッド
アイテムを購入するに記載しているように、このメソッドは、RESPONSE_CODE キーにマッピングされたレスポンス コード整数と、BUY_INTENT キーにマッピングされたアプリ内アイテムの購入フローを開始する PendingIntent を返します。
PendingIntent を受け取ると、Google Play はレスポンス Intent で注文に応じたデータを送信します。
表 3 はレスポンス Intent で返されるデータの一覧です。
表 3. In-app Billing Version 3 の購入リクエストに対するレスポンス データ
| キー | 説明 |
|---|---|
RESPONSE_CODE | 購入が成功すれば、値は 0、そうでなければエラーになります。 |
INAPP_PURCHASE_DATA | 注文の詳細情報を含む JSON 形式の文字列。 JSON フィールドの説明は、表 4 をご覧ください。 |
INAPP_DATA_SIGNATURE | デベロッパーの秘密鍵で署名された購入データの署名を含む文字列。 データ署名には RSASSA-PKCS1-v1_5 スキームが使われています。 |
表 4 は注文に対するレスポンス データで返される JSON フィールドの説明です。
表 4. INAPP_PURCHASE_DATA の JSON フィールドの説明
| フィールド | 説明 |
|---|---|
autoRenewing | 定期購入が自動更新されたかどうかを示します。
true の場合は定期購入が有効で、次の課金日に自動的に更新されます。
false の場合はユーザーが定期購入をキャンセルしたことを示します。
ユーザーは次の課金日までは定期購入コンテンツにアクセスできますが、自動更新を再度有効にするか、手動更新しなければ（手動更新に記載）、次の課金日にはアクセスできなくなります。
猶予期間を設けた場合、猶予期間が過ぎるまでは、この値は全定期購入に対して true に設定されたままになります。
次の課金日は、猶予期間の終了時点、またはユーザーが支払いメソッドを固定するまでは毎日動的に延長されます。
|
orderId | トランザクション用の固有の注文識別子です。
この識別子は、Google ペイメントの注文 ID に対応しています。
アプリ内課金サンドボックス経由でテスト購入した注文の場合、orderId は空欄です。 |
packageName | 購入が発生したアプリケーション パッケージを表します。 |
productId | アイテムの商品識別子です。 各アイテムには商品 ID があり、Google Play Developer Console 上のアプリ商品リストで指定する必要があります。 |
purchaseTime | 商品が購入された時間を、1970 年 1 月 1 日から始まるミリ秒で表しています。 |
purchaseState | 注文の購入状況を表します。
有効な値は 0（購入済み）、1（キャンセル済み）、2（返金済み）です。 |
developerPayload | デベロッパーが指定する文字列で、注文の補足情報が含まれます。
getBuyIntent リクエストをする際、このフィールドの値を指定できます。 |
purchaseToken | 任意のアイテムとユーザーのペアにおける購入を一意に識別するトークンです。 |
getBuyIntentToReplaceSkus() メソッド
このメソッドは、定期購入のアップグレード、ダウングレードに使用します。getBuyIntent() と似ていますが、購入される SKU で置き換えられる既に購入済みの SKU リストをとる点が異なります。
ユーザーが購入を完了すると、Google Play は古い SKU をキャンセルし、定期購入期間における未使用分を比例配分して、クレジットとしてユーザーに付与します。
Google Play では、この付与されたクレジットを新たな定期購入に適用し、クレジットを使い切るまではユーザーに対して新たな定期購入分の課金を行いません。
このメソッドは、In-app Billing Version 5 API で追加されました。メソッドが報告されたことを確認するには、isBillingSupported AIDL リクエストを送ります。
注: このメソッドは定期購入にのみ使用できます。
渡された type パラメータが "subs" 以外の場合、メソッドは BILLING_RESPONSE_RESULT_DEVELOPER_ERROR を返します。さらに、渡された SKU にはシーズン定期購入の SKU が含まれない場合があります。
アイテムを購入するに記載しているように、このメソッドは、RESPONSE_CODE キーにマッピングされたレスポンス コード整数と、BUY_INTENT キーにマッピングされたアプリ内定期購入の購入フローを開始する PendingIntent を返します。
PendingIntent を受け取ると、Google Play はレスポンス Intent で注文に応じたデータを送信します。
表 5 はレスポンス Intent で返されるデータの一覧です。
表 5. In-app Billing Version 5 の購入リクエストに対するレスポンス データ
| キー | 説明 |
|---|---|
RESPONSE_CODE | 購入が成功した場合の値は 0 です。
失敗した場合はエラーコードが含まれます。 |
INAPP_PURCHASE_DATA | 注文の詳細情報を含む JSON 形式の文字列。 JSON フィールドの説明は、表 4 をご覧ください。 |
INAPP_DATA_SIGNATURE | デベロッパーの秘密鍵で署名された購入データ署名を含む文字列。 データ署名には RSASSA-PKCS1-v1_5 スキームが使われます。 |
getPurchases() メソッド
このメソッドは現時点でユーザーが所有する未消費の商品を返します。購入済み商品およびプロモーションコードで決済して取得したアイテムが含まれます。
表 6 は Bundle で返されるレスポンス データの一覧です。
表 6. getPurchases リクエストに対するレスポンス データ
| キー | 説明 |
|---|---|
RESPONSE_CODE | 購入が成功すれば値は 0、そうでなければエラーになります。 |
INAPP_PURCHASE_ITEM_LIST | このアプリで購入した商品 ID リストを含む StringArrayList。 |
INAPP_PURCHASE_DATA_LIST | このアプリでの購入詳細情報を含む StringArrayList。
リストの各 INAPP_PURCHASE_DATA アイテムに保存される詳細情報については、表 4 の一覧をご覧ください。 |
INAPP_DATA_SIGNATURE_LIST | このアプリでの購入の署名を含む StringArrayList。 |
INAPP_CONTINUATION_TOKEN | ユーザーが所有するアプリ内アイテムの次のセットを呼び出すための継続トークンを含む文字列。
ユーザーが所有する商品数が非常に多い場合に限り、Google Play サービスによって設定されます。
レスポンス内に継続トークンが存在する場合は、再度 getPurchases を呼び出して、受信した継続トークンを渡す必要があります。
再度 getPurchases を呼び出すと、さらなる購入と、場合によっては別の継続トークンが返されます。
|