ウェブアプリ用アプリ内課金(IAP)API - APIリファレンス
Amazon Servicesライブラリ
Amazon Servicesライブラリには次のメソッドがあります。
- AmazonIapV2.addListener(listener)
- このクラスは、使用する前にオブザーバーを登録する必要があります。
- このメソッドは、onLoad()ライフサイクルメソッド内で呼び出す必要があります。
- AmazonIapV2.purchase(sku)
- このメソッドは、特定のSKUの購入を開始します。
- すべての種類の購入可能アイテムに使用できます。
- ユーザーインターフェイスに表示される購入フローは、SKUで構成された情報に基づいて決定されます。
- このメソッドは、アプリからいつでも呼び出すことができます。
- AmazonIapV2.getProductData(skus)
- このメソッドは、複数のSKUに関するアイテムデータを取得します。
- すべての種類の購入可能アイテムに使用できます。
- このメソッドは、アプリからいつでも呼び出すことができます。
- skusパラメーターには、SKUを表す文字列の配列を指定します。
- AmazonIapV2.getPurchaseUpdates(options)
- このメソッドは、以前の購入および取り消された非消費型アイテムをデバイス間で同期するために使用します。
- アクティビティのonStart()メソッドまたはonResume()メソッドで、getPurchaseUpdates()を呼び出します。また、注文に対してアイテムを二重に付与することを防ぐために、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に設定したら、ステータスを再び変更することはできません。
レスポンスオブジェクト
Amazon Servicesライブラリを通じて呼び出しを開始すると、registerObserver()で指定した対応するレスポンスハンドラーにレスポンスが送られます。これらのレスポンスでは、それぞれ1つのレスポンスオブジェクトが使用されます。各レスポンスの詳細は次のとおりです。
- GetUserIdResponse - 現在Amazonクライアントにログインしているユーザーのアプリ固有UserIDを提供します。
- PurchaseUpdatesResponse - 開始リクエストで渡されたオフセット以降のレシートと取り消されたSKUを、ページ分割されたリストとして提供します。レシートは、ソートされていない1つのセットとして返されます。
- ItemDataResponse - SKUをキーとしてアイテムデータを提供します。
- PurchaseResponse - アプリ内で開始された購入のステータスを提供します。購入で発生するエラーは開発者から認識できないため、アプリにエラー処理を実装する必要はありません。エラーはアプリ内課金(IAP)APIによって管理されます。
購入ハンドラー
以下のレスポンスハンドラーを実装し、registerObserverメソッドでAmazon Servicesライブラリに登録する必要があります。
- onSdkAvailable(onAvailableResponse) - IAP サービスがコードから呼び出し可能になったときに呼び出されます。
- 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
IAP APIで実行できる購入のタイプ。
この列挙型に定義されている値は次のとおりです。
- CONSUMABLE
- ENTITLEMENT
- SUBSCRIPTIONS
Offset
更新のアップデートを取得する開始時点を指定するためのヘルパー値。
プロパティ:
- 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(reset)
ユーザーのレシートを取得します。resetをfalseに設定すると、前回の呼び出し以降に発行された新しいレシートのみが返されます。resetをtrueに設定すると、このユーザーのレシートがすべて返されます。
パラメーター:
名前 | 型 | 説明 |
---|---|---|
reset | Boolean型。キー/値のペアで渡されます(例:{reset: true})。 | falseに設定すると、前回の呼び出し以降に発行された新しいレシートのみが返されます。trueに設定すると、このユーザーのレシートがすべて返されます。 |
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(配列)
- 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(文字列の配列)
- offset
- isMore
onSdkAvailable()
APIを呼び出す準備が整ったときに呼び出されます。これはregisterObserverメソッドに対するコールバックです。