从IAP v1.0迁移到IAP v2.0

重要须知： 我们将会废除亚马逊应用内购买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
添加处理履行的逻辑
更新Receipt Verification Service (RVS) URL和响应
- 更新RVS URL
- 重新映射响应字段
测试您的应用

使用Corona插件的开发者注意事项

自2016年5月11日起，对于提交到亚马逊应用商店新应用及更新的应用，已弃用适用于IAP v1.0的Corona插件。如果您的应用使用Corona插件，请迁移应用以使用较新的IAP v2.0 Corona插件：

使用适用于IAP v1.0的GameSalad或HTML5插件的开发者注意事项

虽然亚马逊目前不提供适用于GameSalad或HTML5开发的IAP v2.0插件，但已发布的应用仍可以使用这些插件，尽管自2016年5月11日起已弃用IAP v1.0。

如果您计划提交的应用会使用其中一个插件，请在提交应用后立即联系亚马逊应用商店，以便安排您的应用顺利完成提交过程，否则可能会被拒绝。联系亚马逊应用商店时，请附上应用名称、应用密钥、即时ASIN和您的应用使用的确切SDK（GameSalad或HTML5），以便将您的应用标记为待审批：

亚马逊应用商店联系表

从IAP v1.0升级到v2.0的好处

将您的IAP代码库从v1.0升级到v2.0后，主要好处是让您的应用可以检索未履行的消费品购买。此升级还使应用能够在履行消费品购买后通知亚马逊。

从IAP v1.0到v2.0的更改摘要

本节概述了IAP API v2.0与v1.0相比有何变化。在测试和提交应用之前，请使用本节中的列表作为指导，以验证您是否已在代码库中解决了这些更改（如果适用）。

代码重构

以下列表概述了IAP v2.0中的命名更改。有关这些更改的更多详细信息，请参阅“重构应用的源代码”中的表格。

GetUserIdResponse类现在是UserDataResponse类。
Item类现在是Product类。
PurchasingManager类现在是PurchasingService类。
PurchasingObserver类现在是PurchasingListener类。
子字符串“product”取代了方法和枚举中的子字符串“item”。
子字符串“UserData”取代了方法和枚举中的子字符串“UserId”。
子字符串“get”取代了方法中的子字符串“initiate”。

其他更改和新功能

下面的列表介绍了为IAP 2.0实现的其他更改和新功能：

每个交易现在都具有唯一交易ID。
AndroidManifest.xml文件中android:name属性的值已更改。
对于订阅交易，开始日期和停止日期现在称为购买日期和取消日期。
IAP v2.0包含用于跟踪购买履行状态的新notifyFulfillment API。
Receipt Verification Service (RVS)具有新URL和新响应映射。
App Tester工具取代SDK Tester，用于在本地对应用进行测试。

将您的应用从IAP v1.0升级到v2.0

要将应用从IAP v1.0迁移到IAP v2.0，请执行以下任务：

修改应用的AndroidManifest.xml文件。
重构代码以使用IAP v2.0的新类和方法名称。
实现与处理购买的履行和收据相关的逻辑。
为Receipt Verification Service (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 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偏移)`	`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属性来确定客户使用的亚马逊市场。较旧版本的应用商店可能不提供市场信息。

添加处理履行的逻辑

IAP v2.0的一个新功能是添加了用于跟踪购买履行情况的新方法。这些方法检查购买收据的状态并通知亚马逊商品的履行状态。

实现notifiyFulfillment

IAP 2.0提供了新API，可用于跟踪购买的履行状态。要跟踪购买的履行状态，请实现notifyFulfillment() API。在履行商品后，实现此调用，以将购买状态发送给亚马逊。

在履行商品后，如果您没有使用FULFILLED状态调用notifyFulfillment()，则交付将保持待定状态。在这种情况下，将在您下次调用getPurchaseUpdates()时通过onPurchaseUpdatesResponse()回调继续尝试进行交付。最终，如果亚马逊未收到使用此API对履行的明确确认，则可能会取消订单。
如果您无法履行商品，请使用UNAVAILABLE状态。您可以随时从应用中使用UNAVAILABLE状态调用notifyFulfillment()。

此调用是不可变的。如果通过notifyFulfillment()将订单标记为FULFILLED或UNAVAILABLE，则无法再次更改状态。

实现getPurchaseUpdates

在活动的onStart()或onResume()方法中实现getPurchaseUpdates()。此外，为防止超额履行订单，请根据receiptId删除重复的收据。要了解对于消费品、权利和订阅，实现方法有何具体差异，请参阅以下内容。

消费品：对于消费品，getPurchaseUpdates()方法可返回未履行和已取消的购买收据。在IAP 2.0中实现onPurchaseUpdatesResponse()时，请注意以下事项：
- 请在应用中添加逻辑来处理从getPurchaseUpdates()调用返回的购买收据的履行。相应的PurchasingListener.onPurchaseUpdatesResponse()回调随时可能会发生，包括在应用打开时，所以请谨慎引用可能不可用的用户界面(UI)元素或对象。
- 使用boolean reset参数而非offset参数。将reset设置为true可返回所有购买收据，将reset设置为false可返回自上次getPurchaseUpdates()调用之后新生成的购买收据。
权利：对于权利和订阅，onPurchaseUpdatesResponse()可返回已取消和仍有效的购买的收据。可使用receipt.isCanceled()检查购买是否已取消。在IAP 1.0中，对PurchaseUpdatesResponse对象调用getRevokedSkus()，可返回已取消权利和订阅的收据。
订阅：与权利相同。

处理收据

确认每个已履行的收据。在处理收据时，请先检验收据是否已取消。根据取消状态，执行以下操作之一：

如果收据已取消，而商品尚未撤销，请撤销该商品。
如果收据未取消：
- 检查此receiptId是否已履行。如果已履行，请使用FULFILLED状态为receiptId调用notifyFulfillment()。
- 如果尚未履行，请履行收据。存储receiptId以跟踪已履行的商品，然后使用FULFILLED状态为receiptId调用notifyFulfillment()。
- 如果因商品适用于以前的游戏状态或游戏不支持该商品而无法履行，请使用状态UNAVAILABLE为receiptId调用notifyFulfillment()。如果您在收据处理过程中遇到临时错误，不要发送此状态。

更新Receipt Verification Service (RVS) URL和响应

从IAP v1.0到IAP v2.0，Receipt Verification Service (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 1.0中，使用以下URL进行调用：

https://appstore-sdk.amazon.com/version/2.0/verify/developer/_<developerSecret>_/user/_<userId>_/purchaseToken/_<purchaseToken>_

在IAP 2.0中，receiptId取代了purchaseToken，并使用以下URL：

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

注意：在RVS URL中，“version”字段是指RVS版本号，而非IAP API版本号。

如果使用IAP v1.0，则正确的RVS版本是2.0。
如果使用IAP v2.0，则正确的RVS版本是1.0。

在上面的URL中：

创建账户后，即可在开发者门户上访问_<SharedSecret>_。共享密钥将IAP交易关联到特定供应商，并验证您作为开发者是否有权验证交易的收据。

您可以在亚马逊应用商店开发者账户的“共享密钥”页面上找到您的共享密钥。

https://developer.amazon.com/sdk/shared-key.html
_<receiptId>_和_<userId>_由IAP 2.0提供。

重新映射响应字段

下表显示了从IAP 1.0到IAP 2.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。

在本地测试完应用后，您可以使用动态应用测试服务通过选定的一组用户在生产环境中对应用进行Beta测试。