有了 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 |
lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo |
(無對等欄位) 您可以在已購買的訂閱項目中於 offer 找到這項資訊。 |
developerPayload | (無對等欄位) 開發人員酬載已淘汰 |
paymentState | (無對等欄位) 您可以從 subscriptionState 推測付款狀態:
|
cancelReason 、userCancellationTimeMillis 、cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (不變) |
purchaseType |
測試:透過 testPurchase Promotion: signupPromotion |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName 、emailAddress 、givenName 、familyName 、profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType 、promotionCode |
signupPromotion |
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 支援購買的所有地區回傳換算後的價格 (包括適用的預設稅率)。