本主题包含 Google Play 结算库的版本说明。
Google Play 结算库 7.0.0 版 (2024-05-14)
7.0.0 版 Google Play 结算库和 Kotlin 扩展现已推出 可用。
变更摘要
添加了 API 以支持分期付款订阅。
- 添加了
ProductDetails.InstallmentPlanDetails
。此 API 帮助您的应用确定分期付款方案及其承诺设置 以向用户提供相关信息。如需了解详情,请参阅我们的 分期付款指南。
- 添加了
添加了
PendingPurchasesParams
和BillingClient.Builder.enablePendingPurchases(PendingPurchaseParams)
以替换BillingClient.Builder.enablePendingPurchases()
, 此版本已弃用。- 已废弃的
enablePendingPurchases()
在功能上等同于enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
。
- 已废弃的
添加了 API,以支持订阅预付费方案的待处理交易:
- 使用
PendingPurchasesParams.Builder.enablePrepaidPlans()
以及BillingClient.Builder.enablePendingPurchases(PendingPurchaseParams)
为订阅预付费方案启用待处理的交易。添加 支持,请确保您的应用也正确管理订阅 生命周期如需了解详情,请参阅我们的 “待处理的购买交易”指南。 - 添加了
Purchase.PendingPurchaseUpdate
和Purchase.getPendingPurchaseUpdate()
检索待处理的充值、升级或降级到现有 订阅。
- 使用
移除了
BillingClient.Builder.enableAlternativeBilling()
,AlternativeBillingListener
, 和AlternativeChoiceDetails
。移除了
BillingFlowParams.ProrationMode
,BillingFlowParams.SubscriptionUpdateParams.Builder.setReplaceProrationMode()
, 和BillingFlowParams.SubscriptionUpdateParams.Builder.setReplaceSkusProrationMode()
。- 开发者应使用
BillingFlowParams.SubscriptionUpdateParams.ReplacementMode
与BillingFlowParams.SubscriptionUpdateParams.Builder#setSubscriptionReplacementMode(int)
共享 。 BillingFlowParams.SubscriptionUpdateParams.Builder.setReplaceProrationMode()
。BillingFlowParams.SubscriptionUpdateParams.Builder.setReplaceSkusProrationMode()
。
- 开发者应使用
移除了
BillingFlowParams.SubscriptionUpdateParams.Builder#setOldSkuPurchaseToken()
。BillingClient.queryPurchaseHistoryAsync()
已弃用,并将在未来的版本中移除。开发者应 请改用以下替代方案:- 已确认的购买交易和待处理的购买交易:使用
BillingClient.queryPurchasesAsync()
来获取有效购买交易 - 消耗的购买:开发者应在 自己的服务器
- 已取消的购买:请使用 voided-purchases 和开发者 API。
- 有关详情,请参阅 查询交易记录
- 已确认的购买交易和待处理的购买交易:使用
BillingFlowParams.ProductDetailsParams.setOfferToken()
现在,当开发者指定空的offerToken
时,会抛出异常。将
minSdkVersion
更新为 21,将targetSdkVersion
更新为 34。
Google Play 结算库 6.2.1 版 (2024-04-16)
6.2.1 版 Google Play 结算库和 Kotlin 扩展现已推出 可用。
变更摘要
- 修复了
BillingClient.showAlternativeBillingOnlyInformationDialog()
中的 bug:在对话框完成时,在某些情况下可能无法调用AlternativeBillingOnlyInformationDialogListener
。
Google Play 结算库 6.2.0 版 (2024-03-06)
6.2.0 版 Google Play 结算库和 Kotlin 扩展现已推出 可用。
变更摘要
- 新增了 API 以支持外部优惠
<ph type="x-smartling-placeholder">
- </ph>
- 添加了
BillingClient.Builder.enableExternalOffer()
以实现提供外部优惠的功能。 - 添加了
BillingClient.isExternalOfferAvailableAsync()
检查是否可以提供外部优惠功能。 - 添加了
BillingClient.showExternalOfferInformationDialog()
用于在将用户引导至应用外部之前向用户显示信息对话框。 - 添加了
BillingClient.createExternalOfferReportingDetailsAsync()
,用于创建所需载荷,以便报告通过外部优惠进行的交易。
- 添加了
Google Play 结算库 6.1.0 版 (2023-11-14)
6.1.0 版 Google Play 结算库和 Kotlin 扩展现已推出。
变更摘要
- 添加了 API,以支持仅限备选结算系统(即无需用户自选)的结算方式
- 添加了
BillingClient.Builder.enableAlternativeBillingOnly()
,用于启用相关功能,以提供仅限备选结算系统的结算方式。 - 添加了
BillingClient.isAlternativeBillingOnlyAvailableAsync()
,用于检查是否可以提供仅限备选结算系统的结算方式。 - 添加了
BillingClient.showAlternativeBillingOnlyInformationDialog()
,用于显示信息对话框,以便在使用仅限备选结算系统的结算方式时通知用户。 - 添加了
BillingClient.createAlternativeBillingOnlyReportingDetailsAsync()
,用于创建所需载荷,以便在使用仅限备选结算系统的结算方式进行交易时报告相关交易。
- 添加了
- 更新了用户自选结算方式 API
- 添加了
UserChoiceBillingListener
,以取代标记为已废弃的 AlternativeBillingListener。 - 添加了
UserChoiceDetails
,以取代标记为已废弃的AlternativeChoiceDetails
。 - 添加了
BillingClient.Builder.enableUserChoiceBilling()
,以取代标记为已废弃的BillingClient.Builder.enableAlternativeBilling()
。
- 添加了
- 添加了
BillingClient.getBillingConfigAsync()
,以检索 Google Play 国家/地区。
Google Play 结算库 6.0.1 版 (2023-06-22)
6.0.1 版 Google Play 结算库和 Kotlin 扩展现已推出。
变更摘要
更新 Play 结算库以与 Android 14 兼容。
Google Play 结算库 6.0 版 (2023-05-10)
6.0.0 版 Google Play 结算库和 Kotlin 扩展现已推出。
变更摘要
添加了新的
ReplacementMode
枚举,以取代ProrationMode
。请注意,为实现向后兼容性,
ProrationMode
仍然可用。移除了
PENDING
购买交易的订单 ID。之前,即使购买交易仍待处理,系统一律会创建订单 ID。从 6.0.0 版开始,系统不再为待处理的购买交易创建订单 ID。当购买交易变为
PURCHASED
状态后,系统才会为这类购买交易填充订单 ID。移除了
queryPurchases
和launchPriceConfirmationFlow
方法。从 Play 结算库 6.0.0 中移除了之前标记为已废弃的
queryPurchases
和launchPriceConfirmationFlow
方法。开发者应使用queryPurchasesAsync
,而不是queryPurchases
。如需了解launchPriceConfirmationFlow
替代方法,请参阅价格变动。新增了网络连接错误响应代码。
从 PBL 6.0.0 版开始,新增了网络连接错误响应代码
NETWORK_ERROR
。因网络连接问题而发生错误时,系统便会返回此代码。这类网络连接错误之前报告为SERVICE_UNAVAILABLE
。更新了
SERVICE_UNAVAILABLE
和SERVICE_TIMEOUT
。从 PBL 6.0.0 版开始,由于处理超时而导致的错误将返回
SERVICE_UNAVAILABLE
,而非当前的SERVICE_TIMEOUT
。在早期版本的 PBL 中,此行为不会发生改变。
移除了
SERVICE_TIMEOUT
。从 PBL 6.0.0 版开始,系统将不再返回
SERVICE_TIMEOUT
。旧版 PBL 仍会返回此代码。添加了额外的日志记录。
Play 结算库 6 版包含额外的日志记录,可让您深入了解 API 的使用情况(例如成功和失败)和服务连接问题。此信息将用于提升 Play 结算库的性能,并为修正错误提供更好的支持。
Google Play 结算库 5.2.1 版 (2023-06-22)
5.2.1 版 Google Play 结算库和 Kotlin 扩展现已推出。
变更摘要
更新 Play 结算库以与 Android 14 兼容。
Google Play 结算库 5.2 版 (2023-04-06)
5.2.0 版 Google Play 结算库和 Kotlin 扩展现已推出。
变更摘要
- 添加了类,以支持面向韩国境内移动设备/平板电脑用户的备选结算系统流程:
- 添加了
BillingFlowParams.SubscriptionUpdateParams.Builder.setOriginalExternalTransactionId()
方法,用于指定来源订阅的外部交易 ID。 - 添加了
BillingClient.Builder.enableAlternativeBilling()
方法,以允许韩国用户选择备选结算系统选项。
Google Play 结算库 5.1 版 (2022-10-31)
5.1.0 版 Google Play 结算库和 Kotlin 扩展现已推出。
此版本包含以下变更。
变更摘要
- 添加了
ProductDetails.SubscriptionOfferDetails.getOfferId()
方法,以便检索优惠 ID。 - 添加了
ProductDetails.SubscriptionOfferDetails.getBasePlanId()
方法,以便检索基础方案 ID。 - 将
targetSdkVersion
更新成了 31。
Google Play 结算库 5.0 版 (2022-05-11)
5.0.0 版 Google Play 结算库和 Kotlin 扩展现已推出。
此版本包含以下变更。
变更摘要
- 引入了新的订阅模式,包括可让您为单个订阅商品创建多个优惠的新实体。如需了解详情,请参阅迁移指南。
- 添加了
BillingClient.queryProductDetailsAsync()
,以取代BillingClient.querySkuDetailsAsync()
。 - 添加了
setIsOfferPersonalized()
方法,以满足欧盟个性化定价信息披露要求。如需详细了解如何使用此方法,请参阅指明个性化价格。 - 移除了之前已废弃并被 Google Play 结算库 4.0.0 版中引入的 queryPurchasesAsync 取而代之的
queryPurchases()
。 launchPriceChangeFlow
已废弃,并将在未来的版本中移除。如需详细了解替代选项,请参阅启动价格变动确认流程。- 移除了以前在实例化购买流程时使用的
setVrPurchaseFlow()
。在以前的版本中,此方法会将用户重定向到其 Android 设备上完成购买交易。移除此方法后,用户将通过标准购买流程完成购买交易。
Google Play 结算库 4.1 版 (2022-02-23)
4.1.0 版 Google Play 结算库和 Kotlin 扩展现已推出。
此版本包含以下变更。
变更摘要
- 添加了
BillingClient.showInAppMessages()
,以帮助处理订阅付款遭拒问题。如需详细了解如何使用 In-App Messaging 处理订阅付款遭拒问题,请参阅处理付款遭拒问题。
Google Play 结算库 4.0 版 (2021-05-18)
4.0.0 版 Google Play 结算库和 Kotlin 扩展现已推出。
变更摘要
添加了
BillingClient.queryPurchasesAsync()
以替换BillingClient.queryPurchases()
,我们将在未来的版本中移除后者。添加了新的订阅替换模式
IMMEDIATE_AND_CHARGE_FULL_PRICE
。添加了
BillingClient.getConnectionState()
方法,用于检索 Play 结算库的连接状态。更新了 Javadoc 和实现,用于指明可在哪个线程上调用方法以及发布哪些线程结果。
添加了
BillingFlowParams.Builder.setSubscriptionUpdateParams()
作为发起订阅更新的新方式,用于替换已移除的BillingFlowParams#getReplaceSkusProrationMode
、BillingFlowParams#getOldSkuPurchaseToken
、BillingFlowParams#getOldSku
、BillingFlowParams.Builder#setReplaceSkusProrationMode
和BillingFlowParams.Builder#setOldSku
。添加了
Purchase.getQuantity()
和PurchaseHistoryRecord.getQuantity()
。添加了
Purchase#getSkus()
和PurchaseHistoryRecord#getSkus()
,用于替换已移除的Purchase#getSku
和PurchaseHistoryRecord#getSku
。移除了
BillingFlowParams#getSku
、BillingFlowParams#getSkuDetails
和BillingFlowParams#getSkuType
。
Google Play 结算库 3.0.3 版 (2021-03-12)
3.0.3 版 Google Play 结算库、Kotlin 扩展和 Unity 插件现已推出。
Java 和 Kotlin bug 修复
- 修复了在调用
endConnection()
时发生内存泄漏的问题。 - 修复了利用单个任务启动模式的应用在使用 Google Play 结算库时出现的问题。当应用从 Android 启动器恢复运行时,如果结算对话框在应用暂停之前可见,则将触发
onPurchasesUpdated()
回调。
Unity bug 修复
- 更新到了 Java 3.0.3,解决了内存泄漏问题,并解决了当应用从 Android 启动器恢复运行且结算对话框在应用暂停之前可见时出现的无法购买的问题。
Google Play 结算库 3.0.2 版 (2020-11-24)
3.0.2 版 Google Play 结算库和 Kotlin 扩展现已推出。
bug 修复
- 修复了 Kotlin 扩展中的以下 bug:协程失败并给出错误“Already resumed”。
- 修复了以下 bug:搭配 Kotlin 扩展使用 kotlinx.coroutines 库 1.4 及更高版本时,会出现未解析的引用。
Google Play 结算库 3.0.1 版 (2020-09-30)
3.0.1 版 Google Play 结算库和 Kotlin 扩展现已推出。
bug 修复
- 修复了以下 bug:如果在结算过程中终止后恢复应用,系统可能不会使用购买结果调用
PurchasesUpdatedListener
。
Google Play 结算库 3.0 版 (2020-06-08)
3.0.0 版 Google Play 结算库、Kotlin 扩展和 Unity 插件现已推出。
变更摘要
- 移除了奖励 SKU 支持。
- 移除了
ChildDirected
和UnderAgeOfConsent
参数。 - 移除了已废弃的开发者载荷方法。
- 移除了已废弃的
BillingFlowParams.setAccountId()
和BillingFlowParams.setDeveloperId()
方法。 - 移除了已废弃的
BillingFlowParams.setOldSkus(String oldSku)
和BillingFlowParams.addOldSku(String oldSku)
方法。 - 添加了可为 null 性注释。
bug 修复
SkuDetails.getIntroductoryPriceCycles()
现在返回int
,而不是String
。- 修复了以下 bug:即使未设置任何额外参数,结算流程也会被视为具有额外参数。
Google Play 结算库 2.2.1 版 (2020-05-20)
Google Play 结算库 2.2.1 版现已推出。
bug 修复
- 更新了 Kotlin 扩展所依赖的 Java Play 结算库的默认版本。
Google Play 结算库 2.2.0 版和 Unity 支持 (2020-03-23)
Google Play 结算服务 2.2.0 版提供的功能可帮助开发者确保将购买交易归因于正确的用户。这些更改消除了基于开发者载荷构建自定义解决方案的需求。在此次更新中,开发者载荷功能已废弃并将在未来的版本中移除。如需了解更多信息,包括推荐的替代方法,请参阅开发者载荷。
适用于 Unity 的 Google Play 结算库 2
除了当前的 Java 和 Kotlin 版 Google Play 结算库 2 之外,我们还发布了一个适用于 Unity 的库版本。使用 Unity 内购 API 的游戏开发者可以立即升级,以便充分利用 Google Play 结算库 2 的所有功能,并方便以后升级到 Google Play 结算库的更高版本。
如需了解详情,请参阅通过 Unity 使用 Google Play 结算服务。
变更摘要
- Java Google Play 结算库
- 在
AcknowledgePurchaseParams
中,我们废弃了setDeveloperPayload()
和getDeveloperPayload()
方法。 - 在
ConsumeParams
中,我们废弃了setDeveloperPayload()
和getDeveloperPayload()
方法。 - 在
BillingFlowParams
中,我们将setAccountId()
重命名为setObfuscatedAccountId()
,并记录了长度限制(64 个字符)以及禁止在此字段中使用个人身份信息 (PII) 的限制。setAccountId()
已标记为已废弃,并将在未来的库版本中移除。 - 在
BillingFlowParams
中,我们添加了setObfuscatedProfileId()
,它的工作方式与setObfuscatedAccountId()
类似。如需了解详情,请参阅开发者载荷更新和替代方法。 - 在
Purchase
中,我们添加了getAccountIdentifiers()
方法,以返回在BillingFlowParams
中设置的经过混淆处理的账号标识符。 - 在
BillingClient
中,loadRewardedSku()
方法已在废弃奖励 SKU 的过程中被标记为已废弃。您可以访问 Play 管理中心帮助中心,详细了解废弃情况。
- 在
Google Play 结算库 2.1.0 版和 Kotlin 扩展 2.1.0 版 (2019-12-10)
2.1.0 版 Google Play 结算库和全新 Kotlin 扩展现已推出。Play 结算库 Kotlin 扩展提供符合惯例规则的 API 替代选项,具有更好的 null 安全性和协程,可供开发者在进行 Kotlin 开发时选用。如需查看代码示例,请参阅使用 Google Play 结算库。
此版本包含以下变更。
变更摘要
- 在
BillingFlowParams
中,我们废弃了setOldSku(String oldSku)
并将其替换成setOldSku(String oldSku, String purchaseToken)
,这样在设备上的多个账号拥有相同的 SKU 时,就可以消除歧义。
Google Play 结算库 2.0.3 版 (2019-08-05)
Google Play 结算库 2.0.3 版现已推出。
bug 修复
- 修复了以下 bug:
querySkuDetailsAsync()
有时会发生代号为DEVELOPER_ERROR
的错误,而非返回成功结果。
Google Play 结算库 2.0.2 版 (2019-07-08)
Google Play 结算库 2.0.2 版现已推出。此版本包含对参考文档的更新,没有更改库功能。
Google Play 结算库 2.0.1 版 (2019-06-06)
Google Play 结算库 2.0.1 版现已推出。此版本包含以下变更。
bug 修复
- 修复了以下 bug:在某些情况下,系统将调试消息作为
null
返回。 - 修复了潜在的内存泄漏问题。
Google Play 结算库 2.0 版 (2019-05-07)
Google Play 结算库 2.0 版现已推出。此版本包含以下变更。
必须在三天内确认购买交易
Google Play 支持从您的应用内部(应用内)或您的应用外部(应用外)购买商品。为了确保无论用户在哪里购买您的商品,Google Play 都能提供一致的购买体验,您必须在授予用户权利后尽快确认通过 Google Play 结算库收到的所有购买交易。如果您在三天内未确认购买交易,则用户会自动收到退款,并且 Google Play 会撤消该购买交易。对于待处理的交易(2.0 版中的新功能),三天期限从购买交易变为 PURCHASED
状态时起算,而购买交易处于 PENDING
状态的时间将不算在内。
对于订阅,您必须确认包含新购买令牌的任何购买交易。这意味着,需要确认所有初始购买、计划变更和重新注册,但无需确认后续续订。如要确定购买交易是否需要确认,您可以检查购买交易中的确认字段。
Purchase
对象现在包含 isAcknowledged()
方法,该方法可以指示购买交易是否已得到确认。此外,Google Play Developer API 也包含 Purchases.products
和 Purchases.subscriptions
的确认布尔值。在确认购买交易之前,请务必使用这些方法确定购买交易是否已得到确认。
您可以使用以下某种方法确认购买交易:
- 对于消耗型商品,请使用客户端 API 中的
consumeAsync()
。 - 对于非消耗型商品,请使用客户端 API 中的
acknowledgePurchase()
。 - 还可以使用服务器 API 中新增的
acknowledge()
方法。
已移除 BillingFlowParams.setSku()
此版本已移除之前废弃的 BillingFlowParams#setSku()
方法。现在,在购买流程中渲染商品之前,您必须先调用 BillingClient.querySkuDetailsAsync()
,将生成的 SkuDetails
对象传递给 BillingFlowParams.Builder.setSkuDetails()
。
如需查看代码示例,请参阅使用 Google Play 结算库。
支持开发者载荷
Google Play 结算库 2.0 版添加了对开发者载荷(即,可附加到购买交易的任意字符串)的支持。您可以将开发者载荷参数附加到购买交易,但只有在已确认购买交易或已消耗所购商品时才能附加。这与 AIDL 中的开发者载荷不同,在 AIDL 中,可以在启动购买流程时指定载荷。因为现在可以从您的应用外部发起购买交易,所以此变更可确保您始终有机会将载荷添加到购买交易。
Purchase
对象现在包含一个 getDeveloperPayload()
方法,用于访问新库中的载荷。
一致的报价
当您提供折扣 SKU 时,Google Play 现在会返回 SKU 的原价,以便您向用户显示他们正在享受折扣。
SkuDetails
包含两种检索 SKU 原价的新方法:
getOriginalPriceAmountMicros()
- 返回折扣前未设置格式的 SKU 原价。getOriginalPrice()
- 返回采用其他货币格式的原价。
待处理的交易
在 Google Play 结算库 2.0 版中,您必须支持在授予权利之前需要执行其他操作的购买交易。例如,用户可能会选择使用现金在实体店购买您的应用内商品。也就是说,交易是在应用外部完成的。在这种情况下,您应仅在用户完成交易之后授予权利。
如要启用“待处理的购买交易”功能,请在初始化应用期间调用 enablePendingPurchases()
。
使用 Purchase.getPurchaseState()
方法确定购买交易的状态是 PURCHASED
还是 PENDING
。请注意,只有在状态为 PURCHASED
时,您才能授予权利。您应通过执行以下操作来检查 Purchase
的状态更新:
- 在启动应用时,调用
BillingClient.queryPurchases()
来检索与用户关联的非消耗型商品的列表。 - 对每个返回的
Purchase
对象调用Purchase.getPurchaseState()
。 - 实现
onPurchasesUpdated()
方法来响应对Purchase
对象进行的更改。
此外,Google Play Developer API 还包含 Purchases.products
的 PENDING
状态。订阅不支持待处理的交易。
此版本还引入了一个新的实时开发者通知类型,即 OneTimeProductNotification
。此通知类型包含一个消息,其值为 ONE_TIME_PRODUCT_PURCHASED
或 ONE_TIME_PRODUCT_CANCELED
。仅针对与延迟付款方式(例如现金)相关的购买交易发送此类通知。
在确认待处理的购买交易时,请确保只有在购买状态是 PURCHASED
(而不是 PENDING
)时才确认。
API 变更
Google Play 结算库 2.0 版包含多项 API 变更,以支持新特性并澄清现有功能。
consumeAsync
consumeAsync()
现在采用 ConsumeParams
对象,而非 purchaseToken
。ConsumeParams
包含 purchaseToken
以及可选的开发者载荷。
先前版本的 consumeAsync()
已从此版本中移除。
queryPurchaseHistoryAsync
为了尽量避免混淆,queryPurchaseHistoryAsync()
现在会返回 PurchaseHistoryRecord
对象,而不是 Purchase
对象。PurchaseHistoryRecord
对象与 Purchase
对象相同,只不过它仅反映由 queryPurchaseHistoryAsync()
返回的值,并且不包含 autoRenewing
、orderId
和 packageName
字段。请注意,返回的数据没有任何变化 - queryPurchaseHistoryAsync()
返回的数据与以前相同。
BillingResult 返回值
先前返回一个 BillingResponse
整数值的 API 现在会返回一个 BillingResult
对象。BillingResult
包含 BillingResponse
整数以及可用于诊断错误的调试字符串。该调试字符串使用 en-US 语言环境,不会向最终用户显示。
bug 修复
SkuDetails.getIntroductoryPriceAmountMicros()
现在返回的是long
,而不是String
。
Google Play 结算库 1.2.2 版 (2019-03-07)
Google Play 结算库 1.2.2 版现已推出。此版本包含以下变更。
bug 修复
- 修复了 v1.2.1 中引入的线程问题。后台调用不再阻止主线程。
其他变更
- 虽然仍建议使用主线程,但您现在可以从后台线程实例化 Google Play 结算库。
- 实例化已完全迁移到后台线程,以降低导致 ANR 的几率。
Play 结算库 1.2.1 版 (2019-03-04)
Google Play 结算库 1.2.1 版现已推出。此版本包含以下变更。
主要变更
- 添加了对奖励产品的支持。 如需详细了解变现途径,请参阅添加奖励产品专用功能。
其他变更
- 为
PurchasesResult
和SkuDetailsResult
添加了公共构造函数,以使测试变得更容易。 SkuDetails
对象可以使用新方法getOriginalJson()
。- 所有 AIDL 服务调用现在都由后台线程处理。
bug 修复
- Null 回调监听器不再传递到公共 API 中。
Google Play 结算库 1.2 版 (2018-10-18)
Google Play 结算库 1.2 版现已推出。此版本包含以下变更。
变更摘要
- Google Play 结算库现在依据 Android 软件开发套件许可协议授权。
- 添加了
launchPriceChangeConfirmationFlow
API,用于提示用户检查对订阅价格的待定更改。 - 在升级或降级用户的订阅时,添加了对新的按比例计费模式
DEFERRED
的支持。 - 在
BillingFlowParams
类中,将setSku()
替换成了setSkuDetails()
。 - 修复了一些小 bug 并优化了代码。
价格变动确认
您现在可以在 Google Play 管理中心内更改订阅的价格,并在用户进入您的应用时提示他们查看并接受新价格。
要使用此 API,请使用订阅产品的 skuDetails
创建 PriceChangeFlowParams
对象,然后调用 launchPriceChangeConfirmationFlow()
。当价格变动确认流程完成时,实现 PriceChangeConfirmationListener
来处理结果,如以下代码段所示:
Kotlin
val priceChangeFlowParams = PriceChangeFlowParams.newBuilder() .setSkuDetails(skuDetailsOfThePriceChangedSubscription) .build() billingClient.launchPriceChangeConfirmationFlow(activity, priceChangeFlowParams, object : PriceChangeConfirmationListener() { override fun onPriceChangeConfirmationResult(responseCode: Int) { // Handle the result. } })
Java
PriceChangeFlowParams priceChangeFlowParams = PriceChangeFlowParams.newBuilder() .setSkuDetails(skuDetailsOfThePriceChangedSubscription) .build(); billingClient.launchPriceChangeConfirmationFlow(activity, priceChangeFlowParams, new PriceChangeConfirmationListener() { @Override public void onPriceChangeConfirmationResult(int responseCode) { // Handle the result. } });
价格变动确认流程会显示一个包含新定价信息的对话框,要求用户接受新价格。此流程会返回 BillingClient.BillingResponse
类型的响应代码。
新的按比例计费模式
当升级或降级用户的订阅时,您可以使用新的按比例计费模式 DEFERRED
。此模式会在下次续订时更新用户的订阅。要详细了解如何设置此按比例计费模式,请参阅设置按比例计费模式。
用于设置 SKU 详情的新方法
在 BillingFlowParams
类中,已废弃 setSku()
方法。此变更有助于优化 Google Play 结算服务流程。
在您的应用内购买结算客户端中构造新的 BillingFlowParams
实例时,我们建议您直接使用 setSkuDetails()
来处理 JSON 对象,如以下代码段所示。
在 BillingFlowParams
Builder 类中,已废弃 setSku()
方法。请改用 setSkuDetails()
方法,如以下代码段所示。传入 setSkuDetails()
对象的对象来自 querySkuDetailsAsync()
方法。
Kotlin
private lateinit var mBillingClient: BillingClient private val mSkuDetailsMap = HashMap<String, SkuDetails>() private fun querySkuDetails() { val skuDetailsParamsBuilder = SkuDetailsParams.newBuilder() mBillingClient.querySkuDetailsAsync(skuDetailsParamsBuilder.build() ) { responseCode, skuDetailsList -> if (responseCode == 0) { for (skuDetails in skuDetailsList) { mSkuDetailsMap[skuDetails.sku] = skuDetails } } } } private fun startPurchase(skuId: String) { val billingFlowParams = BillingFlowParams.newBuilder() .setSkuDetails(mSkuDetailsMap[skuId]) .build() }
Java
private BillingClient mBillingClient; private Map<String, SkuDetails> mSkuDetailsMap = new HashMap<>(); private void querySkuDetails() { SkuDetailsParams.Builder skuDetailsParamsBuilder = SkuDetailsParams.newBuilder(); mBillingClient.querySkuDetailsAsync(skuDetailsParamsBuilder.build(), new SkuDetailsResponseListener() { @Override public void onSkuDetailsResponse(int responseCode, List<SkuDetails> skuDetailsList) { if (responseCode == 0) { for (SkuDetails skuDetails : skuDetailsList) { mSkuDetailsMap.put(skuDetails.getSku(), skuDetails); } } } }); } private void startPurchase(String skuId) { BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder() .setSkuDetails(mSkuDetailsMap.get(skuId)) .build(); }
Play 结算库 1.1 版 (2018-05-07)
Google Play 结算库 1.1 版现已推出。此版本包含以下变更。
变更摘要
- 现在,在升级或降级现有订阅时,可以在
BillingFlowParams
中指定按比例计费模式。 BillingFlowParams
不再支持replaceSkusProration
布尔标记,请改用replaceSkusProrationMode
。launchBillingFlow()
现在会对失败响应触发回调。
行为变更
Google Play 结算库 1.1 版包含以下行为变更。
开发者可以在 BillingFlowParams
类中设置 replaceSkusProrationMode
在升级或降级用户的订阅时,ProrationMode
会提供有关按比例计费类型的更多详情。
Kotlin
BillingFlowParams.newBuilder() .setSku(skuId) .setType(billingType) .setOldSku(oldSku) .setReplaceSkusProrationMode(replaceSkusProrationMode) .build()
Java
BillingFlowParams.newBuilder() .setSku(skuId) .setType(billingType) .setOldSku(oldSku) .setReplaceSkusProrationMode(replaceSkusProrationMode) .build();
目前,Google Play 支持以下按比例计费模式:
IMMEDIATE_WITH_TIME_PRORATION |
替换会立即生效,并且系统会按比例计算新的有效期,同时向用户返还余额或收取相关费用。这是当前的默认行为。 |
IMMEDIATE_AND_CHARGE_PRORATED_PRICE |
替换会立即生效,结算周期保持不变。用户需要补足剩余订阅期的差价。
注意:此选项仅适用于订阅升级。 |
IMMEDIATE_WITHOUT_PRORATION |
替换会立即生效,并且会在下个续订时间点按新价格收费。结算周期保持不变。 |
BillingFlowParams
类不再支持 replaceSkusProration
开发者过去可以设置一个布尔标记来针对订阅升级请求收取按比例计算的金额。鉴于我们现已支持 ProrationMode
,它包含更详细的按比例计费说明,因此不再支持此布尔标记。
launchBillingFlow()
现在会对失败的响应触发回调
结算库一律会触发 PurhcasesUpdatedListener
回调并异步返回 BillingResponse
,并且 BillingResponse
的同步返回值也会被保留。
bug 修复
- 当服务断开时,采用异步方法尽早正确退出。
Builder
参数对象不会再改变已构建的对象。- 问题 68087141:
launchBillingFlow()
现在会对失败的响应触发回调。
Google Play 结算库 1.0 版(2017-09-19,公告)
Google Play 结算库 1.0 版现已推出。此版本包含以下变更。
重要变更
- 在库的清单内嵌入了结算权限,因此不再需要在 Android 清单内添加
com.android.vending.BILLING
权限。 - 向
BillingClient.Builder
类中添加了新的构建器。 - 为
SkuDetailsParams
类(在相关方法中用于查询 SKU)引入了构建器模式。 - 为了保持一致(相同的返回参数名称和顺序),更新了几个 API 方法。
行为变更
Google Play 结算库 1.0 版包含以下行为变更。
BillingClient.Builder 类
BillingClient.Builder
现在通过 newBuilder 模式初始化:
Kotlin
billingClient = BillingClient.newBuilder(context).setListener(this).build()
Java
billingClient = BillingClient.newBuilder(context).setListener(this).build();
现在使用 BillingFlowParams 类调用 launchBillingFlow 方法
为购买交易或订阅启动结算流程时,launchBillingFlow()
方法会收到使用请求专用参数初始化的 BillingFlowParams
实例:
Kotlin
BillingFlowParams.newBuilder().setSku(skuId) .setType(billingType) .setOldSku(oldSku) .build() // Then, use the BillingFlowParams to start the purchase flow val responseCode = billingClient.launchBillingFlow(builder.build())
Java
BillingFlowParams.newBuilder().setSku(skuId) .setType(billingType) .setOldSku(oldSku) .build(); // Then, use the BillingFlowParams to start the purchase flow int responseCode = billingClient.launchBillingFlow(builder.build());
查询上架商品的新方式
queryPurchaseHistoryAsync()
和 querySkuDetailsAsync()
方法的参数已封装到 Builder 模式中:
Kotlin
val params = SkuDetailsParams.newBuilder() params.setSkusList(skuList) .setType(itemType) billingClient.querySkuDetailsAsync(params.build(), object : SkuDetailsResponseListener() { ... })
Java
SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder(); params.setSkusList(skuList) .setType(itemType); billingClient.querySkuDetailsAsync(params.build(), new SkuDetailsResponseListener() {...})
现在,为了方便您查看和在我们的 API 之间保持一致,结果会以结果代码和 SkuDetails
对象列表(而不是先前的封装容器类)的形式返回:
Kotlin
fun onSkuDetailsResponse(@BillingResponse responseCode: Int, skuDetailsList: List<SkuDetails>)
Java
public void onSkuDetailsResponse(@BillingResponse int responseCode, List<SkuDetails> skuDetailsList)
已更改 onConsumeResponse()
方法的参数顺序
为了在我们的 API 之间保持一致,已更改 ConsumeResponseListener
接口中的 onConsumeResponse
的参数顺序:
Kotlin
fun onConsumeResponse(@BillingResponse responseCode: Int, outToken: String)
Java
public void onConsumeResponse(@BillingResponse int responseCode, String outToken)
PurchaseResult 对象已解除封装
为了在我们的 API 之间保持一致,PurchaseResult
已解除封装:
Kotlin
fun onPurchaseHistoryResponse(@BillingResponse responseCode: Int, purchasesList: List<Purchase>)
Java
void onPurchaseHistoryResponse(@BillingResponse int responseCode, List<Purchase> purchasesList)
bug 修复
开发者预览版 1(2017-06-12,公告)
发布了开发者预览版,旨在简化结算方面的开发过程,让开发者能够集中精力实现 Android 应用专用逻辑,如应用架构和导航结构。
该库包含一些方便使用的类和功能,供您在将 Android 应用与 Google Play Billing API 集成时使用。此外,该库还在 Android 接口定义语言 (AIDL) 服务之上提供了一个抽象层,让开发者可以更轻松地定义应用与 Google Play Billing API 之间的接口。