从 Google Play 结算库版本 7 或 8 迁移到版本 9

本文档介绍了如何从 Google Play 结算库 (PBL) 7 或 8 迁移到 PBL 9，以及如何与新功能集成。

如需查看版本 9.0.0 的完整变更列表，请参阅版本说明。

概览

PBL 9 改进了现有 API，并移除了之前已弃用的 API。此版本的库还通过新的子响应代码引入了更丰富的错误上下文。

PBL 升级的向后兼容性

如需迁移到 PBL 9，您需要更新或移除应用中的一些现有 API 引用，如版本说明和本迁移指南的后续部分中所述。

从 PBL 7 或 8 升级到 PBL 9

如需从 PBL 7 或 8 升级到 PBL 9，请执行以下步骤：

  1. 更新应用 build.gradle 文件中的 Play 结算库依赖项版本。

    dependencies {
  def billing_version = "9.1.0"
  implementation "com.android.billingclient:billing:$billing_version"
}

    如果您使用的是 Kotlin，Google Play 结算库 KTX 模块包含了 Kotlin 扩展和协程支持，可让您在使用 Google Play 结算库时编写惯用的 Kotlin 代码。如需将这些扩展程序包含在项目中，请将以下依赖项添加到应用的 build.gradle 文件中，如下所示：

    dependencies {
  val billing_version = "9.1.0"
  implementation("com.android.billingclient:billing-ktx:$billing_version")
}

  2. （仅适用于从 PBL 7 升级到 PBL 9）。更新 queryProductDetailsAsync 方法的实现。

    ProductDetailsResponseListener.onProductDetailsResponse 方法的签名发生了变化，这需要您更改应用中的 queryProductDetailsAsync 实现。如需了解详情，请参阅显示可供购买的产品。

  3. 处理已移除的 API。

    下表列出了已移除的 API 以及您必须在应用中使用的相应替代 API。

    从升级

    PBL 9 不再支持下表中列出的 API。 如果您的实现使用了任何这些已移除的 API，请参阅下表了解其对应的替代 API。

    移除了之前已弃用的 API 要使用的替代 API
    queryPurchaseHistoryAsync API 请参阅查询购买交易记录。如果您之前使用 queryPurchaseHistoryAsync 来确定用户是否符合免费试用条件，现在应使用 ProductDetails.getSubscriptionOfferDetails() 来确定用户符合哪些优惠的条件。
    BillingClient.SkuType BillingClient.ProductType。INAPP 和 SUBS 商品类型常量在功能上与已弃用的 SKU 类型常量类似。
    SkuDetails ProductDetails。这是支持一次性产品的新数据模型。
    SkuDetailsParams 将 QueryProductDetailsParams 与 queryProductDetailsAsync 搭配使用。
    SkuDetailsResponseListener 将 ProductDetailsResponseListener 与 queryProductDetailsAsync 搭配使用。
    QueryPurchaseHistoryParams
    • 使用 queryPurchasesAsync 查询有效或待处理的购买交易。
    • 在后端服务器上跟踪已消耗的购买交易。
    • 对于已取消或作废的购买交易，请使用服务器端 Voided Purchases API。
    getSkuDetailsList 和 setSkuDetailsList 使用 BillingFlowParams.Builder.setProductDetailsParamsList
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases()（不带参数的 API） enablePendingPurchases(PendingPurchasesParams params)
    请注意，已废弃的 enablePendingPurchases() 在功能上等同于 enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())。
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    从升级

    下表列出了 PBL 9 中移除的 API，以及您必须在应用中使用的相应替代 API。

    移除了之前已弃用的 API 要使用的替代 API
    BillingClient.SkuType BillingClient.ProductType。INAPP 和 SUBS 商品类型常量在功能上与已弃用的 SKU 类型常量类似。
    SkuDetails ProductDetails。这是支持一次性产品的新数据模型。
    SkuDetailsParams 将 QueryProductDetailsParams 与 queryProductDetailsAsync 搭配使用。
    SkuDetailsResponseListener 将 ProductDetailsResponseListener 与 queryProductDetailsAsync 搭配使用。
    QueryPurchaseHistoryParams
    getSkuDetailsList 和 setSkuDetailsList 使用 BillingFlowParams.Builder.setProductDetailsParamsList

  4. （推荐）启用自动服务重新连接。

    如果在服务断开连接时进行 API 调用，Play 结算库可以尝试自动重新建立服务连接。如需了解详情，请参阅启用自动重新连接服务。

  5. 处理新的子响应代码。

    从 launchBillingFlow() 返回的 BillingResult 现在将包含一个子响应代码字段。此字段仅在某些情况下填充，以提供更具体的失败原因。子响应字段可具有以下值：

    • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS - 当用户的资金少于其尝试购买的商品的价格时返回。
    • USER_INELIGIBLE - 当用户不符合订阅优惠的配置资格要求时返回。
    • NO_APPLICABLE_SUB_RESPONSE_CODE - 默认值，当没有其他适用的子响应代码时返回。

    迁移步骤：更新 PurchasesUpdatedListener 或等效的结果处理，以识别并响应这些特定的子响应代码，从而提供更好的用户体验。例如，提示您修正付款方式或显示特定错误消息。

  6. 错误代码重新分类注意事项。

    如果 Play 商店应用被系统屏蔽（例如在 OEM 自定义的儿童模式下），PBL 的响应代码已从 ERROR 更改为 BILLING_UNAVAILABLE。

    迁移步骤：确保您的错误处理逻辑能够适应此更改，并且在这些特定场景中不会依赖于接收通用错误。

  7. 处理 DeveloperProvidedBillingDetails.getLinkUri() 可为 null 性。

    如果您在外部付款集成中使用 DeveloperProvidedBillingDetails，则 getLinkUri() 现在为 @Nullable。

    迁移步骤：为安全地处理此变更，请确保您的集成代码在解析或启动浏览器 intent 之前，能够处理来自 DeveloperProvidedBillingDetails.getLinkUri() 方法的 null 和空字符串 ("") 值。例如：

    Kotlin

    Java

    String linkUri = details.getLinkUri();
if (!android.text.TextUtils.isEmpty(linkUri)) {
  Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(linkUri));
  context.startActivity(intent);
}

  8. 可选更改。