從 Google Play 帳款服務程式庫第 7 或第 8 版改用第 9 版

本文說明如何從 Google Play 帳款服務程式庫 (PBL) 第 7 或 8 版遷移至第 9 版，以及如何整合新功能。

如需第 9.0.0 版的完整異動清單，請參閱「版本資訊」。

總覽

PBL 9 改善了現有 API，並移除了先前已淘汰的 API。這個版本的程式庫也透過新的子回應代碼，提供更豐富的錯誤背景資訊。

PBL 升級的回溯相容性

如要遷移至 PBL 9，您必須更新或移除應用程式中部分現有的 API 參照，詳情請參閱版本說明和本遷移指南的後續內容。

從 Play 帳款服務程式庫 7 或 8 升級至 Play 帳款服務程式庫 9

如要從 PBL 7 或 8 升級至 PBL 9，請按照下列步驟操作：

  1. 在應用程式的 build.gradle 檔案中，更新 Play 帳款服務程式庫依附元件版本。

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

    如果您使用 Kotlin，Google Play 帳款服務程式庫 KTX 模組會包含 Kotlin 擴充功能和協同程式支援機制，可讓您在使用 Google Play 帳款服務程式庫時編寫慣用的 Kotlin 程式碼。如要在專案中加入這些擴充功能，請將下列依附元件新增至應用程式的 build.gradle 檔案，如下所示：

    dependencies {
  val billing_version = "9.0.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 搭配 queryProductDetailsAsync 使用 QueryProductDetailsParams。
    SkuDetailsResponseListener 搭配 queryProductDetailsAsync 使用 ProductDetailsResponseListener。
    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 搭配 queryProductDetailsAsync 使用 QueryProductDetailsParams。
    SkuDetailsResponseListener 搭配 queryProductDetailsAsync 使用 ProductDetailsResponseListener。
    QueryPurchaseHistoryParams
    • 針對有效或待處理的購買交易，請使用 queryProductDetailsAsync。
    • 在後端伺服器上追蹤已使用的購買交易。
    • 如要處理取消或無效的交易，請使用伺服器端的 Voided Purchases API。
    getSkuDetailsList 和 setSkuDetailsList 使用 BillingFlowParams.Builder.setProductDetailsParamsList

  4. (建議) 啟用自動重新連線服務。

    如果服務中斷連線時發出 API 呼叫，Play Billing Library 可以嘗試自動重新建立服務連線。詳情請參閱「啟用自動重新連線服務」。

  5. 處理新的子回應碼。

    從 launchBillingFlow() 傳回的 BillingResult 現在會包含子回應代碼欄位。這個欄位只會在某些情況下填入，提供更具體的失敗原因。子回應欄位可包含下列值：

    • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS - Returned when the user's funds are less than the price of the item they are attempting to purchase.
    • USER_INELIGIBLE - 使用者不符合訂閱優惠的設定資格條件時，系統會傳回這個錯誤代碼。
    • NO_APPLICABLE_SUB_RESPONSE_CODE：預設值，適用於沒有其他子回應代碼的情況。

    遷移步驟：更新 PurchasesUpdatedListener 或同等結果處理方式，以便辨識及回應這些特定子回應代碼，進而提供更優質的使用者體驗。例如提示修正付款方式或顯示特定錯誤訊息。

  6. 錯誤代碼重新分類注意事項。

    如果系統封鎖 Play 商店應用程式 (例如在 OEM 自訂的兒童模式中)，PBL 的回應代碼會從 ERROR 變更為 BILLING_UNAVAILABLE。

    遷移步驟：請確保錯誤處理邏輯可因應這項變更，且不會在這些特定情境中收到一般錯誤。

  7. 處理 DeveloperProvidedBillingDetails.getLinkUri() 是否可為空值。

    如果您在外部付款整合中使用了 DeveloperProvidedBillingDetails，現在請改用 @Nullable。getLinkUri()

    遷移步驟：為安全處理這項變更，請確保整合程式碼會處理 DeveloperProvidedBillingDetails.getLinkUri() 方法傳回的 null 和空字串 ("") 值，再剖析或啟動瀏覽器 Intent。例如：

    Kotlin

    val linkUri = details.getLinkUri()
if (!linkUri.isNullOrEmpty()) {
  val intent = Intent(Intent.ACTION_VIEW, Uri.parse(linkUri))
  context.startActivity(intent)
}

    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. 可選的變更。