警告: 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 に対して無効な引数が指定されています。また、アプリが正しく署名されていない場合、アプリが請求用に適切にセットアップされていない場合、マニフェストに必要な権限が含まれていない場合も、このエラーが返されます。 |
BILLING_RESPONSE_RESULT_ERROR |
6 | API の動作中に致命的なエラーが発生した |
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED |
7 | アイテムをすでに所有しているので、購入できない |
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED |
8 | アイテムを所有していないので、消費できない |
Google Play 請求サービス AIDL リファレンス - サポート
このセクションでは、アプリで利用できる請求サポートのタイプに関する情報を取得するメソッドについて説明します。
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 |
そのトランザクションに固有の注文識別子です。この識別子は、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 は、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 以降で使用できます。