2022 年 5 月订阅变更指南

Google Play 结算系统是一项可让您在 Android 应用中销售数字商品和内容的服务。在 2022 年 5 月的版本中，我们更改了订阅商品的定义方式，这项变更将影响您在应用内销售和在后端管理订阅商品的方式。如果您是首次集成 Google Play 结算服务，可以阅读做好准备来开始集成。

如果您在 2022 年 5 月之前一直通过 Google Play 结算服务销售订阅内容，请务必了解如何在保留现有订阅的情况下采用新功能。

首先要知道的是，您的所有现有订阅、应用和后端集成的工作方式与 2022 年 5 月的版本之前相同。您不必立即做出更改，可以逐步采用这些新功能。每个主要版本的 Google Play 结算库在发布后都有两年支持期。与 Google Play Developer API 的现有集成将继续像以前一样工作。

下面概括介绍了 2022 年 5 月的更新：

  • 借助新的 Google Play 管理中心，您可以创建和管理订阅、基础方案和优惠，其中包括新订阅和迁移的订阅。
  • Play Developer API 包含用于支持新的 Google Play 管理中心界面功能（API 形式）的更新。值得注意的是，Subscription Purchases API 现在有了新版本。此 API 用于检查订阅状态和管理订阅购买。
  • 新的 Play 结算库版本 5 可让您的应用受益于所有新的订阅功能。当您准备好升级到版本 5 时，请遵循迁移指南中的指导操作。

订阅配置

通过 Google Play 管理中心管理订阅

自 2022 年 5 月起，Google Play 管理中心会出现一些变化。

单个订阅现在可以有多个基础方案和优惠。以前创建的订阅 SKU 现在会在 Play 管理中心内显示为这些新的订阅、基础方案和优惠对象。请参阅 Play 管理中心内订阅方面的近期变更（如果您尚未查看相关内容），查看有关这些新对象的说明（包括其功能和配置）。此前已有的所有订阅商品都会以这种新格式显示于 Google Play 管理中心内。现在，每个 SKU 都以一个订阅对象表示，该对象包含一个基础方案和向后兼容的优惠（如有）。

由于较旧的集成要求每个订阅包含一个优惠（以 SkuDetails 对象表示），因此每个订阅可以有一个向后兼容的基础方案或优惠。如果应用使用的是现已废弃的 querySkuDetailsAsync() 方法，向后兼容的基础方案或优惠将作为 SKU 的一部分返回。如需详细了解如何配置和管理向后兼容的优惠，请参阅了解订阅。待您的应用仅使用 queryProductDetailsAsync() 并且没有旧版应用仍在进行购买后，您就无需再使用向后兼容的优惠了。

通过 Subscriptions Publishing API 管理订阅

Play Developer API 包含订阅购买方面的新功能。用于 SKU 管理的 inappproducts API 将继续像以前一样工作，包括处理一次性购买商品和订阅，因此您无需立即做出任何更改，即可保留您的集成。

但请务必注意，Google Play 管理中心仅使用新的订阅实体。在管理中心开始修改订阅后，inappproducts API 将无法再用于订阅。

如果您在 2022 年 5 月之前使用过 Publishing API，为避免任何问题，所有现有订阅现在都会在 Google Play 管理中心内显示为只读状态。如果您尝试进行更改，可能会收到说明此限制的警告。在管理中心进一步修改订阅之前，您应该更新后端集成，以使用新的订阅发布端点。新的 monetization.subscriptions、monetization.subscriptions.baseplans 和 monetization.subscriptions.offers 端点可让您管理所有可用的基础方案和优惠。您可以在下表中看到不同字段如何从 InAppProduct 实体映射到 monetization.subscriptions 下的新对象：

InAppProduct 订阅
packageName packageName
sku productId
status basePlans[0].state
prices basePlans[0].regionalConfigs.price
listings 商品详情
defaultPrice 没有对等项
subscriptionPeriod basePlans[0].autoRenewingBasePlanType.billingPeriodDuration
trialPeriod basePlans[0].offers[0].phases[0].regionalConfigs[0].free
gracePeriod basePlans[0].autoRenewingBasePlanType.gracePeriodDuration
subscriptionTaxesAndComplianceSettings taxAndComplianceSettings

这项必需的 API 更新仅适用于 Publishing API（SKU 管理）。

Play 结算库变更

为了支持逐步迁移，Play 结算库囊括了以前的版本中提供的所有方法和对象。SkuDetails 对象和函数（例如 querySkuDetailsAsync()）仍然存在，因此您可以通过升级使用新功能，而不必立即更新现有订阅代码。您还可以通过这些方法将相关优惠标记为向后兼容，从而控制哪些优惠可用。

除了保留旧方法之外，Play 结算库 5 现在还添加了一个新的 ProductDetails 对象和一个对应的 queryProductDetailsAsync() 方法，用于处理新的实体和功能。现在，ProductDetails 也支持现有的应用内商品（一次性购买和消耗品）。

对于订阅，ProductDetails.getSubscriptionOfferDetails() 会返回一个列表，列出用户符合购买条件的所有基础方案和优惠。这意味着，您可以访问用户符合购买条件的所有基础方案和优惠，无论其向后兼容性如何。对于非订阅商品，getSubscriptionOfferDetails() 会返回 null。对于一次性购买，您可以使用 getOneTimePurchaseOfferDetails()。

Play 结算库 5 还包含用于启动购买流程的新方法和旧方法。如果使用 SkuDetails 对象配置传递给 BillingClient.launchBillingFlow() 的 BillingFlowParams 对象，系统会从与 SKU 相对应的向后兼容基础方案或优惠中提取销售信息。如果使用 ProductDetailsParams 对象配置传递给 BillingClient.launchBillingFlow() 的 BillingFlowParams 对象，因为前者包含 ProductDetails 和一个表示购买交易专用优惠令牌的 String，所以系统会使用该信息标识用户将获得的商品。

queryPurchasesAsync() 会返回用户拥有的所有购买交易。如需指明所请求的商品类型，您可以传入一个 BillingClient.SkuType 值（与旧版本一样）或一个 QueryPurchasesParams 对象（包含一个表示新订阅实体的 BillingClient.ProductType 值）。

我们建议您尽快将您的应用更新到该库的版本 5，以便您开始充分利用这些新的订阅功能。

管理订阅状态

本部分将介绍迁移到版本 5 需要实现的 Google Play 结算系统集成后端组件的主要变更。

实时开发者通知

很快，SubscriptionNotification 对象将不再包含 subscriptionId。如果您依靠此字段来标识订阅商品，应进行更新，以便在收到通知后使用 purchases.subscriptionv2:get 从订阅状态中获取此信息。作为购买状态的一部分返回的 lineItems 集合中的每个 SubscriptionPurchaseLineItem 元素都将包含相应的 productId。

Subscriptions Purchases API：获取订阅状态

在以前版本的 Subscriptions Purchases API 中，您可以使用 purchases.subscriptions:get 查询订阅状态。此端点保持不变，仍将适用于向后兼容的订阅购买。此端点不支持 2022 年 5 月发布的任何新功能。

在新版本的 Subscriptions Purchases API 中，使用 purchases.subscriptionsv2:get 获取订阅购买状态。此 API 与迁移的订阅、新订阅（预付费和自动续订）以及各种类型的购买交易兼容。您可以在收到通知后使用此端点检查订阅状态。返回的对象 SubscriptionPurchaseV2 包含一些新字段，但仍包含继续支持现有订阅所需的旧数据。

预付费方案的 SubscriptionPurchaseV2 字段

为了支持由用户延期而不是自动续订的预付费方案，新增了一些字段。所有字段都适用于预付费方案，正如其适用于自动续订型订阅一样，但以下字段除外：

  • [新字段] lineItems[0].prepaid_plan.allowExtendAfterTime：表示何时允许用户再次充值以延长其预付费方案，因为用户一次只能有一笔未用完的充值费用。
  • [新字段] SubscriptionState：指定订阅对象状态。对于预付费方案，此值始终为 ACTIVE、PENDING 或 CANCELED。
  • lineItems[0].expiryTime：对于预付费方案，此字段始终存在。
  • paused_state_context：此字段从不存在，因为预付费方案无法暂停。
  • lineItems[0].auto_renewing_plan：对于预付费方案，此字段不存在。
  • canceled_state_context：对于预付费方案，此字段不存在，因为此字段仅适用于主动取消订阅的用户。
  • lineItems[0].productId：此字段替换了以前版本中的 subscriptionId。

周期性订阅的 SubscriptionPurchaseV2 字段

purchases.subscriptionv2 包含一些新字段，用于提供有关新订阅对象的更多详细信息。下表显示了旧订阅端点中的字段与 purchases.subscriptionv2 中相应字段的对应关系。

SubscriptionPurchase SubscriptionPurchaseV2
countryCode regionCode
orderId latestOrderId
（无等效字段） lineItems（SubscriptionPurchaseLineItem 的列表），表示通过购买获得的商品
（无等效字段） lineItems.offerDetails.basePlanId
（无等效字段） lineItems.offerDetails.offerId
（无等效字段） lineItems.offerDetails.offerTags
startTimeMillis startTime
expiryTimeMillis lineItems.expiryTime（购买交易中获得的每项订阅都有自己的 expiryTime）
（无等效字段） subscriptionState（表示订阅的状态）
（无等效字段） pausedStateContext（仅当订阅状态为 SUBSCRIPTION_STATE_PAUSED 时才存在）
autoResumeTimeMillis pausedStateContext.autoResumeTime
（无等效字段） canceledStateContext（仅当订阅状态为 SUBSCRIPTION_STATE_CANCELED 时才存在）
（无等效字段） testPurchase（仅在已获许可的测试人员购买交易中才存在）
autoRenewing lineItems.autoRenewingPlan.autoRenewEnabled
priceCurrenceCode、priceAmountMicros、introductoryPriceInfo （无等效字段）
可在购买的每项订阅的 basePlan/offer 中找到此信息。
developerPayload （无等效字段）开发者载荷已被废弃
paymentState （无等效字段）
可根据 subscriptionState 推断付款状态：
  • 付款正在等待处理：
    • SUBSCRIPTION_STATE_PENDING（具有待处理交易的新购买交易）
    • SUBSCRIPTION_STATE_IN_GRACE_PERIOD
    • SUBSCRIPTION_STATE_ON_HOLD
  • 付款已收讫：
    • SUBSCRIPTION_STATE_ACTIVE
  • 免费试订：
    • （无等效字段）
  • 延迟升级/降级：
    • SUBSCRIPTION_STATE_PENDING
cancelReason、userCancellationTimeMillis、cancelSurveyResult canceledStateContext
linkedPurchaseToken linkedPurchaseToken（无更改）
purchaseType 测试：通过 testPurchase
促销：signupPromotion
priceChange lineItems.autoRenewingPlan.priceChangeDetails
profileName、emailAddress、givenName、familyName、profileId subscribeWithGoogleInfo
acknowledgementState acknowledgementState (no change)
promotionType、promotionCode signupPromotion
externalAccountId、obfuscatedExternalAccountId、obfuscatedExteranlProfileId externalAccountIdentifiers

其他订阅管理函数

虽然 purchases.subscriptions:get 已升级到 purchases.subscriptionsv2:get，但 purchases.subscriptions 端点中的其余开发者订阅管理函数目前保持不变，因此您可以像以前一样继续使用 purchases.subscriptions:acknowledge、purchases.subscriptions:cancel、purchases.subscriptions:defer、purchases.subscriptions:refund 和 purchases.subscriptions:revoke。

定价 API

您可以使用 monetization.convertRegionPrices 端点计算地区性价格，就像通过 Play 管理中心计算一样。对于可通过 Google Play 进行购买的所有地区，此方法接受 Play 支持的任意币种的单个价格，并返回相应地区的换算价格（包括适用的默认税率）。