ウェブアプリ向けアプリ内課金（IAP）APIのメソッド

ウェブアプリにIAPを実装するには、一連のレスポンスハンドラーをAmazon Servicesライブラリに登録する必要があります。

• Amazon Servicesライブラリ
  • ProductData
  • PurchaseReceipt
  • resetパラメーター
  • レスポンスオブジェクト
  • 購入ハンドラー
  • レシートの処理

IAP APIは、Amazon Servicesライブラリ（JavaScriptライブラリ）とレスポンスハンドラーという2つの主要コンポーネントで構成されます。開発者がレスポンスハンドラーを実装し、初期化時に引数としてAmazon Servicesライブラリへ渡します。

Amazon Servicesライブラリを組み込むには、ウェブアプリに次の<script>タグを追加します。

<script src="https://resources.amazonwebapps.com/v1/latest/Amazon-Web-App-API.min.js">
</script>

Amazon Servicesライブラリ

Amazon Servicesライブラリには次のメソッドがあります。

• AmazonIapV2.addListener(listener)
  • AmazonIapV2クラスには、使用前にオブザーバーを登録する必要があります。
  • このメソッドは、onLoad()ライフサイクルメソッド内で呼び出す必要があります。
• AmazonIapV2.purchase(sku)
  • このメソッドは、特定のSKUの購入を開始します。
  • すべての種類の購入可能アイテムに使用できます。
  • ユーザーインターフェイスに表示される購入フローは、SKUに構成された情報に基づいて決定されます。
  • このメソッドは、アプリからいつでも呼び出すことができます。
• AmazonIapV2.getProductData(skus)
  • このメソッドは、複数のSKUに関するアイテムデータを取得します。
  • すべての種類の購入可能アイテムに使用できます。
  • このメソッドは、アプリからいつでも呼び出すことができます。
  • skusパラメーターには、SKUを表す文字列の配列を指定します。
• AmazonIapV2.getPurchaseUpdates(reset)
  • このメソッドは、以前の購入および取り消された非消費型アイテムをデバイス間で同期するために使用します。
  • アクティビティのonStart()メソッドまたはonResume()メソッドで、getPurchaseUpdates()を呼び出します。また、注文に対してアイテムを二重に付与することを防ぐために、receiptIdを使用してレシートの重複を排除します。消費型アイテム、非消費型アイテム、定期購入型アイテムの違いに注目した実装の詳細は以下のとおりです。
  • 消費型アイテム： getPurchaseUpdates()メソッドは、付与が完了していない消費型アイテムまたはキャンセルされた消費型アイテムの購入レシートを返します。IAP 2.0のgetPurchaseUpdatesResponse()では、次の点に注意してください。
    • getPurchaseUpdates()の呼び出しから返された購入レシートについて、アイテム付与を処理するロジックをアプリに追加します。対応するPurchaseUpdatesResponse()コールバックは、アプリが開かれたときや、ほかの任意のタイミングで実行されることがあります。その時点で利用できない可能性のあるユーザーインターフェイス（UI）要素やオブジェクトを参照するときは注意してください。
    • すべての購入レシートを返すには、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に設定したら、ステータスを再び変更することはできません。

ProductData

商品データは購入可能なアイテムを表し、そのアイテムに関する情報をストアに提供します。ベストプラクティスとして、ユーザーが購入操作を開始する前に、購入可能アイテムの価格情報を取得して表示することをお勧めします。ProductDataクラスを使用すると、ローカライズされた価格、タイトル、説明の文字列にアクセスすることができます。価格の文字列には通貨記号が含まれ、ロケールに基づいて適切な書式が設定されます。

PurchaseReceipt

購入が行われると、そのたびにPurchaseReceiptが提供されます。各レシートにはrecieptIdが含まれており、これを使用してレシート検証サービスで購入を検証できます。レシートはセキュアであり、レシートに基づいてアプリ内のコンテンツや機能へのアクセスを安全に承認できます。開発者は、各購入のuserData、receiptId、SKUにアクセスできます。recieptIdは、レシートデータが返されるたびに動的に生成される一意の値であり、レスポンスオブジェクトで返されたレシートデータを検証するために使用されます。各recieptIdは、レシート検証サービスによる検証をいつでも正常に通過します。

resetパラメーター

IAP 2.0では、1.0のoffsetパラメーターではなく、boolean型のresetパラメーターを使用します。すべての購入レシートを返すには、resetをtrueに設定します。getPurchaseUpdates()の前回の呼び出し以降に行われた購入のレシートを返すには、resetをfalseに設定します。

レスポンスオブジェクト

Amazon Servicesライブラリを通じて呼び出しを開始すると、addListener()メソッドで指定した対応するレスポンスハンドラーにレスポンスが送られます。これらのレスポンスでは、それぞれ1つのレスポンスオブジェクトが使用されます。各レスポンスの詳細は次のとおりです。

• getUserDataResponse - 現在Amazonクライアントにログインしているユーザーのアプリ固有UserDataを提供します。
• PurchaseUpdatesResponse - 開始リクエストで渡されたオフセット以降のレシートとアイテムデータを入手できないSKUを、ページ分割されたリストとして提供します。レシートは、ソートされていない1つのセットとして返されます。
• ProductDataResponse - SKUをキーとしてアイテムデータを提供します。
• PurchaseResponse - アプリ内で開始された購入のステータスを提供します。購入で発生するエラーは開発者から認識できないため、アプリにエラー処理を実装する必要はありません。エラーはアプリ内課金（IAP）APIによって管理されます。

購入ハンドラー

以下のレスポンスハンドラーを実装し、addListenerメソッドでAmazon Servicesライブラリに登録する必要があります。

• getUserDataResponse(userDataResponse) - GetUserDataへのレスポンスとして呼び出されます。
• getProductDataResponse(productDataResponse) - getProductDataへのレスポンスとして呼び出されます。data.productDataMapは、SKUをキーとするproductDataオブジェクトのハッシュテーブルです。
• purchaseResponse(purchaseResponse) - 購入操作のステータスをレポートするために呼び出されます。purchaseResponse.statusにレスポンスのステータスが含まれています。アプリの前回のセッションが購入レスポンスの配信前に終了した場合は、アプリの新しいセッションで購入ハンドラーが登録されたときに、この関数が呼び出されます。
• getPurchaseUpdateResponse(data) - ユーザーに付与された非消費型アイテムのリストと共に呼び出されます。data.receiptsには、SKUをキーとするハッシュテーブルが含まれています。ハッシュテーブルの値は、ユーザーに付与されたIAPのレシートです。

レシートの処理

各レシートに対して、アイテム付与の通知を実装します。レシートを処理するときは、まずレシートがキャンセルされているかどうかを確認します。キャンセルのステータスに応じて、次のいずれかを行います。

• レシートがキャンセルされていて、アイテムがまだ取り消されていない場合は、アイテムを取り消します。
• レシートがキャンセルされていない場合は、次の処理を行います。
  • このreceiptIdに対してアイテム付与が完了しているかどうかを確認します。完了している場合は、このreceiptIdについて、FULFILLEDステータスを指定してnotifyFulfillment()を呼び出します。
  • まだアイテム付与が完了していない場合は、レシートのアイテムを付与します。付与済みのアイテムをトラッキングできるようにreceiptIdを保存してから、receiptIdとFULFILLEDステータスを指定してnotifyFulfillment()を呼び出します。
  • アイテムが以前のゲーム状態に対応するものであった場合や、ゲームでサポートされていない場合など、アイテム付与を完了できないときは、receiptIdとUNAVAILABLEステータスを指定してnotifyFulfillment()を呼び出します。レシートの処理中にエラーが発生した場合は、このステータスを送信しないでください。