有了 Google Play 帳單系統，您就能在 Android 應用程式中銷售數位產品和內容。在 2022 年 5 月推出的版本中，我們變更了訂閱產品的定義，這會影響產品在應用程式內的銷售方式及後端管理。如果您是首次整合 Google Play 帳款服務，請參閱「事前準備」一文開始整合作業。
如果您在 2022 年 5 月前，就已透過 Google Play 帳款服務販售訂閱項目，請務必瞭解如何在維持現有項目的同時採用新功能。
首先請注意，所有現存訂閱項目、應用程式和後端整合功能的運作方式，都與 2022 年 5 月的版本推出前相同。您可以慢慢開始採用這些新功能，不一定要立刻做出變更。Google Play 帳款服務程式庫的每個主要版本發布後，都提供兩年支援。目前與 Google Play Developer API 整合的功能仍會照常運作。
以下是 2022 年 5 月的更新總覽：
- 透過新版 Google Play 管理中心，您可以新增並管理訂閱項目、基本方案和優惠，新建和遷移的訂閱項目都包括在內。
- Play Developer API 的更新項目能以 API 的形式，支援 Google Play 管理中心 UI 的新功能。值得一提的是，Subscription Purchases API 已推出新版本。您可以使用這項 API 查看訂閱狀態，並管理訂閱項目購買資料。
- 新的 Play 帳款服務程式庫第 5 版推出全新的訂閱功能，您的應用程式可加以運用。準備好要升級至第 5 版時，請按照「遷移指南」中的說明操作。
訂閱設定
透過 Google Play 管理中心管理訂閱項目
自 2022 年 5 月起，Google Play 管理中心可能會有一些差異。
單一訂閱項目現在可包含多項基本方案和優惠。在 Play 管理中心內，先前建立的訂閱 SKU 會顯示為新的訂閱、基本方案和優惠物件。如果您尚未查看 Play 管理中心訂閱項目最近的變更，請參考連結內容，瞭解新物件的功能和設定等相關說明。所有現存的訂閱產品，都會以物件這種新格式顯示在 Google Play 管理中心。每個 SKU 都會顯示為訂閱物件，內含一個基本方案和回溯相容的優惠 (如適用)。
由於舊版整合作業預期每項訂閱都有一項優惠 (以 SkuDetails 物件代表)，因此每個訂閱項目都可包含一項可回溯相容的基本方案或優惠。如果應用程式採用的 querySkuDetailsAsync() 方法現已淘汰，則系統將把回溯相容的基本方案或優惠當做 SKU 的一部分回傳。如欲進一步瞭解如何設定及管理與回溯相容的方案，請參閱「瞭解訂閱服務」一文。如果應用程式只使用 queryProductDetailsAsync()，而且沒有任何舊版應用程式仍在進行購買交易，您就不必再使用回溯相容的優惠。
透過 Subscriptions Publishing API 管理訂閱項目
Play Developer API 提供訂閱項目購買交易的新功能。用於 SKU 管理的 inappproducts API 仍會照常運作，包括處理一次性購買產品和訂閱。因此，您無須立即進行變更來維持整合作業。
不過請注意，Google Play 管理中心只會使用新的訂閱實體。當您開始在主控台中編輯訂閱項目時，inappproducts API 將無法再用於訂閱。
如果您在 2022 年 5 月前使用 Publishing API，為避免發生問題，所有現有訂閱項目現在在 Google Play 管理中心都會顯示為唯讀狀態。如果您嘗試進行變更，可能會收到這項限制的警示說明。在主控台中進一步編輯訂閱項目之前，請先更新後端整合，以使用新的訂閱發布端點。您可以使用新的 monetization.subscriptions、monetization.subscriptions.baseplans 和 monetization.subscriptions.offers 端點，管理所有可用的基本方案和優惠。請參閱下表，瞭解不同欄位如何從 InAppProduct 實體對應至 monetization.subscriptions 下的新物件：
| InAppProduct | 訂閱 |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
資訊列表 |
defaultPrice |
無對等項目 |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
taxAndComplianceSettings |
這項必要 API 更新僅適用於 Publishing API (SKU 管理)。
Play 帳款服務程式庫異動
為支援逐步遷移，「Play 帳款服務程式庫」包含先前版本中的所有方法和物件。SkuDetails 物件和函式 (例如 querySkuDetailsAsync()) 仍然存在，您可以升級使用新的功能，而不需立即更新現有的訂閱程式碼。您也可以將各種方法標示為回溯相容，以控制透過這些方法提供的優惠。
除了保留舊版方法以外，「Play 帳款服務程式庫 5」現還提供新的 ProductDetails 物件以及相對應的 queryProductDetailsAsync() 方法來處理新的實體和功能。現在，ProductDetails 也支援現有的應用程式內產品 (一次性購買和消耗品)。
若為訂閱項目，ProductDetails.getSubscriptionOfferDetails() 將回傳使用者能夠購買的所有基本方案與優惠清單。也就是說，無論回溯相容性為何，您都可以存取所有適合使用者的基本方案和優惠方案。getSubscriptionOfferDetails() 會針對非訂閱產品回傳 null。如果是一次性消費，可使用 getOneTimePurchaseOfferDetails()。
Play 帳款服務程式庫 5 還包含啟動購買流程的新版和舊版方法。如果傳遞到 BillingClient.launchBillingFlow() 的 BillingFlowParams 物件是使用 SkuDetails 物件設定的，系統會擷取優惠資訊，並藉此銷售與基本 SKU 相容的基本方案或優惠。如果傳遞到 BillingClient.launchBillingFlow() 的 BillingFlowParams 物件是使用 ProductDetailsParams 物件 (包括 ProductDetails 和 String) 設定的，則表示優惠購買後，系統會根據相關資訊識別使用者所要取得的產品。
queryPurchasesAsync() 會回傳使用者擁有的所有購買項目。若要表示所要求的產品類型，您可以向舊版一樣傳入 BillingClient.SkuType 值，或傳入一個包含代表新訂閱實體的 BillingClient.ProductType 數值的 QueryPurchasesParams 物件。
建議您盡快將應用程式更新至程式庫第 5 版，以便開始利用新的訂閱功能。
管理訂閱狀態
本節說明 Google Play 帳款服務整合後端元件的主要變更，您需要實作該整合才能遷移至第 5 版。
即時開發人員通知
不久之後，SubscriptionNotification 物件將不再包含「subscriptionId」。如果您利用此欄位來識別訂閱項目產品，當您收到通知後，應使用 purchases.subscriptionv2:get 進行更新，以便從訂閱狀態取得這項資訊。在購買狀態傳回的 lineItems 集合中，每個 SubscriptionPurchaseLineItem 元素都會包含對應的 productId。
Subscriptions Purchases API：取得訂閱狀態
在舊版 Subscription Purchases API 中，您可以使用 purchases.subscriptions:get 來查詢訂閱狀態。此端點並未變更，且會繼續支援與回溯相容的訂閱項目購買。此端點不支援 2022 年 5 月推出的新功能。
在新版 Subscription Purchases API 中，使用 purchases.subscriptionsv2:get 取得訂閱項目購買狀態。此 API 與已遷移的訂閱項目、新的訂閱項目 (預付與自動續約) 及各類型的購買交易相容。您可以使用此端點，在接收通知時檢查訂閱狀態。回傳的物件 SubscriptionPurchaseV2 包含新欄位，但其中仍包含持續支援現有訂閱項目所需的舊版資料。
預付方案的 PurchasePurchaseV2 欄位
新增欄位支援由使用者擴增的預付方案，而非自動續約。所有欄位不僅適用於預付方案，更適用於自動續訂的訂閱項目，但有以下限制：
- [New field] lineItems[0].prepaid_plan.allowExtendedAFTERTime：指出使用者何時可以再購買儲值方案延長預付方案 (使用者一次只能有一筆未消費的儲值)。
- [New field] subscriptionState：指定訂閱物件狀態。如果是預付方案，此值必須是
ACTIVE、PENDING或CANCELED。 - lineItems[0].expiryTime：預付方案一律提供此欄位。
- paused_state_context：此欄位一律不予顯示，因為預付方案無法暫停。
- lineItems[0].auto_renewing_plan：不適用於預付方案。
- canceled_state_context：不適用於預付方案，因為此欄位僅適用於主動取消訂閱項目的使用者。
- lineItems[0].productId：此欄位會取代先前版本中的
subscriptionId。
週期或經常性訂閱項目的 PurchasePurchaseV2 欄位
purchases.subscriptionv2 包含新欄位，可提供新訂閱物件的詳細資訊。下表顯示舊版訂閱項目端點的欄位如何對應至 purchases.subscriptionv2 中的對應欄位。
| 訂閱購買 | 訂閱購買第 2 版 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (無對等欄位) | lineItems (subscriptionPurchaseLineItem 清單)，代表購買的產品 |
| (無對等欄位) | lineItems.offerDetails.basePlanId |
| (無對等欄位) | lineItems.offerDetails.offerId |
| (無對等欄位) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (購買時所獲取的各個訂閱項目都有各自的 expiryTime) |
| (無對等欄位) | subscriptionState (代表訂閱狀態) |
| (無對等欄位) | pausedStateContext (只有在訂閱狀態為 SUBSCRIPTION_STATE_PAUSED 時才會顯示) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (無對等欄位) | canceledStateContext (只有在訂閱狀態為 SUBSCRIPTION_STATE_CANCELED 時才會顯示) |
| (無對等欄位) | testPurchase (僅適用於已獲授權的測試人員購買) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode、priceAmountMicros、introductoryPriceInfo |
(無對等欄位) 您可以在已購買的訂閱項目中於 basePlan/offer 找到這項資訊。 |
| developerPayload | (無對等欄位) 開發人員酬載已淘汰 |
| paymentState | (無對等欄位) 您可以從 subscriptionState 推測付款狀態：
|
cancelReason、userCancellationTimeMillis、cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (不變) |
purchaseType |
測試：透過 testPurchase促銷活動：(無對等欄位)。即將推出 |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName、emailAddress、givenName、familyName、profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType、promotionCode |
(無對等欄位)；即將推出 |
externalAccountId、obfuscatedExternalAccountId、obfuscatedExteranlProfileId |
externalAccountIdentifiers |
其他訂閱管理功能
雖然 purchases.subscriptions:get 已升級為 purchases.subscriptionsv2:get，但系統目前並未變更 purchases.subscriptions 端點中的其餘開發人員訂閱管理功能，因此您可以照常使用 purchases.subscriptions:acknowledge、purchases.subscriptions:cancel、purchases.subscriptions:defer、purchases.subscriptions:refund 和 purchases.subscriptions:revoke。
定價 API
使用 monetization.convertRegionPrices 端點計算區域價格的方式，就像使用 Play 管理中心一樣。此方式接受單一價格，且支援 Google Play 使用的所有貨幣，並且針對 Google Play 支援購買的所有地區回傳換算後的價格 (包括適用的預設稅率)。