アプリ内課金(IAP)をv1.0からv2.0に移行させる


アプリ内課金(IAP)をv1.0からv2.0に移行させる

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

Coronaプラグインを使用中の場合

IAP v1.0向けのCoronaプラグインは、2016年5月11日をもちまして、Amazonアプリストアに申請する新規のアプリおよびアプリのアップデートでは使用できなくなりました。アプリで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を使用することができます。

今後、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への変更点のまとめ

このセクションでは、v1.0からv2.0へのIAP APIの大まかな変更点を説明します。以下の変更点で該当するものがある場合は、このセクションのリストをガイドラインとして使用し、コードベースで対応済みであることをアプリのテストや申請の前に確認しておいてください。

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

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に移行するには次のタスクを実行してください。

  1. アプリのAndroidManifest.xmlファイルを修正します。
  2. IAP v2.0の新しいクラス名とメソッド名を使うようにコードをリファクタリングします。
  3. 購入のアイテム付与とレシートの処理に関連するロジックを実装します。
  4. RVSのURLとレスポンスを更新します。
  5. 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" >
    <intent-filter>
      <action android:name = "com.amazon.inapp.purchasing.NOTIFY"
              android:permission = "com.amazon.inapp.purchasing.Permission.NOTIFY" />
    </intent-filter>
  </receiver>
  ...
</application>

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

IAP v1.0からIAP v2.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を実装する

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

  • 消費型アイテムgetPurchaseUpdates()メソッドは、課金が完了していない消費型アイテムまたはキャンセルされた消費型アイテムの購入レシートを返します。IAP 2.0のonPurchaseUpdatesResponse()では次の点に注意してください。

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

レシートを処理する

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

  • レシートがキャンセルされていて、アイテムがまだ取り消されていない場合は、アイテムを取り消します。
  • レシートがキャンセルされていない場合は、次のように処理します。

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

レシート検証サービス(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/_<developerSecret>_/user/_<userId>_/purchaseToken/_<purchaseToken>_

IAP 2.0では、purchaseTokenreceiptIdに置き換えられたため、次のURLを使用します。

  • https://appstore-sdk.amazon.com/version/1.0/verifyReceiptId/developer/_<SharedSecret>_/user/_<userId>_/receiptId/_<receiptId>_

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

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

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

このURLで指定する項目は次のとおりです。

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

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

    https://developer.amazon.com/sdk/shared-key.html

  • _<receiptId>__<userId>_ はIAP 2.0によって指定されます。

レスポンスフィールドをリマップする

IAP v1.0からIAP v2.0へのレスポンスフィールドのマッピングは次の表のとおりです。

IAP 1.0IAP v2.0
itemTypeproductType
startDatepurchaseDate
endDatecancelDate
skuproductId
purchaseTokenreceiptId

次のコードは、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をインストールして使用します。

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