Google Play 帳款服務程式庫版本資訊

本主題提供 Google Play 帳款服務程式庫的版本資訊。

Google Play 帳款服務程式庫 5.0 版 (2022 年 5 月 11 日)

現已推出 5.0.0 版的 Google Play 帳款服務程式庫和 Kotlin 擴充功能。

這個版本包含下列異動:

異動內容摘要

  • 推出新的訂閱模型,包括可讓您為單一訂閱產品建立多項優惠的新模式。詳情請參閱「遷移指南」。
  • 新增 BillingClient.queryProductDetailsAsync() 以取代 BillingClient.querySkuDetailsAsync()
  • 新增 setIsOfferPersonalized() 方法來滿足歐盟個人化定價揭露規定。如要進一步瞭解如何使用此方法,請參閱「註明個人化價格」。
  • 移除 queryPurchases(),此 API 現已淘汰,並由 Google Play 帳款服務程式庫 4.0.0 版中導入的 queryPurchasesAsync 取代。
  • launchPriceChangeFlow 現已淘汰,並將在日後推出的版本中移除。如要進一步瞭解替代方案,請參閱「啟動價格變更確認流程」一文。
  • 移除先前用於執行實例化購買流程的 setVrPurchaseFlow()。在先前的版本中,此方法會將使用者重新導向到自己的 Android 裝置。移除此方法後,使用者就會透過標準購買流程完成購買程序。

Google Play 帳款服務程式庫 4.1 版 (2022 年 2 月 23 日)

現已推出 4.1.0 版的 Google Play 帳款服務程式庫和 Kotlin 擴充功能。

這個版本包含下列異動:

異動內容摘要

Google Play 帳款服務程式庫 4.0 版 (2021 年 5 月 18 日)

現已推出 4.0.0 版的 Google Play 帳款服務程式庫和 Kotlin 擴充功能。

異動內容摘要

Google Play 帳款服務程式庫 3.0.3 版 (2021 年 3 月 12 日)

現已推出 3.0.3 版的 Google Play 帳款服務程式庫、Kotlin 擴充功能和 Unity 外掛程式。

修正 Java 和 Kotlin 錯誤

  • 修正呼叫 endConnection() 時的記憶體流失問題。
  • 修正仰賴單一工作啟動模式的應用程式使用 Google Play 帳款服務程式庫時出現的問題。應用程式透過 Android 啟動器重新啟用後,系統會觸發 onPurchasesUpdated() 回呼,並在帳單暫停前顯示帳單對話方塊。

修正 Unity 錯誤

  • 更新至 Java 3.0.3 版以修正記憶體流失問題;解決應用程式透過 Android 啟動器重新啟用而造成的購買問題,並在帳單暫停前顯示帳單對話方塊。

Google Play 帳款服務程式庫 3.0.2 版 (2020 年 11 月 24 日)

現已推出 3.0.2 版的 Google Play 帳款服務程式庫和 Kotlin 擴充功能。

修正錯誤

  • 已修正 Kotlin 擴充功能中,協同程式因「已重新啟用」錯誤而失敗的錯誤。
  • 已修正將 Kotlin 擴充功能與 kotlinx.coroutines 程式庫 1.4 以上版本搭配使用時,未解決的參考問題。

Google Play 帳款服務程式庫 3.0.1 版 (2020 年 9 月 30 日)

現已推出 3.0.1 版的 Google Play 帳款服務程式庫和 Kotlin 擴充功能。

修正錯誤

  • 已修正如果應用程式在帳單流程期間終止並還原,可能會無法呼叫 PurchasesUpdatedListener 取得購買結果的錯誤。

Google Play 帳款服務程式庫 3.0.0 版 (2020 年 6 月 8 日)

現已推出 3.0.0 版的 Google Play 帳款服務程式庫、Kotlin 擴充功能和 Unity 外掛程式。

異動內容摘要

  • 已移除獎勵 SKU 支援。
  • 已移除 ChildDirectedUnderAgeOfConsent 參數。
  • 已移除淘汰的開發人員酬載方法。
  • 已移除淘汰的方法 BillingFlowParams.setAccountId()BillingFlowParams.setDeveloperId()
  • 已移除淘汰的方法 BillingFlowParams.setOldSkus(String oldSku)BillingFlowParams.addOldSku(String oldSku)
  • 已新增是否可為空值備註。

修正錯誤

Google Play 帳款服務程式庫 2.2.1 版 (2020 年 5 月 20 日)

現已推出 Google Play 帳款服務程式庫 2.2.1 版。

修正錯誤

  • 已更新 Kotlin 擴充功能依賴的 Java Play 帳款服務程式庫的預設版本。

Google Play 帳款服務程式庫 2.2.0 版和 Unity 支援 (2020 年 3 月 23 日)

Google Play 帳款服務 2.2.0 版提供相關功能,可協助開發人員將購買交易歸因於正確的使用者。這些異動會取代根據開發人員酬載建構自訂解決方案的需求。在本次更新中,我們已淘汰開發人員酬載功能,並會在日後的版本中移除。如需更多資訊 (包括建議的替代方案),請參閱「開發人員酬載」。

適用於 Unity 的 Google Play 帳款服務程式庫 2

除了目前 Google Play 帳款服務程式庫 2 的 Java 和 Kotlin 版本,我們還發布了適用於 Unity 的程式庫版本。使用 Unity In-App Purchase API 的遊戲開發人員可以立即升級,以享有 Google Play 帳款服務程式庫 2 的所有功能,並在日後可以更輕鬆地升級至新版 Google Play 帳款服務程式庫。

詳情請參閱「搭配 Unity 使用 Google Play 帳款服務」。

異動內容摘要

Google Play 帳款服務程式庫 2.1.0 版和 Kotlin 擴充功能 2.1.0 版 (2019 年 12 月 10 日)

現已推出 Google Play 帳款服務程式庫 2.1.0 版和新版 Kotlin 擴充功能。Play 帳款服務程式庫 Kotlin 擴充功能為 Kotlin 消費提供慣用的 API 替代方案,具有更出色的空值和協同程式。如需程式碼範例,請參閱「使用 Google Play 帳款服務程式庫」。

這個版本包含下列異動:

異動內容摘要

  • BillingFlowParams 中淘汰了 setOldSku(String oldSku) 並取代為 setOldSku(String oldSku, String purchaseToken),以釐清裝置上有多個帳戶擁有同一個 SKU 的情況。

Google Play 帳款服務程式庫 2.0.3 版 (2019 年 8 月 5 日)

現已推出 Google Play 帳款服務程式庫 2.0.3 版。

修正錯誤

  • 已修正 querySkuDetailsAsync() 有時會因代碼 DEVELOPER_ERROR 失敗,而不會傳回成功結果的錯誤。

Google Play 帳款服務程式庫 2.0.2 版 (2019 年 7 月 8 日)

現已推出 Google Play 帳款服務程式庫 2.0.2 版。這個版本包含參考文件更新,不會影響程式庫的功能。

Google Play 帳款服務程式庫 2.0.1 版 (2019 年 6 月 6 日)

現已推出 Google Play 帳款服務程式庫 2.0.1 版。這個版本包含下列異動:

修正錯誤

  • 已修正在某些情況下以 null 傳回偵錯訊息的錯誤。
  • 已修正潛在的記憶體流失問題。

Google Play 帳款服務程式庫 2.0 版 (2019 年 5 月 7 日)

現已推出 Google Play 帳款服務程式庫 2.0 版。這個版本包含下列異動:

購買交易必須在三天內確認

Google Play 支援購買在應用程式內部 (應用程式內) 或外部 (應用程式外) 的產品。為了讓使用者在 Google Play 各處購買產品時都能獲得一致的購物體驗,請務必在向使用者授予權限後,盡快透過 Google Play 帳款服務程式庫確認所有購買交易。如果您未在三天內確認購買交易,使用者會自動收到退款,Google Play 則會撤銷購買。針對未完成交易 (2.0 版的新功能),系統會在購買交易變為 PURCHASED 狀態時啟動三天確認期,而對於處於 PENDING 狀態的交易則不會啟動。

針對訂閱,您必須確認所有具有新購買憑證的購買交易。換句話說,您必須確認所有初次購買、方案變更及重新申請,但不需要確認後續的續約事宜。如要判斷購買交易是否需要確認,請查看購買交易中的確認欄位。

Purchase 物件現在包含 isAcknowledged() 方法,可指出交易是否已確認。此外,Google Play Developer API 也提供 Purchases.productsPurchases.subscriptions 的確認布林值。在確認購買交易之前,請務必使用以下方法判斷交易是否已確認。

您可以採用下列其中一種方式確認購買交易:

  • 如果是消耗性產品,請使用用戶端 API 中的 consumeAsync()
  • 如果尚未消耗的產品,請使用用戶端 API 中的 acknowledgePurchase()
  • Server API 也提供新的 acknowledge() 方法。

已移除 BillingFlowParams.setSku()

先前淘汰的 BillingFlowParams#setSku() 方法已從這個版本中移除。在購買流程中顯示產品之前,您必須呼叫 BillingClient.querySkuDetailsAsync(),並將產生的 SkuDetails 物件傳遞給 BillingFlowParams.Builder.setSkuDetails()

如需程式碼範例,請參閱「使用 Google Play 帳款服務程式庫」。

支援開發人員酬載

Google Play 帳款服務程式庫 2.0 版現已支援「開發人員酬載」功能,可做為交易中附加的任意字串。您可以將開發人員酬載參數附加至交易,但只有在購買交易已確認或已消耗的情況下。這與 AIDL 中的開發人員酬載不同,後者可在啟動購買流程時指定酬載。由於現在可以從應用程式外部發起購買程序,因此這項異動可確保您有機會在交易中加入酬載。

如要在新程式庫中存取酬載,Purchase 物件現已包含 getDeveloperPayload() 方法。

一致的優惠

提供優惠 SKU 時,Google Play 現在會傳回 SKU 的原始價格,方便您向使用者顯示折扣優惠。

SkuDetails 提供兩個擷取原始 SKU 價格的新方法:

未完成交易

使用 Google Play 帳款服務程式庫 2.0 版時,您「必須」支援在授予權限前需要額外步驟的購買交易。舉例來說,使用者可能會選擇在實體商店中以現金購買應用程式內產品。這代表交易會在應用程式外部完成。在這種情況下,建議僅在使用者完成交易後授予相關權限。

如要啟用未完成的購物交易,請在初始化應用程式時呼叫 enablePendingPurchases()

使用 Purchase.getPurchaseState() 判斷購買狀態是 PURCHASED 還是 PENDING。請注意,只有在狀態為 PURCHASED 時才可授予權限。請按照下列步驟檢查 Purchase 狀態更新:

  1. 啟動應用程式時,請呼叫 BillingClient.queryPurchases() 來擷取與使用者相關聯的未消耗產品清單。
  2. 請透過 Purchase.getPurchaseState() 呼叫每個傳回的 Purchase 物件。
  3. 執行 onPurchasesUpdated() 方法以回應 Purchase 物件的變更。

此外,Google Play Developer API 還提供 Purchases.products 適用的 PENDING 狀態。未完成交易功能不適用於訂閱項目。

這個版本還推出了新的即時開發人員通知類型 OneTimeProductNotification。此通知類型包含單一訊息,值為 ONE_TIME_PRODUCT_PURCHASEDONE_TIME_PRODUCT_CANCELED,並僅適用於與延遲付款方式相關聯的購買交易,例如現金。

確認未完成的購買交易時,請只在購買狀態為 PURCHASED (而不是 PENDING) 時確認。

API 變更

Google Play 帳款服務程式庫 2.0 版包含多項 API 變更,以支援新功能並釐清現有功能。

consumeAsync

consumeAsync() 現在使用 ConsumeParams 物件,而不是 purchaseTokenConsumeParams 包含 purchaseToken 和選用的開發人員酬載。

舊版 consumeAsync() 已從這個版本中移除。

queryPurchaseHistoryAsync

為了盡量避免混淆,queryPurchaseHistoryAsync() 現在會傳回 PurchaseHistoryRecord 物件,而不是 Purchase 物件。PurchaseHistoryRecord 物件與 Purchase 物件相同,但只反映 queryPurchaseHistoryAsync() 傳回的值,不含 autoRenewingorderIdpackageName 欄位。請注意,傳回的資料不會有任何改變,queryPurchaseHistoryAsync() 會傳回與之前相同的資料。

BillingResult 傳回值

先前傳回 BillingResponse 整數值的 API 現在會傳回 BillingResult 物件。BillingResult 包含 BillingResponse 整數,以及可用來診斷錯誤的偵錯字串。偵錯字串使用 en-US 語言代碼,並且不對使用者顯示。

修正錯誤

Google Play 帳款服務程式庫 1.2.2 版 (2019 年 3 月 7 日)

現已推出 Google Play 帳款服務程式庫 1.2.2 版。這個版本包含下列異動:

修正錯誤

  • 已修正 1.2.1 版中的執行緒問題,背景呼叫不會再封鎖主要執行緒。

其他異動

  • 雖然仍建議使用主要執行緒,但現在已可從背景執行緒將 Google Play 帳款服務程式庫執行個體化。
  • 執行個體化程序已完全遷移至背景執行緒,以減少發生 ANR 的可能性。

Play 帳款服務程式庫 1.2.1 版 (2019 年 3 月 4 日)

現已推出 Google Play 帳款服務程式庫 1.2.1 版。這個版本包含下列異動:

主要異動

其他異動

  • 已新增 PurchasesResultSkuDetailsResult 的公開建構函式,以便簡化測試程序。
  • SkuDetails 物件可以使用新方法 getOriginalJson()
  • 現在所有 AIDL 服務呼叫均將由背景執行緒處理。

修正錯誤

  • 空值回呼事件監聽器不會再傳遞至公用 API。

Google Play 帳款服務程式庫 1.2 版 (2018 年 10 月 18 日)

現已推出 Google Play 帳款服務程式庫 1.2 版。這個版本包含下列異動:

異動內容摘要

  • Google Play 帳款服務程式庫現已獲得《Android 軟體開發套件授權協議》授權。
  • 已新增 launchPriceChangeConfirmationFlow API,提示使用者查看訂閱項目價格的待定變更。
  • 支援新計費模式 DEFERRED,可在升級或降級使用者的訂閱項目時使用。
  • BillingFlowParams 類別中,將 setSku() 取代為 setSkuDetails()
  • 修正小錯誤並改善程式碼。

價格異動確認

您現在可以在 Google Play 管理中心變更訂閱項目價格,並在使用者進入應用程式時提示使用者檢視並接受新價格。

如要使用這個 API,請使用訂閱項目產品的 skuDetails 建立 PriceChangeFlowParams 物件,然後呼叫 launchPriceChangeConfirmationFlow()。執行 PriceChangeConfirmationListener 來處理價格異動確認流程完成後的結果,如以下程式碼片段所示:

Kotlin

val priceChangeFlowParams = PriceChangeFlowParams.newBuilder()
    .setSkuDetails(skuDetailsOfThePriceChangedSubscription)
    .build()

billingClient.launchPriceChangeConfirmationFlow(activity,
        priceChangeFlowParams,
        object : PriceChangeConfirmationListener() {
            override fun onPriceChangeConfirmationResult(responseCode: Int) {
                // Handle the result.
            }
        })

Java

PriceChangeFlowParams priceChangeFlowParams =
        PriceChangeFlowParams.newBuilder()
    .setSkuDetails(skuDetailsOfThePriceChangedSubscription)
    .build();

billingClient.launchPriceChangeConfirmationFlow(activity,
        priceChangeFlowParams,
        new PriceChangeConfirmationListener() {
            @Override
            public void onPriceChangeConfirmationResult(int responseCode) {
                // Handle the result.
            }
        });

價格異動確認流程會顯示一個對話方塊,列出新價格資訊,並要求使用者接受新價格。這個流程會傳回 BillingClient.BillingResponse 類型的回應代碼。

全新計費模式

升級或降級使用者的訂閱項目時,您可以使用新計費模式 DEFERRED,這個模式會在下次續約時更新使用者的訂閱項目。如要進一步瞭解如何設定此計費模式,請參閱「設定計費模式」。

設定 SKU 詳細資料的新方法

BillingFlowParams 類別中,已淘汰 setSku() 方法。這項異動是為了最佳化 Google Play 帳款服務流程。

在應用程式內結帳用戶端中建構新的 BillingFlowParams 執行個體時,建議您直接改用 setSkuDetails() 處理 JSON 物件,如以下程式碼片段所示:

BillingFlowParams 建構工具類別中,已淘汰 setSku() 方法。請改用 setSkuDetails() 方法,如以下程式碼片段所示。傳遞至 setSkuDetails() 物件的物件來自 querySkuDetailsAsync() 方法。

Kotlin

private lateinit var mBillingClient: BillingClient
private val mSkuDetailsMap = HashMap<String, SkuDetails>()

private fun querySkuDetails() {
    val skuDetailsParamsBuilder = SkuDetailsParams.newBuilder()
    mBillingClient.querySkuDetailsAsync(skuDetailsParamsBuilder.build()
    ) { responseCode, skuDetailsList ->
        if (responseCode == 0) {
            for (skuDetails in skuDetailsList) {
                mSkuDetailsMap[skuDetails.sku] = skuDetails
            }
        }
    }
}

private fun startPurchase(skuId: String) {
    val billingFlowParams = BillingFlowParams.newBuilder()
    .setSkuDetails(mSkuDetailsMap[skuId])
    .build()
}

Java

private BillingClient mBillingClient;
private Map<String, SkuDetails> mSkuDetailsMap = new HashMap<>();

private void querySkuDetails() {
    SkuDetailsParams.Builder skuDetailsParamsBuilder
            = SkuDetailsParams.newBuilder();
    mBillingClient.querySkuDetailsAsync(skuDetailsParamsBuilder.build(),
            new SkuDetailsResponseListener() {
                @Override
                public void onSkuDetailsResponse(int responseCode,
                        List<SkuDetails> skuDetailsList) {
                    if (responseCode == 0) {
                        for (SkuDetails skuDetails : skuDetailsList) {
                            mSkuDetailsMap.put(skuDetails.getSku(), skuDetails);
                        }
                    }
                }
            });
}

private void startPurchase(String skuId) {
    BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
            .setSkuDetails(mSkuDetailsMap.get(skuId))
            .build();
}

Play 帳款服務程式庫 1.1 版 (2018 年 5 月 7 日)

現已推出 Google Play 帳款服務程式庫 1.1 版。這個版本包含下列異動:

異動內容摘要

  • 現已支援在升級/降級現有訂閱項目時,在 BillingFlowParams 中指定計費模式。
  • 系統不再支援 BillingFlowParams 中的 replaceSkusProration 布林值標記,改用 replaceSkusProrationMode
  • launchBillingFlow() 現在會觸發失敗回應的回呼。

行為異動

Google Play 帳款服務程式庫 1.1 版包含下列行為異動。

開發人員可在 BillingFlowParams 類別中設定 replaceSkusProrationMode

在升級或降級使用者的訂閱項目時,ProrationMode 提供了計費類型的詳細說明。

Kotlin

BillingFlowParams.newBuilder()
    .setSku(skuId)
    .setType(billingType)
    .setOldSku(oldSku)
    .setReplaceSkusProrationMode(replaceSkusProrationMode)
    .build()

Java

BillingFlowParams.newBuilder()
    .setSku(skuId)
    .setType(billingType)
    .setOldSku(oldSku)
    .setReplaceSkusProrationMode(replaceSkusProrationMode)
    .build();

目前 Google Play 支援下列計費模式:

IMMEDIATE_WITH_TIME_PRORATION 替換內容會立即生效,而新的到期時間將按比例計算,並支付給使用者或向使用者收費。這是目前的預設行為。
IMMEDIATE_AND_CHARGE_PRORATED_PRICE 替換內容會立即生效,帳單週期則維持不變。系統會收取剩餘期間的價格。

注意:這個選項僅適用於訂閱項目升級。

IMMEDIATE_WITHOUT_PRORATION 替換內容會立即生效,系統會從下個週期開始以新價格收費,帳單週期則維持不變。

BillingFlowParams 類別已停止支援 replaceSkusProration

開發人員先前可以設定布林值標記,以針對訂閱項目升級要求按比例收費。由於我們現已支援 ProrationMode,內含更多的詳細計費指示,因此不再支援這項布林值標記。

launchBillingFlow() 現在會觸發失敗回應的回呼

帳款服務一律會觸發 PurhcasesUpdatedListener 回呼,並非同步傳回 BillingResponse。系統也會保留 BillingResponse 的同步傳回值。

修正錯誤

  • 在服務中斷連線時,以非同步方式提前結束。
  • Builder 參數物件不會再變更建構的物件。
  • 問題 68087141launchBillingFlow() 現在會觸發失敗回應的回呼。

Google Play 帳款服務程式庫 1.0 版 (2017 年 9 月 19 日,公告)

現已推出 Google Play 帳款服務程式庫 1.0 版。這個版本包含下列異動:

重要異動

  • 程式庫資訊清單內現已嵌入帳單權限,您不再需要在 Android 資訊清單內加入 com.android.vending.BILLING 權限。
  • 已將新的建構工具新增至 BillingClient.Builder 類別。
  • 已為 SkuDetailsParams 類別推出新的建構工具模式,用於查詢 SKU。
  • 為求一致性,已更新多個 API 方法 (相同的傳回引數名稱和順序)。

行為異動

Google Play 帳款服務程式庫 1.0 版包含下列行為異動。

BillingClient.Builder 類別

BillingClient.Builder 現在是透過 newBuilder 模式初始化:

Kotlin

billingClient = BillingClient.newBuilder(context).setListener(this).build()

Java

billingClient = BillingClient.newBuilder(context).setListener(this).build();

現已採用 BillingFlowParams 類別呼叫 launchBillingFlow 方法

如要啟動購買交易或訂閱項目的帳單流程,launchBillingFlow() 方法會收到使用請求特定參數初始化的 BillingFlowParams 執行個體:

Kotlin

BillingFlowParams.newBuilder().setSku(skuId)
        .setType(billingType)
        .setOldSku(oldSku)
        .build()

// Then, use the BillingFlowParams to start the purchase flow
val responseCode = billingClient.launchBillingFlow(builder.build())

Java

BillingFlowParams.newBuilder().setSku(skuId)
                              .setType(billingType)
                              .setOldSku(oldSku)
                              .build();

// Then, use the BillingFlowParams to start the purchase flow
int responseCode = billingClient.launchBillingFlow(builder.build());

查詢可用產品的新方式

queryPurchaseHistoryAsync()querySkuDetailsAsync() 方法的引數會包裝進建構模式:

Kotlin

val params = SkuDetailsParams.newBuilder()
params.setSkusList(skuList)
        .setType(itemType)
billingClient.querySkuDetailsAsync(params.build(), object : SkuDetailsResponseListener() {
    ...
})

Java

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();
params.setSkusList(skuList)
        .setType(itemType);
billingClient.querySkuDetailsAsync(params.build(), new SkuDetailsResponseListener() {...})

為方便起見,我們現在會透過結果程式碼和 SkuDetails 物件清單 (而不是先前的包裝函式類別) 傳回結果,讓您可在我們的 API 中保持一致:

Kotlin

fun onSkuDetailsResponse(@BillingResponse responseCode: Int, skuDetailsList: List<SkuDetails>)

Java

public void onSkuDetailsResponse(@BillingResponse int responseCode, List<SkuDetails> skuDetailsList)

已變更 onConsumeResponse() 方法的參數順序

ConsumeResponseListener 介面上 onConsumeResponse 的引數順序已變更,以便在 API 中保持一致:

Kotlin

fun onConsumeResponse(@BillingResponse responseCode: Int, outToken: String)

Java

public void onConsumeResponse(@BillingResponse int responseCode, String outToken)

未包裝的 PurchaseResult 物件

PurchaseResult 已解除包裝,以便在 API 中保持一致:

Kotlin

fun onPurchaseHistoryResponse(@BillingResponse responseCode: Int, purchasesList: List<Purchase>)

Java

void onPurchaseHistoryResponse(@BillingResponse int responseCode, List<Purchase> purchasesList)

修正錯誤

開發人員預覽版 1 (2017 年 6 月 12 日,公告)

開發人員預覽版旨在簡化帳單的開發程序,讓開發人員能專注於執行 Android 應用程式專屬的邏輯,例如應用程式架構和導覽結構。

這個程式庫提供多種便利的類別和功能,可讓您整合 Android 應用程式與 Google Play Billing API。另也提供 Android 介面定義語言 (AIDL) 服務頂端的抽象層,可讓開發人員更輕鬆地定義應用程式和 Google Play Billing API 之間的介面。