將 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 = "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 字串清單以及 ProductTypeProductType 可以是一次性產品的 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.
}

在極少數情況下,某些裝置無法支援 ProductDetailsqueryProductDetailsAsync(),這通常是因為 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 中列出的其中一個回應代碼。請務必查看這項結果,確認啟動時購買流程沒有發生錯誤。BillingResponseCodeOK 表示啟動成功。

成功呼叫 launchBillingFlow() 時,系統會顯示 Google Play 購買畫面。圖 1 顯示某個訂閱項目的購買畫面:

Google Play 購買畫面顯示可供購買的訂閱項目
圖 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 購買成功畫面。

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

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

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

標示個人化的價格

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

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

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

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

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

處理購買交易

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

此外,如果您在安全後端設有即時開發人員通知用戶端,可以接收 subscriptionNotificationoneTimeProductNotification (僅適用於未完成的購買交易) 來註冊新交易。這兩者都會在有新的購買交易時通知您。收到這類通知後,請呼叫 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 您已授予購買交易的權限。

授權和確認購買交易的程序會因該交易的購買項目 (非消耗性產品、消耗性產品或訂閱項目) 而有所不同。

消耗性產品

如果應用程式設有安全的後端,建議您針對消耗性產品,使用 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 商店畫面顯示先前放棄的購買交易的購買提示
圖 2. Google Play 商店畫面顯示先前放棄交易的購買提示。

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

處理未完成的交易

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

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

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

當應用程式收到新購買交易 (透過 PurchasesUpdatedListener 或呼叫 queryPurchasesAsync() 時),請使用 getPurchaseState() 方法判斷購買狀態是 PURCHASEDPENDING只有在狀態為 PURCHASED 時才可授予權限。

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

當購買交易從 PENDING 轉換為 PURCHASED 時,您的即時開發人員通知用戶端會收到 ONE_TIME_PRODUCT_PURCHASEDSUBSCRIPTION_PURCHASED 通知。如果購買交易遭到取消,您會收到 ONE_TIME_PRODUCT_CANCELEDSUBSCRIPTION_PENDING_PURCHASE_CANCELED 通知。如果客戶在指定時間範圍內未完成付款,就可能發生這種情況。 請注意,您隨時可以使用 Google Play Developer API 查看購買交易的目前狀態。

處理多件購買交易

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

為了滿足多件購買交易的需求,應用程式的佈建邏輯需要檢查項目數量。您可以透過下列任一 API 存取 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
        }
      }
    });