本頁面由 Cloud Translation API 翻譯而成。

外部優惠計畫的應用程式內整合指南

本指南說明如何整合 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 的連線。

測試外部優惠

請使用授權測試人員測試外部優惠整合情形。對於授權測試人員帳戶所發起的交易，您不會收到月結單。如要進一步瞭解如何設定授權測試人員，請參閱「使用應用程式授權測試應用程式內結帳」。

後續步驟

完成應用程式內整合作業後，即可開始整合後端。