このドキュメントでは、In-app Billing API の利用に関する技術情報をリファレンスとして提供します。
サーバー レスポンス コード
下記の表に、Google Play からアプリに送信されるサーバー レスポンス コードの一覧を示します。レスポンス コードはレスポンス Bundle 内の RESPONSE_CODE キーにマッピングされる整数であり、Google Play から同期して送信されます。アプリではこれらのレスポンス コードをすべて処理する必要があります。
表 1. In-app Billing API の呼び出しに対するレスポンス コードの一覧
| レスポンス コード | 値 | 説明 |
|---|---|---|
BILLING_RESPONSE_RESULT_OK |
0 | 成功 |
BILLING_RESPONSE_RESULT_USER_CANCELED |
1 | ユーザーが [戻る] を選択した、またはダイアログを閉じた |
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE |
2 | ネットワーク接続がダウンした |
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE |
3 | リクエストされたタイプは、Billing API のこのバージョンでサポートされていない |
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 | アイテムを所有していないので、消費できない |
Billing Support API リファレンス
このセクションでは、アプリで利用可能なアプリ内課金のサポートの種類について、情報を確認するメソッドを紹介します。
isBillingSupported() メソッド
このメソッドでは、以下について確認できます。
- 指定する API のバージョンがアプリでサポートされている。
- ユーザーの国で Google Play が課金をサポートしている。
- アプリのパッケージで課金が有効になっている。
- 指定するアイテムのタイプをアプリでの課金の際に使用できる。
表 2. isBillingSupported() のパラメータ
| キー | タイプ | 説明 |
|---|---|---|
apiVersion
|
int
|
アプリが使用している In-app Billing API のバージョン番号です。 |
packageName
|
String
|
このメソッドを呼び出しているアプリのパッケージ名です。 |
type
|
String
|
値はアプリ内アイテムの場合 inapp、定期購入の場合 subs です。
|
このメソッドは In-app Billing API version 3 以降で使用できます。
isBillingSupportedExtraParams() メソッド
このメソッドは、4 番目の引数以外は isBillingSupported() と同じです。4 番目の Bundle には追加のパラメータを含めることができます。
表 3. isBillingSupportedExtraParams() のパラメータ
| キー | タイプ | 説明 |
|---|---|---|
apiVersion
|
int
|
アプリが使用している In-app Billing API のバージョン番号です。 |
packageName
|
String
|
このメソッドを呼び出しているアプリのパッケージ名です。 |
type
|
String
|
値はアプリ内アイテムの場合 inapp、定期購入の場合 subs です。
|
extraParams
|
Bundle
|
アプリがサポートするアプリ内課金のタイプを追加して指定できるパラメータ セットです。 このバンドルには、ブール値の |
このメソッドは In-app Billing API version 7 以降で使用できます。
Billing Details API リファレンス
In-app Billing API は、version 3 のサンプル アプリケーションに含まれる IInAppBillingService.aidl ファイルで定義されています。
getSkuDetails() メソッド
getSkuDetails() メソッドは、商品 ID リストに対応する商品の詳細情報を取得するのに使用します。
表 4. GetSkuDetails() のパラメータ
| キー | タイプ | 説明 |
|---|---|---|
apiVersion
|
int
|
アプリが使用している In-app Billing API のバージョン番号です。 |
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 は PendingIntent を受け取ると、レスポンス Intent にその注文のデータを含めて送信します。レスポンス Intent に返されるデータを表 6 にまとめます。
注: このメソッドではなく、機能が追加された getBuyIntentExtraParams() を使用することをおすすめします。
表 6. アプリ内課金の購入リクエストに対するレスポンス データ
| キー | 説明 |
|---|---|
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
|
アプリが使用している In-app Billing API のバージョン番号です。 |
packageName
|
String
|
このメソッドを呼び出しているアプリのパッケージ名です。 |
purchaseToken
|
String
|
購入情報 JSON 内のトークンで、消費する購入を特定します。 |
このメソッドは、正常に消費できると RESULT_OK(0) を返し、失敗すると該当するレスポンス コードを返します。
getBuyIntentToReplaceSkus() メソッド
このメソッドは、定期購入のアップグレードやダウングレードに使用します。getBuyIntent() と似ていますが、購入済みの SKU 1 個が含まれるリストを受け取り、購入する SKU でそれを置き換える点が異なります。ユーザーが購入を完了すると、今までの SKU がキャンセルされ、定期購入期間における未使用分を比例配分したクレジットがユーザーに付与されます。このクレジットは新しい定期購入に適用され、このクレジットを使い切るまで、定期購入の新たな課金は行われません。
注: このメソッドではなく、機能が追加された getBuyIntentExtraParams() を使用することをおすすめします。
このメソッドは、In-app Billing API version 5 で追加されました。このメソッドが報告されたことを確認するには、isBillingSupported AIDL リクエストを送信します。
注: このメソッドは定期購入の場合にのみ使用できます。type パラメータに "subs" 以外が渡されると、メソッドは BILLING_RESPONSE_RESULT_DEVELOPER_ERROR を返します。また、シーズン契約の定期購入の SKU を渡すことはできません。
このメソッドは、RESPONSE_CODE キーにマッピングされたレスポンス コードを表す整数と、BUY_INTENT キーにマッピングされたアプリ内アイテムの購入フローを開始する PendingIntent を返します。詳しくは、アプリ内課金の実装についての説明をご覧ください。Google Play は PendingIntent を受け取ると、レスポンス Intent にその注文のデータを含めて送信します。レスポンス Intent に返されるデータを表 9 にまとめます。
表 9. In-app Billing version 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 です。 |
accountId
|
String
|
アプリ内のユーザー アカウントと一意に関連付けられた文字列を難読化したもので、省略可能です。この値が渡されると、Google Play では、短期間に多くの端末で同じアカウントを使って購入するような、異常なアクティビティを検出することができます。 このフィールドに、デベロッパー ID やユーザーの Google ID は指定しないでください。また、ユーザー ID を難読化せずに指定してはなりません。一方向ハッシュを使ってユーザー ID から生成した文字列をこのフィールドに指定することをおすすめします。 |
vr
|
boolean
|
指定されたインテントがバーチャル リアリティ（VR）購入フローの開始を表すかどうかを指定します。 注: アプリでこの追加のパラメータを有効にするには、In-app Billing version 7 API 以降を使用する必要があります。 |
このメソッドは In-app Billing API version 6 以降で使用できます。
getPurchases() メソッド
このメソッドは現時点でユーザーが所有する未消費の商品を返します。購入済みのアイテムと、プロモーション コードを利用して取得したアイテムの両方が含まれます。Bundle に返されるレスポンス データの一覧を表 11 に示します。
表 11. getPurchases リクエストに対するレスポンス データ
| キー | 説明 |
|---|---|
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 を続けて呼び出すと、購入情報がさらに返され、場合によってはまた継続トークンが返されます。 |
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() メソッドは getPurchases() よりオーバーヘッドが多くなります。Google Play サーバーを呼び出す必要があるためです。ユーザーの購入履歴が実際には必要ない場合は、getPurchases() を使用してください。
このメソッドは In-app Billing API version 6 以降で使用できます。