提醒:自 2022 年 8 月 2 日起,所有新應用程式都必須採用帳款服務程式庫 4.0 以上版本 自 2022 年 11 月 1 日起,現有應用程式的所有更新都必須採用帳款服務程式庫 4.0 以上版本。瞭解詳情

Google Play 帳款服務程式庫 4 至 5 遷移指南

本主題說明如何從 Google Play 帳款服務程式庫 4 遷移至 Google Play 帳款服務程式庫 5,以及如何使用新的訂閱功能。

總覽

Google Play 帳款服務程式庫 5 推出了「訂閱方案和訂閱優惠」,相較於舊版,這些功能可擴大您販售訂閱項目的方式,並降低整合的複雜度。

您可以使用 Play Developer Console 或 Play Developer API 設定含有多項基本方案的單一訂閱項目。訂閱方案具有彈性的定價模式和適用資格。您可以在訂閱生命週期的不同階段使用各種自動續訂和預付方案建立優惠。詳情請參閱整合指南

移轉步驟

更新 Google Play 帳款服務程式庫

將現有的 Play 帳款服務程式庫依附元件改為更新版應用程式的 build.gradle 檔案。

dependencies {
    def billingVersion = "5.0.0"

    implementation "com.android.billingclient:billing:$billingVersion"
}

即使您尚未修改任何方法的呼叫,您的專案也應立即建構,因為我們在 Play 帳款服務程式庫 5 中已建立回溯相容性。但 SKU 的概念已不適用。

初始化帳單用戶端並建立與 Google Play 的連線。

從 Android 應用程式啟動購買流程的第一步如下:

顯示可購買的產品

如何取得使用者有資格購買的所有優惠:

  • QueryProductDetailsParams 取代 SkuDetailsParams
  • 切換 BillingClient.querySkuDetailsAsync() 呼叫,以使用 BillingClient.queryProductDetailsAsync()

請注意,查詢結果現在是 ProductDetails,而不是 SkuDetails。各個 ProductDetails 項目都含有產品相關資訊 (ID、名稱、類型等等)。如果是訂閱產品,ProductDetails 則包含 List<ProductDetails.SubscriptionOfferDetails>,這是訂閱項目優惠詳細資料的清單。針對一次性購買產品,ProductDetails 包含 ProductDetails.OneTimePurchaseOfferDetails。這些屬性可用來決定要向使用者顯示哪些優惠。

以下範例顯示應用程式進行上述變更前後的樣子:

之前

Kotlin

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS)

billingClient.querySkuDetailsAsync(params.build()) {
    billingResult,
    skuDetailsList ->
    // Process the result
}

Java

List<String> skuList = new ArrayList<>();

skuList.add("up_basic_sub");

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();

params.setSkusList(skuList).setType(SkuType.SUBS);

billingClient.querySkuDetailsAsync(params.build(),
    new SkuDetailsResponseListener() {
        @Override
        public void onSkuDetailsResponse(BillingResult billingResult,
                List<SkuDetails> skuDetailsList) {
            // Process the result.
        }
    }
);

之後

Kotlin

val productList =
    listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("up_basic_sub")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )

val params = QueryProductDetailsParams.newBuilder().setProductList(productList)

billingClient.queryProductDetailsAsync(params.build()) {
    billingResult,
    productDetailsList ->
    // Process the result
}

Java

ImmutableList<Product> productList = ImmutableList.of(Product.newBuilder()
                                            .setProductId("up_basic_sub")
                                            .setProductType(ProductType.SUBS)
                                            .build());

QueryProductDetailsParams params = QueryProductDetailsParams.newBuilder()
    .setProductList(productList)
    .build();

billingClient.queryProductDetailsAsync(
        params,
        new ProductDetailsResponseListener() {
                public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) {
                    // Process the result
                }
        }
);

queryProductDetailsAsync 的回呼會回傳 List<ProductDetails>。各個 ProductDetails 項目都含有產品相關資訊 (ID、名稱、類型等等)。主要差異在於訂閱項目產品現在包含 List<ProductDetails.SubscriptionOfferDetails>,其中包含使用者可用的所有優惠。

由於舊版 Play 帳款服務程式庫不支援新的物件 (訂閱項目、基礎方案、優惠等),因此新系統可將各個訂閱 SKU 轉換成單個回溯相容基本方案和優惠 可用的一次性購買產品也會轉移至 ProductDetails 物件。一次性購買產品的優惠詳細資料可透過 getOneTimePurchaseOfferDetails() 方法存取。

啟動優惠購買流程

啟動優惠的購買流程與啟動 SKU 流程非常類似。如要使用第 5 版提出購買要求,請按照下列步驟操作:

  • BillingFlowParams 使用 ProductDetailsParams 而非 SkuDetails
  • 您可以使用 SubscriptionOfferDetails 物件取得優惠詳細資料。

如要購買使用者所選優惠的產品,請取得所選優惠的 offerToken 並將其傳送到 ProductDetailsParams 物件。

建立 BillingFlowParams 物件後,使用 BillingClient 啟動計費流程將維持不變。

以下範例為應用程式在變更前後的可能內容:

之前

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
val billingFlowParams = BillingFlowParams.newBuilder()
                            .setSkuDetails(skuDetails)
                            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setSkuDetails(skuDetails)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

之後

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;
// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
val offerToken = productDetails.offerDetails(selectedOfferIndex).offerToken

val productDetailsParamsList =
    listOf(
        BillingFlowParams.ProductDetailsParams.newBuilder()
            .setProductDetails(productDetails)
            .setofferToken(offerToken)
            .build()
    )
val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
String offerToken = productDetails
                     .getSubscriptionOfferDetails(selectedOfferIndex)
                     .getOfferToken();
// Set the parameters for the offer that will be presented
// in the billing flow creating separate productDetailsParamsList variable
ImmutableList<ProductDetailsParams> productDetailsParamsList =
        ImmutableList.of(
                 ProductDetailsParams.newBuilder()
                     .setProductDetails(productDetails)
                     .setOfferToken(offerToken)
                     .build()
        )

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(productDetailsParamsList)
            .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

正在處理購買交易

使用 Google Play 帳款服務程式庫 5 處理交易的方式與先前版本類似。

如要提取使用者擁有的所有有效購買交易,並查詢新購買,請執行下列操作:

  • 請改為傳送包含 BillingClient.ProductType 值的 QueryPurchasesParams 物件,而不是將 BillingClient.SkuType 值傳送至 queryPurchasesAsync()

以下範例為應用程式在變更前後的可能內容:

之前

Kotlin

billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
    billingResult,
    purchaseList -> {
        // Process the result
    }
}

Java


billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List&lt;Purchase> purchases) {
            // process the result
        }
    }
);

之後

Kotlin

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
) { billingResult, purchaseList ->
    // Process the result
}

Java

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(),
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // Process the result
        }
    }
);

管理應用程式購買交易待處理交易的操作步驟並未變更。

管理訂閱狀態

如果您的後端具有訂閱狀態管理元件可檢查狀態及管理訂閱購買,您必須使用 Subscription Purchases API。如要詳細瞭解先前版本所做的變更,請參閱 2022 年 5 月全新訂閱功能指南