將 Google Play 帳款服務程式庫整合至應用程式

注意：閱讀本主題前，請務必詳閱 Play 管理中心的說明中心文件，瞭解有關購買交易的重要概念，以及如何建立及設定要銷售的產品。此外，請確認您已預先按照「事前準備」中的步驟完成 Google Play 設定。

本主題說明如何將 Google Play 帳款服務程式庫整合至應用程式，以便開始販售產品。

本主題提供的程式碼範例是以 GitHub 上的官方範例應用程式為基礎。如需可供整合使用的範例應用程式和其他資源完整清單，請參閱「其他資源」。

購買流程

以下是一次性消費或訂閱項目的一般購買流程。

1. 向使用者說明可以購買的內容。
2. 啟動購買流程，以便使用者接受購買。
3. 在伺服器上驗證購買交易。
4. 將內容提供給使用者。
5. 確認內容的交付程序。如果是消費性產品，請先消耗購買項目，讓使用者可以再次購買該商品。

訂閱會自動續約，直到取消為止。訂閱可呈現下列狀態：

• 有效：使用者記錄良好，有權存取訂閱項目。
• 已取消：使用者已取消訂閱，但在到期前仍擁有存取權。
• 寬限期：使用者遇到付款問題，但仍擁有存取權，同時 Google 正在重試付款方式以扣除款項。
• 保留中：使用者因遇到付款問題而不再擁有存取權，同時 Google 正在重試以該付款方式扣除款項。
• 已暫停：使用者已暫停存取權，取消暫停後才可繼續存取。
• 已到期：使用者已取消訂閱並失去存取權。訂閱到期後，系統會將使用者視為「已流失」。

啟動與 Google Play 的連線

如要整合 Google Play 的帳單系統，首先請將 Google Play 帳款服務程式庫新增至應用程式並啟動連線。

新增 Google Play 帳款服務程式庫依附元件

注意：如果您已按照「事前準備」指南的說明進行，則您已新增必要的依附元件，可以繼續下個部分的操作。

將 Google Play 帳款服務程式庫依附元件新增至應用程式的 build.gradle 檔案，如下所示：

Groovy

dependencies {
    def billing_version = "6.1.0"

    implementation "com.android.billingclient:billing:$billing_version"
}

Kotlin

dependencies {
    val billing_version = "6.1.0"

    implementation("com.android.billingclient:billing:$billing_version")
}

如果您使用 Kotlin，Google Play 帳款服務程式庫 KTX 模組會包含 Kotlin 擴充功能和協同程式支援機制，可讓您在使用 Google Play 帳款服務程式庫時編寫慣用的 Kotlin 程式碼。如要在專案中加入這些擴充功能，請將下列依附元件新增至應用程式的 build.gradle 檔案，如下所示：

Groovy

dependencies {
    def billing_version = "6.1.0"

    implementation "com.android.billingclient:billing-ktx:$billing_version"
}

Kotlin

dependencies {
    val billing_version = "6.1.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)
   .enablePendingPurchases()
   .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)
    .enablePendingPurchases()
    .build();

注意：Google Play 帳款服務程式庫會以 BillingResult 的形式傳回錯誤。BillingResult 包含 BillingResponseCode，用來分類應用程式可能會遇到的帳單相關錯誤。舉例來說，假如您收到 SERVICE_DISCONNECTED 錯誤代碼，則應用程式應重新啟動與 Google Play 的連線。此外，BillingResult 還包含一則偵錯訊息，適合在開發期間用來診斷錯誤。

連線至 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.
    }
});

注意：強烈建議您自行實作連線重試邏輯，並覆寫 onBillingServiceDisconnected() 方法。執行任何方法時，請務必維持 BillingClient 連線。

顯示可供購買的產品

與 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 = ArrayList<String>()
    productList.add(
              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 會將不符資格的情況告知使用者，讓他們可以選擇改為購買基本方案。

注意：有些 Android 裝置可能搭載舊版 Google Play 商店應用程式，因而不支援部分產品類型，例如訂閱項目。您可以在應用程式進入結帳流程之前呼叫 isFeatureSupported()，判斷裝置是否支援要販售的產品。 如需受支援的產品類型清單，請參閱 BillingClient.FeatureType。

啟動購買流程

如要透過應用程式啟動購買要求，請從應用程式的主要執行緒呼叫 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)
        // 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 productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // to get an offer token, call ProductDetails.getSubscriptionOfferDetails()
            // 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 顯示某個訂閱項目的購買畫面：

圖 1. Google Play 購買畫面顯示可供購買的訂閱項目。

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 購買成功畫面。

圖 2. Google Play 的購買成功畫面。

購買成功後還會產生購買憑證，這是一個不重複 ID，代表已購買應用程式內商品的使用者和產品 ID。應用程式可在使用者的裝置上儲存購買憑證。不過，建議您將該憑證傳遞至安全的後端伺服器，方便驗證購買交易及防範詐欺行為。下一節會進一步說明這項程序。

使用者也會收到隨附交易收據的電子郵件，收據內含該筆交易的訂單 ID 或專屬 ID。系統會在使用者每次購買一次性產品和初始訂閱項目，以及後續定期自動續訂時，發送內含專屬訂單 ID 的電子郵件。您可以在 Google Play 管理中心使用這組訂單 ID 管理退款。

標示個人化的價格

如果應用程式可以發布給歐盟使用者，請使用 setIsOfferPersonalized() 方法向使用者揭露，應用程式是以自動化決策功能提供個人化商品價格。

圖 3. Google Play 購買畫面顯示已針對使用者自訂價格。

您必須查閱《消費者權益指令》(2011/83/EU) 6 (1) (ea) CRD 條款，確定您為使用者提供的價格是否經過個人化處理。

setIsOfferPersonalized() 接受布林輸入。如果為 true，Play UI 會包含揭露事項。如果為 false，UI 會省略揭露事項。預設值為 false。

詳情請參閱消費者說明中心。

處理購買交易

使用者完成購買後，應用程式就需要處理該筆購買交易。在大多數情況下，應用程式會透過 PurchasesUpdatedListener 收到購買通知。但在某些情況下，應用程式會藉由呼叫 BillingClient.queryPurchasesAsync() 得知購買交易，如「擷取購買交易」中所述。

此外，如果您在安全後端設有即時開發人員通知用戶端，可以接收 subscriptionNotification 或 oneTimeProductNotification (僅適用於未完成的購買交易) 來註冊新交易。這兩者都會在有新的購買交易時通知您。收到這類通知後，請呼叫 Google Play Developer API，取得完整狀態並更新自己的後端狀態。

應用程式應以下列方式處理購買交易：

1. 驗證購買交易。
2. 將內容提供給使用者，並確認內容的交付程序。視需要將項目標示為「已消耗」，以便使用者再次購買。

如要驗證購買交易，請先確認購買狀態是否為 PURCHASED， 如果購買狀態為 PENDING，請按照「處理未完成交易」的說明處理購買交易。對於透過 onPurchasesUpdated() 或 queryPurchasesAsync() 收到的購買交易，在應用程式授權之前，應進一步驗證購買交易以確保合法性。如要瞭解如何正確驗證購買交易，請參閱「在授權前驗證購買交易」。

驗證購買交易後，應用程式就可以授權給使用者。如要識別與購買交易相關聯的使用者帳戶，可以使用 Purchases.products:get 傳回的 ProductPurchase.obfuscatedExternalAccountId (適用於應用程式內商品的購買交易) 和 Purchases.subscriptions:get 傳回的 SubscriptionPurchase.obfuscatedExternalAccountId (適用於伺服器端的訂閱項目)，或是 Purchase.getAccountIdentifiers() 在用戶端提供的 obfuscatedAccountId (適用於在完成交易時有使用 setObfuscatedAccountId 設定的情況)。

授權後，應用程式就必須確認購買交易。這項確認作業會通知 Google Play 您已授予購買交易的權限。

注意：如果您未在三天內確認購買交易，使用者會自動收到退款，且 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);
}

注意：消耗要求偶爾可能會失敗，因此您必須檢查安全後端伺服器，確認每個購買憑證皆未使用，以確保應用程式沒有為同一筆交易多次授權。或者，應用程式可以等您收到 Google Play 的成功消耗回應後再授權。如果您選擇在 Google Play 傳送成功消耗回應前禁止使用者消耗購買交易，請務必在提出消耗要求後密切追蹤購買情形。

非消耗性產品

如果應用程式設有安全的後端，建議您使用 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 purchases) {
        // check billingResult
        // process returned purchase list, e.g. display the plans user owns

      }
    }
);

擷取購買記錄

queryPurchaseHistoryAsync() 會傳回使用者購買各項產品的最近一筆交易，即使該購買交易已過期、取消或消耗也一樣。

如果您使用 Kotlin 擴充功能，就可以使用 queryPurchaseHistory() 擴充功能函式。

Kotlin

val params = QueryPurchaseHistoryParams.newBuilder()
               .setProductType(ProductType.SUBS)

// uses queryPurchaseHistory Kotlin extension function
val purchaseHistoryResult = billingClient.queryPurchaseHistory(params.build())

// check purchaseHistoryResult.billingResult
// process returned purchaseHistoryResult.purchaseHistoryRecordList, e.g. display purchase

Java

billingClient.queryPurchaseHistoryAsync(
    QueryPurchaseHistoryParams.newBuilder()
        .setProductType(ProductType.SUBS)
        .build(),
    new PurchaseHistoryResponseListener() {
      public void onPurchaseHistoryResponse(
        BillingResult billingResult, List purchasesHistoryList) {
          // check billingResult
          // process returned purchase history list, e.g. display purchase history
        }
    }
);

處理應用程式外的購買交易

某些購買交易 (例如促銷兌換) 可能會在應用程式外進行。使用者在應用程式外購物時，會希望應用程式在內部顯示訊息，或透過某種通知機制讓他們瞭解應用程式已正確接收並處理購買交易。可接受的機制如下：

• 顯示應用程式內彈出式視窗。
• 將訊息傳送至應用程式內通訊訊息方塊，並清楚說明應用程式內通訊訊息方塊中有新訊息。
• 使用作業系統通知訊息。

請注意，即使您的應用程式辨識出購買交易，應用程式仍可能處於任何狀態，使用者甚至可能在購買後仍未安裝您的應用程式。無論應用程式處於何種狀態，使用者都希望重新啟用應用程式時收到購買項目。

在購買發生時，無論應用程式處於何種狀態，您都必須偵測出購買交易。然而，在某些例外情況下，我們可能不會立即通知使用者已收到項目。例如：

• 在遊戲需要大量操作的部分中，顯示訊息可能會分散使用者的注意力。在此情況下，您必須在操作結束後通知使用者。
• 在過場畫面顯示訊息可能會分散使用者的注意力。在此情況下，您必須在過場畫面結束後通知使用者。
• 遊戲的初始教學課程和使用者設定期間。建議您在新使用者開啟遊戲後或初次進行使用者設定期間，立即發出獎勵通知。不過，也可以等到主要遊戲序列出現，才通知使用者。

在決定向使用者發出應用程式外購買交易通知的時機與方式時，請務必從使用者的觀點考量。如果使用者沒有立即收到通知，他們可能會感到困惑、停止使用應用程式、聯絡使用者支援團隊，或在社群媒體上抱怨。注意：PurchasesUpdatedListener 在註冊時會使用您應用程式的相關資訊，以便處理購買交易更新事項，包括在應用程式外發起的購買交易。也就是說，如果應用程式程序不存在，PurchasesUpdatedListener 就不會收到通知。因此，應用程式應呼叫 onResume() 方法中的 BillingClient.queryPurchasesAsync()，如「擷取購買交易」一節中所述。

處理未完成交易

注意：Google Play 帳款服務程式庫 2.0 以上版本必須處理未完成交易，請明確處理未完成的交易。

注意：購買訂閱項目時無法使用其他付款方式。

Google Play 支援「未完成的交易」，這類交易程序從使用者發起購買交易開始，到系統處理購買交易付款方式的這段期間，需要完成一或多個額外步驟。除非 Google 通知您已透過使用者的付款方式成功扣款，否則應用程式不應授權給這類購買交易。

舉例來說，使用者可以選擇使用現金付款，建立狀態為 PENDING 的應用程式內商品購買交易。使用者可以選擇要完成交易的實體商店，然後透過通知和電子郵件接收代碼。當使用者來到實體商店時，就可以向收銀員兌換代碼，再用現金付款。接著，Google 會通知您和使用者已收到現金，您的應用程式就可以向使用者授權。

應用程式必須在初始化的過程中呼叫 enablePendingPurchases()，以便支援未完成的交易。

無論應用程式是透過 PurchasesUpdatedListener 還是呼叫 queryPurchasesAsync() 而收到新的購買交易，都須使用 getPurchaseState() 方法來判斷購買狀態是 PURCHASED 或 PENDING。

注意：只有在狀態是 PURCHASED 時才可授權。請使用 getPurchaseState() 而不是 getOriginaljson()，並務必正確處理 PENDING 交易。

如果使用者完成購買時您的應用程式正在運作，系統會再次呼叫 PurchasesUpdatedListener，而 PurchaseState 現已變為 PURCHASED。這時，應用程式可按照一次性消費的標準處理方法處理購買交易。應用程式也需要呼叫應用程式 onResume() 方法中的 queryPurchasesAsync()，處理在應用程式未運作期間轉換為 PURCHASED 狀態的購買交易。

注意：您只應在狀態為 PURCHASED 時確認購買交易，也就是說，不要確認處於 PENDING 狀態的購買交易。只有當購買狀態從「PENDING」轉換為「PURCHASED」後，才會開始為期三天的確認期。

應用程式也可以監聽 OneTimeProductNotifications，搭配使用即時開發人員通知與未完成購買交易。當購買交易從 PENDING 轉換為 PURCHASED 時，應用程式會收到 ONE_TIME_PRODUCT_PURCHASED 通知。如果購買交易遭到取消，應用程式會收到 ONE_TIME_PRODUCT_CANCELED 通知，如果客戶在指定時間範圍內未完成付款，就可能發生這種情況。 收到這類通知時，您可以使用 Google Play Developer API，其中包含 Purchases.products 的 PENDING 狀態。

注意：可以透過授權測試人員來測試未完成交易。除了兩張測試信用卡外，授權測試人員還可使用兩種工具來測試延遲付款方式，也就是系統會在幾分鐘後自動完成或取消付款。在測試應用程式期間使用上述任一工具購物後，驗證應用程式不會立即授權或確認交易。如果使用會自動完成付款的測試工具進行購物，您應確認應用程式會在購買完成後授權並確認交易。

如需測試此情境的詳細步驟，請參閱「測試未完成的購買交易」。

處理多件購買交易

在 Google Play 帳款服務程式庫 4.0 以上版本中，Google Play 允許客戶在購物車中指定購買數量，在一筆交易中購買多件相同的應用程式內商品。應用程式必須有能力處理多件購買交易，並按照指定的購買數量授權。

注意：多件購買交易適用於消耗性應用程式內商品，也就是可購買、消耗和再次購買的商品。請勿對無法重複購買的商品啟用這項功能。

為了滿足多件購買交易的需求，應用程式的佈建邏輯需要檢查項目數量。您可以透過下列任一 API 存取 quantity 欄位：

• Google Play 帳款服務程式庫的 getQuantity()。
• Google Play Developer API 的 Purchases.products.quantity。

加入多件購買交易的處理邏輯後，您需要前往 Google Play 管理中心的應用程式內商品管理頁面，為相應的產品啟用多件購買交易功能。

注意：請先確認應用程式支援多件購買交易功能，再前往管理中心啟用這項功能。您可能需要將應用程式強制更新為提供支援的版本，才能對產品啟用這項功能。

查詢使用者的結帳設定

getBillingConfigAsync() 會提供使用者要用於 Google Play 的國家/地區。

注意：請勿儲存 getBillingConfigAsync() 傳回的任何資料；這項資料僅供使用一次，且隨時可能變更。請不要使用 getBillingConfigAsync() 資料建立或強化使用者個人資料，或基於廣告/行銷目的將客戶設為指定目標或加以追蹤。

建立 BillingClient 後，即可查詢使用者的結帳設定。下列程式碼片段說明如何呼叫 getBillingConfigAsync()。實作 BillingConfigResponseListener 來處理回應。凡是從應用程式啟動的結帳設定查詢，都會由這個事件監聽器接收更新內容。

如果傳回的 BillingResult 沒有任何錯誤，您可以檢查 BillingConfig 物件的 countryCode 欄位，取得使用者的 Play 國家/地區。

注意：國家/地區代碼格式採用 ISO-3166-1 alpha2 (聯合國國家/地區代碼)。 詳情請參閱地域分類編碼表。

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
        }
      }
    });