ウェブアプリのアプリ内課金(IAP)APIに関するメソッド


ウェブアプリのアプリ内課金(IAP)APIに関するメソッド

ウェブアプリにIAPを実装するために、Amazon Services JavaScriptライブラリに対する一連のレスポンスハンドラーが用意されています。

アプリ内課金(IAP)APIは、AmazonServicesとレスポンスハンドラーという2つの主要コンポーネントで構成されています。レスポンスハンドラーは初期化の際に実装し、Amazon Servicesライブラリに引数として渡します。

そのライブラリをインクルードするには、次の<script>タグをウェブアプリに追加します。

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

Amazon Service

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に設定されると、ステータスを再び変更することはできません。

ProductData

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

PurchaseReceipt

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

Reset

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

レスポンスオブジェクト

AmazonServicesを使用して呼び出しを行うと、addListener()メソッドで指定された、対応するレスポンスハンドラーによってレスポンスが受信されます。これらのレスポンスでは、それぞれ1つのレスポンスオブジェクトが使用されます。レスポンスの詳細は次のとおりです。

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

購入ハンドラー

以下のレスポンスハンドラーを実装し、AmazonServicesでaddListenerに登録する必要があります。

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

レシートを処理する

アイテム付与の通知をレシートごとに実装します。レシートを処理するときは、まずレシートがキャンセルされているかどうかをチェックします。キャンセルのステータスに応じて、下記のいずれかを行います。

  • レシートがキャンセルされていて、アイテムがまだ取り消されていない場合は、アイテムを取り消します。
  • レシートがキャンセルされていない場合は、次のように処理します。
    • このreceiptIdについてアイテム付与が完了しているかどうかをチェックします。完了している場合は、FULFILLEDステータスを指定してreceiptIdのnotifyFulfillment()を呼び出します。
    • まだアイテム付与が完了していない場合は、このレシートのアイテムを付与します。既に付与されたアイテムをトラッキングするためのreceiptIdを格納し、FULFILLEDステータスを指定してnotifyFulfillment()を呼び出します。
    • アイテムが以前のゲーム状態向けであるか、ゲームでサポートされていないためにアイテム付与ができない場合は、UNAVAILABLEステータスを指定してreceiptIdのnotifyFulfillment()を呼び出します。レシートの処理中にエラーが発生した場合は、このステータスを送信しないでください。