本指南說明如何整合 API,支援外部優惠 只能在符合資格的應用程式和地區放送進一步瞭解外部優惠計畫 包括資格規定和地理位置範圍,請參閱 計畫規範。
Play 帳款服務程式庫設定
如要使用外部優惠 API, 加入 6.2.1 以上版本的 Play 帳款服務程式庫依附元件 連結你的 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 回報
即可從後端呼叫 Google Play Developer API外部交易
必須先回報
使用以下項目取得的 externalTransactionToken
:
createExternalOfferReportingDetailsAsync
API。如果使用者多次製作
你也可以使用相同的
externalTransactionToken
即可回報每筆交易。如要瞭解如何回報
交易,請參閱後端整合指南。
回應處理
發生錯誤時,isExternalOfferAvailableAsync
方法、
createExternalOfferReportingDetailsAsync
和
showExternalOfferInformationDialog
可能會傳回
BillingResponseCode.OK
。建議您按照以下方式處理這些回應代碼:
ERROR
:這是內部錯誤。請勿繼續交易,或 開啟外部網站致電時再試一次showExternalOfferInformationDialog()
,即可顯示資訊 下次您嘗試引導使用者前往 應用程式。FEATURE_NOT_SUPPORTED
:以下來源不支援外部優惠 API: 。請勿繼續交易,或 開啟外部網站USER_CANCELED
:請勿繼續開啟外部網站。致電 再次showExternalOfferInformationDialog()
即可顯示資訊 下次您嘗試將使用者引導至 外部的 應用程式BILLING_UNAVAILABLE
:交易不符合外部優惠資格 因此不應以本計畫為準可能的原因包括 使用者不在本計畫適用的國家/地區,或您的帳戶已 未成功註冊加入計畫。如果是後者,請檢查 註冊狀態。DEVELOPER_ERROR
:要求出錯。請先使用偵錯訊息找出並修正錯誤,然後再繼續操作。NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE
:這些是 暫時錯誤,應使用適當的重試政策處理。 如果是SERVICE_DISCONNECTED
,請使用 Google Play,然後再試一次。
測試外部優惠
請使用授權測試人員測試外部優惠整合功能。個人中心 我們不會針對授權測試人員啟動的交易收取帳單費用 帳戶。詳情請參閱「使用應用程式授權測試應用程式內結帳」 關於設定授權測試人員的資訊。
後續步驟
完成應用程式內整合作業後,即可開始整合後端。