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

本指南說明如何整合 API，支援外部優惠 只能在符合資格的應用程式和地區放送進一步瞭解外部優惠計畫 包括資格規定和地理位置範圍，請參閱 計畫規範。

Play 帳款服務程式庫設定

如要使用外部優惠 API， 加入 6.2.1 以上版本的 Play 帳款服務程式庫依附元件 連結你的 Android 應用程式如需從先前的版本進行遷移，請按照 請先參閱遷移指南中的操作說明，再嘗試 外部優惠。

連線至 Google Play

整合程序的第一步與 帳單整合指南 (其中有一些修改) 初始化 BillingClient：

以下示範如何透過變更後的做法初始化 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，然後再試一次。

測試外部優惠

請使用授權測試人員測試外部優惠整合功能。個人中心 我們不會針對授權測試人員啟動的交易收取帳單費用 帳戶。詳情請參閱「使用應用程式授權測試應用程式內結帳」 關於設定授權測試人員的資訊。

後續步驟

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