开发人员控制台

从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日起,提交到亚马逊应用商店的新的和更新的应用已弃用适用于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和您的应用使用的确切开发工具包(GameSalad或HTML5),以将您的应用标记为待审批:

亚马逊应用商店联系表

从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偏移) 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()将订单标记为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交易关联到特定供应商,并验证您作为开发者是否有权验证交易的收据。

    共享密钥可在亚马逊应用商店中您的开发者账户的“Shared Key”(共享密钥)页面上找到:

    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测试。