アプリ内課金（IAP）v1.0からv2.0への移行

重要： Amazonアプリ内課金（IAP）SDK v2.0（IAP v2.0）は、現状問題なく動作するものの、将来的にサポート終了が予定されています（終了時期は未定）。本ドキュメントには、IAP v2.0 SDKに関する情報が記載されています。最新のエクスペリエンスを提供するには、Appstore SDKを使用してください。

現在、アプリ内課金（IAP）v1.0は廃止となり、IAP v2.0に置き換えられています。新しいバージョンのIAP APIでは、付与が完了していない消費型アイテムの取得、購入された消費型アイテムの付与完了の通知、一意のトランザクションIDの付与を行うことができます。このページでは、IAP v1.0コードベースを使用しているアプリを、IAP v2.0コードベースにアップグレードする方法について説明します。

Coronaプラグインを使用している場合の注意事項
IAP v1.0向けGameSaladプラグインまたはHTML5プラグインを使用している場合の注意事項
IAP v1.0からv2.0にアップグレードするメリット
IAP v1.0からv2.0への変更点のまとめ
- コードのリファクタリング
- その他の変更点と新機能
アプリをIAP v1.0からv2.0にアップグレード
アイテム付与を処理するロジックの追加
レシート検証サービス（RVS）のURLとレスポンスの更新
- RVSのURLの更新
- レスポンスフィールドの再マッピング
アプリのテスト

Coronaプラグインを使用している場合の注意事項

IAP v1.0向けのCoronaプラグインは、2016年5月11日をもって、Amazonアプリストアに申請する新規のアプリおよびアプリのアップデートでは使用できなくなりました。アプリでCoronaプラグインを使用している場合は、下記リンク先を参照して、IAP v2.0向けのCoronaプラグインに移行してください。

IAP v2.0向けCoronaプラグインに関するお知らせ（英語のみ）
IAP v2.0向けCoronaプラグインに関する技術ドキュメント（英語のみ）

IAP v1.0向けGameSaladプラグインまたはHTML5プラグインを使用している場合の注意事項

IAP v1.0は、2016年5月11日をもって廃止されました。現在、AmazonではGameSalad・HTML5開発用のIAP v2.0プラグインを提供していません。ただし、既に公開済みのアプリでは引き続きIAP v1.0を使用することができます。

今後、これらのプラグインを使用するアプリを申請する場合は、アプリの申請プロセスを正しく開始できるように、申請後すぐにAmazonアプリストアにご連絡ください。ご連絡がない場合、申請が拒否される可能性があります。Amazonアプリストアへのご連絡の際は、アプリに承認用フラグを設定できるように、アプリ名、アプリキー、ライブのASIN（Amazon Standard Identification Number）、アプリで使用されている正確なSDK（GameSaladまたはHTML5）をお知らせください。

Amazonアプリストアお問い合わせフォーム

IAP v1.0からv2.0にアップグレードするメリット

IAPコードベースをv1.0からv2.0にアップグレードすると、主なメリットとして、付与が完了していない消費型アイテムの情報をアプリで取得できるようになります。また、購入された消費型アイテムの付与が完了したときにAmazonに通知することもできるようになります。

IAP v1.0からv2.0への変更点のまとめ

このセクションでは、IAP APIがv1.0からv2.0でどのように変わったかを大まかに説明します。アプリをテストして申請する前に、このセクションのリストをガイドラインとして使用して、影響を受ける各変更についてコードベースで対応済みであることを確認してください。

コードのリファクタリング

IAP v2.0では、次に示すような名前の変更が行われています。変更の詳細については、「アプリのソースコードのリファクタリング」の表を参照してください。

GetUserIdResponseクラスはUserDataResponseクラスになりました。
ItemクラスはProductクラスになりました。
PurchasingManagerクラスはPurchasingServiceクラスになりました。
PurchasingObserverクラスはPurchasingListenerクラスになりました。
メソッドと列挙型で、「item」という部分文字列が「product」に変更されました。
メソッドと列挙型で、「UserId」という部分文字列が「UserData」に変更されました。
メソッドで、「initiate」という部分文字列が「get」に変更されました。

その他の変更点と新機能

IAP 2.0に実装されたその他の変更点と新機能は次のとおりです。

各トランザクションに一意のトランザクションIDが割り当てられるようになりました。
AndroidManifest.xmlファイルのandroid:name属性の値が変更されました。
定期購入型トランザクションで、開始日と停止日が購入日とキャンセル日と呼ばれるようになりました。
IAP v2.0には、購入のアイテム付与完了ステータスをトラッキングするための新しいnotifyFulfillment APIが含まれています。
レシート検証サービス（RVS）のURLとレスポンスマッピングが新しくなりました。
アプリをローカルでテストするためのSDK TesterツールがApp Testerツールに置き換えられました。

アプリをIAP v1.0からv2.0にアップグレード

アプリをIAP v1.0からIAP v2.0に移行するには、以下を実行します。

アプリのAndroidManifest.xmlファイルを変更します。
IAP v2.0の新しいクラス名とメソッド名を使用するようにコードをリファクタリングします。
購入のアイテム付与とレシートの処理に関連するロジックを実装します。
レシート検証サービス（RVS）のURLとレスポンスを更新します。
アプリをローカルでテストするためにSDK Testerを使用していた場合は、SDK Testerをアンインストールし、新しいApp Testerアプリをインストールします。

AndroidManifest.xmlファイルの変更

以前のバージョンと現在のバージョンのどちらを使用しているかは、AndroidManifest.xmlファイルを調べることで特定できます。

以前のバージョン：

<receiver android:name = "com.amazon.inapp.purchasing.ResponseReceiver">

現在のバージョン：

<receiver android:name = "com.amazon.device.iap.ResponseReceiver">

次の例は、IAP v2.0を使用するアプリのreceiver要素のandroid:nameに対する正しい値を示しています。

<application>
  ...
  <receiver android:name = "com.amazon.device.iap.ResponseReceiver"
      android:permission = "com.amazon.inapp.purchasing.Permission.NOTIFY" >
    <intent-filter>
      <action android:name = "com.amazon.inapp.purchasing.NOTIFY" />
    </intent-filter>
  </receiver>
  ...
</application>

アプリのソースコードのリファクタリング

IAP v2.0では、多くのクラス名とメソッド名がIAP v1.0から変更されています。次の表を参照して、IAP v2.0の正しい名前を使用するようにコードをリファクタリングしてください。

IAP v1.0の要素名	IAP v2.0の要素名	要素の種類
`GetUserIdResponse`	`UserDataResponse`	クラス
`GetUserIdResponse.getUserId()`	`UserDataResponse.getUserData()`	メソッド
`GetUserIdResponse.GetUserIdRequestStatus`	`UserDataResponse.RequestStatus`	列挙型
`Item`	`Product`	クラス
`Item.getItemType`	`Product.getProductType`	メソッド
`Item.ItemType`	`ProductType`	列挙定数
`ItemDataResponse`	`ProductDataResponse`	クラス
`ItemDataResponse.getItemData()`	`ProductDataResponse.getProductData`	メソッド
`ItemDataResponse.ItemDataRequestStatus`	`ProductDataResponse.RequestStatus`	列挙定数
`PurchasingManager`	`PurchasingService`	クラス
`PurchasingManager.initiateItemDataRequest(java.util.Set <java.lang.String> skus)`	`PurchasingService.getProductData(java.util.Set <java.lang.String> skus)`	メソッド
`PurchasingManager.initiatePurchaseUpdatesRequest (Offset offset)`	`PurchasingService.getPurchaseUpdates(boolean reset)`	メソッド
`PurchasingManager.initiateGetUserIdRequest()`	`PurchasingService.getUserData()`	メソッド
`PurchasingObserver`	`PurchasingListener`	クラス
`PurchasingObserver.onGetUserIdResponse (GetUserIdResponse getUserIdResponse)`	`PurchasingListener.onUserDataResponse (UserDataResponse userDataResponse)`	メソッド
`PurchasingObserver.onItemDataResponse(ItemDataResponse itemDataResponse)`	`PurchasingListener.onProductDataResponse (ProductDataResponse productDataResponse)`	メソッド
`Receipt.getPurchaseToken`	`Receipt.getReceiptId`	メソッド
`token`	`receiptId`	プロパティ

marketplaceプロパティの実装

ユーザーが利用しているマーケットプレイスを確認するには、UserDataクラスのmarketplaceプロパティを使用します。marketplaceプロパティで、ユーザーが利用中のAmazonマーケットプレイスを識別できます。古いバージョンのAmazonアプリストアでは、マーケットプレイス情報が提供されないことがあります。

アイテム付与を処理するロジックの追加

IAP v2.0では、新機能の1つとして、購入のアイテム付与をトラッキングする新しいメソッドが追加されています。これらのメソッドは、購入レシートのステータスをチェックし、アイテム付与のステータスをAmazonに通知します。

notifiyFulfillmentの呼び出し

IAP 2.0には、購入のアイテム付与ステータスをトラッキングするための新しいAPIが用意されています。アイテム付与ステータスをトラッキングするには、notifyFulfillment() APIを呼び出します。アイテム付与の完了後にこの呼び出しを追加して、購入ステータスをAmazonに送信します。

アイテム付与が完了しても、FULFILLEDステータスを指定してnotifyFulfillment()を呼び出さないと、アイテムの配信は保留のままになります。この場合、getPurchaseUpdates()の次回の呼び出し時に、onPurchaseUpdatesResponse()コールバックを通じて配信の試行が続行されます。このAPIによるアイテム付与完了の通知がAmazonに届かないと、最終的に注文がキャンセルされることがあります。
アイテムを付与できない場合は、UNAVAILABLEステータスを使用します。UNAVAILABLEステータスを指定したnotifyFulfillment()は、アプリからいつでも呼び出すことができます。

この呼び出しはイミュータブルです。notifyFulfillment()によって注文をFULFILLEDまたはUNAVAILABLEに設定したら、ステータスを再び変更することはできません。

getPurchaseUpdatesの呼び出し

アクティビティのonStart()メソッドまたはonResume()メソッドで、getPurchaseUpdates()を呼び出します。また、注文に対してアイテムを二重に付与することを防ぐために、receiptIdを使用してレシートの重複を排除します。消費型アイテム、非消費型アイテム、定期購入型アイテムの違いから見た実装の詳細は以下のとおりです。

消費型アイテム： getPurchaseUpdates()メソッドは、付与が完了していない消費型アイテムまたはキャンセルされた消費型アイテムの購入レシートを返します。IAP 2.0のonPurchaseUpdatesResponse()では、次の点に注意してください。
- getPurchaseUpdates()の呼び出しから返された購入レシートについて、アイテム付与を処理するロジックをアプリに追加します。対応するPurchasingListener.onPurchaseUpdatesResponse()コールバックは、アプリが開かれたときや、ほかの任意のタイミングで実行されることがあります。その時点で利用できない可能性のあるユーザーインターフェイス（UI）要素やオブジェクトを参照するときは注意してください。
- offsetパラメーターではなく、boolean型のresetパラメーターを使用します。すべての購入レシートを返すには、resetをtrueに設定します。getPurchaseUpdates()の前回の呼び出し以降に行われた購入のレシートを返すには、resetをfalseに設定します。
非消費型アイテム：onPurchaseUpdatesResponse()は、非消費型アイテムおよび定期購入型アイテムのキャンセルされた購入とアクティブな購入のレシートを返します。購入がキャンセルされたかどうかを確認するには、receipt.isCanceled()を使用します。IAP 1.0では、キャンセルされた非消費型アイテムおよび定期購入型アイテムのレシートは、PurchaseUpdatesResponseオブジェクトのgetRevokedSkus()を呼び出して取得していました。
定期購入型アイテム：非消費型アイテムと同じです。

レシートの処理

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

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

レシート検証サービス（RVS）のURLとレスポンスの更新

IAP v1.0とIAP v2.0では、レシート検証サービス（RVS）にいくつかの変更が加えられています。アプリで生成されたレシートをRVSを使用して検証している場合は、RVSのURLとレスポンスマッピングを更新する必要があります。

RVSによるテストでは、リスナーを登録した後で（registerListener(PurchasingListener listener)）、PurchaseService.IS_SANDBOX_MODE()を呼び出すことができます。アプリがサンドボックスモードの場合はtrueが返され、本番モードの場合はfalseが返されます。

注： IAP v2.0のRVSでは、定期購入型アイテムの更新エンドポイントを呼び出す必要がなくなりました。IAP v2.0のRVSでは、verifyReceiptIdという名前のサービスだけが公開されます。IAP v1.0 RVSのpurchaseTokenのように、リクエストパラメーターの内容を更新する必要はありません。

RVSのURLの更新

IAP v1.0での呼び出しには、次のURLが使用されていました。

https://appstore-sdk.amazon.com/version/2.0/verify/developer/_<開発者シークレット>_/user/_<ユーザーID>_/purchaseToken/_<購入トークン>_

IAP 2.0では、購入トークンがレシートIDに置き換えられ、次のURLが使用されます。

https://appstore-sdk.amazon.com/version/1.0/verifyReceiptId/developer/_<共有シークレット>_/user/_<ユーザーID>_/receiptId/_<レシートID>_

注： RVSのURLの「version」フィールドは、IAP APIのバージョン番号ではなく、RVSのバージョン番号を指しています。

IAP v1.0を使用している場合、正しいRVSのバージョンは2.0です。
IAP v2.0を使用している場合、正しいRVSのバージョンは1.0です。

このURLに指定するフィールドは次のとおりです。

_<共有シークレット>_には、アカウントの作成後に開発者ポータルからアクセスできます。「共有シークレット」とは、IAPトランザクションを特定のベンダーに紐付けし、その開発者にトランザクションのレシートを検証する権利があることを証明するものです。

共有シークレットは、下記Amazonアプリストアの開発者アカウントの [共有キー] ページで確認できます。

https://developer.amazon.com/sdk/shared-key.html
_<レシートID>_と_<ユーザーID>_は、IAP 2.0から渡されます。

レスポンスフィールドの再マッピング

次の表は、IAP v1.0からIAP v2.0へのレスポンスフィールドのマッピングを示しています。

IAP 1.0	IAP 2.0
`itemType`	`productType`
`startDate`	`purchaseDate`
`endDate`	`cancelDate`
`sku`	`productId`
`purchaseToken`	`receiptId`

次のコードは、IAP v2.0でRVSから返されるレスポンスの例です。

{
  "betaProduct": false,
  "cancelDate": null,
  "parentProductId": null,
  "productId": "my.app.sku",
  "productType": "CONSUMABLE",
  "purchaseDate": 138474794983,
  "quantity": 1,
  "receiptId": "WNkddEp39kcA387948nDDhd699C48jdklEnsQQL_Y=:1:31",
  "testTransaction": true
}

アプリのテスト

SDK Testerは、IAP v1.0アプリのテスト用ツールです。IAP v2.0では、このツールがApp Testerツールに置き換えられています。

App TesterはSDK Testerと互換性がないため、IAP v2.0に合わせてアプリのコードをアップグレードするときは、テストに使用するモバイルデバイスからSDK Testerをアンインストールしてください。SDK Testerをアンインストールしたら、アプリ内課金（IAP）をテストするに記載されている手順とリンクに従って、App Testerをインストールして使用します。

アプリをローカルでテストした後は、ライブアプリテストサービスを使用して、特定のユーザーグループを対象に本番環境でアプリのベータテストを行うことができます。