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，以便开始利用这些新的订阅功能。
管理订阅状态
本节介绍 Google Play 结算系统集成后端组件的主要更改，这些更改需要为迁移到版本 5 而实施。
实时开发者通知
很快，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促销：（无等效字段）；即将推出 |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName、emailAddress、givenName、familyName、profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState（无变化） |
promotionType、promotionCode |
（无等效字段）；即将推出 |
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 Console 进行操作一样。此方法接受任何 Play 支持的货币中的单一价格，并返回所有 Google Play 支持购买的地区的转换价格（包括适用的默认税率）。