ウェブアプリのアプリ内課金（IAP）API（APIリファレンス）
ウェブアプリのアプリ内課金（IAP）API（APIリファレンス）
Amazon Services
AmazonServicesのメソッドには次のものがあります。
- AmazonIapV2.addListener(listener)
- このクラスは、使用する前にオブザーバーを登録する必要があります。
- このメソッドは、onLoad()ライフサイクルメソッド内で呼び出す必要があります。
- AmazonIapV2.purchase(sku)
- このメソッドは、1つのSKUの購入を開始する際に呼び出します。
- すべてのタイプの購入可能アイテムに使用することができます。
- UIに表示される購入フローは、SKUで構成された情報に基づいて決定されます。
- このメソッドは、いつでもアプリから呼び出すことができます。
- AmazonIapV2.getProductData(skus)
- このメソッドは、複数のSKUに関するアイテムデータを取得する際に呼び出します。
- すべてのタイプの購入可能アイテムに使用することができます。
- このメソッドは、いつでもアプリから呼び出すことができます。
- パラメーターの「SKUs」は、SKUを表す文字列の配列です。
- AmazonIapV2.getPurchaseUpdates(offset)
- このメソッドは、購入履歴や無効になった非消費型アイテムをデバイス間で同期するために使用します。
- getPurchaseUpdates()をアクティビティのonStart()メソッドまたはonResume()メソッドに実装します。また、注文に対して二重にアイテム付与することを防ぐために、receiptIdを使用してレシートの重複を排除します。消費型アイテム、非消費型アイテム、定期購入型アイテムの相違点から見た実装の詳細は以下のとおりです。
- 消費型アイテム： getPurchaseUpdates()メソッドは、課金が完了していない消費型アイテムまたはキャンセルされた消費型アイテムの購入レシートを返します。IAP 2.0のgetPurchaseUpdatesResponse()では次の点に注意してください。
- getPurchaseUpdates()の呼び出しで返される購入レシートのアイテム付与を処理するロジックをアプリに追加します。アプリが開くときや、それ以外の任意のタイミングで、対応するPurchaseUpdatesResponse()コールバックが実行されることがあるため、利用できない可能性のあるユーザーインターフェイス（UI）要素やオブジェクトを参照するときは注意してください。
- offsetパラメーターの代わりにboolean型のresetパラメーターを使用します。購入レシートをすべて返すには、resetをtrueに設定します。getPurchaseUpdates()の前回の呼び出し以降に行われた購入のレシートを返すには、resetをfalseに設定します。
- 非消費型アイテム：onPurchaseUpdatesResponse()は、非消費型アイテムおよび定期購入型アイテムのキャンセルされた購入とアクティブな購入のレシートを返します。購入がキャンセルされたかどうかはreceipt.isCanceled()で確認します。IAP 1.0では、キャンセルされた非消費型アイテムおよび定期購入型アイテムのレシートが返されるように、PurchaseUpdatesResponseオブジェクトのgetRevokedSkus()を呼び出していました。
- 定期購入型アイテム： 非消費型アイテムと同じです。
- AmazonIapV2.getUserData()
- このメソッドは、現在ログインしているユーザーのアプリ固有IDを取得するために使用します。
- このメソッドはonLoad()メソッド内で呼び出す必要があります。
- AmazonIapV2.notifyFulfillment(receiptId, fulfillmentResult)
- IAP 2.0には、アイテム付与ステータスをトラッキングするための新しいAPIが用意されています。アイテム付与ステータスをトラッキングするには、notifyFulfillment() APIを実装します。アイテムの付与が完了した後にこの呼び出しを実装し、購入ステータスをAmazonに送信します。
- アイテム付与が完了した後に、FULFILLEDステータスを指定したnotifyFulfillment()を呼び出さないと、アイテムの配信は保留のままになります。この場合は、次回getPurchaseUpdates()を呼び出したときに、onPurchaseUpdatesResponse()コールバックによって配信の試行が続行されます。このAPIによるアイテム付与の通知がAmazonに届かない場合、最終的には注文がキャンセルされることがあります。
- アイテム付与ができないアイテムの場合は、UNAVAILABLEステータスを使用します。UNAVAILABLEステータスを指定したnotifyFulfillment()は任意の時点でアプリから呼び出すことができます。
- この呼び出しはイミュータブルです。notifyFulfillment()によって注文がFULFILLEDまたはUNAVAILABLEに設定されると、ステータスを再び変更することはできません。
レスポンスオブジェクト
AmazonServicesを使用して呼び出しを行うと、registerObserver()で指定された、対応するレスポンスハンドラーによってレスポンスが受信されます。これらのレスポンスでは、それぞれ1つのレスポンスオブジェクトが使用されます。レスポンスの詳細は次のとおりです。
- GetUserIdResponse：現在Amazonクライアントにログインしているユーザーのアプリ固有UserIDを提供する。
- PurchaseUpdatesResponse：開始リクエストで渡されたオフセット以降のレシートと無効なSKUをページ分割されたリストとして提供する。レシートは1つのセットとして返され、整列されていません。
- ItemDataResponse：SKUをキーとしてアイテムデータを提供する。
- PurchaseResponse：アプリ内で開始された購入のステータスを提供する。購入で発生するエラーは開発者から認識できないため、アプリにエラー処理を実装する必要はありません。エラーはアプリ内課金（IAP）APIによって管理されます。
購入ハンドラー
以下のレスポンスハンドラーを実装し、registerObserverメソッドでAmazonServicesに登録する必要があります。
- onSdkAvailable(onAvailableResponse)：アプリ内課金サービスがコードから呼び出し可能になると、呼び出される。
- onGetUserIdResponse(userIdResponse)：GetUserIdへのレスポンスとして呼び出される。
- onItemDataResponse(itemDataResponse)：GetItemDataへのレスポンスとして呼び出される。data.itemDataは、SKUをキーとするitemDataオブジェクトのハッシュテーブルです。
- onPurchaseResponse(purchaseResponse)：購入操作のステータスをレポートするために呼び出される。purchaseResponse.purchaseRequestStatusにレスポンスのステータスが含まれています。アプリの前回のセッションが購入レスポンスの配信前に終了した場合、アプリの新しいセッションによって購入ハンドラーが登録されたときに、この関数が呼び出されます。
- onPurchaseUpdateResponse(data)：ユーザーに付与された非消費型アイテムのリストと共に呼び出される。data.receiptsには、SKUをキーとするハッシュテーブルが含まれています。テーブルの内容は、ユーザーに付与されたIAPのレシートです。data.revokedSkusには、ユーザーが使用できなくなったSKUのリストが含まれています。
APIリファレンス： AmazonInAppPurchasing
メンバー
ItemDataStatus
getItemData()のレスポンスコードです。
- INVALID_INPUT
- SUCCESSFUL
- FAILED
- SUCCESSFUL_WITH_UNAVAILABLE_SKU
ItemType
Amazonアプリ内課金（IAP）APIで作成可能な購入タイプです。
この列挙には次の値が含まれます。
- CONSUMABLE
- ENTITLEMENT
- SUBSCRIPTIONS
オフセット
最初の時点から更新された購入を見つけるヘルパー値です。
プロパティ：
- BEGINNING - デフォルト値はNULL
PurchaseStatus
レシートのステータスです。
- INVALID_INPUT
- SUCCESSFUL
- FAILED
- INVALID_SKU
- ALREADY_ENTITLED
PurchaseUpdatesStatus
getPurchaseData()のレスポンスコードです。
- INVALID_INPUT
- SUCCESSFUL
- FAILED
UserIdStatus
getUserId()のレスポンスコードです。
- SUCCESSFUL
- FAILED
メソッド
getItemData(skus)
SKUリストのアイテムデータを取得します。
パラメーター：
| 名前 | 型 | 説明 |
|---|---|---|
| skus | Array | このリストにあるSKUの項目情報を取得します。 |
getPurchaseUpdates(offset)
指定した時点より後に発行されたレシートを取得します。Offset.BEGINNINGを使用すると、ユーザー履歴の最初の時点以降のレシートを取得できます。ここで返されるレシートの数は限られているため、レシートが多くなる場合は、前回呼び出したレシートを頼りに、ユーザー履歴のページをめくっていきます。
パラメーター：
| 名前 | 型 | 説明 |
|---|---|---|
| offset | ユーザー履歴のこの時点から結果を返しはじめます。 |
getUserId()
ユーザーIDをリクエストします。結果が取得可能な状態であれば、onGetUserIdResponseが呼び出されます。
purchaseItem(sku)
指定されたSKUの購入が開始されます。
パラメーター：
| 名前 | 型 | 説明 |
|---|---|---|
| sku | リクエストされたSKUです。 |
registerObserver()
Amazonアプリ内課金（IAP）APIからの非同期レスポンスを扱うために、コールバックハンドラーを登録します。
呼び出される関数のハッシュテーブルを受け取ります。
- onSdkAvailable
- onGetUserIdResponse
- onItemDataResponse
- onPurchaseResponse
- onPurchaseUpdatesResponse
型定義
onGetUserIdResponse(event)
getUserIdに対するレスポンスとして呼び出されます。
イベントオブジェクトの構造は次のとおりです。
- requestId
- getUserIdRequestStatus
- userId
パラメーター：
| 名前 | 型 | イベント |
|---|---|---|
| event | リクエストされたSKUです。 |
onItemDataResponse(event)
getItemDataに対するレスポンスとして、リクエストされたアイテムデータと共に呼び出されます。
イベントオブジェクトの構造は次のとおりです。
- requestId
- itemDataRequestStatus
- itemData (array)
- sku
- price
- title
- itemType
- description
- smallIconUrl
onPurchaseResponse(event)
purchaseItemに対するレスポンスとして、レシートと共に呼び出されます。
イベントオブジェクトの構造は次のとおりです。
- requestId
- userId
- purchaseRequestStatus
- receipt
- sku
- itemType
- purchaseToken
- subscriptionPeriod（定期購入型のレシートの場合はnull）
- startDate
- endDate
onPurchaseUpdatesResponse(event)
getPurchaseUpdatesに対するレスポンスとして、レシートと共に呼び出されます。
イベントオブジェクトの構造は次のとおりです。
- requestId
- purchaseUpdatesRequestStatus
- receipts（配列）
- sku
- itemType
- purchaseToken
- subscriptionPeriod（定期購入型のレシートの場合はnull）
- startDate
- endDate
- revokedSkus（文字列の配列）
- boolean reset
- isMore
onSdkAvailable()
APIでさらに呼び出しを行う準備ができている場合に呼び出されます。これはregisterObserverメソッドのregisterObserverに対するコールバックです。