Google Play 的计费系统 是一项服务，允许您在 Android 应用中销售数字产品和内容。在 2022 年 5 月发布的版本中，我们更改了订阅产品的定义方式，这会影响它们在应用中的销售方式以及在后端管理的方式。如果您是第一次与 Google Play 计费集成，您可以阅读 准备工作 开始集成。
如果您在 2022 年 5 月之前使用 Google Play 计费销售订阅，则务必了解如何在采用新功能的同时维护现有订阅。
首先要知道的是，您所有现有的订阅、应用和后端集成都与 2022 年 5 月发布之前一样正常工作。您无需立即进行任何更改，并且可以随着时间的推移采用这些新功能。 Google Play 计费库 的每个主要版本在发布后都支持两年。与 Google Play 开发者 API 的现有集成将继续像以前一样工作。
以下是 2022 年 5 月更新的概述
- 新的 Google Play Console 允许您创建和管理订阅、基础套餐和优惠。这包括新订阅和已迁移的订阅。
- Play 开发者 API 包含更新，以 API 形式支持新的 Google Play Console UI 功能。值得注意的是， 订阅购买 API 有一个新版本。使用此 API 检查订阅状态并管理订阅购买。
- 新的 Play 计费库版本 5 允许您的应用受益于所有新的订阅功能。当您准备好升级到版本 5 时，请遵循 迁移指南 中的指导。
订阅配置
通过 Google Play Console 管理订阅
从 2022 年 5 月开始，您会注意到 Google Play Console 中的一些差异。
单个订阅现在可以有多个基础套餐和优惠。先前创建的订阅 SKU 现在在 Play Console 中显示为这些新的订阅、基础套餐和优惠对象。如果您尚未阅读，请参阅 Play Console 中订阅的最新更改，以了解新对象的描述，包括其功能和配置。您所有预先存在的订阅产品都将以这种新格式显示在 Google Play Console 中。每个 SKU 现在都由一个订阅对象表示，该对象包含一个基础套餐和一个向后兼容的优惠（如果适用）。
由于旧版集成期望每个订阅包含单个由 SkuDetails 对象表示的优惠，因此每个订阅可以有一个向后兼容的基础计划或优惠。对于正在使用现已弃用的 querySkuDetailsAsync() 方法的应用，向后兼容的基础计划或优惠将作为 SKU 的一部分返回。有关配置和管理向后兼容优惠的更多信息，请参阅 了解订阅 一旦您的应用仅使用 queryProductDetailsAsync()，并且一旦没有旧版应用仍在进行购买，您就不再需要使用向后兼容的优惠。
通过订阅发布 API 管理订阅
Play 开发者 API 包含订阅购买的新功能。用于 SKU 管理的 inappproducts API 继续按原样工作，包括处理一次性购买产品和订阅，因此您无需立即进行任何更改即可维护您的集成。
但是，请务必注意，Google Play Console 仅使用新的订阅实体。一旦您开始在控制台中编辑订阅，则 inappproducts API 将无法再用于订阅。
如果您在 2022 年 5 月之前使用过发布 API，为了避免任何问题，任何现有订阅现在在 Google Play Console 中均显示为只读。如果您尝试进行更改，可能会收到一条警告，解释此限制。在控制台中进一步编辑订阅之前，您应更新您的后端集成以使用新的订阅发布端点。新的 monetization.subscriptions、monetization.subscriptions.baseplans 和 monetization.subscriptions.offers 端点允许您管理所有可用的基础计划和优惠。您可以在下表中查看不同字段如何从 InAppProduct 实体映射到 monetization.subscriptions 下的新对象
| InAppProduct | Subscription |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
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 更新仅适用于发布 API（SKU 管理）。
Play 结算库更改
为了支持逐步迁移，Play 结算库包含先前版本中提供的所有方法和对象。 SkuDetails 对象和 querySkuDetailsAsync() 等函数仍然存在，因此您可以升级以使用 新功能，而无需立即更新现有订阅代码。您还可以通过将这些优惠标记为向后兼容来控制哪些优惠可用。
除了保留旧版方法外，Play 结算库 5 现在还包括一个新的 ProductDetails 对象和相应的 queryProductDetailsAsync() 方法来处理新的实体和功能。现有的应用内产品（一次性购买和消耗品）现在也受 ProductDetails 支持。
对于订阅，ProductDetails.getSubscriptionOfferDetails() 返回用户有资格购买的所有基础计划和优惠的列表。这意味着您可以访问用户有资格获得的所有基础计划和优惠，而无需考虑向后兼容性。对于非订阅产品，getSubscriptionOfferDetails() 返回 null。对于一次性购买，您可以使用 getOneTimePurchaseOfferDetails()。
Play 结算库 5 还包括用于启动购买流程的新旧方法。如果传递给 BillingClient.launchBillingFlow() 的 BillingFlowParams 对象是使用 SkuDetails 对象配置的，则系统会提取要出售的优惠信息，这些信息来自与 SKU 对应的向后兼容的基础计划或优惠。如果传递给 BillingClient.launchBillingFlow() 的 BillingFlowParams 对象是使用 ProductDetailsParams 对象配置的，这些对象包括 ProductDetails 和一个表示要购买的优惠的特定优惠令牌的 String，则系统会使用这些信息来识别用户获取的产品。
queryPurchasesAsync() 返回用户拥有的所有购买。为了指示请求的产品类型，您可以传入 BillingClient.SkuType 值（如旧版中那样），或者传入包含表示新订阅实体的 BillingClient.ProductType 值的 QueryPurchasesParams 对象。
我们建议您 尽快将您的应用更新 到库的版本 5，以便您可以开始利用这些新的订阅功能。
管理订阅状态
本节介绍需要为迁移到版本 5 而实现的 Google Play 结算系统集成后端组件的主要更改。
实时开发者通知
很快，SubscriptionNotification 对象将不再包含 subscriptionId。如果您依赖此字段来识别订阅产品，则应在收到通知后使用 purchases.subscriptionv2:get 从订阅状态获取此信息。作为购买状态的一部分返回的 lineItems 集合中的每个 SubscriptionPurchaseLineItem 元素都将包含相应的 productId。
订阅购买 API：获取订阅状态
在旧版订阅购买 API 中，您可以使用 purchases.subscriptions:get 查询订阅状态。此端点保持不变，并继续适用于向后兼容的订阅购买。此端点不支持 2022 年 5 月发布的任何新功能。
在新版订阅购买 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 推断付款状态
|
cancelReason、userCancellationTimeMillis、cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken（无变化） |
purchaseType |
测试：通过 testPurchase
促销：(无等效字段)；即将推出 |
价格变更 |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName、emailAddress、givenName、familyName、profileId |
使用 Google 信息订阅 |
确认状态 |
确认状态（无变化） |
promotionType、promotionCode |
(无等效字段)；即将推出 |
externalAccountId、obfuscatedExternalAccountId、obfuscatedExteranlProfileId |
外部账户标识符 |
其他订阅管理功能
虽然 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 Console 进行操作一样。此方法接受任何 Play 支持货币的单个价格，并返回所有 Google Play 支持购买的地区的转换价格（包括适用的默认税率）。