Google Play 结算系统是一项服务，可让您在 Android 应用中销售数字商品和内容。借助 2022 年 5 月发布的功能，我们改变了订阅产品的定义方式，这会影响到它们在应用内销售和在后端管理的方式。如果您是首次集成 Google Play Billing，可以先阅读准备工作来开始集成。
如果您在 2022 年 5 月之前通过 Google Play Billing 销售订阅，务必了解如何在采用新功能的同时维护现有订阅。
首先需要了解的是，您的所有现有订阅、应用和后端集成仍可按 2022 年 5 月发布之前的方式正常运行。您无需立即进行任何更改，可以逐步采用这些新功能。每个主要版本的Google Play Billing Library在发布后都会提供两年的支持。与Google Play Developer API的现有集成仍可按之前的方式正常运行。
以下是 2022 年 5 月更新的概览
- 新的Google Play 管理中心可让您创建和管理订阅、基本方案和优惠。这包括新的订阅和迁移的订阅。
- Play Developer API包含更新，以 API 形式支持新的 Google Play 管理中心界面功能。值得注意的是，新版本Subscription Purchases API现已推出。使用此 API 可检查订阅状态并管理订阅购买。
- 新的Play Billing Library 5版本让您的应用能够受益于所有新的订阅功能。当您准备升级到版本 5 时，请遵循迁移指南中的指导。
订阅配置
通过 Google Play 管理中心管理订阅
自 2022 年 5 月起，您会注意到 Google Play 管理中心的一些变化。
单个订阅现在可以包含多个基本方案和优惠。以前创建的订阅 SKU 现在会在 Play 管理中心显示为新的订阅、基本方案和优惠对象。如果您尚未查看，请参阅Play 管理中心近期针对订阅所做的更改，了解这些新对象的说明，包括其功能和配置。您的所有现有订阅产品都以这种新格式显示在 Google Play 管理中心中。如果适用，每个 SKU 现在都由一个订阅对象表示，该对象包含一个基本方案和向后兼容的优惠。
由于较旧的集成预期每个订阅都包含单个优惠（由 SkuDetails 对象表示），因此每个订阅都可以有一个向后兼容的基本方案或优惠。对于使用现已弃用的 querySkuDetailsAsync() 方法的应用，向后兼容的基本方案或优惠会作为 SKU 的一部分返回。如需详细了解如何配置和管理向后兼容的优惠，请参阅了解订阅。一旦您的应用仅使用 queryProductDetailsAsync()，并且不再有旧版本的应用进行购买，您就不再需要使用向后兼容的优惠。
通过 Subscriptions Publishing API 管理订阅
Play Developer API包含用于订阅购买的新功能。inappproducts API（用于 SKU 管理）仍可按之前的方式正常运行，包括处理一次性购买产品和订阅，因此您无需进行任何立即更改来维护您的集成。
但是，务必注意 Google Play 管理中心仅使用新的订阅实体。一旦您开始在管理中心修改订阅，就不能再使用inappproducts API 处理订阅了。
如果您在 2022 年 5 月之前使用过 Publishing API，为避免任何问题，现有订阅现在会在 Google Play 管理中心显示为只读。如果您尝试进行更改，可能会收到一条警告，解释此限制。在管理中心进一步修改订阅之前，您应该更新后端集成，以使用新的 Subscription Publishing 端点。新的 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 更新仅适用于 Publishing API（SKU 管理）。
Play Billing Library 变更
为支持逐步迁移，Play Billing Library 包含了先前版本中可用的所有方法和对象。SkuDetails 对象和诸如 querySkuDetailsAsync() 之类的方法仍然存在，因此您可以升级到使用新功能，而无需立即更新现有订阅代码。您还可以通过将优惠标记为向后兼容来控制哪些优惠可通过这些方法获取。
除了保留旧方法外，Play Billing Library 5 现在还包含一个新的 ProductDetails 对象和相应的 queryProductDetailsAsync() 方法来处理新的实体和功能。现有应用内产品（一次性购买和消耗品）现在也支持 ProductDetails。
对于订阅，ProductDetails.getSubscriptionOfferDetails() 会返回用户有资格购买的所有基本方案和优惠列表。这意味着无论是否向后兼容，您都可以访问用户有资格享受的所有基本方案和优惠。getSubscriptionOfferDetails() 对于非订阅产品返回 null。对于一次性购买，您可以使用 getOneTimePurchaseOfferDetails()。
Play Billing Library 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。
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 |
lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo |
(无对应字段) 此信息可在购买的每个订阅的 offer 中找到。 |
| developerPayload | (无对应字段) developer payload 已弃用 |
| paymentState | (无对应字段) 您可以从 subscriptionState 推断支付状态。
|
cancelReason, userCancellationTimeMillis, cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken（无变化） |
purchaseType |
测试：通过 testPurchase促销： signupPromotion |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName, emailAddress, givenName, familyName, profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState（无变化） |
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 管理中心操作一样。此方法接受任何 Play 支持币种的单一价格，并返回 Google Play 支持购买交易的所有区域的换算价格（包括适用的默认税率）。