订阅加购服务

含加购项的订阅可让您将多个订阅产品捆绑在一起，以便一起购买、结算和管理。您可以将现有产品目录订阅无缝地作为加购项提供，而无需任何预先指定或额外配置。您可以启动包含多个现有订阅产品的购买流程，并将这些产品作为加购项进行销售。

注意事项

使用含附加项的订阅功能时，请考虑以下几点：

• 含附加服务的订阅仅支持自动续订型基础方案。

• 购买交易中的所有商品必须具有相同的周期性结算周期。例如，您不能拥有按年结算的订阅，但附加服务却按月结算。

• 如果购买了加购项，订阅中最多可以包含 50 项内容。

• 此功能在印度 (IN) 和韩国 (KR) 地区不可用。

与 Play 结算库集成

本部分介绍了如何将“含附加项的订阅”功能与 Play 结算库 (PBL) 集成。本文假定您熟悉初始 PBL 集成步骤，例如向应用添加 PBL 依赖项、初始化 BillingClient 和连接到 Google Play。本部分重点介绍与含附加项的订阅相关的 PBL 集成方面。

启动购买流程

如需为包含附加服务的订阅启动购买流程，请执行以下步骤：

1. 使用 BillingClient.queryProductDetailsAsync 方法提取所有订阅项。

2. 为每个商品设置 ProductDetailsParams 对象。

   由 ProductDetailsParams 对象表示的商品，用于指定表示订阅商品的 ProductDetails 和选择特定订阅 base plan 或 offer 的 offerToken。

3. 在 BillingFlowParams.Builder.setProductDetailsParamsList 方法中指定商品详情。BillingFlowParams 类用于指定购买流程的详细信息。

   以下示例展示了如何针对包含多个商品的订阅购买交易启动结算流程：

   Java

      BillingClient billingClient = …;
   
       // ProductDetails obtained from queryProductDetailsAsync().
       ProductDetailsParams productDetails1 = ...;
       ProductDetailsParams productDetails2 = ...;
       ArrayList productDetailsList = new ArrayList<>();
       productDetailsList.add(productDetails1);
       productDetailsList.add(productDetails2);
   
       BillingFlowParams billingFlowParams =
           BillingFlowParams.newBuilder()
              .setProductDetailsParamsList(productDetailsList)
              .build();
       billingClient.launchBillingFlow(billingFlowParams);

适用于购买交易中商品的规则

• 为确保加购项续订日期最终与基础商品的续订日期保持一致，Google Play 可能会在任何试用或促销价格阶段结束后插入按比例计算的费用。
• 系统会针对每件商品单独评估优惠资格。

处理购买交易

处理含附加项的订阅与处理单件商品购买交易相同，如将 Google Play 结算库集成到您的应用中中所述。唯一的区别是，用户可以通过一次购买交易获得多项授权。购买包含加购项的订阅会返回多个商品，这些商品可以使用 Google Play 结算库中的 Purchase.getProducts() 进行检索，然后使用 Google Play Developer API 的 purchases.subscriptionsv2.get 中的 lineItems 列表进行检索。

修改包含加购项的订阅

对含附加服务的订阅所做的任何更改都会导致升级或降级。如需了解详情，请参阅升级或降级订阅。

如需在应用中更改或恢复包含加购项的现有订阅购买交易，您必须使用其他参数调用 launchBillingFlow API，并确保满足以下条件：

• 始终使用当前订阅购买交易的购买令牌调用 setOldPurchaseToken。
• 如需升级、降级或交叉升级商品，请调用 SubscriptionProductReplacementParams.setReplacementMode 以指定应如何在旧购买商品和新购买商品之间处理方案变更。否则，无需设置此参数。
• 即使基本项未发生变化，您仍然可以调用 SubscriptionProductReplacementParams.setSubscriptionReplacementMode 来应用特定的替换行为。如需了解此情形下的适用规则，请参阅重新订阅或在同一订阅中切换方案。
• 新加购项将立即生效，并按比例收取费用，以使下一个续订日期与订阅中的基础商品保持一致。
• 移除的加购项将在当前结算周期结束时失效。
• 启动结算流程时，您需要指定含加购项的订阅中的所有有效商品（要移除的商品除外），以及所有新加购项。

以下示例展示了在更改包含加购项的现有订阅购买交易时，如何调用 launchBillingFlow API：

BillingClient billingClient = …;

int replacementMode =…;

// ProductDetails obtained from queryProductDetailsAsync().
ProductDetailsParams productDetails1 = ...;
ProductDetailsParams productDetails2 = ...;
ProductDetailsParams productDetails3 = ...;

ArrayList newProductDetailsList = new ArrayList<>();
newProductDetailsList.add(productDetails1);
newProductDetailsList.add(productDetails1);
newProductDetailsList.add(productDetails1);

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setSubscriptionUpdateParams(
          SubscriptionUpdateParams.newBuilder()
              .setOldPurchaseToken(purchaseTokenOfExistingSubscription)
              // No need to set if change does not affect the base item.
             .setSubscriptionReplacementMode(replacementMode)
             .build())
        .setProductDetailsParamsList(productDetailsList)
        .build();

billingClient.launchBillingFlow(billingFlowParams);

订阅修改方案

下表列出了含加购项的订阅的各种修改场景，以及相应的行为。

使用 SubscriptionProductReplacementParams 时

使用 SubscriptionUpdateParams 时

实时开发者通知

对于包含多个商品使用权的附加服务订阅的购买交易，RTDN 中未提供 subscriptionId 字段。不过，您可以使用 Play Developer API 获取购买交易并查看关联的商品使用权。

适用于现有订阅者的价格变动

更改包含加购项的订阅的现有订阅者的订阅价格，与更改单项订阅的订阅价格类似，如更改订阅价格中所述。不过，如本部分所述，存在一些限制和功能差异。

停用旧价格同类群组

停用旧同类群组也会影响包含加购项的订阅购买交易。以下规则适用：

• 所有未完成的“用户选择接受才生效”类型的价格上调都应与新价格具有相同的续订时间。如果含加购项的订阅中的某项商品的价格上调采用“用户接受才生效”机制，但用户尚未确认，那么除非其他商品的新价格上调会导致新价格的生效续订时间与处于 OUTSTANDING 状态的现有价格上调相同，否则系统会忽略其他商品的新价格上调。用户确认价格上调后，系统会注册任何更新的价格变动。 用户只能一次性接受所有未确认的“用户选择接受才生效”类型的价格上调。

  示例：

  • 假设某订阅包含加购项（商品 A 和 B），每月 7 日续订。
  • 商品 A 的价格目前正在从 7 美元迁移到 10 美元，预计价格上调将于 7 月 7 日生效。
  • 商品 B 的新价格迁移（从 5 美元到 6 美元）于 6 月 2 日开始。由于“用户选择接受才生效”类型的价格上调会在迁移后 37 天开始生效，因此商品 B 的最早价格上调时间为 8 月 7 日。

  在这种情况下，在用户接受商品 A 的价格变动之前（即在商品 A 的价格变动处于 CONFIRMED 状态之前），系统不会为相应订阅购买交易注册商品 B 的价格变动，并且 SubscriptionPurchaseV2 不会返回商品 B 的价格变动详情。在用户确认商品 A 的价格变动后，商品 B 的价格变动开始。用户只有在接受商品 A 的“用户接受才生效”价格上调后，才会收到商品 B 的“用户接受才生效”价格上调。

• Google Play 的电子邮件包含一份列表，其中列出了所有价格上调或下调的商品，这些价格变动会在同一天生效。

取消包含加购项的订阅

用户可以在 Play 订阅中心内取消包含加购项的整个订阅，而您只能使用 Google Play Developer API 取消包含加购项的整个订阅。

如果取消订阅购买交易，但不撤消交易，则购买交易中的所有商品都不会自动续订，但用户在相应结算周期结束之前仍可继续访问有权访问的商品。

撤消含加购项的订阅并退款

以下是有关撤消和退款订阅的一些准则：

• 使用 Play 管理中心为特定订单发放基于金额的退款，而无需撤消订阅访问权限。

• 调用 orders.refund 可全额退还用户已支付的特定订阅款项，而不会撤消用户对相应订阅的访问权限。

• 调用 purchases.subscriptionsv2.revoke 可立即撤消对所有订阅商品的访问权限。借助此 API，您可以：

  • 撤消对所有商品的访问权限，并提供按比例退款。

  • 如果使用按比例退款的方式撤消含加购项的订阅，系统会针对每个商品的最新订单按比例退款，退款金额取决于距离下次续订的剩余时间。

  • 撤消对所有商品的访问权限，并提供全额退款。

  • 撤消单个商品的访问权限，并全额退还该商品的款项。

撤消包含加购项的订阅中的单个商品

如需在不撤消整个购买交易的情况下撤消含附加项的订阅中的单个订阅项，请在 RevocationContext 中设置 ItemBasedRefund 字段，然后调用 purchases.subscriptionsv2.revoke。应撤消并退款的商品的 productId 可在 ItemBasedRefund 字段中设置。

对于包含一项或多项自动续订型订阅商品的购买交易，可以设置 ItemBasedRefund 字段。

• 如果撤消 ItemBasedRefund 中指定的商品后，订阅购买交易中仍有有效商品，则只会撤消该商品，并全额退款，而不会中断订阅状态。
• 如果撤消 ItemBasedRefund 中指定的商品后，订阅购买交易中不再有有效商品，则该商品会被撤消并全额退款，且订阅会被取消。

注意事项

• 使用 ItemBasedRefund 时，一次只能撤消一项内容。 如果需要撤消不同的商品，可以多次调用该请求。
• 当订阅购买交易处于任何付款遭拒状态，或者 ItemBasedRefund 中指定的商品未被拥有或已过期时，商品关闭会被阻止。
• 预付费订阅不支持调低商品价格。

付款遭拒期间商品过期

对于购买了附加服务的订阅，某些续订可能只需要延长部分商品使用权，而不会影响未来到期的商品。

无论续订涉及哪些商品，如果续订付款遭拒，整个订阅购买交易都会进入宽限期，并且账号会进入中止状态，如下面的文档中所述。

恢复期选择

由于宽限期本身仍会授予用户使用权，因此在购买包含加购项的订阅后，如果续订付款遭拒，系统会选择所有有效商品中宽限期最短的商品，并将其宽限期和账号冻结期作为恢复期应用于此次续订。

有效商品包括在续订尝试之前购买含附加项的订阅时有效的商品，但不包括任何新添加的商品（在恢复之前不会获得授权），也不包括因移除或停用而不再有效的任何商品。

系统会应用所选最短宽限期商品的账号冻结设置。如果有多件商品的最短宽限期相同，但账号冻结期不同，则系统会应用最长的账号冻结期。

宽限期

当订阅续订付款遭拒时，相应订阅购买交易将进入宽限期状态。在宽限期内，用户将继续有权访问上一个续订周期中的所有有效内容。宽限期结束后，如果付款方式仍未修正，整个订阅购买交易将进入账号保留状态。如果在宽限期内有任何其他商品的续订日期到来，那么在订阅因付款遭拒而恢复后，系统会立即尝试为这些商品收取新费用。

账号保留功能

在订阅购买交易处于账号保留状态期间，用户将无法访问所有订阅内容，直到付款恢复为止。

如果恢复了处于账号保留状态的订阅，则订阅购买会继续保持现有状态。如果未恢复订阅，则付款遭拒的商品将过期，而其他商品的使用权限将在剩余结算周期内恢复。

示例：

• 某用户订阅了我的基础方案，该方案每月 1 日续订。然后，该用户在 8 月 15 日添加了附加方案，该方案每月 10 美元，并提供 7 天免费试用期。这两项商品均未设置宽限期，且账号保留期均为 30 天。

• 8 月 22 日，系统会向用户收取 2.90 美元（10*9/31），以按比例计算 8 月 31 日之前的费用，但用户的付款方式在此之前已过期，因此订阅在 8 月 22 日进入付款被拒状态。

如果订阅因付款被拒而进入账号保留状态，用户将无法访问包含加项的订阅中的任何内容。当订阅因付款已恢复或已取消而退出账号保留状态时，系统会将未续订的商品的剩余时间返还给用户。

在前面的示例中，订阅于 8 月 22 日进入账号保留状态。

• 如果用户在 9 月 1 日的续订截止日期之前（即 8 月 25 日）恢复了账号，则当天即可重新获得基础方案和加购方案的访问权限。下一个结算日期已更改为 9 月 4 日。

• 如果 30 天后仍未恢复账号，则订阅将于 9 月 21 日取消，用户将无法再使用加购方案，但可以继续使用我的基础方案，直到 9 月 30 日。

在此示例中，您必须获取包含附加服务的订阅中所有商品的更新后的 expiryTime，因为某些商品可能会在宽限期和账号中止期结束后恢复其使用权。

财务报告和对账

您可以使用收入报告来核对有效订阅与 Play 上的交易。每个交易订单项都有一个订单 ID。如果购买交易涉及多件商品，“收入”和“估算的销售额”报告将针对每件商品涉及的每笔交易（例如扣款、费用、税费和退款）分别显示一行。

对于 Play 管理中心内的信息中心：

• 控制台财务报告部分中显示的收入统计信息按商品细分。

• 订单管理反映了包含加购项的订阅购买交易，并显示了所购商品的明细列表。在订单管理中，您可以撤消、取消或全额退款给用户。