本指南說明如何整合 API,讓符合資格的應用程式和地區支援外部優惠。如要進一步瞭解外部優惠計畫,包括資格規定和地理位置範圍,請參閱計畫規定。
Play 帳款服務程式庫設定
如要使用外部提供 API,請將 Play 帳款服務程式庫依附元件加入 6.2.1 以上版本至您的 Android 應用程式。如需從舊版遷移至新版,請先按照遷移指南的指示操作,再嘗試實作外部優惠。
連線至 Google Play
整合程序的前幾個步驟如同帳單整合指南所述,但初始化 BillingClient
時以下幾點:
- 您需要呼叫以下新方法,指出您要使用外部優惠:
enableExternalOffer
。
以下示範如何透過變更後的做法初始化 BillingClient
:
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build();
初始化 BillingClient
後,請按照整合指南的說明與 Google Play 建立連線。
查看產品供應情形
應用程式應呼叫 isExternalOfferAvailableAsync
,確認可以取得外部優惠。
如果有外部優惠,這個 API 會傳回 BillingResponseCode.OK
。如要進一步瞭解應用程式應如何回應其他回應代碼,請參閱「回應處理」。
Kotlin
billingClient.isExternalOfferAvailableAsync(
object : ExternalOfferAvailabilityListener {
override fun onExternalOfferAvailabilityResponse(
billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external offers unavailable, etc.
return
}
// External offers are available. Continue with steps in the
// guide.
})
Java
billingClient.isExternalOfferAvailableAsync(
new ExternalOfferAvailabilityListener() {
@Override
public void onExternalOfferAvailabilityResponse(
BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external offers being unavailable, etc.
return;
}
// External offers are available. Continue with steps in the
// guide.
}
});
準備外部交易憑證
如要向 Google Play 回報外部交易,您必須擁有從 Play 帳款服務程式庫產生的外部交易憑證。每次使用者透過外部優惠 API 造訪外部網站時,都必須產生新的外部交易憑證。只要呼叫 createExternalOfferReportingDetailsAsync
API 即可。這個權杖必須在使用者導向應用程式外部前立即產生。這類權杖一律不得快取,且每次將使用者導向應用程式外時,都必須產生新的權杖。
Kotlin
billingClient.createExternalOfferReportingDetailsAsync(
object : ExternalOfferReportingDetailsListener {
override fun onExternalOfferReportingDetailsResponse(
billingResult: BillingResult,
externalOfferReportingDetails: ExternalOfferReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
externalOfferReportingDetails?.externalTransactionToken
// Persist the transaction token locally. Pass it to the external
// website when showExternalOfferInformationDialog is called.
}
})
Java
billingClient.createExternalOfferReportingDetailsAsync(
new ExternalOfferReportingDetailsListener() {
@Override
public void onExternalOfferReportingDetailsResponse(
BillingResult billingResult,
@Nullable ExternalOfferReportingDetails
externalOfferReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
externalOfferReportingDetails.getExternalTransactionToken();
// Persist the external transaction token locally. Pass it to the
// external website when showExternalOfferInformationDialog is
// called.
}
});
向使用者顯示的資訊對話方塊
如要整合外部優惠,符合資格的應用程式必須顯示資訊畫面,讓使用者瞭解即將被導向到外部網站的應用程式。您每次連結至外部優惠前,必須先呼叫 showExternalOfferInformationDialog
API 向使用者顯示資訊畫面。
Kotlin
// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;
val listener : ExternalOfferInformationDialogListener =
ExternalOfferInformationDialogListener {
override fun onExternalOfferInformationDialogResponse(
billingResult: BillingResult){
// Check billingResult
}
}
val billingResult = billingClient.showExternalOfferInformationDialog(
activity, listener)
Java
// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;
ExternalOfferInformationDialogListener listener =
new ExternalOfferInformationDialogListener() {
@Override
public void onExternalOfferInformationDialogResponse(
BillingResult billingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
}
// Open the external website, passing along the external transaction
// token as a URL parameter. If the user purchases an item, be sure
// to report the transaction to Google Play.
}
}
BillingResult billingResult =
billingClient.showExternalOfferInformationDialog(activity, listener);
如果這個方法傳回 BillingResponseCode.OK
,就表示應用程式可以繼續將使用者導向外部網站。如果這個方法傳回 BillingResponseCode.USER_CANCELED
,則應用程式不得繼續開啟網站。
向 Google Play 回報交易
所有外部交易都必須從後端呼叫 Google Play Developer API,向 Google Play 回報。提供使用 createExternalOfferReportingDetailsAsync
API 取得的 externalTransactionToken
時,必須回報外部交易。如果使用者進行多次購買交易,您可以使用相同的 externalTransactionToken
回報每筆購買交易。如要瞭解如何回報交易,請參閱後端整合指南。
回應處理
發生錯誤時,isExternalOfferAvailableAsync
、createExternalOfferReportingDetailsAsync
和 showExternalOfferInformationDialog
方法可能會傳回 BillingResponseCode.OK
以外的回應。請考慮按照下列方式處理這些回應代碼:
ERROR
:這是內部錯誤。請勿繼續交易或開啟外部網站。請呼叫showExternalOfferInformationDialog()
再試一次,在您下次嘗試將使用者導向應用程式外部時,向使用者顯示資訊對話方塊。FEATURE_NOT_SUPPORTED
:目前裝置的 Play 商店不支援外部優惠 API。請勿繼續交易或開啟外部網站。USER_CANCELED
:請勿繼續開啟外部網站。下次嘗試將使用者引導至應用程式外部時,請再次呼叫showExternalOfferInformationDialog()
,向使用者顯示資訊對話方塊。BILLING_UNAVAILABLE
:交易不符合外部優惠資格,因此不應以本計畫名義繼續進行。這是因為使用者不在本計畫適用的國家/地區,或是您的帳戶未成功註冊加入計畫。如果原因是後者,請前往 Play 管理中心查看註冊狀態。DEVELOPER_ERROR
:要求出錯。請先使用偵錯訊息找出並修正錯誤,然後再繼續操作。NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE
:這些是暫時性錯誤,應透過適當的重試政策處理。如果是SERVICE_DISCONNECTED
,請在重試前重新建立與 Google Play 的連線。
測試外部優惠
請使用授權測試人員測試外部優惠整合情形。對於授權測試人員帳戶所發起的交易,您不會收到月結單。如要進一步瞭解如何設定授權測試人員,請參閱「使用應用程式授權測試應用程式內結帳」。
後續步驟
完成應用程式內整合作業後,即可開始整合後端。