从 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. 可选更改。