Google Play 請求サービス AIDL リファレンス

警告: AIDL はすでにサポートが終了しており、将来のリリースで完全に削除される予定です。Google Play 請求サービス機能を実装するには、Google Play 請求サービスライブラリを使用してください。

このドキュメントでは、Google Play 請求サービス AIDL を使用する際のテクニカルリファレンス情報について説明します。

サーバーレスポンスコード

下記の表に、Google Play からアプリに送信されるサーバーレスポンスコードの一覧を示します。レスポンスコードはレスポンス Bundle 内の RESPONSE_CODE キーにマッピングされる整数であり、Google Play から同期して送信されます。アプリではこれらのレスポンスコードをすべて処理する必要があります。

表 1: Google Play 請求サービス AIDL 呼び出しに対するレスポンスコードの概要

レスポンスコード	値	説明
`BILLING_RESPONSE_RESULT_OK`	0	成功
`BILLING_RESPONSE_RESULT_USER_CANCELED`	1	ユーザーが [戻る] を選択した、またはダイアログを閉じた
`BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE`	2	ネットワーク接続がダウンした
`BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE`	3	リクエストされたタイプは、この Google Play 請求サービス AIDL バージョンではサポートされていません。
`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	アイテムを所有していないため、消費できません。

Google Play 請求サービスサポート AIDL リファレンス

このセクションでは、アプリで利用できる Google Play 請求サービスサポートのタイプについて情報を取得するメソッドについて説明します。

isBillingSupported() メソッド

このメソッドでは、以下について確認できます。

指定した AIDL バージョンがアプリでサポートされているかどうか。
ユーザーの国で Google Play が課金をサポートしているかどうか。
アプリパッケージで Google Play 請求サービスが有効になっているかどうか。
指定したアイテムタイプをアプリが課金の際に使用できるかどうか。

表 2: isBillingSupported() のパラメータ

キー	タイプ	説明
`apiVersion`	`int`	アプリが使用している Google Play 請求サービス AIDL のバージョン番号。
`packageName`	`String`	このメソッドを呼び出しているアプリのパッケージ名。
`type`	`String`	値は、アプリ内アイテムの場合 `inapp`、定期購入の場合 `subs` です。

このメソッドは、Google Play 請求サービス AIDL バージョン 3 以降で使用できます。

isBillingSupportedExtraParams() メソッド

このメソッドは、4 番目の引数以外は isBillingSupported() と同じです。4 番目の Bundle には追加のパラメータを格納することができます。

表 3: isBillingSupportedExtraParams() のパラメータ

キー	タイプ	説明
`apiVersion`	`int`	アプリが使用している Google Play 請求サービス AIDL のバージョン番号。
`packageName`	`String`	このメソッドを呼び出しているアプリのパッケージ名。
`type`	`String`	値は、アプリ内アイテムの場合 `inapp`、定期購入の場合 `subs` です。
`extraParams`	`Bundle`	アプリがサポートする Google Play 請求サービスのタイプを指定できる追加パラメータセット。このバンドルには、ブール値の `vr` というキー（省略可）を格納することができます。このフラグは、このアプリがバーチャルリアリティ（VR）購入フローをサポートしているかどうかを示します。

このメソッドは、Google Play 請求サービス AIDL バージョン 7 以降で使用できます。

Google Play 請求サービス詳細 AIDL リファレンス

Google Play 請求サービス AIDL は、IInAppBillingService.aidl ファイル内で定義されています。このファイルは、バージョン 3 のサンプルアプリに含まれています。

getSkuDetails() メソッド

getSkuDetails() メソッドは、商品 ID リストに対応する商品の詳細情報を取得するのに使用します。

表 4. GetSkuDetails() のパラメータ

キー	タイプ	説明
`apiVersion`	`int`	アプリが使用している Google Play 請求サービス AIDL のバージョン番号。
`packageName`	`String`	このメソッドを呼び出しているアプリのパッケージ名。
`type`	`String`	アプリ内アイテムのタイプ（1 回だけの購入の場合は「inapp」、定期購入の場合は「subs」）です。
`skusBundle`	`Bundle`	`ITEM_ID_LIST` をキーとする SKU の `StringArrayList` を含めたバンドルです。

getSkuDetails() メソッドが正常に機能すると、Google Play からレスポンス Bundle が送信されます。クエリの結果は Bundle 内で、DETAILS_LIST キーにマッピングされた文字列 ArrayList 内に保存されます。その詳細リスト内の文字列に、それぞれの商品の詳細が JSON 形式で含まれます。表 5 に、商品の詳細を含む JSON 文字列のフィールドをまとめます。

表 5. 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`	商品の説明。
`subscriptionPeriod`	定期購入の期間を ISO 8601 形式で示します。たとえば、`P1W` は 1 週間、`P1M` は 1 か月、`P3M` は 3 か月、`P6M` は 6 か月、`P1Y` は 1 年に相当します。注: 定期購入の場合にのみ返されます。
`freeTrialPeriod`	Google Play Console で設定された無料試用期間を ISO 8601 形式で示します。たとえば、`P7D` は 7 日間に相当します。無料試用の資格について詳しくは、アプリ内定期購入についての記事をご覧ください。注: 無料試用期間が設定された定期購入の場合にのみ返されます。
`introductoryPrice`	定期購入のお試し価格で、`€3.99` のように通貨記号付けてフォーマット済みです（税抜き）。注: お試し価格期間が設定された定期購入の場合にのみ返されます。
`introductoryPriceAmountMicros`	マイクロ単位でのお試し価格。通貨は `price_currency_code` と同じです。注: お試し価格期間が設定された定期購入の場合にのみ返されます。
`introductoryPricePeriod`	お試し価格の請求対象期間を ISO 8601 形式で示します。注: お試し価格期間が設定された定期購入の場合にのみ返されます。
`introductoryPriceCycles`	そのユーザーにお試し価格で提供する定期購入の請求対象期間の数（例: 3）です。注: お試し価格期間が設定された定期購入の場合にのみ返されます。

getBuyIntent() メソッド

このメソッドは、RESPONSE_CODE キーにマッピングされたレスポンスコード整数と、BUY_INTENT キーにマッピングされたアプリ内アイテムの購入フローを開始する PendingIntent を返します。詳細については、Google Play 請求サービスを実装するをご覧ください。Google Play は PendingIntent を受け取ると、レスポンス Intent 内にその購入オーダーのデータを格納して送信します。レスポンス Intent 内で返されるデータを表 6 に示します。

注: このメソッドではなく、機能が追加された getBuyIntentExtraParams() を使用することをおすすめします。

表 6: Google Play 請求サービス購入リクエストに対するレスポンスデータ

キー	説明
`RESPONSE_CODE`	購入が成功した場合、値は `0`。それ以外はエラーです。
`INAPP_PURCHASE_DATA`	注文に関する詳細が含まれる JSON 形式の文字列です。この JSON フィールドの説明は、表 7 をご覧ください。
`INAPP_DATA_SIGNATURE`	購入データの署名が含まれる文字列です。デベロッパーの秘密鍵を使い、RSASSA-PKCS1-v1_5 スキームで署名したものです。

注文に対するレスポンスデータで返される JSON フィールドについて、表 7 で説明します。

表 7. INAPP_PURCHASE_DATA の JSON フィールドの説明

フィールド	説明
`autoRenewing`	定期購入が自動的に更新されるかどうかを示します。`true` の場合は定期購入は有効で、次の課金日に自動的に更新されます。`false` の場合は、ユーザーが定期購入をキャンセルしたことを示します。ユーザーは次の課金日までは定期購入のコンテンツにアクセスできますが、自動更新を再度有効にするか、手動更新しなければ（手動更新の説明を参照）、次の課金日からアクセスできなくなります。猶予期間を設けた場合、猶予期間が過ぎるまで、この値はどの定期購入でも `true` に設定されたままになります。猶予期間の終了日まで、またはユーザーがお支払い方法を修正するまで、次の課金日は毎日動的に延長されます。
`orderId`	そのトランザクションに固有の注文識別子です。この識別子は、Google でのお支払いの注文 ID に対応しています。
`packageName`	購入が発生したアプリのパッケージです。
`productId`	アイテムの商品 ID です。アイテムごとに商品 ID を設定し、Google Play Console でアプリの商品リスト内に指定する必要があります。
`purchaseTime`	商品が購入された時刻を、エポック（1970 年 1 月 1 日）からのミリ秒で示します。
`purchaseState`	注文の購入状況。常に `0`（購入済み）が返されます。
`developerPayload`	注文に関する補足情報が含まれる文字列で、デベロッパーが指定します。`getBuyIntent` をリクエストする際、このフィールドの値を指定できます。
`purchaseToken`	各アイテムとユーザーの組み合わせにおける購入を一意に識別するトークンです。

consumePurchase() メソッド

指定された購入トークンに対応する購入を消費します。これにより、getPurchases() に対する以降のすべてのレスポンスからそのアイテムが削除され、同じ SKU のアイテムを再購入できるようになります。

表 8: consumePurchase() のパラメータ

キー	タイプ	説明
`apiVersion`	`int`	アプリが使用している Google Play 請求サービス AIDL のバージョン番号。
`packageName`	`String`	このメソッドを呼び出しているアプリのパッケージ名。
`purchaseToken`	`String`	購入情報 JSON 内のトークンで、消費する購入を特定します。

このメソッドは、正常に消費できると RESULT_OK(0) を返し、失敗すると該当するレスポンスコードを返します。

getBuyIntentToReplaceSkus() メソッド

このメソッドは、定期購入のアップグレードやダウングレードに使用します。このメソッドは getBuyIntent() と似ていますが、購入済みの SKU 1 個を含むリストを受け取り、購入する SKU でそれを置き換える点が異なります。ユーザーが購入を完了すると、今までの SKU がキャンセルされ、定期購入期間における未使用分を比例配分したクレジットがユーザーに付与されます。このクレジットは新しい定期購入に適用され、このクレジットを使い切るまで、定期購入の新たな課金は行われません。

注: このメソッドではなく、機能が追加された getBuyIntentExtraParams() を使用することをおすすめします。

このメソッドは、Google Play 請求サービス AIDL バージョン 5 で追加されました。このメソッドがレポートされたか検証するには、isBillingSupported AIDL リクエストを送信します。

注: このメソッドを使用できるのは、定期購入の場合に限られます。type パラメータに "subs" 以外が渡されると、このメソッドは BILLING_RESPONSE_RESULT_DEVELOPER_ERROR を返します。また、シーズン単位定期購入の SKU を渡すことはできません。

このメソッドは、RESPONSE_CODE キーにマッピングされたレスポンスコード整数と、BUY_INTENT キーにマッピングされたアプリ内定期購入の購入フローを開始する PendingIntent を返します。詳細については、Google Play 請求サービスを実装するをご覧ください。Google Play は PendingIntent を受け取ると、レスポンス Intent 内にその購入オーダーのデータを格納して送信します。レスポンス Intent 内で返されるデータを表 9 に示します。

表 9: Google Play 請求サービス AIDL バージョン 5 購入リクエストに対するレスポンスデータ

キー	説明
`RESPONSE_CODE`	購入が成功した場合、値は `0` です。失敗した場合は、エラーコードが含まれます。
`INAPP_PURCHASE_DATA`	注文に関する詳細が含まれる JSON 形式の文字列です。この JSON フィールドの詳細については、表 7 をご覧ください。
`INAPP_DATA_SIGNATURE`	購入データの署名が含まれる文字列です。デベロッパーが秘密鍵を使って、RSASSA-PKCS1-v1_5 スキームで署名したものです。

getBuyIntentExtraParams() メソッド

このメソッドは購入リクエストを開始します。このメソッドは、getBuyIntent() メソッドに extraParams パラメータが追加されたメソッドです。追加パラメータは、キーと値の Bundle であり（省略可）、メソッドの動作は表 10 に示すとおりです。

表 10: getBuyIntentExtraParams() の追加パラメータ

キー	タイプ	説明
`skusToReplace`	`List<String>`	ユーザーがアップグレードまたはダウングレードする元の SKU を 1 つ含むリストで、省略可能です。既存の定期購入をアップグレードまたはダウングレードする購入の場合に、このフィールドを渡します。ユーザーが購入する SKU で、元の SKU が置き換えられます。置き換えは、次の請求期間の開始時に行われます。
`replaceSkusProration`	`boolean`	元の SKU の定期購入期間における未使用分を、クレジットとしてユーザーに付与するかどうかを指定します。このフィールドを true に設定すると、元の SKU はキャンセルされ、定期購入期間における未使用分を比例配分したクレジットがユーザーに付与されます。このクレジットは新しい定期購入に適用され、このクレジットを使い切るまで、定期購入の新たな課金は行われません。このフィールドを false に設定すると、定期購入期間における未使用分のクレジットはユーザーに付与されず、請求期間の更新日は変更されません。デフォルト値は true です。`skusToReplace` を渡さない場合は無視されます。
`accountId`	`String`	アプリ内のユーザーアカウントと一意に関連付けられた文字列を難読化したもので、省略可能です。この値が渡されると、Google Play は、短期間に多数のデバイスで同一アカウントを使用して購入を行うなど、異常なアクティビティを検出することができます。このフィールドは、単一のユーザーを示すという点で `developerId` と似ています。ただし、アプリが複数ある場合、`accountId` は、単一ユーザーであってもアプリごとに異なる値になりますが、`developerId` は、単一ユーザーであればすべてのアプリで同じ値になります。このフィールドに、Google Play Console デベロッパー ID やユーザーの Google ID は使用しないでください。また、このフィールドに、ユーザー ID を平文で格納しないようにしてください。このフィールドには、一方向ハッシュを使用してユーザー ID から生成した文字列を格納することをおすすめします。
`developerId`	`String`	すべてのアプリを横断してユーザーアカウントに対して一意に関連付けられた文字列を難読化したもので、省略可能です。このフィールドは、単一のユーザーを示すという点で `accountId` と似ています。ただし、このフィールドは、単一ユーザーであればすべてのアプリで同じ値にする必要がありますが、`accountId` は、単一ユーザーであってもアプリごとに別の値になる場合があります。このフィールドに、Google Play Console デベロッパー ID やユーザーの Google ID は使用しないでください。また、このフィールドに、ユーザー ID を平文で格納しないようにしてください。このフィールドには、一方向ハッシュを使用してユーザー ID から生成した文字列を格納することをおすすめします。
`vr`	`boolean`	指定されたインテントがバーチャルリアリティ（VR）購入フローの開始を示すかどうかを指定します。注: アプリに対してこの追加パラメータを有効にするには、Google Play 請求サービス AIDL バージョン 7 以降の API を使用する必要があります。

このメソッドは、Google Play 請求サービス AIDL バージョン 6 以降で使用できます。

getPurchases() メソッド

このメソッドは現時点でユーザーが所有する未消費の商品を返します。購入済みのアイテムと、プロモーションコードを利用して取得したアイテムの両方が含まれます。Bundle 内で返されるレスポンスデータのリストを表 11 に示します。

表 11. getPurchases リクエストに対するレスポンスデータ

キー	説明
`RESPONSE_CODE`	リクエストが成功した場合、値は `0`。それ以外はエラーです。
`INAPP_PURCHASE_ITEM_LIST`	このアプリから購入した productId のリストが含まれる `StringArrayList` です。
`INAPP_PURCHASE_DATA_LIST`	このアプリからの購入情報を格納する `StringArrayList`。リスト内の各アイテムに格納される詳細情報のリストについては、表 13 をご覧ください。
`INAPP_DATA_SIGNATURE_LIST`	このアプリからの購入の署名を格納する `StringArrayList`。
`INAPP_CONTINUATION_TOKEN`	ユーザーが所有するアプリ内アイテムの次のセットを取得するための継続トークンが含まれる文字列です。ユーザーが所有する商品数が非常に多い場合に限り、Google Play サービスによって設定されます。レスポンス内に継続トークンが存在する場合は、再度 `getPurchases` を呼び出して、受信した継続トークンを渡す必要があります。`getPurchases` を続けて呼び出すと、購入情報がさらに返され、場合によってはまた継続トークンが返されます。

getPurchaseHistory() メソッド

このメソッドでは、各 SKU について、ユーザーの前回の購入情報が返されます。期限切れの購入、キャンセルされた購入、消費済みの購入も対象です。Bundle 内で返されるレスポンスデータのリストを表 12 に示します。

表 12. getPurchaseHistory リクエストに対するレスポンスデータ

キー	説明
`RESPONSE_CODE`	リクエストが成功した場合、値は `0`。それ以外はエラーです。
`INAPP_PURCHASE_ITEM_LIST`	このアプリで購入した productId のリストが含まれる `StringArrayList` です。
`INAPP_PURCHASE_DATA_LIST`	このアプリで前回購入した詳細情報が含まれる `StringArrayList` です。リスト内の各 `INAPP_PURCHASE_DATA` アイテムに保存される詳細情報については、表 6 の一覧をご覧ください。
`INAPP_DATA_SIGNATURE_LIST`	このアプリからの購入の署名を格納する `StringArrayList`。
`INAPP_CONTINUATION_TOKEN`	ユーザーが所有するアプリ内アイテムの次のセットを取得するための継続トークンが含まれる文字列です。ユーザーが所有する商品数が非常に多い場合に限り、Google Play サービスによって設定されます。レスポンス内に継続トークンが存在する場合は、再度 `getPurchases` を呼び出して、受信した継続トークンを渡す必要があります。`getPurchases` を続けて呼び出すと、購入情報がさらに返され、場合によってはまた継続トークンが返されます。

表 13. getPurchaseHistory() で返される購入履歴の JSON フィールドの説明

フィールド	説明
`productId`	アイテムの商品 ID です。アイテムごとに商品 ID を設定し、Google Play Console でアプリの商品リスト内に指定する必要があります。
`purchaseTime`	商品が購入された時刻を、エポック（1970 年 1 月 1 日）からのミリ秒で示します。
`developerPayload`	注文に関する補足情報が含まれる文字列で、デベロッパーが指定します。`getBuyIntent` をリクエストする際、このフィールドの値を指定できます。
`purchaseToken`	各アイテムとユーザーの組み合わせにおける購入を一意に識別するトークンです。

注: getPurchaseHistory() メソッドは、Google Play サーバーを呼び出す必要があるため、getPurchases() よりもオーバーヘッドが多くなります。ユーザーの購入履歴が実際には必要ない場合は、getPurchases() を使用してください。