设置快速订阅

重要须知： 目前，快速订阅仅面向部分合作伙伴开放。

有关快速订阅的概述，请参阅快速订阅概述。当您准备好开始操作时，请联系您的亚马逊代表，让他们在您的账户上启用“快速订阅”。然后，按照本页面上的步骤进行操作。

步骤1：在开发者控制台中配置快速订阅
步骤2：配置安全配置文件
步骤3：实现getPurchaseUpdates
步骤4：集成收据验证服务 (RVS)
步骤5：将履行结果发送给亚马逊
步骤6：集成实时通知 (RTN)
步骤7：集成一键账户信息共享功能
步骤8：使用LAT测试快速订阅
相关主题

重要须知

可供客户在应用内购买的任何订阅应该也可通过快速订阅购买，快速订阅中提供的所有订阅都应可在应用内购买。例外情况：如果应用内可供购买的订阅数量达到5个以上，则必须从中选择4个订阅以将其通过快速订阅提供。

要为应用配置快速订阅，请按照以下步骤操作。

登录开发者控制台。
在应用列表中，找到要设置为使用快速订阅的应用。
在应用程序内商品列中，单击链接打开“应用程序内商品”屏幕。
选择创建快速订阅。
随即出现一个叠加弹出窗口，如下图所示。
“创建新的快速订阅”对话框

选择默认订阅下拉列表中列出了现有IAP订阅。选择要启用快速订阅的订阅。
在选择期限下拉列表中，选择快速订阅的期限。
如果要为快速订阅提供其他订阅，请选择添加其他快速订阅。您最多可以添加四个快速订阅。
勾选相应的复选框，选择快速订阅的目标设备。
选择是仅为动态应用测试 (LAT) 创建快速订阅，还是同时为LAT和上线应用创建快速订阅。
- 要仅为LAT创建快速订阅，请选择为测试创建快速订阅。
- 要为LAT和上线应用创建快速订阅，请选择为测试和上线创建快速订阅。
注意： 有关如何使用LAT测试快速订阅的详细信息，请参阅使用LAT测试快速订阅。

创建了快速订阅后，可以选择快速订阅商品对应的操作，删除或修改创建的快速订阅。

步骤2：配置安全配置文件

警告： 确保将正确的安全配置文件附加到您的应用。将安全配置文件附加到应用后，您将无法通过开发者控制台对其进行更改。如果您需要更新附加到应用的安全配置文件，则必须联系亚马逊代表。

要为应用配置安全配置文件，请按照以下步骤操作。

登录开发者控制台。
打开应用列表并选择应用。
选择应用服务，然后滚动到安全配置文件部分。
单击选择现有安全配置文件或新建以展开相关选项。
通过下拉列表选择要映射到该应用的安全配置文件，然后单击启用安全配置文件。或者，也可通过单击创建安全配置文件来创建新的安全配置文件。

步骤3：实现getPurchaseUpdates

重要须知： 要正确地实现快速订阅，您必须在onResume() 方法中调用getPurchaseUpdates()。

getPurchaseUpdates() 方法可获取用户收据。快速订阅使用来自getPurchaseUpdates() 的信息来验证用户的购买状态，从而确保用户能够访问他们有权访问的内容。

在onResume()方法中调用getPurchaseUpdates()。getPurchaseUpdates() 方法使用一个布尔参数：reset。将reset设置为false，可仅返回自上次调用此方法之后生成的新收据。将reset设置为true可返回此用户的所有收据。

@Override
protected void onResume() {
  super.onResume();

//...

  PurchasingService.getUserData();

//...

  PurchasingService.getPurchaseUpdates(false);
}

有关如何集成getPurchaseUpdates() 方法的更多信息，请参阅IAP API文档。

Android—实现getPurchaseUpdates方法
网页应用—getPurchaseUpdates(reset)

实现要求

按照这些要求来正确实现getPurchaseUpdates() 方法。

您必须在Android活动的onResume() 生命周期方法中调用getPurchaseUpdates()。
在onResume() 中调用getPurchaseUpdates() 获取最新收据时，请务必使用false标记。如果使用true标记，它将返回收据的完整历史记录，并且您必须添加额外的筛选逻辑来处理响应。
在您的应用中添加“Restore Purchases”（恢复购买）选项，当客户选择该选项时，该选项会调用带有true标记的getPurchaseUpdates()。
务必保存通过getPurchaseUpdates() 收到的收据，并且必须将该收据映射到应用的登录ID。使用此映射在客户打开应用时解锁其订阅的内容。

步骤4：集成RVS

使用收据验证服务 (RVS)，可以验证应用用户进行的购买。向RVS服务器发出请求后，返回的JSON响应包含一个purchaseMetadataMap字段。如果使用快速订阅发起了购买，则purchaseMetadataMap会显示为{"QuickSubscribe":"true"}，如下例所示。

{
  "autoRenewing": true,
  "betaProduct": false,
  "binCountryCode": null,
  "cancelDate": 1641131573000,
  "cancelReason": 2,
  "deferredDate": null,
  "deferredSku": null,
  "freeTrialEndDate": null,
  "fulfillmentDate": 1641131345000,
  "fulfillmentResult": "FULFILLED",
  "gracePeriodEndDate": null,
  "parentProductId": null,
  "productId": "IntroFreeTrial.sku",
  "productType": "SUBSCRIPTION",
  "promotions": null,
  "purchaseDate": 1641131345000,
  "purchaseMetadataMap": {
      "QuickSubscribe": "true"
  },
  "quantity": null,
  "receiptId": "k9om1rUS7gZJIg8RMfw7AlbxA3aP56ay-vdgeLU40zw=:3:11",
  "renewalDate": null,
  "term": "1 Month",
  "termSku": null,
  "testTransaction": false
}

如果没有使用快速订阅发起购买，则purchaseMetadataMap会显示为null。下表提供了响应对象中所有字段的说明。

字段	数据类型	描述
`autoRenewing`	布尔值	表示客户的订阅是否会自动续订。
`betaProduct`	布尔值	指示所购买的产品是否是动态应用测试产品。
`cancelDate`	长整数	取消购买的日期，或订阅到期的日期。如果购买未取消，则此字段为null。时间以毫秒为单位。
`cancelReason`	整数	指示取消产品的原因。可能的值为null、0、1或2，其中每个整数分别代表一项取消原因： `null` - 购买未取消。 `0` - 当前无法提供取消原因，将在之后提供。 `1` - 客户取消了订单。 `2` - 亚马逊系统取消了购买。例如，客户用于购买订阅的付款无效，并且无法在宽限期内完成购买。如果亚马逊客户支持部门应客户要求取消订单，也会返回此代码。
`freeTrialEndDate`	长整数	表示订阅处于免费试用期内。提供订阅免费试用的结束日期，以epoch（毫秒）为单位。如果订阅不在免费试用期内，则此字段为null。
`fulfillmentDate`	长整数	在订阅购买中，为确认履行的日期。以纪元以后的毫秒数存储。如果未确认订阅履行，则为null。消费品和权利始终为null。
`fulfillmentResult`	字符串	在订阅购买中，履行的状态。有效值： `FULFILLED`：您提供了内容，并且客户使用了内容。 `UNAVAILABLE`：您无法向客户提供内容。如果未确认订阅履行，则为null。消费品和权利始终为null。
`gracePeriodEndDate`	长整数	表示订阅处于宽限期内。提供订阅宽限期的结束日期，以epoch（毫秒）为单位。如果订阅不在宽限期内，则此字段为null。
`parentProductId`	字符串	Null。预留以供将来使用。
`productId`	字符串	您在应用中为此商品定义的SKU。
`productType`	字符串	所购买产品的类型。有效产品类型为`CONSUMABLE`、`SUBSCRIPTION`和`ENTITLED`。
`promotions`	List<Promotion>	订阅购买的促销定价或留存优惠的详细信息。如果没有促销，则为Null。请参阅RVS中的促销。
`purchaseDate`	长整数	购买日期，以纪元以后的毫秒数存储。对于订阅商品，`purchaseDate`代表首次购买日期，而不是后续续订的购买日期。
`purchaseMetadataMap`	Map <String, String>	如果购买是通过快速订阅发起的，则值为`{"QuickSubscribe":true}`。否则为null。
`quantity`	整数	购买的数量。始终为null或1。
`receiptId`	字符串	购买的全局唯一标识符。
`renewalDate`	长整数	需要续订订阅购买的日期。日期以纪元以后的毫秒数存储。
`term`	字符串	订阅IAP将保持有效的持续时间（期限从购买之日开始）。期限由数字和时间段（天、周、月、年）构成，如1周或2个月。
`termSku`	字符串	对应于订阅期的唯一SKU。
`testTransaction`	布尔值	表明此购买是否作为亚马逊发布和测试过程的一部分进行。

有关RVS的更多详细信息，请参阅适用于Appstore SDK IAP的收据验证服务。

步骤5：将履行结果发送给亚马逊

重要须知： 要正确实现快速订阅，必须向亚马逊发送履行结果。

当您发送履行结果时，请确保亚马逊可以确认用户是否可以访问其付费购买的内容。务必将履行结果传达给亚马逊。为此，请使用Appstore SDK中包含的notifyFulfillment() 方法。

客户登录后，在履行订阅后调用状态为FULFILLED的notifyFulfillment()。如果客户已经订阅，请调用状态为UNAVAILABLE的notifyFulfillment()，以表明客户已登录但购买不适用。有关notifyFulfillment() 方法的更多信息，请参阅将履行结果发送给亚马逊并向用户授予商品。

如果您之前已经集成了确认收据API，则可以继续使用它来代替notifyFulfillment() 方法。您必须在应用中使用notifyFulfillment() 方法或确认收据API将履行结果传达给亚马逊。

实现要求

按照这些要求来正确实现notifyFulfillment() 方法。

每次客户打开应用并尝试访问内容时，您都必须调用notifyFulfillment()。
如果您成功将客户映射到收据并为该客户解锁订阅内容，则必须调用状态为FULFILLED的notifyFulfillment()。
如果您确定客户已有订阅，则必须调用状态为UNAVAILABLE的notifyFulfillment()。
如果您因遇到问题而调用了状态为UNAVAILABLE的notifyFulfillment()，请务必在成功将客户映射到收据并解锁客户的订阅内容后，调用状态为FULFILLED的notifyFulfillment()。

确认收据API

注意： 如果这是您首次为应用添加快速订阅，请使用包含在Appstore SDK中的首选notifyFulfillment() 方法，而不是确认收据API。如果已经集成了确认收据API，则可以继续使用它。

亚马逊使用自动取消来确保客户不会为他们无权访问的订阅继续付款。如果客户在购买后30天内未登录该应用，则会自动取消订阅并退款。此外，如果您未发送确认收据，则亚马逊应用商店会在30天后自动取消订阅。

确认收据API使用acknowledgeReceipt操作，可以通知亚马逊订阅购买已履行，这样客户就不会失去访问权限。

acknowledgeReceipt操作是一个REST API，很像RVS中使用的verifyReceiptId操作，但您必须使用PUT请求，而非GET请求。

PUT https://appstore-sdk.amazon.com/version/1.0/acknowledgeReceipt?developer={shared-secret}&user={user-id}=&receiptId={receipt-id}&fulfillmentResult={fulfillment-result}

acknowledgeReceipt操作的版本号为1.0。有关查询参数的更多详细信息，请查阅下表。

查询参数

确认收据API响应使用以下查询参数。

查询参数	描述	必需
developer	用于标识发出请求的开发者的共享密钥。您可以在亚马逊应用商店开发者账户的共享密钥页面上找到您的共享密钥。	是
user	代表亚马逊应用商店应用中不同亚马逊客户的ID： `PurchaseResponse.getUserData().getUserId()`。	是
receiptId	购买的唯一ID： `PurchaseResponse.getReceipt().getReceiptId()` 或`PurchaseUpdatesResponse.getReceipts()` → `Receipt.getReceiptId()`。	是
fulfillmentResult	履行状态。有效值： `FULFILLED`：您提供了内容，并且客户使用了内容。 `UNAVAILABLE`：您无法向客户提供内容。发送此值不会立即取消订单。将在30天后取消订单并退款。有关发送哪个fulfillmentResult的更多详细信息，请参阅调用notifyFulfillment的指南。	是

响应代码

提出HTTP请求后，确认收据API会使用以下代码之一进行响应。

响应代码	描述
HTTP 200	成功：收据ID、用户ID和共享密钥都是有效的。订阅被标记为已履行。
HTTP 400	此receiptId表示的交易无效，或没有找到此receiptId的交易。
HTTP 410	此receiptId表示的交易不再有效。请将其作为已取消的收据。
HTTP 429	该请求已被限制节流。请降低您的调用速率并稍后重试。
HTTP 496	共享密钥无效
HTTP 497	用户ID无效。
HTTP 500	出现内部服务器错误。

确认收据常见问题解答

以下是关于确认收据API的常见问题解答 (FAQ)。

问：应在每次续订后调用确认收据API，还是仅在购买后调用？: 应在购买之后调用确认收据API。
问：已经确认后，如果调用的确认收据API状态为FULFILLED，会发送什么响应？: 多次调用状态为FULFILLED的确认收据API是一种幂等操作，每次都会得到相同的响应。
问：有没有可以还原acknowledgeReceipt操作的方法？如果acknowledgeReceipt的状态已更新为FULFILLED，是否可以将其设置为UNAVAILABLE？: 不可以，acknowledgeReceipt的状态可以从UNAVAILABLE转换为FULFILLED，但不能从FULFILLED转换为UNAVAILABLE。如果发现收据有错误，请联系我们寻求帮助。

步骤6：集成RTN

借助快速订阅，客户可以通过亚马逊订阅您的应用，而不是通过您的应用订阅。这可能会导致您的应用缺少部分关于客户购买状态的信息。getPurchaseUpdates() 方法仅在应用打开时发送数据。

实时通知 (RTN) 可为所有交易提供客户购买信息，包括发生在您应用以外的交易。您的服务器收到来自亚马逊RTN服务器的购买通知后，请使用适用于Appstore SDK IAP的收据验证服务 (RVS) 验证收据。

有关如何设置RTN的详细信息，请参阅使用实时通知。

按照本指南操作，可让您的应用集成一键账户信息共享功能。

先决条件

集成Login with Amazon SDK。有关详细信息，请参阅安装适用于Android的Login with Amazon SDK。
与Appstore SDK版本3.0.5或更高版本集成。有关详细信息，请参阅集成Appstore SDK。

更新应用清单

要向亚马逊应用商店表明您的应用支持一键账户信息共享功能，请使用以下代码更新您的应用清单。

<uses-feature android:name="amazon.lwa.quicksignup.supported"/>

要确定客户是否已同意共享其亚马逊账户详细信息，请在应用主活动的onCreate() 方法中调用getUserData() 方法，同时将UserDataRequest对象的setFetchLWAConsentStatus() 标记设置为true。

以下示例展示了在客户已同意Login with Amazon (LWA) 获取其详细信息的情况下，如何构建UserDataRequest对象并将其传递到getUserData()。

@Override
protected void onCreate(Bundle savedInstanceState) 
{
  super.onCreate(savedInstanceState);

//...

  // 传递要注册的PurchasingListener的引用
  PurchasingService.registerListener(this.getApplicationContext(), purchasingListener);
  // 在isLoggedIn() 中实现逻辑以识别客户的登录状态
  if (!isLoggedIn()) {
     PurchasingService.getUserData(UserDataRequest.newBuilder().setFetchLWAConsentStatus(true).build());
  }
//...
}

如果客户已表示同意，则UserData对象的LWAConsentStatus状态为CONSENTED。如果客户未表示同意，或者同意令牌已过期，则LWAConsentStatus的状态为UNAVAILABLE。

注意： 同意令牌在首次查询后过期。

以下代码展示了如何处理从UserDataResponse对象收到的同意数据。

@Override
public void onUserDataResponse( final UserDataResponse response) {

 final UserDataResponse.RequestStatus status = response.getRequestStatus();

 switch (status) {
   case SUCCESSFUL:
     if (LWAConsentStatus.CONSENTED.equals(response.getUserData().getLWAConsentStatus())) {
        // lwaMager将在后面的部分中实现。
        lwaManager.startAutoLoginWorkflow();
     }
     break ;

   case FAILED:
   case NOT_SUPPORTED:
     // 优雅地失败。
     break ;
 }
}

如果客户表示同意，请从LWA调用authorize() 方法来检索访问令牌，以从您的服务器获取客户的详细信息。有关如何设置服务器的详细信息，请参阅为您的服务器获取客户信息。然后使用客户信息，在后端系统中创建账户。

以下代码展示了如何使用LWAManager为已表示同意的客户启用自动登录。

//..
private RequestContext requestContext;
private Context context;
//..

LWAManager(RequestContext requestContext, Context context) {
   this.requestContext = requestContext;
   this.context = context;
   requestContext.registerListener(new AuthorizeListener() {
      //..
      @Override
      public void onSuccess(AuthorizeResult authorizeResult) {
           signUpAccountWithAccessToken(authorizeResult.getAccessToken());
      }
      
      //..
   });
}

public void startAutoSignupWorkflow() {
    AuthorizationManager.authorize(
          new AuthorizeRequest.Builder(requestContext)
                  .addScopes(ProfileScope.profile(), ProfileScope.postalCode())
                  .build()
   );
           
}

private void signUpAccountWithAccessToken(final String accessToken) {
    // 将accessToken传递给应用的后端API以获取用于创建账户的客户信息。
    // 后端API实现的详细信息可以在以下位置查阅：
    // https://developer.amazon.com/zh/docs/login-with-amazon/customer-profile-other-platforms-cbl-docs.html#get-customer-information-to-your-server 
    invokeAppBackendToCreateAccount(accessToken);
}

[可选] 如果客户不同意，请显示带有 “Login with Amazon” 按钮的登录屏幕。然后，客户可以使用键盘输入凭证或使用 “Login with Amazon” 按钮来登录您的应用。

流程图

下图展示了采用一键账户信息共享功能的快速订阅代码流程。

账户设置的最佳实践

请遵循以下客户账户设置的最佳实践。

如果LWAConsentStatus在getUserData() 响应中的值为CONSENTED，请执行以下操作：
- 从Login with Amazon服务器获取用户信息。使用此信息来创建采用临时密码的登录帐户。无需向客户请求重置密码或提供其他详细信息，即可让客户登录应用。
- 之后，通过电子邮件要求客户重置密码。
如果LWAConsentStatus的值为UNAVAILABLE，请为客户使用默认的应用注册体验。

要使用动态应用测试 (LAT) 测试快速订阅，请先使用在开发者控制台中配置快速订阅中的步骤，在开发者控制台中为LAT配置快速订阅。您可以仅为LAT配置快速订阅，也可以为上线应用和LAT应用配置快速订阅，如下图所示。

如果您选择仅为LAT配置快速订阅，则稍后可以通过选择操作>升级为上线版本，将配置升级到上线应用，如下图所示。

如果您对LAT应用进行的快速订阅配置与对上线应用进行的配置不同，则LAT应用的快速订阅详细信息中会显示测试标签，如下图所示。

您可以通过亚马逊零售网站或Fire设备测试快速订阅流程。当您开始动态应用测试时，可以向测试者发送邀请。测试者会收到一封电子邮件，其中会附上提供LAT版本应用的亚马逊网站链接。

在LAT邀请电子邮件中，选择您所在市场的亚马逊网站。在应用详情页面上，选择订阅选项，该选项显示为订阅期限的付费选项，例如每月20.00美元。然后选择要交付至哪个设备，接着单击Get App（获取应用）。

要开始在设备上测试快速订阅，您可以使用LAT邀请电子邮件或设备通知。

通过LAT邀请进行测试：

使用邀请电子邮件中的链接转到亚马逊网站上的应用详情页面。
选择App Only（仅限应用）选项。
在Deliver to:（交付至）下拉菜单中，选择Cloud Only（仅限云）。
单击Get App（获取应用）。
在与亚马逊账户关联的Fire TV设备上，单击Your Apps & Channels（您的应用和频道）的图标（该图标在导航栏上显示为三个正方形和一个加号）。
找到您应用的LAT版本，该应用的图标上有一个TEST（测试）横幅。您可能需要单击App Library（应用库）才能查看该应用。
选择应用图标以打开设备上的应用详情页面。
选择Subscription Options（订阅选项）并下载应用。

通过通知进行测试：

发送LAT邀请后，与测试者电子邮件相关联的测试设备会收到通知。如果您在通知出现时打开通知，则会进入LAT应用详情页面。此通知会显示5-10秒。如果您在通知首次出现时错过了通知，可以单击设置图标（齿轮图标）并选择Notifications（通知）来查看它。然后您可以阅读通知并转到应用详情页面。选择Subscription Options（订阅选项）并下载应用。

重要须知

在以下情况下，不支持通过LAT测试快速订阅：
- 当您选择要交付到哪个具体设备时，请使用网站上的App Only选项。
- 使用设备上的App Only选项。
要通过LAT就快速订阅以外的目的测试应用，您可以使用App Only选项并选择要将应用交付到哪个具体设备。
在测试快速订阅时关闭加速订阅。
要重置测试账号的快速订阅，可前往开发者控制台为LAT重置订阅。有关详细信息，请参阅为LAT中的所有测试者重置应用内商品或管理单个测试者。
如果您想将30天的取消时间范围缩短为1天的测试时间范围，请联系您的亚马逊代表。

快速订阅测试案例

Last updated: 2024年10月2日

设置快速订阅

步骤1： 在开发者控制台中配置快速订阅

步骤2： 配置安全配置文件

步骤3： 实现getPurchaseUpdates

实现要求

步骤4： 集成RVS

步骤5： 将履行结果发送给亚马逊

实现要求

确认收据API

查询参数

响应代码

确认收据常见问题解答

步骤6： 集成RTN

步骤7： 集成一键账户信息共享功能

先决条件

更新应用清单

实现getUserData并集成Login with Amazon

流程图

账户设置的最佳实践

步骤8： 使用LAT测试快速订阅

在网站上测试快速订阅

在设备上测试快速订阅

相关主题

步骤1：在开发者控制台中配置快速订阅

步骤2：配置安全配置文件

步骤3：实现getPurchaseUpdates

步骤4：集成RVS

步骤5：将履行结果发送给亚马逊

步骤6：集成RTN

步骤7：集成一键账户信息共享功能

步骤8：使用LAT测试快速订阅