本指南說明如何整合 API,僅在符合資格的應用程式中提供其他結帳系統 (即不讓使用者自選)。如要進一步瞭解這些計畫,包括資格規定和地理位置範圍,請參閱「關於其他結帳系統」。
Play 帳款服務程式庫設定
請將 Play 帳款服務程式庫依附元件新增至您的 Android 應用程式。您需要採用 6.1 以上版本,才能使用其他結帳系統 API。
連線至 Google Play
整合程序的前幾個步驟如同 Google Play 帳款服務整合指南所述,但初始化 BillingClient 的做法有些改變:
- 您需要呼叫以下新方法,指出應用程式僅使用其他結帳系統:
enableAlternativeBillingOnly
。
以下示範如何透過變更後的做法初始化 BillingClient
:
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableAlternativeBillingOnly()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableAlternativeBillingOnly()
.build();
初始化 BillingClient
後,請按照整合指南的說明與 Google Play 建立連線。
檢查可用性
應用程式應呼叫 isAlternativeBillingOnlyAvailableAsync
,確認可以僅採用其他結帳系統。
如果可以僅使用其他結帳系統,這個 API 會傳回 BillingResponseCode.OK。如要進一步瞭解應用程式應如何回應其他回應代碼,請參閱「回應處理」。
Kotlin
billingClient.isAlternativeBillingOnlyAvailableAsync(object:
AlternativeBillingOnlyAvailabilityListener {
override fun onAlternativeBillingOnlyAvailabilityResponse(
billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling alternative billing only being unavailable, etc.
return
}
// Alternative billing only is available. Continue with steps in
// the guide.
}
});
Java
billingClient.isAlternativeBillingOnlyAvailable(
new AlternativeBillingOnlyAvailabilityListener() {
@Override
public void onAlternativeBillingOnlyAvailabilityResponse(
BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling alternative billing only being unavailable,
// etc.
return;
}
// Alternative billing only is available. Continue with steps in
// the guide.
}
});
向使用者顯示的資訊對話方塊
如果只要整合其他結帳系統,符合資格的應用程式必須顯示資訊畫面,讓使用者瞭解帳單不會由 Google Play 管理。您每次啟動其他結帳流程前,必須呼叫 showAlternativeBillingOnlyInformationDialog
API 向使用者顯示資訊畫面。如果使用者已在對話方塊中點選「確認」,使用這個 API 一般不會導致對話方塊再次顯示。不過,有時在某些情況下 (例如使用者清除裝置上的快取時),系統可能仍會再次向使用者顯示該對話方塊。
Kotlin
// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;
val listener : AlternativeBillingOnlyInformationDialogListener =
AlternativeBillingOnlyInformationDialogListener {
override fun onAlternativeBillingOnlyInformationDialogResponse(
billingResult: BillingResult) {
// check billingResult
}
}
val billingResult =
billingClient.showAlternativeBillingOnlyInformationDialog(activity,
listener)
Java
// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;
AlternativeBillingOnlyInformationDialogListener listener =
new AlternativeBillingOnlyInformationDialogListener() {
@Override
public void onAlternativeBillingOnlyInformationDialogResponse(
BillingResult billingResult) {
// check billingResult
}
};
BillingResult billingResult =
billingClient.showAlternativeBillingOnlyInformationDialog(activity,
listener);
如果這個方法傳回 BillingResponseCode.OK,表示應用程式可以繼續交易。若是傳回 BillingResponseCode.USER_CANCELED,應用程式應呼叫 showAlternativeBillingOnlyInformationDialog,再次向使用者顯示對話方塊。其他回應代碼請參閱「回應處理」一節。
向 Google Play 回報交易
對於透過其他結帳系統完成的所有交易,您都必須在 24 小時內從後端呼叫 Google Play Developer API,藉此向 Google Play 回報,並提供可用下述 API 取得的 externalTransactionToken
。每當有一次性消費、新的訂閱情形發生,或任何現有訂閱項目升級/降級時,系統應該都會產生新的 externalTransactionToken。如要瞭解如何在取得 externalTransactionToken
後回報交易,請參閱後端整合指南。
Kotlin
billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
AlternativeBillingOnlyReportingDetailsListener {
override fun onAlternativeBillingOnlyTokenResponse(
billingResult: BillingResult,
alternativeBillingOnlyReportingDetails:
AlternativeBillingOnlyReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
alternativeBillingOnlyReportingDetails?
.externalTransactionToken
// Send transaction token to backend and report to Google Play.
}
});
Java
billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
new AlternativeBillingOnlyReportingDetailsListener() {
@Override
public void onAlternativeBillingOnlyTokenResponse(
BillingResult billingResult,
@Nullable AlternativeBillingOnlyReportingDetails
alternativeBillingOnlyReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
alternativeBillingOnlyReportingDetails
.getExternalTransactionToken();
// Send transaction token to backend and report to Google Play.
}
});
回應處理
如果發生錯誤,上述方法 isAlternativeBillingOnlyAvailableAsync(),
showAlternativeBillingOnlyInformationDialog()
和 createAlternativeBillingOnlyReportingDetailsAsync()
可能會傳回 BillingResponseCode.OK 以外的回應。錯誤的建議處理方式如下:
ERROR
:這是內部錯誤。請勿繼續交易。 致電時再試一次showAlternativeBillingOnlyInformationDialog()
,即可顯示資訊 使用者下次使用 就會告訴客戶FEATURE_NOT_SUPPORTED
:目前裝置的 Play 商店不支援其他結帳系統 API。請勿繼續交易。USER_CANCELED
:請勿繼續交易。致電 再次showAlternativeBillingOnlyInformationDialog()
,即可顯示 擷取的資訊對話方塊,在使用者下次嘗試 購買。BILLING_UNAVAILABLE
:無法僅透過其他結帳系統完成交易,因此不應以本計畫名義繼續進行。這是因為使用者不在本計畫適用的國家/地區,或是您的帳戶未成功註冊加入計畫。如果原因是後者,請前往 Play 管理中心查看註冊狀態。DEVELOPER_ERROR
:要求出錯。請先使用偵錯訊息找出並修正錯誤,然後再繼續操作。NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE
:這些是暫時性錯誤,您應重試操作。當出現SERVICE_DISCONNECTED
時,請在重試前重新建立與 Google Play 的連線。
測試其他結帳系統
請使用授權測試人員測試其他結帳系統的整合作業。個人中心 我們不會針對授權測試人員啟動的交易收取帳單費用 帳戶。詳情請參閱「使用應用程式授權測試應用程式內結帳」 關於設定授權測試人員的資訊。
後續步驟
完成應用程式內整合作業後,即可開始整合後端。