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

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

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

購買流程

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

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

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

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

啟動與 Google Play 的連線

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

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

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

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

Groovy

dependencies {
    def billing_version = "8.0.0"

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

Kotlin

dependencies {
    val billing_version = "8.0.0"

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

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

Groovy

dependencies {
    def billing_version = "8.0.0"

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

Kotlin

dependencies {
    val billing_version = "8.0.0"

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

初始化 BillingClient

加入 Google Play 帳款服務程式庫的依附元件後，您需要初始化 BillingClient 例項。BillingClient 是 Google Play 帳款服務程式庫與應用程式其餘部分之間通訊的主要介面。BillingClient 提供同步和非同步的便利方法，適用於許多常見的結帳作業。請注意以下事項：

• 建議您一次啟用一組有效的 BillingClient 連線，以免單一事件發生多次 PurchasesUpdatedListener 回呼。
• 建議您在應用程式啟動或移至前景時，為 BillingClient 啟動連線，確保應用程式能及時處理購買交易。如要達成這項目標，請使用 registerActivityLifecycleCallbacks 註冊的 ActivityLifecycleCallbacks，並在首次偵測到活動恢復時，監聽 onActivityResumed 以初始化連線。如要進一步瞭解為何應遵循這項最佳做法，請參閱「處理購買交易」一節。請記得在關閉應用程式時結束連線。

如要建立 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 帳款服務程式庫會以 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 連線。

自動重新建立連線

在 8.0.0 版中，BillingClient.Builder 引進了 enableAutoServiceReconnection() 方法，因此如果在服務中斷連時發出 API 呼叫，Play 帳款服務程式庫現在可以自動重新建立服務連線。由於重新連線會在 API 呼叫之前在內部處理，因此可能會導致 SERVICE_DISCONNECTED 回應減少。

如何啟用自動重新連線功能

建構 BillingClient 例項時，請使用 BillingClient.Builder 中的 enableAutoServiceReconnection() 方法啟用自動重新連線功能。

Kotlin

val billingClient = BillingClient.newBuilder(context)
    .setListener(listener)
    .enablePendingPurchases()
    .enableAutoServiceReconnection() // Add this line to enable reconnection
    .build()

Java

BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(listener)
    .enablePendingPurchases()
    .enableAutoServiceReconnection() // Add this line to enable reconnection
    .build();

顯示可供購買的產品

與 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,
    queryProductDetailsResult ->
      if (billingResult.getResponseCode() == BillingResponseCode.OK) {
               for (ProductDetails productDetails : queryProductDetailsResult.getProductDetailsList()) {
                 // Process successfully retrieved product details here.
               }

               for (UnfetchedProduct unfetchedProduct : queryproductDetailsResult.getUnfetchedProductList()) {
                 // Handle any unfetched products as appropriate.
               }
            }
}

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,
                QueryProductDetailsResult queryProductDetailsResult) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
               for (ProductDetails productDetails : queryProductDetailsResult().getProductDetailsList()) {
                 // Process success retrieved product details here.
               }

               for (UnfetchedProduct unfetchedProduct : queryproductDetailsResult.getUnfetchedProductList()) {
                 // Handle any unfetched products as appropriate.
               }
            }
        }
    }
)

查詢產品詳細資料時，請傳遞 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 帳款服務程式庫 7 遷移指南，瞭解如何使用回溯相容性功能。

處理結果

Google Play 帳款服務程式庫會將查詢結果儲存在 QueryProductDetailsResult 物件中。QueryProductDetailsResult 包含 ProductDetails 物件的 List。接著，您可以在清單中的每個 ProductDetails 物件上呼叫各種方法，查看成功擷取的一次性產品相關資訊，例如價格或說明。如要查看可用產品的詳細資訊，請參閱 ProductDetails 類別中的方法清單。

QueryProductDetailsResult 也包含 UnfetchedProduct 物件的 List。接著，您可以查詢每個 UnfetchedProduct，取得對應於擷取失敗原因的狀態碼。如要查看可用的未擷取產品資訊，請參閱 UnfetchedProduct 類別中的方法清單。

在提供待售項目之前，請先檢查使用者是否尚未擁有該項目。如果使用者的商品庫中仍有可消耗項目，必須先消耗該項目才能再次購買。

提供訂閱項目前，請先確認使用者尚未訂閱， 此外，也請注意下列事項：

• 針對訂閱項目，queryProductDetailsAsync() 方法會傳回訂閱產品詳細資料，每個訂閱項目最多 50 項使用者符合資格的優惠。如果使用者嘗試購買不符資格的優惠方案 (例如應用程式顯示過舊的優惠清單)，Play 會將不符資格的情況告知使用者，讓他們可以選擇改為購買基本方案。

• 對於一次性產品，queryProductDetailsAsync() 方法只會傳回使用者符合資格的優惠。如果使用者嘗試購買不符資格的優惠方案 (例如使用者已達到購買數量上限)，Play 會將不符資格的消息告知使用者，讓他們可以選擇改為購買購買選項。

注意：我們不建議使用快取 ProductDetails 物件，因為過時的物件可能會導致 launchBillingFlow() 失敗。

注意：有些 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)
        // Get the offer token:
        // a. For one-time products, call ProductDetails.getOneTimePurchaseOfferDetailsList()
        // for a list of offers that are available to the user.
        // b. For subscriptions, 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)
            // Get the offer token:
            // a. For one-time products, call ProductDetails.getOneTimePurchaseOfferDetailsList()
            // for a list of offers that are available to the user.
            // b. For subscriptions, 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 顯示某個訂閱項目的購買畫面：

圖 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) {
           // Process the purchase as described in the next section.
       }
   } else if (billingResult.responseCode == BillingResponseCode.USER_CANCELED) {
       // Handle an error caused by a user canceling 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) {
            // Process the purchase as described in the next section.
        }
    } else if (billingResult.getResponseCode() == BillingResponseCode.USER_CANCELED) {
        // Handle an error caused by a user canceling the purchase flow.
    } else {
        // Handle any other error codes.
    }
}

購買成功後，系統會產生與圖 2 類似的 Google Play 購買成功畫面。

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

購買成功後還會產生購買憑證，這是一個不重複 ID，代表已購買一次性產品的使用者和產品 ID。應用程式可在使用者的裝置上儲存購買憑證。不過，我們強烈建議您將該憑證傳遞至安全的後端伺服器，以便驗證購買交易及防範詐欺行為。如要進一步瞭解這項程序，請參閱「偵測及處理購買交易」。

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

顯示個人化的價格

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

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

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

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

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

附加使用者 ID

啟動購買流程時，應用程式可以使用 obfuscatedAccountId 或 obfuscatedProfileId，為購買交易的使用者附加任何使用者 ID。舉例來說，您可以將系統中使用者登入資訊的模糊處理版本做為 ID。設定這些參數有助於 Google 偵測詐欺。此外，如同「授予使用者授權」一文所述，這項功能還可確保購買交易歸給正確的使用者。

偵測及處理購買交易

本節所述的購買交易偵測和處理程序適用於所有類型的購買交易，包括促銷兌換等應用程式外購買交易。

應用程式會透過下列任一方式偵測新購買交易和完成的待處理購買交易：

1. 當應用程式呼叫 launchBillingFlow 而導致呼叫 onPurchasesUpdated 時 (如前一個章節所述)，或是當應用程式在應用程式外完成購買交易或完成待處理的購買交易時，使用 Billing Library 連線執行應用程式。例如，家人在另一部裝置上核准待處理的購買交易。
2. 應用程式呼叫 queryPurchasesAsync 以查詢使用者的購買交易。

對於 #1，只要應用程式正在執行且有有效的 Google Play 帳款服務程式庫連線，系統就會自動呼叫 onPurchasesUpdated 來處理新購買交易或已完成的購買交易。如果應用程式未執行，或應用程式沒有有效的 Google Play 帳款服務程式庫連線，就不會叫用 onPurchasesUpdated。請注意，只要應用程式處於前景，就建議應用程式嘗試保持有效連線，以便及時取得購買交易更新。

針對 #2，您必須呼叫 BillingClient.queryPurchasesAsync()，確保應用程式能處理所有購買交易。建議您在應用程式成功與 Google Play 帳款服務程式庫建立連線時執行這項操作 (如需瞭解詳情，請參閱「初始化 BillingClient」一文)。方法是收到 onServiceConnected 的成功結果時，呼叫 queryPurchasesAsync。如要處理下列事件和情況，請務必遵循這項建議：

• 購買期間發生網路問題：使用者成功完成購買交易且收到 Google 的確認通知，但使用者的裝置在透過 PurchasesUpdatedListener 收到購買通知前失去網路連線。
• 多部裝置：使用者在某部裝置上購買商品，且希望在切換至其他裝置時也能看到該商品。
• 處理應用程式外的購買交易：某些購買交易可在應用程式外完成，例如促銷兌換。
• 處理購買狀態轉換：使用者可能會在應用程式未運作時完成待處理購買交易的付款，並預期在開啟應用程式時收到購買交易完成的確認訊息。

注意： 您也可以選擇監聽即時開發人員通知，以便即時瞭解新購買交易和已完成的待處理購買交易，即使使用者在事件發生時未使用您的應用程式，也能掌握相關資訊。這有助於您隨時保持後端狀態同步。如需進一步瞭解這項功能，請參閱「一次性購買交易」和「訂閱項目」的後端整合部分。

應用程式偵測到新購買交易或完成購買交易後，應執行以下操作：

• 驗證購買交易。
• 為已完成購買的使用者授予內容。
• 通知使用者。
• 通知 Google，您的應用程式已處理完成的購買交易。

這些步驟會在後續章節中詳細討論，接著會提供一節來總結所有步驟。

驗證購買交易

在向使用者提供福利前，應用程式應一律驗證購買交易的合法性。如要這樣做，請按照「在授權前驗證購買交易」一文所述規範操作。只有在驗證購買交易後，應用程式才應繼續處理購買交易，並授予使用者權限，這會在下一節中討論。

授予使用者授權

應用程式驗證購買交易後，就可以繼續將授權授予使用者，並通知使用者。授予授權前，請確認應用程式會檢查購買狀態是否為 PURCHASED。如果購買交易處於「待處理」狀態，應用程式應通知使用者，他們仍需完成相關動作，才能獲得授權。只有在購買交易狀態從「PENDING」轉換為「SUCCESS」時，才會授予授權。詳情請參閱「處理未完成的交易」。

如果您已按照「附加使用者 ID」一節所述，將使用者 ID 附加至購買交易，即可擷取這些 ID，並將其歸給系統中的正確使用者。當應用程式可能遺失購買交易的使用者相關資訊時，這項技巧就很實用。請注意，應用程式外的購買交易不會設定這些 ID。在這種情況下，您的應用程式可以將授權授予登入的使用者，或提示使用者選擇偏好的帳戶。

對於預購，購買交易會在發布時間之前處於「待處理」狀態。預購交易會在發布時間完成，並將狀態變更為「已購買」，無須採取其他行動。

通知使用者

授予使用者授權後，應用程式應顯示通知，確認購買交易成功。由於有通知，使用者不會對購買交易是否成功完成感到困惑，這可能會導致使用者停止使用您的應用程式、聯絡使用者支援團隊，或在社群媒體上投訴。請注意，應用程式在生命週期中的任何時間點都可能偵測到購買交易更新。舉例來說，如果家長在另一部裝置上核准待處理的購買交易，應用程式可能會延後通知使用者，直到適當時間為止。以下列舉幾個適合延遲的情況：

• 在遊戲動作部分或過場畫面中，顯示訊息可能會分散使用者的注意力。在這種情況下，您必須在操作結束後通知使用者。
• 遊戲的初始教學課程和使用者設定期間。舉例來說，使用者可能在安裝應用程式前，就已在應用程式外購買商品。建議您在新使用者開啟遊戲後或初次進行使用者設定期間，立即發出獎勵通知。如果您的應用程式要求使用者建立帳戶或登入帳戶，才能授予使用者授權，建議您向使用者說明完成哪些步驟才能兌換購買項目。這點非常重要，因為如果應用程式未處理購買交易，系統會在 3 天後退款。

當您向使用者通知購買交易時，Google Play 建議採用下列機制：

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

通知應通知使用者已獲得的福利。例如：「你購買了 100 枚金幣！」。此外，如果購買交易是因為 Play Pass 等計畫提供的福利，應用程式會向使用者說明這點。例如「收到商品了！您剛剛使用 Play Pass 兌換了 100 顆寶石。繼續。」每個計畫可能都會提供建議文字指南，讓您向使用者說明相關優點。

通知 Google 購買交易已處理完畢

應用程式授予使用者授權，並通知他們交易成功後，就必須通知 Google 已成功處理購買交易。您必須在三天內確認購買交易，否則系統會自動退款並撤銷授權。下文將說明如何確認不同類型的購買交易。

消耗性產品

如果應用程式設有安全的後端，建議您針對消耗性產品，使用 Purchases.products:consume 確實消耗購買項目。您可以根據呼叫 Purchases.products:get 的結果檢查 consumptionState，確認購買項目尚未消耗。如果應用程式只有用戶端而沒有後端，請使用 Google Play 帳款服務程式庫的 consumeAsync()。這兩種方法都能執行確認要求，且會指出應用程式已授權給使用者。應用程式也可以使用這些方法，提供與輸入購買憑證相應的一次性產品，讓使用者再次購買。使用 consumeAsync() 時，您也必須傳遞實作 ConsumeResponseListener 介面的物件，這個物件會處理消耗作業的結果。您可以覆寫 onConsumeResponse() 方法，Google Play 帳款服務程式庫會在作業完成後呼叫此方法。

以下範例示範如何使用相關聯的購買憑證，透過 Google Play 帳款服務程式庫消耗產品：

Kotlin

    val consumeParams =
        ConsumeParams.newBuilder()
            .setPurchaseToken(purchase.getPurchaseToken())
            .build()
    val consumeResult = withContext(Dispatchers.IO) {
        client.consumePurchase(consumeParams)
    }

Java

    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 的成功消耗回應後再授權。如果您選擇在 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 = ...

val acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder()
    .setPurchaseToken(purchase.purchaseToken)
val ackPurchaseResult = withContext(Dispatchers.IO) {
     client.acknowledgePurchase(acknowledgePurchaseParams.build())
}

Java

BillingClient client = ...
AcknowledgePurchaseResponseListener acknowledgePurchaseResponseListener = ...

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() 確認訂閱。所有初始訂閱項目的購買交易都需經過確認，訂閱項目的續訂則無需確認。如要進一步瞭解需要確認訂閱項目的時機，請參閱「販售訂閱項目」主題。

重點回顧

以下程式碼片段重點說明這些步驟。

Kotlin

fun handlePurchase(Purchase purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your
    // onPurchasesUpdated.
    Purchase purchase = ...;

    // Step 1: Send the purchase to your secure backend to verify the purchase
    // following
    // https://developer.android.com/google/play/billing/security#verify
.
    // Step 2: Update your entitlement storage with the purchase. If purchase is
    // in PENDING state then ensure the entitlement is marked as pending and the
    // user does not receive benefits yet. It is recommended that this step is
    // done on your secure backend and can combine in the API call to your
    // backend in step 1.

    // Step 3: Notify the user using appropriate messaging (delaying
    // notification if needed as discussed above).

    // Step 4: Notify Google the purchase was processed using the steps
    // discussed in the processing purchases section.
}

Java

void handlePurchase(Purchase purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your
    // onPurchasesUpdated.
    Purchase purchase = ...;

    // Step 1: Send the purchase to your secure backend to verify the purchase
    // following
    // https://developer.android.com/google/play/billing/security#verify

    // Step 2: Update your entitlement storage with the purchase. If purchase is
    // in PENDING state then ensure the entitlement is marked as pending and the
    // user does not receive benefits yet. It is recommended that this step is
    // done on your secure backend and can combine in the API call to your
    // backend in step 1.

    // Step 3: Notify the user using appropriate messaging (delaying
    // notification if needed as discussed above).

    // Step 4: Notify Google the purchase was processed using the steps
    // discussed in the processing purchases section.
}

如要確認應用程式已正確實作這些步驟，您可以按照測試指南操作。

處理未完成的交易

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

舉例來說，使用者可以選擇實體商店，然後稍後以現金付款，藉此啟動交易。使用者會透過通知和電子郵件接收代碼。當使用者來到實體商店時，就可以向收銀員兌換代碼，再用現金付款。接著，Google 會通知您和使用者已收到付款，您的應用程式就可以向使用者授權。

在初始化 BillingClient 時呼叫 enablePendingPurchases()，即可為應用程式啟用未完成的交易。應用程式必須啟用並支援一次性產品的未完成交易。新增支援功能前，請務必瞭解待處理交易的購買生命週期。

注意： 如果應用程式使用 Google Play 帳款服務程式庫 7.0 以上版本，您可以為訂閱預付方案購買交易啟用未完成交易。如要瞭解如何在應用程式中支援這項功能，請參閱「處理訂閱項目待處理交易」。

無論應用程式是透過 PurchasesUpdatedListener 還是呼叫 queryPurchasesAsync 而收到新的購買交易，都請使用 getPurchaseState() 方法來判斷購買狀態是 PURCHASED 或 PENDING。只有在狀態為 PURCHASED 時才可授予權限。

如果使用者完成購買時您的應用程式正在運作，且您有有效的 Play 帳款服務程式庫連線，系統會再次呼叫 PurchasesUpdatedListener，而 PurchaseState 現已變為 PURCHASED。這時，應用程式可按照偵測及處理購買交易的標準方法處理購買交易。應用程式也需要呼叫應用程式 onResume() 方法中的 queryPurchasesAsync()，處理在應用程式未運作期間轉換為 PURCHASED 狀態的購買交易。

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

當購買交易從 PENDING 變為 PURCHASED 時，您的 real_time_developer_notifications 用戶端會收到 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 的國家/地區。

注意：請勿儲存 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
        }
      }
    });

Google Play 遊戲首頁的購物車放棄提醒 (預設為啟用)

如果遊戲開發人員透過一次性產品營利，則可透過「購物車未結帳提醒」功能，在 Google Play 管理中心中啟用有效的庫存單位 (SKU)，在應用程式外銷售。這項功能會在使用者瀏覽 Google Play 商店時，提醒他們完成先前未結帳的購買交易。這些交易是在應用程式外，透過 Google Play 商店的 Google Play 遊戲首頁完成。

這項功能預設為啟用，可協助使用者繼續閱讀先前中斷的內容，並協助開發人員盡可能提高銷售量。不過，您可以提交購物車未結帳提醒功能停用表單，為應用程式停用這項功能。如要瞭解在 Google Play 管理中心管理 SKU 的最佳做法，請參閱「建立應用程式內產品」。

以下圖片顯示 Google Play 商店中的購物車放棄提醒：

圖 2. Google Play 商店畫面顯示先前放棄的購買交易提示。

圖 3. Google Play 商店畫面顯示先前未完成的購買交易的購買提示。