Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

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 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 そのトランザクションに固有の注文識別子です。この識別子は、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() を使用してください。

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