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

本文說明如何從 Google Play Billing Library (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 Billing Library 依附元件版本。

    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
    • 針對有效或購物交易未完成的購買交易，請使用 queryProductDetailsAsync。
    • 在後端伺服器上追蹤已消耗的購買交易。
    • 使用伺服器端 Voided Purchases API 處理取消或作廢的購買交易。
    getSkuDetailsList 和 setSkuDetailsList 使用 BillingFlowParams.Builder.setProductDetailsParamsList

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

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

  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() 是否可為空值。

    如果您在整合外部付款系統時使用 DeveloperProvidedBillingDetails，getLinkUri() 現已改為 @Nullable。

    遷移步驟：為安全處理這項異動，請確保整合代碼在剖析或啟動瀏覽器意圖前，能同時處理 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. 選用變更。