警告: AIDL はすでにサポートが終了しており、将来のリリースで完全に削除される予定です。Google Play 請求サービス機能を実装するには、Google Play Billing Library を使用してください。
このドキュメントでは、Google Play 請求サービス AIDL を使用する際のテクニカル リファレンス情報について説明します。
サーバー レスポンス コード
Google Play からアプリに送信されるサーバー レスポンス コードの一覧を下記の表に示します。Google Play は、各レスポンス コードを、レスポンス Bundle 内の RESPONSE_CODE キーにマッピングされる整数として同期送信します。アプリではこれらのレスポンス コードをすべて処理する必要があります。
表 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 請求サービスのタイプを指定できる追加パラメータ セット。 このバンドルには、ブール値の |
このメソッドは、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
|
SKU の StringArrayList と ITEM_ID_LIST キーを格納するバンドル。
|
getSkuDetails() メソッドが正常に処理されると、Google Play からレスポンス Bundle が送信されます。クエリの結果は、Bundle 内において、DETAILS_LIST キーにマッピングされた文字列 ArrayList の内部に格納されます。詳細リスト内の各文字列は、単一のアイテムのアイテム情報を JSON 形式で格納します。アイテム情報を格納する JSON 文字列フィールドの概要を表 5 に示します。
表 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 |
そのトランザクションに固有のオーダー ID です。この識別子は、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 によって置き換えられます。指定した SKU の置き換えは、次の請求期間の開始時に行われます。 |
replaceSkusProration
|
boolean
|
元の SKU の定期購入期間における未使用分を、クレジットとしてユーザーに付与するかどうかを指定します。このフィールドを true に設定すると、元の SKU はキャンセルされ、定期購入期間における未使用分を比例配分したクレジットがユーザーに付与されます。このクレジットは新しい定期購入に適用され、このクレジットを使い切るまで、新しい定期購入の課金は行われません。 このフィールドを false に設定すると、定期購入期間における未使用分のクレジットはユーザーに付与されず、請求期間の更新日は変更されません。
デフォルト値は true です。 |
accountId
|
String
|
アプリ内のユーザー アカウントに対して一意に関連付けられている難読化文字列（省略可）。この値が渡されると、Google Play は、短期間に多数のデバイス上で同一アカウントを使用して購入を行っているケースなど、異常なアクティビティを検出できるようになります。 このフィールドは、単一のユーザーを示すという点で このフィールドに、Google Play Console デベロッパー ID やユーザーの Google ID は使用しないでください。 また、このフィールドに、ユーザー ID を平文で格納しないようにしてください。 このフィールドには、一方向ハッシュを使用してユーザー ID から生成した文字列を格納することをおすすめします。 |
developerId
|
String
|
すべてのアプリにわたってユーザー アカウントに一意に関連付けられた難読化文字列（省略可）。このフィールドは、単一のユーザーを示すという点で このフィールドに、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() を使用してください。
このメソッドは、Google Play 請求サービス AIDL バージョン 6 以降で使用できます。