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

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

このドキュメントでは、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 請求サービスのタイプを指定できる追加パラメータ セット。

このバンドルには、ブール値の 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 SKU の StringArrayListITEM_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 priceISO 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 です。この ID は、Google お支払いオーダー ID に対応しています。
packageName 購入が発生したアプリ パッケージ。
productId そのアイテムのアイテム ID。アイテムごとに固有のアイテム 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 です。skusToReplace を渡さなかった場合は無視されます。

accountId String

アプリ内のユーザー アカウントに対して一意に関連付けられている難読化文字列(省略可)。この値が渡されると、Google Play は、短期間に多数のデバイス上で同一アカウントを使用して購入を行っているケースなど、異常なアクティビティを検出できるようになります。

このフィールドは、単一のユーザーを示すという点で developerId と似ています。ただし、アプリが複数ある場合、accountId は、単一ユーザーであってもアプリごとに異なる値になりますが、 は、単一ユーザーであればすべてのアプリで同じ値になります。

このフィールドに、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 があります。アイテム ID は、Google Play Console にあるアプリのアイテムリスト内で指定する必要があります。
purchaseTime アイテムが購入された時刻。エポック(1970 年 1 月 1 日)を起点としてミリ秒単位で示します。
developerPayload オーダーに関する補足情報を格納する文字列。デベロッパーが指定します。getBuyIntent リクエストを行う際に、このフィールドの値を指定できます。
purchaseToken 指定したアイテムとユーザーの組み合わせを対象として、各購入を一意に識別するトークン。

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

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