本主題說明了如何將 Google Play 帳款服務程式庫整合至您的應用程式,以便開始販售產品。
購買流程
以下是一次性消費或訂閱項目的一般購買流程。
- 向使用者說明可以購買的內容。
- 啟動購買流程,以便使用者接受購買。
- 在伺服器上驗證購買交易。
- 將內容提供給使用者。
- 確認內容的交付程序。如果是消費性產品,請先消耗購買項目,讓使用者可以再次購買該商品。
訂閱會自動續約,直到取消為止。訂閱可呈現下列狀態:
- 有效:使用者記錄良好,有權存取訂閱項目。
- 已取消:使用者已取消訂閱,但在到期前仍擁有存取權。
- 寬限期:使用者遇到付款問題,但仍擁有存取權,同時 Google 正在重試付款方式以扣除款項。
- 保留中:使用者因遇到付款問題而不再擁有存取權,同時 Google 正在重試以該付款方式扣除款項。
- 已暫停:使用者已暫停存取權,取消暫停後才可繼續存取。
- 已到期:使用者已取消訂閱並失去存取權。訂閱到期後,系統會將使用者視為「已流失」。
啟動與 Google Play 的連線
如要整合 Google Play 的帳單系統,首先請將 Google Play 帳款服務程式庫新增至應用程式並啟動連線。
新增 Google Play 帳款服務程式庫依附元件
將 Google Play 帳款服務程式庫依附元件新增至應用程式的 build.gradle
檔案,如下所示:
Groovy
dependencies { def billing_version = "7.0.0" implementation "com.android.billingclient:billing:$billing_version" }
Kotlin
dependencies { val billing_version = "7.0.0" implementation("com.android.billingclient:billing:$billing_version") }
如果您使用 Kotlin,Google Play 帳款服務程式庫 KTX 模組會包含 Kotlin 擴充功能和協同程式支援機制,可讓您在使用 Google Play 帳款服務程式庫時編寫慣用的 Kotlin 程式碼。如要在專案中加入這些擴充功能,請將下列依附元件新增至應用程式的 build.gradle
檔案,如下所示:
Groovy
dependencies { def billing_version = "7.0.0" implementation "com.android.billingclient:billing-ktx:$billing_version" }
Kotlin
dependencies { val billing_version = "7.0.0" implementation("com.android.billingclient:billing-ktx:$billing_version") }
初始化 BillingClient
加入 Google Play 帳款服務程式庫的依附元件後,您需要初始化 BillingClient
例項。BillingClient
是 Google Play 帳款服務程式庫與應用程式其餘部分之間通訊的主要介面。BillingClient
提供同步和非同步的便利方法,適用於許多常見的結帳作業。強烈建議您一次啟用一組有效的 BillingClient
連線,避免單一事件發生多次 PurchasesUpdatedListener
回呼。
如要建立 BillingClient
,請使用 newBuilder()
。
您可以將任何相關資訊傳遞至 newBuilder()
,BillingClient
就可用來取得應用程式相關資訊。也就是說,您不必擔心記憶體流失的問題。如要接收購買交易的最新動態,您也必須呼叫 setListener()
,並傳遞指向 PurchasesUpdatedListener
的參照。這個事件監聽器會接收應用程式內所有購買交易的最新動態。
Kotlin
private val purchasesUpdatedListener = PurchasesUpdatedListener { billingResult, purchases -> // To be implemented in a later section. } private var billingClient = BillingClient.newBuilder(context) .setListener(purchasesUpdatedListener) // Configure other settings. .build()
Java
private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() { @Override public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) { // To be implemented in a later section. } }; private BillingClient billingClient = BillingClient.newBuilder(context) .setListener(purchasesUpdatedListener) // Configure other settings. .build();
連線至 Google Play
建立 BillingClient
後,您需要與 Google Play 建立連線。
如要連線至 Google Play,請呼叫 startConnection()
。
連線程序為非同步性質,您必須實作 BillingClientStateListener
,才能在用戶端完成設定並準備好提出進一步要求後收到回呼。
您還必須實作重試邏輯,處理與 Google Play 連線中斷的問題。如要實作重試邏輯,請覆寫 onBillingServiceDisconnected()
回呼方法,並確認 BillingClient
會呼叫 startConnection()
方法,重新與 Google Play 連線,再提出進一步要求。
以下範例說明如何啟動連線,並測試是否可供使用:
Kotlin
billingClient.startConnection(object : BillingClientStateListener { override fun onBillingSetupFinished(billingResult: BillingResult) { if (billingResult.responseCode == BillingResponseCode.OK) { // The BillingClient is ready. You can query purchases here. } } override fun onBillingServiceDisconnected() { // Try to restart the connection on the next request to // Google Play by calling the startConnection() method. } })
Java
billingClient.startConnection(new BillingClientStateListener() { @Override public void onBillingSetupFinished(BillingResult billingResult) { if (billingResult.getResponseCode() == BillingResponseCode.OK) { // The BillingClient is ready. You can query purchases here. } } @Override public void onBillingServiceDisconnected() { // Try to restart the connection on the next request to // Google Play by calling the startConnection() method. } });
顯示可供購買的產品
與 Google Play 建立連線後,就可以開始查詢可用的產品,並向使用者顯示。
向使用者顯示產品之前,查詢產品詳細資料是非常重要的步驟,因為這會傳回本地化的產品資訊。如果是訂閱項目,請確保產品顯示方式遵守所有 Play 政策。
如要查詢應用程式內商品的詳細資料,請呼叫 queryProductDetailsAsync()
。
如要處理非同步作業的結果,您必須一併指定實作 ProductDetailsResponseListener
介面的事件監聽器。接著,您可以覆寫 onProductDetailsResponse()
,在查詢完成時通知事件監聽器,如以下範例所示:
Kotlin
val queryProductDetailsParams = QueryProductDetailsParams.newBuilder() .setProductList( ImmutableList.of( Product.newBuilder() .setProductId("product_id_example") .setProductType(ProductType.SUBS) .build())) .build() billingClient.queryProductDetailsAsync(queryProductDetailsParams) { billingResult, productDetailsList -> // check billingResult // process returned productDetailsList }
Java
QueryProductDetailsParams queryProductDetailsParams = QueryProductDetailsParams.newBuilder() .setProductList( ImmutableList.of( Product.newBuilder() .setProductId("product_id_example") .setProductType(ProductType.SUBS) .build())) .build(); billingClient.queryProductDetailsAsync( queryProductDetailsParams, new ProductDetailsResponseListener() { public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) { // check billingResult // process returned productDetailsList } } )
查詢產品詳細資料時,請傳遞 QueryProductDetailsParams
例項,此例項可指定在 Google Play 管理中心內建立的產品 ID 字串清單以及 ProductType
。ProductType
可以是一次性產品的 ProductType.INAPP
,也可以是訂閱項目的 ProductType.SUBS
。
使用 Kotlin 擴充功能進行查詢
如果您使用 Kotlin 擴充功能,可以呼叫 queryProductDetails()
擴充功能函式,查詢應用程式內商品的詳細資料。
queryProductDetails()
會利用 Kotlin 協同程式,因此您不需定義單獨的事件監聽器。相對的,函式會先暫停直到查詢完成為止,之後您可以處理結果:
suspend fun processPurchases() {
val productList = listOf(
QueryProductDetailsParams.Product.newBuilder()
.setProductId("product_id_example")
.setProductType(BillingClient.ProductType.SUBS)
.build()
)
val params = QueryProductDetailsParams.newBuilder()
params.setProductList(productList)
// leverage queryProductDetails Kotlin extension function
val productDetailsResult = withContext(Dispatchers.IO) {
billingClient.queryProductDetails(params.build())
}
// Process the result.
}
在極少數情況下,某些裝置無法支援 ProductDetails
和 queryProductDetailsAsync()
,這通常是因為 Google Play 服務版本過舊。為確保能妥善支援此情境,請參閱 Play 帳款服務程式庫 5 遷移指南,瞭解如何使用回溯相容性功能。
處理結果
Google Play 帳款服務程式庫會將查詢結果儲存在 ProductDetails
物件的 List
中。接著,您可以對清單中的各個 ProductDetails
物件呼叫各種方法,查看應用程式內商品的相關資訊,例如價格或說明。如要查看可用產品的詳細資料,請參閱 ProductDetails
類別中的方法清單。
在提供待售項目之前,請先檢查使用者是否尚未擁有該項目。如果使用者的商品庫中仍有可消耗項目,必須先消耗該項目才能再次購買。
提供訂閱項目前,請先確認使用者尚未訂閱, 同時注意下列事項:
queryProductDetailsAsync()
會傳回訂閱產品詳細資料,每個訂閱項目最多 50 項優惠。queryProductDetailsAsync()
只會傳回使用者有資格享有的優惠。如果使用者嘗試購買不符資格的優惠方案 (例如應用程式顯示過舊的優惠清單),Play 會將不符資格的情況告知使用者,讓他們可以選擇改為購買基本方案。
啟動購買流程
如要透過應用程式啟動購買要求,請從應用程式的主要執行緒呼叫 launchBillingFlow()
方法。這個方法會參照 BillingFlowParams
物件,其中包含藉由呼叫 queryProductDetailsAsync()
取得的相關 ProductDetails
物件。
如要建立 BillingFlowParams
物件,請使用 BillingFlowParams.Builder
類別。
Kotlin
// An activity reference from which the billing flow will be launched. val activity : Activity = ...; val productDetailsParamsList = listOf( BillingFlowParams.ProductDetailsParams.newBuilder() // retrieve a value for "productDetails" by calling queryProductDetailsAsync() .setProductDetails(productDetails) // For One-time product, "setOfferToken" method shouldn't be called. // For subscriptions, to get an offer token, call ProductDetails.subscriptionOfferDetails() // for a list of offers that are available to the user .setOfferToken(selectedOfferToken) .build() ) val billingFlowParams = BillingFlowParams.newBuilder() .setProductDetailsParamsList(productDetailsParamsList) .build() // Launch the billing flow val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
Java
// An activity reference from which the billing flow will be launched. Activity activity = ...; ImmutableList<ProductDetailsParams> productDetailsParamsList = ImmutableList.of( ProductDetailsParams.newBuilder() // retrieve a value for "productDetails" by calling queryProductDetailsAsync() .setProductDetails(productDetails) // For one-time products, "setOfferToken" method shouldn't be called. // For subscriptions, to get an offer token, call // ProductDetails.subscriptionOfferDetails() for a list of offers // that are available to the user. .setOfferToken(selectedOfferToken) .build() ); BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder() .setProductDetailsParamsList(productDetailsParamsList) .build(); // Launch the billing flow BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);
launchBillingFlow()
方法會傳回 BillingClient.BillingResponseCode
中列出的其中一個回應代碼。請務必查看這項結果,確認啟動時購買流程沒有發生錯誤。BillingResponseCode
為 OK
表示啟動成功。
成功呼叫 launchBillingFlow()
時,系統會顯示 Google Play 購買畫面。圖 1 顯示某個訂閱項目的購買畫面:
Google Play 會呼叫 onPurchasesUpdated()
,將購物作業的結果提供給實作 PurchasesUpdatedListener
介面的事件監聽器。該事件監聽器是在初始化用戶端期間使用 setListener()
方法指定。
您必須實作 onPurchasesUpdated()
來處理可能的回應代碼。以下範例說明如何覆寫 onPurchasesUpdated()
:
Kotlin
override fun onPurchasesUpdated(billingResult: BillingResult, purchases: List<Purchase>?) { if (billingResult.responseCode == BillingResponseCode.OK && purchases != null) { for (purchase in purchases) { handlePurchase(purchase) } } else if (billingResult.responseCode == BillingResponseCode.USER_CANCELED) { // Handle an error caused by a user cancelling the purchase flow. } else { // Handle any other error codes. } }
Java
@Override void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) { if (billingResult.getResponseCode() == BillingResponseCode.OK && purchases != null) { for (Purchase purchase : purchases) { handlePurchase(purchase); } } else if (billingResult.getResponseCode() == BillingResponseCode.USER_CANCELED) { // Handle an error caused by a user cancelling the purchase flow. } else { // Handle any other error codes. } }
購買成功後,系統會產生與圖 2 類似的 Google Play 購買成功畫面。
購買成功後還會產生購買憑證,這是一個不重複 ID,代表已購買應用程式內商品的使用者和產品 ID。應用程式可在使用者的裝置上儲存購買憑證。不過,建議您將該憑證傳遞至安全的後端伺服器,方便驗證購買交易及防範詐欺行為。下一節會進一步說明這項程序。
使用者也會收到隨附交易收據的電子郵件,收據內含該筆交易的訂單 ID 或專屬 ID。系統會在使用者每次購買一次性產品和初始訂閱項目,以及後續定期自動續訂時,發送內含專屬訂單 ID 的電子郵件。您可以在 Google Play 管理中心使用這組訂單 ID 管理退款。
標示個人化的價格
如果應用程式可以發布給歐盟使用者,請使用 setIsOfferPersonalized()
方法向使用者揭露,應用程式是以自動化決策功能提供個人化商品價格。
您必須查閱《消費者權益指令》2011/83/EU 6 (1) (ea) CRD 條款,確定您為使用者提供的價格是否經過個人化處理。
setIsOfferPersonalized()
接受布林輸入。如果為 true
,Play UI 會包含揭露事項。如果為 false
,UI 會省略揭露事項。預設值為 false
。
詳情請參閱消費者說明中心。
處理購買交易
使用者完成購買後,應用程式就需要處理該筆購買交易。在大多數情況下,應用程式會透過 PurchasesUpdatedListener
收到購買通知。但在某些情況下,應用程式會藉由呼叫 BillingClient.queryPurchasesAsync()
得知購買交易,如「擷取購買交易」中所述。
此外,如果您在安全後端設有即時開發人員通知用戶端,可以接收 subscriptionNotification
或 oneTimeProductNotification
(僅適用於未完成的購買交易) 來註冊新交易。這兩者都會在有新的購買交易時通知您。收到這類通知後,請呼叫 Google Play Developer API,取得完整狀態並更新自己的後端狀態。
您的應用程式應以下列方式處理購買交易:
- 驗證購買交易。
- 將內容提供給使用者,並確認內容的交付程序。視需要將項目標示為「已消耗」,以便使用者再次購買。
如要驗證購買交易,請先確認購買狀態是否為 PURCHASED
,
如果購買狀態為 PENDING
,請按照「處理未完成交易」的說明處理購買交易。對於透過 onPurchasesUpdated()
或 queryPurchasesAsync()
收到的購買交易,在應用程式授權之前,應進一步驗證購買交易以確保合法性。如要瞭解如何正確驗證購買交易,請參閱「在授權前驗證購買交易」。
驗證購買交易後,應用程式就可以授權給使用者。如要識別與購買交易相關聯的使用者帳戶,可以使用 Purchases.products:get
傳回的 ProductPurchase.obfuscatedExternalAccountId
(適用於應用程式內商品的購買交易) 和 Purchases.subscriptions:get
傳回的 SubscriptionPurchase.obfuscatedExternalAccountId
(適用於伺服器端的訂閱項目),或是 Purchase.getAccountIdentifiers()
在用戶端提供的 obfuscatedAccountId
(適用於在完成交易時有使用 setObfuscatedAccountId
設定的情況)。
授權後,應用程式就必須確認購買交易。這項確認作業會通知 Google Play 您已授予購買交易的權限。
授權和確認購買交易的程序會因該交易的購買項目 (非消耗性產品、消耗性產品或訂閱項目) 而有所不同。
消耗性產品
如果應用程式設有安全的後端,建議您針對消耗性產品,使用 Purchases.products:consume
確實消耗購買項目。您可以根據呼叫 Purchases.products:get
的結果檢查 consumptionState
,確定購買項目尚未消耗。如果應用程式只有用戶端而沒有後端,請使用 Google Play 帳款服務程式庫的 consumeAsync()
。這兩種方法都能執行確認要求,且會指出應用程式已授權給使用者。應用程式也可以使用這些方法,提供與輸入購買憑證相應的一次性產品,讓使用者再次購買。使用 consumeAsync()
時,您也必須傳遞可實作 ConsumeResponseListener
介面的物件,這個物件會處理消耗作業的結果。您可以覆寫 onConsumeResponse()
方法,Google Play 帳款服務程式庫會在作業完成後呼叫此方法。
以下範例示範如何使用相關聯的購買憑證,透過 Google Play 帳款服務程式庫消耗產品:
Kotlin
suspend fun handlePurchase(purchase: Purchase) { // Purchase retrieved from BillingClient#queryPurchasesAsync or your PurchasesUpdatedListener. val purchase : Purchase = ...; // Verify the purchase. // Ensure entitlement was not already granted for this purchaseToken. // Grant entitlement to the user. val consumeParams = ConsumeParams.newBuilder() .setPurchaseToken(purchase.getPurchaseToken()) .build() val consumeResult = withContext(Dispatchers.IO) { client.consumePurchase(consumeParams) } }
Java
void handlePurchase(Purchase purchase) { // Purchase retrieved from BillingClient#queryPurchasesAsync or your PurchasesUpdatedListener. Purchase purchase = ...; // Verify the purchase. // Ensure entitlement was not already granted for this purchaseToken. // Grant entitlement to the user. ConsumeParams consumeParams = ConsumeParams.newBuilder() .setPurchaseToken(purchase.getPurchaseToken()) .build(); ConsumeResponseListener listener = new ConsumeResponseListener() { @Override public void onConsumeResponse(BillingResult billingResult, String purchaseToken) { if (billingResult.getResponseCode() == BillingResponseCode.OK) { // Handle the success of the consume operation. } } }; billingClient.consumeAsync(consumeParams, listener); }
非消耗性產品
如果應用程式設有安全的後端,建議您使用 Purchases.products:acknowledge
確認非消耗性產品的購買交易。您可以根據呼叫 Purchases.products:get
的結果檢查 acknowledgementState
,確定購買交易先前未經確認。
如果應用程式只有用戶端,請在應用程式中使用 Google Play 帳款服務程式庫的 BillingClient.acknowledgePurchase()
。在確認購買交易之前,應用程式應檢查該筆交易是否已使用 Google Play 帳款服務程式庫的 isAcknowledged()
方法完成確認。
以下範例說明如何使用 Google Play 帳款服務程式庫確認購買交易:
Kotlin
val client: BillingClient = ... val acknowledgePurchaseResponseListener: AcknowledgePurchaseResponseListener = ... suspend fun handlePurchase() { if (purchase.purchaseState === PurchaseState.PURCHASED) { if (!purchase.isAcknowledged) { val acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder() .setPurchaseToken(purchase.purchaseToken) val ackPurchaseResult = withContext(Dispatchers.IO) { client.acknowledgePurchase(acknowledgePurchaseParams.build()) } } } }
Java
BillingClient client = ... AcknowledgePurchaseResponseListener acknowledgePurchaseResponseListener = ... void handlePurchase(Purchase purchase) { if (purchase.getPurchaseState() == PurchaseState.PURCHASED) { if (!purchase.isAcknowledged()) { AcknowledgePurchaseParams acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder() .setPurchaseToken(purchase.getPurchaseToken()) .build(); client.acknowledgePurchase(acknowledgePurchaseParams, acknowledgePurchaseResponseListener); } } }
訂閱項目
處理訂閱項目的方式與非消耗性產品類似。如果可能,請使用 Google Play Developer API 提供的 Purchases.subscriptions.acknowledge
,從安全的後端確認購買交易。驗證購買交易先前未經確認,方法是透過 Purchases.subscriptions:get
檢查購買資源中的 acknowledgementState
。否則,您也可以在檢查 isAcknowledged()
後,使用 Google Play 帳款服務程式庫的 BillingClient.acknowledgePurchase()
確認訂閱。所有初始訂閱項目的購買交易都需經過確認,訂閱項目的續訂則無需確認。如要進一步瞭解需要確認訂閱項目的時機,請參閱販售訂閱項目主題。
擷取購買交易
使用 PurchasesUpdatedListener
監聽購買狀態更新,不足以確保應用程式能夠順利處理所有購買交易。應用程式可能不會得知使用者完成的所有購買交易。如果是以下情境,應用程式可能無法掌握或無法得知購買交易:
- 購買期間發生網路問題:使用者成功完成購買交易且收到 Google 的確認通知,但使用者的裝置在透過
PurchasesUpdatedListener
收到購買通知前失去網路連線。 - 多部裝置:使用者在某部裝置上購買商品,且希望在切換至其他裝置時也能看到該商品。
- 處理應用程式外的購買交易:某些購買交易可在應用程式外完成,例如促銷兌換。
如要處理這類情況,請務必讓應用程式呼叫 onResume()
方法中的 BillingClient.queryPurchasesAsync()
,確保所有購買交易都按照「處理購買交易」所述的方式順利處理。
以下範例說明如何擷取使用者的訂閱交易。請注意,queryPurchasesAsync()
只會傳回有效的訂閱項目,以及非消耗的一次性消費。
Kotlin
val params = QueryPurchasesParams.newBuilder() .setProductType(ProductType.SUBS) // uses queryPurchasesAsync Kotlin extension function val purchasesResult = billingClient.queryPurchasesAsync(params.build()) // check purchasesResult.billingResult // process returned purchasesResult.purchasesList, e.g. display the plans user owns
Java
billingClient.queryPurchasesAsync( QueryPurchasesParams.newBuilder() .setProductType(ProductType.SUBS) .build(), new PurchasesResponseListener() { public void onQueryPurchasesResponse(BillingResult billingResult, List<Purchase> purchases) { // check billingResult // process returned purchase list, e.g. display the plans user owns } } );
處理應用程式外的購買交易
某些購買交易可在應用程式外完成,例如促銷兌換或Google Play 遊戲應用程式內結帳功能 (IAP) 的購物車放棄提醒。使用者在應用程式外購買商品時,會希望應用程式顯示應用程式內訊息,或使用某種通知機制,讓使用者知道應用程式已正確收到並處理購買交易。可接受的機制如下:
- 顯示應用程式內彈出式視窗。
- 將訊息傳送至應用程式內通訊訊息方塊,並清楚說明應用程式內通訊訊息方塊中有新訊息。
- 使用作業系統通知訊息。
請注意,即使您的應用程式辨識出購買交易,應用程式仍可能處於任何狀態,使用者甚至可能在購買後仍未安裝您的應用程式。無論應用程式處於何種狀態,使用者都希望重新啟用應用程式時收到購買項目。
在購買發生時,無論應用程式處於何種狀態,您都必須偵測出購買交易。然而,在某些例外情況下,我們可能不會立即通知使用者已收到項目。例如:
- 在遊戲需要大量操作的部分中,顯示訊息可能會分散使用者的注意力。在此情況下,您必須在操作結束後通知使用者。
- 在過場畫面顯示訊息可能會分散使用者的注意力。在此情況下,您必須在過場畫面結束後通知使用者。
- 遊戲的初始教學課程和使用者設定期間。建議您在新使用者開啟遊戲後或初次進行使用者設定期間,立即發出獎勵通知。不過,也可以等到主要遊戲序列出現,才通知使用者。
在決定向使用者發出應用程式外購買交易通知的時機與方式時,請務必從使用者的觀點考量。如果使用者沒有立即收到通知,他們可能會感到困惑、停止使用應用程式、聯絡使用者支援團隊,或在社群媒體上抱怨。
Google Play 遊戲首頁的放棄購物車提醒 (預設為啟用)
對於透過應用程式內購功能營利的遊戲開發人員而言,如果想在應用程式外銷售 Google Play 管理中心中啟用的 SKU,可以使用「購物車未結帳提醒」功能,提醒使用者在瀏覽 Google Play 商店時完成先前未結帳的購買交易。這些購買交易會在應用程式外進行,透過 Google Play 商店中的 Google Play 遊戲首頁進行。
這項功能預設為啟用,可協助使用者繼續閱讀,並協助開發人員盡可能提高銷售量。不過,您可以提交購物車未結帳提醒功能停用表單,為應用程式停用這項功能。如要瞭解在 Google Play 管理中心管理 SKU 的最佳做法,請參閱「建立應用程式內產品」。
以下圖片顯示 Google Play 商店中的購物車放棄提醒:
處理未完成的交易
Google Play 支援「未完成的交易」,這類交易程序從使用者發起購買交易開始,到系統處理購買交易付款方式的這段期間,需要完成一或多個額外步驟。除非 Google 通知您已透過使用者的付款方式成功扣款,否則應用程式不應授權給這類購買交易。
舉例來說,使用者可以選擇實體商店,然後稍後以現金付款,以便啟動交易。使用者會透過通知和電子郵件接收代碼。當使用者來到實體商店時,就可以向收銀員兌換代碼,再用現金付款。接著,Google 會通知您和使用者已收到付款,您的應用程式就可以向使用者授權。
請在初始化 BillingClient
時呼叫 enablePendingPurchases()
,為應用程式啟用未完成的交易。您的應用程式必須啟用及支援一次性產品未完成的交易。新增支援服務前,請務必瞭解待處理交易的購買交易生命週期。
當應用程式收到新購買交易 (透過 PurchasesUpdatedListener
或呼叫 queryPurchasesAsync()
時),請使用 getPurchaseState()
方法判斷購買狀態是 PURCHASED
或 PENDING
。只有在狀態為 PURCHASED
時才可授予權限。
如果使用者完成購買時您的應用程式正在運作,系統會再次呼叫 PurchasesUpdatedListener
,而 PurchaseState
現已變為 PURCHASED
。這時,應用程式可按照處理購買交易的標準方法處理購買交易。應用程式也需要呼叫應用程式 onResume()
方法中的 queryPurchasesAsync()
,處理在應用程式未運作期間轉換為 PURCHASED
狀態的購買交易。
當購買交易從 PENDING
轉換為 PURCHASED
時,您的即時開發人員通知用戶端會收到 ONE_TIME_PRODUCT_PURCHASED
或 SUBSCRIPTION_PURCHASED
通知。如果購買交易遭到取消,您會收到 ONE_TIME_PRODUCT_CANCELED
或 SUBSCRIPTION_PENDING_PURCHASE_CANCELED
通知。如果客戶在指定時間範圍內未完成付款,就可能發生這種情況。
請注意,您隨時可以使用 Google Play Developer API 查看購買交易的目前狀態。
處理多件購買交易
在 Google Play 帳款服務程式庫 4.0 以上版本中,Google Play 允許客戶在購物車中指定購買數量,在一筆交易中購買多件相同的應用程式內商品。應用程式必須有能力處理多件購買交易,並按照指定的購買數量授權。
為了滿足多件購買交易的需求,應用程式的佈建邏輯需要檢查項目數量。您可以透過下列任一 API 存取 quantity
欄位:
- Google Play 帳款服務程式庫的
getQuantity()
。 - Google Play Developer API 的
Purchases.products.quantity
。
加入多件購買交易的處理邏輯後,您需要前往 Google Play 管理中心的應用程式內商品管理頁面,為相應的產品啟用多件購買交易功能。
查詢使用者的結帳設定
getBillingConfigAsync()
會提供使用者要用於 Google Play 的國家/地區。
建立 BillingClient
後,即可查詢使用者的結帳設定。下列程式碼片段說明如何呼叫 getBillingConfigAsync()
。實作 BillingConfigResponseListener
來處理回應。凡是從應用程式啟動的結帳設定查詢,都會由這個事件監聽器接收更新內容。
如果傳回的 BillingResult
沒有任何錯誤,您可以檢查 BillingConfig
物件的 countryCode
欄位,取得使用者的 Play 國家/地區。
Kotlin
// Use the default GetBillingConfigParams.
val getBillingConfigParams = GetBillingConfigParams.newBuilder().build()
billingClient.getBillingConfigAsync(getBillingConfigParams,
object : BillingConfigResponseListener {
override fun onBillingConfigResponse(
billingResult: BillingResult,
billingConfig: BillingConfig?
) {
if (billingResult.responseCode == BillingResponseCode.OK
&& billingConfig != null) {
val countryCode = billingConfig.countryCode
...
} else {
// TODO: Handle errors
}
}
})
Java
// Use the default GetBillingConfigParams.
GetBillingConfigParams getBillingConfigParams = GetBillingConfigParams.newBuilder().build();
billingClient.getBillingConfigAsync(getBillingConfigParams,
new BillingConfigResponseListener() {
public void onBillingConfigResponse(
BillingResult billingResult, BillingConfig billingConfig) {
if (billingResult.getResponseCode() == BillingResponseCode.OK
&& billingConfig != null) {
String countryCode = billingConfig.getCountryCode();
...
} else {
// TODO: Handle errors
}
}
});