如果你在安卓系統上使用應用程式內購買功能，遲早你會遇到這個問題。 Google Play 結算庫 v7這不僅僅是一次普通的更新：它包含了 API 變更、新的訂閱功能、控制台要求，以及Google非常明確的截止日期。如果你想繼續在 Google Play 上發布或更新你的應用程式，避免任何意外情況的發生，那麼忽視這次更新已經不再可行。
本文將向您展示如何 更新並實作 Google Play 結算庫 v7 循序漸進：從與 PBL 5 和 6 的區別，到如何整合訂閱、一次性購買、RTDN，如何使用 Play Billing Lab 進行測試，以及如何在官方支援滯後的 .NET MAUI 等生態系統中生存。目標是讓您在閱讀本文後，能夠自信地完成遷移，並且無需花費一分錢。
Google Play結算庫v7概述
Google Play 結算庫 7 對帳單管理方式進行了重大改進。 付款、訂閱和特殊計劃不過，它的設計旨在使遷移過程相對平穩。好消息是，許多新的 API 都是可選的：您可以更新依賴項，調整一些引用，基本整合仍然可以正常運作。
本版本重點在於三個關鍵領域： 新的訂閱選項 （例如虛擬配額），更好地支持 預付費方案中的待處理購買此外，API 也進行了更改，清理了先前版本（PBL 5 和 6）中已過時的內容。同時，Google 也調整了一些錯誤處理方式以及處理待處理事務的方式，以避免不一致的情況。
首先，你需要更新應用程式模組中檔案的依賴項。 構建.gradle:
dependencies {
def billingVersion = "7.0.0"
implementation "com.android.billingclient:billing:$billingVersion"
}
完成這一步驟後，就該審查使用舊版 API 的程式碼了。許多調用都與此相關。 訂閱費用按比例計算和替代計費方式 它們已被重新命名或刪除，因此在編譯任何內容並將其上傳到 Play 控制台之前，最好仔細查看所有對 BillingClient 和 BillingFlowParams 的參考。
透過一次性購買和訂閱實現盈利的策略
當你在應用程式內銷售數位產品時，光貼購買對話框就完事是不夠的：設計一個 整個購買週期中流暢的使用者體驗這適用於單一產品（消耗型或非消耗型）和訂閱服務。流程越自然流暢，轉換率越高，取消率就越低。
使用 Play Billing 進行購買的典型流程（無論是訂閱還是單件商品）通常遵循以下幾個明確的階段，您的後端也應該了解這些階段：
- 使用者瀏覽可供選擇的產品並選擇一款。
- 該應用程式會啟動 Google Play 結算流程以完成付款。
- 購買已完成，您的應用程式已收到結果。
- 您的伺服器會根據 Google Play 開發者 API 驗證購買行為。
- 您的系統中已授予使用者相應的內容或權限。
- Google 已收到購買已處理（已消費或已確認）的通知。
對於消耗品而言，至關重要的是 在適當的時機使用令牌。 以便實現無縫重購和協助 阻止在 Google Play 上發生意外購買在訂閱服務中，您必須控制續訂、寬限期、暫停和取消，以便用戶能夠獲得他們所支付的全部內容，而不會少一天。
整合到應用程式中只是工作的一半：您的伺服器必須維護一個 可靠的權利和購買狀態記錄如果您提供跨平台存取或需要有關收入、留存率和流失率的詳細統計數據，這一點尤其重要。即時開發者通知 (RTDN) 正是在這種情況下發揮作用，它就像購買生命週期中的「黑盒子」一樣。
借助 RTDN，您可以近乎即時地對關鍵事件做出反應：例如新購買、續訂失敗、訂閱進入寬限期或購買取消。這使您能夠制定相應的策略。 用戶恢復和 預防詐欺例如，當付款失敗時自動發送電子郵件，或當客戶因網路問題未收到訊息時自動調整權限。
即時開發者通知 (RTDN) 和 Google Cloud Pub/Sub
RTDN 使用 谷歌云發布/訂閱 作為 Google Play 和您的後端之間的即時訊息系統。 Google Play 會發布關於發布/訂閱主題的事件，您可以訂閱該主題，以便在購買或訂閱狀態發生變化時收到訊息。
基本流程很簡單：Google Play 向 Pub/Sub 主題發送 base64 編碼的訊息，您的訂閱者提取該訊息，對其進行解碼，然後處理通知。在字段中 data 訊息中包含一個 JSON 對象 開發者通知其中包括訊息版本、套件名稱、活動時間以及有關一次性購買、訂閱、取消購買或試用的具體數據等資訊。
{
"version": string,
"packageName": string,
"eventTimeMillis": long,
"oneTimeProductNotification": OneTimeProductNotification,
"subscriptionNotification": SubscriptionNotification,
"voidedPurchaseNotification": VoidedPurchaseNotification,
"testNotification": TestNotification
}
多虧了這些信息，你可以 即使用戶設備發生故障，也要保持後端同步。想像一下，用戶成功完成購買，Google Play 也確認了交易，但行動裝置在您的應用程式收到結算庫的回呼之前就斷開了網路連線。如果沒有 RTDN，您可能永遠不會知道這件事。而有了發布/訂閱機制，您的伺服器會收到單獨的通知，並可以獨立於客戶端授予授權。
RTDN 的雲端發布/訂閱配置
在 Google Play 控制台中啟用 RTDN 之前，您需要準備一個專案。 Google雲端平台（GCP） 並在那裡配置發布/訂閱。過程相對簡單，但最好仔細按照步驟操作，以免權限或資源名稱出現任何意外情況。
創建主題
首先，您必須建立一個 發布/訂閱主題 這將作為您的 Google Play 發佈點。在 Google Cloud 控制台中，選擇您的項目，前往「發布/訂閱」部分，然後按照官方的「建立主題」指南建立新主題。建立的主題名稱將採用以下格式：
projects/{project_id}/topics/{topic_name}
啟用通知時，你需要將這個完整名稱貼到 Play 管理中心。
訂閱創建
要閱讀此主題中的消息，您需要一個 出版/訂閱您可以將其配置為 推 或作為 拉在參考代碼實驗室中，我們使用拉取訂閱，其中後端發起請求來檢索訊息。
您應該查看 Cloud Pub/Sub 訂閱者指南中的選項，以確定推送還是拉取更適合您的架構。確定後，請按照「新增訂閱」文件中的步驟操作，並將其連結到您先前建立的主題。之後，Google Play 在該主題中發布的任何消息都將對您的訂閱者可見。
授予 Google Play 向您的主題發佈內容的權限
除非您明確授權，否則 Pub/Sub 不會允許 Google Play 發布任何內容。 服務帳戶在 Google Cloud 控制台中，您需要前往主題權限設定並新增主權限：
[email protected]
賦予此帳戶以下角色 出版/訂閱出版商 （發布者）儲存變更後，Google Play 就可以向您的主題發送 RTDN，而不會出現授權問題。
在 Google Play 控制台中啟用 RTDN
發布/訂閱配置完成後，您需要告訴 Play 管理中心通知的發送位置。在 Google Play 管理中心的應用程式內，前往… 透過 Play 獲利 > 獲利設置 找到即時開發者通知部分。
在那裡你需要：
- 勾選此方塊以啟用即時通知。
- 請在對應的欄位中輸入完整的 Pub/Sub 主題名稱，格式請遵循以下規定。
projects/{project_id}/topics/{topic_name}. - 使用測試按鈕發送測試訊息。
測試訊息對於驗證以下內容至關重要： 整合實施得很順利。如果您擁有拉取訂閱，您可以前往雲端控制台，選擇該訂閱，點擊“檢視訊息”，然後提取測試訊息。別忘了執行此操作。 ACK 避免重複接收您閱讀的任何訊息。
對於推送訂閱，請驗證您的端點是否收到訊息並傳回有效的 HTTP 代碼。如果發生問題，控制台會在發布測試時顯示錯誤，通常與主題名稱或服務帳戶權限有關。
最後，您可以設定要接收哪些類型的通知：僅接收訂閱和已取消購買的通知，或者 所有通知，包括一次性購買通知 （例如一次性產品購買和一次性產品取消等事件）。如果您也使用獨特產品，通常的做法是啟動整個產品集，以便全面了解所有產品。
在後端建置發布/訂閱系統
主題和訂閱都準備就緒後，現在是時候實施了。 讀取和處理 RTDN 的訂閱者Google 提供了多種語言的範例；一個典型的 Java 範例使用 Cloud Pub/Sub 用戶端程式庫來啟動一個 Subscriber 誰會監聽訊息和打電話 MessageReceiver.
總體模式始終相同：檢索訊息，解碼字段 data 您將 base64 轉換為文本，解析 JSON，並提取相關字段（例如： packageName, oneTimeProductNotification o subscriptionNotification）並決定在您的系統中執行什麼操作。成功處理通知後，您必須 請回覆確認訊息。 這樣 Pub/Sub 就不會再發送了。
範例程式碼展示了接收器如何列印版本號和包名，但在實際應用中，你還需要做更多： 您需要驗證購買訊息，並將權限授予正確的使用者。您需要更新資料庫，並在必要時呼叫 Play Developer API 來處理或識別購買行為。
將通知連結到使用者：使用混淆的帳戶 ID
從伺服器管理採購時，一個常見的問題是確定特定 RTDN 通知屬於哪個使用者。為此，計費客戶端 API 允許您附加一個 混淆的帳戶標識符 當您啟動購買流程： obfuscatedAccountId.
其想法是使用系統中的穩定標識符（例如，使用者的內部 ID），但 出於隱私和安全考慮，已進行模糊處理。該值與購買相關聯，然後出現在 Google Play Developer API 傳回的資訊中，這樣，當您收到 RTDN 並驗證令牌時，您就能明確地知道應該將權限授予資料庫中的哪個帳戶。
在客戶方面，準備時 BillingFlowParams你只需要建立一個列表 ProductDetailsParams 並打電話 setObfuscatedAccountId(obfuscatedAccountId) 在啟動流程之前進行此操作。這不會改變使用者體驗，但會大大簡化流程。 後端採購分配邏輯 並幫助谷歌偵測詐欺行為。
使用 Google Play 開發者 API 驗證購買
在授予您伺服器上的任何權限之前，必須透過致電來驗證購買的合法性。 Google Play 開發者 API僅僅依賴客戶端甚至RTDN的資訊是不夠的：你必須驗證… purchaseToken 直接針對官方端點，如有必要 管理退款.
對於獨一無二的產品，您將使用端點 purchases.products:get對於訂閱用戶來說，路徑是這樣的： purchases.subscriptionsv2:get建議的流程是：
- 提取
purchaseToken來自 Pub/Sub 訊息。 - 檢查您的資料庫，看看是否已經處理過它；每個令牌都是 全球獨一無二因此，它非常適合用作主鍵，以避免重複。
- 如果是新應用，請使用軟體包號、SKU 和…呼叫 Google Play 開發者 API。
purchaseToken. - 確認回覆表示已完成購買。 已購買 （非待處理或已取消）。
- 如果一切匹配，則註冊令牌並授予關聯用戶相應的權限。
要從 Java 與 Play Developer API 通信，您可以使用 AndroidPublisher使用 JSON 格式的服務帳戶憑證進行初始化。您可以配置範圍 AndroidPublisherScopes.ANDROIDPUBLISHER你建立客戶端並呼叫該方法 purchases().products().get(...)若因臨時網路或服務問題導致通話失敗，建議 實現指數退避重試 以免錯過此次活動。
從伺服器確認或完成購買
驗證購買並在系統中授予授權後，下一步是通知 Google 交易已成功處理。對於單件商品，您有兩種選擇： 消費購買 或簡單地 認出她.
消耗品（例如虛擬貨幣、生命值等）必須經過此端點。 purchases.products:consume這會將代幣標記為已使用，並允許用戶重新購買相同商品而不會發生衝突。對於非消耗性產品（例如終身解鎖高級版），您必須調用 purchases.products:acknowledge這會通知 Google 使用者已經擁有相關權限。
使用訂閱 purchases.subscriptions:acknowledge這表示訂閱已成功處理並分配給使用者。如果您未在合理的時間範圍內確認購買，Google 可能會認為有問題並撤銷交易，因此請務必及時確認。 授予權利後，立即進行返回操作。.
在你的 AndroidPublisher 助手類別中，你可以加入以下方法： executeProductPurchasesConsume y executeProductPurchasesAcknowledge 調用相應的端點。同樣，建議在偶爾出現故障時實施重試機制，以確保沒有令牌處於危險的中間狀態。
使用 Play Billing Lab 進行進階測試
許多開發者低估了測試階段的重要性。要自信地發布產品，你需要能夠進行模擬測試。 網路錯誤、非標準回應和極端情況這時 Play Billing Lab 就派上了用場，這是一款在 Google Play 上提供的免費應用程序，專門用於測試 Play Billing Library 集成。
Play Billing Lab 包括 答案模擬器 這使得可以強制執行不同的 BillingResponseCode 在您的應用程式呼叫計費庫時，可以這樣做。這樣，您就可以重現一些場景，例如，客戶由於網路問題無法完成購買，但您的後端能夠正確處理 RTDN，並最終在無需用戶幹預的情況下授予授權。
為了使您的應用程式能夠與模擬器通信，您需要在設定檔中啟用使用元資料的「計費覆蓋」測試。 AndroidManifest.xml:
<manifest ... >
<application ... >
...
<meta-data
android:name="com.google.android.play.largest_release_audience.NONPRODUCTION"
android:value="" />
<meta-data
android:name="com.google.android.play.billingclient.enableBillingOverridesTesting"
android:value="true" />
</application>
</manifest>
標籤 啟用計費覆蓋測試 在計費庫中啟用模擬響應測試。 「NONPRODUCTION」標籤提醒您，此版本不應在啟用覆蓋設定的情況下投入生產環境。在準備最終版本供使用者使用時，請確保： 移除此元資料或使用單獨的清單.
配置完成後，從 Play Billing Lab 應用程式中使用許可證測試員帳戶登錄，啟動「模擬 Play Billing Library 回應」選項，並選擇要為每個 API 傳回的錯誤代碼（例如，特定錯誤）。 consumeAsync然後，您只需打開您的應用程式並執行要測試的流程：模擬器將返回配置的回應，您可以驗證您的重試邏輯、錯誤處理和 RTDN 是否按預期運行。
遷移到 Play Billing Library 7 時的關鍵 API 變更
除了 RTDN 和測試之外，遷移到 PBL 7 還涉及一些特定的 API 點。對於從 PBL 5 或 6 遷移過來的用戶，建議仔細查看最相關的變更，以確保專案能夠順利編譯，並且業務邏輯保持一致。
首先，與以下方面相關的 API： 按比例分配模式 訂閱更改選項已移除。現在使用以下方式： 替換模式 用於管理計劃變更（升級、降級等）。如果您仍然使用類似以下的方法： setReplaceProrationMode o setReplaceSkusProrationMode您需要將它們遷移到新版本。 setSubscriptionReplacementMode 並根據更新後的文檔調整邏輯。
API 也已移除。 launchPriceConfirmationFlow該功能已被標記為過時。要處理訂閱價格變更，您應該參考價格變更指南中的新工作流程和建議，其中詳細說明如何正確通知使用者以及如何管理使用者同意。
另一點也很重要，那就是 替代計費 API方法 BillingClient.Builder.enableAlternativeBilling, AlternativeBillingListener y AlternativeChoiceDetails 已經消失，取而代之的是一套更統一的命名法：現在你必須使用 BillingClient.Builder.enableUserChoiceBilling() 旁 UserChoiceBillingListener y UserChoiceDetails根據Google本身的說法，這基本上只是名稱變更，行為並無改變，相關協議也印證了這一點。 Google和Epic Games同意開放Android.
最後，輸入了一個新的錯誤代碼。 網路錯誤 en BillingResult以及……的含義和條件 SERVICE_TIMEOUT 和 SERVICE_UNAVAILABLE如果您有自訂錯誤處理邏輯（例如，決定何時向使用者顯示訊息、何時靜默重試等），建議您進行審查，以考慮這些新的細微差別。
待處理交易，購買前缺少訂單編號
PBL 7 的一個細微變化是，庫不再生成 待處理訂單的訂單編號。在這些情況下， orderId 只有當購買狀態變成「已購買」後，此功能才會可用。這尤其會影響從一開始就使用訂單 ID 作為主要參考資訊的流程。
谷歌的建議是，你應該依賴… 用於記錄和對帳的購買令牌至少在交易進行期間是如此。如果您發現某筆購買已從 Play 商店消失，請檢查。 如果購買記錄消失了該怎麼辦？.
如果您尚未處理過未結餘額，請查看計費庫整合指南和相關文件。 採購生命週期管理在那裡，您將找到不同的狀態、如何應對每種狀態以及 RTDN 如何融入這個難題。
PBL 7 新增選購功能：虛擬分期付款與預付款
PBL 7 的一些「不錯」的新功能包括： 虛擬付費訂閱 （虛擬分期付款訂閱）以及預付費訂閱待處理購買的擴展支援。這些功能並非強制性的，但它們可以幫助您在調整商業模式以適應不同市場時擁有更大的靈活性。
虛擬分期付款允許用戶支付更長期的訂閱費用 小額定期付款谷歌解釋說，開發者無需一次性支付大筆款項，而是按照年度計劃按月分期付款。如果用戶錯過付款，您和Google都不應該試圖追回已支付的款項。這使得它在實際使用中與標準的月度訂閱非常相似，至少在初期是如此。
目前，這些訂閱費用僅在以下地區提供： 巴西、法國、義大利和西班牙Google 建議密切關注 Play 管理中心，以了解新增支援的國家。配置可透過以下方式完成： ProductDetails.InstallmentPlanDetails 並按照具體指南將它們整合到您的應用程式中。
同時，支持力道也在擴大。 待處理的預付訂閱購買現在，您可以提供這樣的模式：使用者在應用程式內開始購買，然後透過其他方式完成付款，而計費庫能夠正確處理此流程。激活是透過調用完成的。 enablePendingPurchases() 初始化 BillingClient 時，特別是對於預付費計劃，使用 PendingPurchasesParams.Builder.enablePrepaidPlans().
Play Billing Library 5 和 6 的折舊期
隨著 PBL 7 的到來，Google已經確定了明確的日期。 停止對版本 5 和 6 的支持如果你仍然處於其中任何階段，你必須在日曆上用紅色標記：
- Google Play結算庫5將於2024年8月31日正式停止支援新應用程式和更新。雖然可以申請延期至2024年11月1日，但不建議長期依賴此方案。
- Google Play 結算庫 6 可用於發布新應用，有效期至 2025 年 8 月 1 日；也可用於更新現有應用，有效期至 2025 年 11 月 1 日。
在此日期之後，如果您尚未遷移到至少版本 6 或理想情況下遷移到版本 7，則需要更新至最新版本。 版本7您的應用程式在 Play 管理中心的更新將被封鎖。雖然您的應用程式仍可在使用者裝置上繼續運行，但您將無法進行任何更新，包括修復錯誤或新增依賴在應用程式商店發布的新功能。
.NET MAUI 案例及當前限制
如果你正在使用 .NET MAUI 和 Android 訂閱功能，你可能已經了解或體驗過，這並非易事。許多項目都使用了… 插件.應用內結算 該插件由 James Montemagno 開發，但已存檔且不再維護，因此不會更新以支援 Billing Library 7。同時，官方軟體包也已停止維護。 Xamarin.Android.Google.BillingClient 它一直依附於 Xamarin.Android 生態系統，與 .NET MAUI 不直接相容。
實際結果是： Play 主機發出警告 您的應用程式未使用 Billing Library 7.0.0 或更高版本，如果您繼續使用舊版本庫，將會阻止更新。一些開發者選擇了較極端的解決方案，例如暫時禁用訂閱功能以上傳新版本，但顯然，如果您的商業模式依賴於訂閱盈利，這種做法是不可持續的。
在這種情況下，許多團隊正在考慮其他方案，例如 第三方 SDK 這些服務底層已支援 PBL 7，並提供更穩定、跨平台的 API（例如，提供 Android、iOS 和其他平台 SDK 的訂閱後端解決方案）。這些服務通常能夠處理 Billing Library 版本遷移，並提供穩定的封裝層，從而顯著降低 Google 每次棄用新版本帶來的壓力。
直到微軟和MAUI團隊提供 官方軟體包已更新，完全相容 使用 Billing Library 7，您可以選擇以下方案：自行實現與原生 Billing Library 的綁定、使用第三方服務，或重新考慮如何在 MAUI 專案中整合購買功能。無論如何，最好不要等到最後一刻才做決定，因為 Play 的截止日期是固定的。
總體而言，Google Play Billing Library v7 的更新包括審查依賴項、清理過時的 API、透過購買驗證和即時資料網路 (RTDN) 加強後端邏輯，以及利用 Play Billing Lab 等測試工具在正式上線前發現所有漏洞。那些花時間對此次遷移進行微調的用戶將能夠更好地處理預付費套餐、虛擬費用、網路錯誤和訂閱生命週期變更，並更有可能在 Google Play 上保持穩定的收入和流暢的用戶體驗。 分享訊息，讓更多用戶了解主題。