设置快速订阅

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

快速订阅可减少在Fire TV设备以及应用零售页面上购买订阅时所需的点击次数。借助快速订阅，客户在下载应用、购买订阅和创建权利时，可享受简化的体验。

在典型的账户创建流程中，客户需要进行超过150次点击才能完成账户注册。快速订阅现在提供了一键创建账户功能。借助快速订阅中的一键创建账户功能，客户只需一次点击即可与您的应用共享他们的名字、姓氏、邮政编码和电子邮件地址，这样可以减少客户在创建账户和登录时的摩擦。

用户流程比较
快速订阅如何运行？
设置快速订阅
在开发者控制台中配置快速订阅
在开发者控制台中配置安全配置文件
处理getPurchaseUpdates
确认收据API
与RTN和RVS集成
集成一键创建账户功能
使用LAT测试快速订阅
快速订阅常见问题解答

用户流程比较

下图展示了在不使用快速订阅的情况下，在Fire TV上注册订阅时的典型客户体验。

通过快速订阅，客户在第一步就可以直接从应用详情页面订阅。下图展示了通过快速订阅中的一键创建账户功能在Fire TV上注册订阅时的客户体验。

通过一键创建账户功能，亚马逊会向客户显示同意屏幕，他们可以同意与您的应用共享个人详细信息。如果客户表示同意，则在应用下载并启动后，可以从亚马逊检索客户的详细信息并创建账户。然后，您的应用可以绕过输入凭证的步骤，让客户自动登录。

如果已经集成了快速订阅，但尚未使用一键创建账户功能，则客户不会自动登录，而是需要使用Fire TV遥控器输入其账户凭证才能登录。这种体验不太人性化，平均需要进行超过150次点击。下图展示了不使用快速订阅中的一键创建账户功能在Fire TV上注册订阅时的客户体验。

以下步骤介绍了如何将快速订阅与Fire设备、亚马逊应用内购买 (IAP)、Login with Amazon (LWA)、您的应用和您的服务器配合使用。

步骤1：客户从Fire TV上的应用详情页面发起订阅购买。

步骤2：亚马逊显示同意屏幕，请求客户允许与您的应用共享他们的姓名、邮政编码和电子邮件地址。

步骤3：亚马逊通知客户其购买已完成。

步骤4：应用自动下载并在客户的设备上打开。

步骤5：启动时，应用判定客户是否已登录。如果客户尚未登录，则应用程序从亚马逊IAP调用getUserData()方法，亚马逊返回客户的同意状态。

如果同意状态为CONSENTED（已同意），则应用将执行步骤6到8。否则，应用将回退到默认登录体验。

步骤6：应用调用LWA SDK的authorize()方法来启动会话。

步骤7：应用使用来自LWA的User.fetch()方法来获取客户的详细信息，包括姓名、邮政编码和电子邮件地址。

步骤8：应用使用客户的详细信息来创建新账户或映射到现有账户，然后让客户自动登录。

步骤9：客户登录后，应用在onResume()方法中调用来自亚马逊IAP的getPurchaseUpdates()方法来检索购买收据。

步骤10：应用调用来自IAP的notifyFulfillment()方法，确认购买收据并确认客户有权访问相应内容。或者，如果之前已经集成了确认收据API，则应用会调用acknowledgeReceipt REST API来确认客户已访问相应内容。

步骤11：应用使用购买数据更新您的服务器，并通过调用verifyReceiptIdREST API，使用收据验证服务 (RVS) 对购买数据进行验证。

步骤12：应用允许客户访问相应内容。

注意： 运行Fire OS版本5及更高版本的Fire TV设备以及应用的零售网页支持快速订阅。

要在您的应用中设置快速订阅，请完成以下步骤：

请联系您的亚马逊代表以启用快速订阅。
在开发者控制台中配置快速订阅。
在开发者控制台中配置安全配置文件。
如果尚未集成IAP API，请完成这一步骤，并确保在应用的onResume()方法中处理getPurchaseUpdates。
客户通过快速订阅进行购买后，在客户登录应用后调用notifyFulfillment() API。如果客户在购买后30天内未登录该应用，则会自动取消订阅并退款。有关notifyFulfillment() API的更多信息，请参阅向用户授予商品。
与实时通知 (RTN) 和收据验证服务 (RVS) 集成。RTN和RVS可以提供更多通知，能够更好地管理订阅。
集成一键创建账户功能。

请参阅以下各节，以了解有关必需步骤的更多详细信息。

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

登录开发者控制台。
在应用列表中，找到要设置为使用快速订阅的应用。
在应用程序内商品列中，单击链接打开“应用程序内商品”屏幕。
选择创建快速订阅。
会显示叠加弹出窗口。在选择默认订阅下拉列表中，会使用现有IAP订阅填充该列表。选择要启用快速订阅的订阅。
在选择期限下拉列表中，选择快速订阅的期限。
如果要为快速订阅提供其他订阅，请选择添加其他快速订阅。您最多可以添加四个快速订阅。
勾选相应的复选框，选择快速订阅的目标设备。
选择创建快速订阅。

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

在开发者控制台中配置安全配置文件

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

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

处理getPurchaseUpdates

重要须知： 如果已使用应用内购买，您很可能已将getPurchaseUpdates()集成为IAP设置的一部分。否则，您需要在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)

确认收据API

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

亚马逊使用自动取消来确保客户不会为他们无权访问的订阅继续付款。如果客户在购买后30天内未登录该应用，则会自动取消订阅并退款。请考虑这样一种情况：客户有意进行了购买并访问了订阅，但没有收到确认通知，或者发生延迟。在此情况下，自购买日期起30天后，客户会通过自动取消失去对订阅的访问权限。调用确认收据API可以防止这种情况发生。

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

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

PUT https://appstore-sdk.amazon.com/version/1.0/acknowledgeReceipt?developer={Shared_secret}&user={UserId}=&receiptId={ReceiptId}&fulfillmentResult={FulfillmentResult}

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

查询参数

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

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

响应代码

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

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

确认收据常见问题解答

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

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

与RTN和RVS集成

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

实时通知 (RTN) 可为所有交易提供客户购买信息，包括发生在您应用以外的交易。您的服务器收到来自亚马逊RTN服务器的购买通知后，请使用收据验证服务 (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个月",
  "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`	[映射] <字符串，字符串>	如果购买是通过快速订阅发起的，则值为`{"QuickSubscribe":"true"}`。否则为null。
`quantity`	整数	购买的数量。始终为null或1。
`receiptId`	字符串	购买的唯一标识符。
`renewalDate`	长整数	需要续订订阅购买的日期。日期以纪元以后的毫秒数存储。
`term`	字符串	订阅IAP将保持有效的持续时间（期限从购买之日开始）。期限由数字和时间段（天、周、月、年）构成，如1周或2个月。
`termSku`	字符串	对应于订阅期的唯一SKU。
`testTransaction`	布尔值	表明此购买是否作为亚马逊发布和测试过程的一部分进行。

有关RVS的更多详细信息，请参阅IAP应用的收据验证。

集成一键创建账户功能

按照本指南操作，可将您的应用与一键创建账户功能集成。

先决条件

与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);

//...

  PurchasingService.registerListener(this.getApplicationContext(), purchasingListener);
  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())) {
        lwaManager.startAutoLoginWorkflow();
     }
     break ;

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

如果客户表示同意，请调用来自LWA的authorize()方法以启动会话，并调用User.fetch()方法以获取客户详细信息。使用共享的用户信息，在后端系统中创建账户。

以下代码展示了如何使用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) {
           fetchUserProfileInfo();
      }
      
      //..
   });
}

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

private void fetchUserProfileInfo() {
    User.fetch(context, new Listener<User, AuthError>() {
      //..
      
      @Override
      public void onSuccess(User user) {
          final String name = user.getUserName();
          final String email = user.getUserEmail();
          final String zipCode = user.getUserPostalCode();
          
          // 在后端创建或映射账户并让客户登录
      }
      
      //..
   });

}

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

流程图

下图展示了采用一键创建账户功能的快速订阅代码流程。

您可以使用动态应用测试（LAT）来测试快速订阅。为此，请让您的亚马逊代表为您的LAT应用ASIN启用快速订阅。您可以通过亚马逊零售网站或Fire TV设备测试快速订阅流程。当您开始动态应用测试时，可以向测试者发送邀请。测试者会收到一封电子邮件，其中会附上提供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天的测试时间范围，请联系您的亚马逊代表。

以下是有关快速订阅的常见问题解答(FAQ)。

问：亚马逊是否强制要求开发者移除应用账户创建方可使用快速订阅？: 不强制。快速订阅初次启动时不支持跳过应用账户创建。
问：如果我还提供免费试用版，我可以提供快速订阅吗？: 可以，您可以针对同一订阅产品同时提供快速订阅和免费试用。但是，快速订阅不支持60天免费试用。
问：如果我的客户之前使用过免费试用，会怎么样？: 快速订阅可以检测到之前在亚马逊应用商店上创建的免费试用，并且不会允许客户享受额外的试用期。不过，如果客户在亚马逊之外开始试用，快速订阅将无法检测到此信息，因此客户可能会进入额外的免费试用期。
问：如果客户通过快速订阅购买订阅，并希望在第二台设备上下载该应用，会发生什么情况？: 客户通过快速订阅进行订阅后，订阅会添加到客户的账户中。客户可以使用“仅应用”选项在其他设备上下载应用。然后，客户可以在这些设备上访问其订阅。
问：如果提供促销定价，还可以提供快速订阅吗？: 可以，您可以针对同一订阅产品同时提供快速订阅和促销定价。但是，快速订阅不支持周期为每周或每两周的促销定价。

一键创建账户功能常见问题解答

问：我需要将我的服务器与适用于OAuth的Login with Amazon (LWA) 集成吗？: 不需要，您只需在应用中集成LWA。使用您的应用检索的数据来创建客户账户。使用您的账户管理系统来管理未来客户登录。
问：确认收据API和notifyFulfillment() API之间有什么区别？我是否需要集成这两者？: notifyFulfillment()方法是包含在Appstore SDK中的客户端API，可以确认商品的履行。确认收据API可实现相同的目标，但会利用acknowledgeReceipt操作通过服务器之间的调用来实现。亚马逊应用商店强烈建议您在应用中实现notifyFulfillment() API。如果尚未实现notifyFulfillment()，则可以在服务器端使用确认收据API作为备份选项。
问：如果客户仅通过手机号码使用Login with Amazon (LWA)，他们会获得什么样的体验？: 如果客户仅通过手机号码使用LWA，则LWA会返回一封空白电子邮件，并且应用必须回退到默认登录体验。
问：如果创建账户需要除电子邮件、姓名和邮政编码之外的其他信息，该怎么办？: 如果需要其他信息，则您的应用必须请求客户提供所需的信息。
问： IAP SDK v2.0是否支持一键创建账户功能？: 不支持。必须与Appstore SDK集成才能使用一键创建账户功能。如果应用使用的是采用IAP SDK v2.0的快速订阅，则必须升级为Appstore SDK。Appstore SDK v3.0.5及更高版本支持一键创建账户功能。
问：我可以使用动态应用测试 (LAT) 测试对一键创建账户功能进行测试吗？我可以重置LAT测试者的同意以重新开始测试吗？: 是的，您可以使用LAT测试对一键创建账户功能进行测试。要重置同意，LAT测试者必须转到Manage Login with Amazon（管理Login with Amazon），然后在Manage Connection（管理连接）列中单击Remove（移除）。没有批量撤销同意状态的选项。
问：我可以使用App Tester对一键创建账户功能进行测试吗？: 可以使用App Tester来模拟getUserData() API的同意状态属性。要对集成进行测试，请将对同意状态的响应设置为CONSENTED或UNAVAILABLE。如果返回的状态为CONSENTED，则应用程序应调用Login with Amazon API以获取客户数据并自动让客户登录。如果返回的状态为UNAVAILABLE，则应用程序应回退到默认登录体验。

Last updated: 2024年3月27日

设置快速订阅

用户流程比较

快速订阅如何运行？