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


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

应用内购买 (IAP) v1.0 现已弃用,并已替换为 IAP v2.0。更新版本的 IAP API 使您的应用能够检索未履行的消费品项目,在履行消费品购买后通知亚马逊,以及提供唯一的交易 ID。本页介绍如何将您的应用从使用 IAP v1.0 代码库升级为使用 IAP v2.0 代码库。

针对使用 Corona 插件的开发者的说明

自 2016 年 5 月 11 日起,为提交到 Amazon Appstore 的新的和更新的应用弃用适用于 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 也是如此。

如果您计划提交一个使用其中一个插件的应用,请在提交您的应用后立即联系 Amazon Appstore 以正确安排您的应用通过提交过程,否则它可能会被拒绝。当您联系 Amazon Appstore 时,请附上您的应用名称、应用键、真实的 ASIN 和您的应用使用的准确软件开发工具包(GameSalad 或 HTML5),以便您的应用可标记为待审批:

Amazon Appstore 联系表

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

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

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

本节概述了 IAP API v1.0 与 v2.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:

  1. 修改您的应用的 AndroidManifest.xml 文件。
  2. 重构您的代码以使用 IAP v2.0 的新类和方法名称。
  3. 实现与处理购买的履行和收据相关的逻辑。
  4. 为 Receipt Verification Service (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"
      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 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 属性来标识客户使用的亚马逊市场。较旧版本的 Appstore 可能没有提供市场信息。

添加逻辑以处理履行

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

实现 notifiyFulfillment

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

  • 如果您没有在履行项目后使用 FULFILLED 状态调用 notifyFulfillment(),则交付将保持挂起。在这种情况下,将在下次您调用 getPurchaseUpdates() 时继续通过 onPurchaseUpdatesResponse() 回调进行交付尝试。​最终,如果亚马逊未收到使用此 API 对履行进行的明确确认,则可能会取消订单。

  • 如果您无法履行项目,请使用 UNAVAILABLE 状态。​您可以随时从您的应用中使用 UNAVAILABLE 状态调用​ notifyFulfillment()

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

实现 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()
    • 如果因项目适用于以前的游戏状态或游戏不支持该项目而无法履行,请使用状态​ UNAVAILABLEreceiptId 调用 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 交易连接到特定供应商并验证作为开发者的您是否有权验证交易的收据。

    共享密钥可在 Amazon Appstore 中您的开发者账户的“Shared Key”(共享密钥)页面上找到:

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

  • _<receiptId>_ and _<userId>_ are provided by 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。

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