アプリ内課金(IAP)v1.0からv2.0への移行
現在、アプリ内課金(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とレスポンスの更新
- アプリのテスト
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を使用することができます。
今後、これらのプラグインを使用するアプリを申請する場合は、アプリの申請プロセスを正しく開始できるように、申請後すぐにAmazonアプリストアにご連絡ください。ご連絡がない場合、申請が拒否される可能性があります。Amazonアプリストアへのご連絡の際は、アプリに承認用フラグを設定できるように、アプリ名、アプリキー、ライブのASIN(Amazon Standard Identification Number)、アプリで使用されている正確なSDK(GameSaladまたはHTML5)をお知らせください。
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アプリストアの開発者アカウントの [共有キー] ページで確認できます。
-
_<レシート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をインストールして使用します。
アプリをローカルでテストした後は、ライブアプリテストサービスを使用して、特定のユーザーグループを対象に本番環境でアプリのベータテストを行うことができます。