外部內容連結的應用程式內整合指南

本文說明如何整合 Play 結帳服務程式庫 API，以便在符合資格的應用程式中提供外部內容連結。包括將美國使用者從 Play 應用程式導向其他平台，向他們提供應用程式內數位內容的優惠和應用程式下載連結。如要進一步瞭解這項計畫，請參閱計畫規定。

Play 帳款服務程式庫設定

請將 Play 帳款服務程式庫依附元件新增至您的 Android 應用程式。您需要採用 8.2 以上版本，才能使用外部連結 API。如需從舊版遷移至新版，請先按照遷移指南的指示操作，再新增外部內容連結。

初始化帳單用戶端

如要初始化帳單用戶端，請按照「初始化 BillingClient」一節所述的步驟操作，並進行下列修改：

  • 請勿啟用 PurchasesUpdatedListener，外部內容連結不需要這個接聽程式。
  • 使用 BillingProgram.EXTERNAL_CONTENT_LINK 呼叫 enableBillingProgram()，指出應用程式使用外部內容連結。

以下範例說明如何透過變更後的做法初始化 BillingClient：

Kotlin

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .build();

連線至 Google Play

初始化 BillingClient 後，請按照「連線至 Google Play」一文的說明操作。

檢查使用者資格

連結至 Google Play 後，您必須呼叫 isBillingProgramAvailableAsync() 方法，檢查使用者是否符合外部內容連結計畫的資格。如果使用者符合外部內容連結計畫的資格，這個方法會傳回 BillingResponseCode.OK。以下範例說明如何檢查使用者是否符合外部內容連結的資格：

Kotlin

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingProgram: Int, billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return
        }

        // External content links are available. Prepare an external
        // transaction token.
      }
    })

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return;
        }

        // External content links are available. Prepare an external
        // transaction token.
      }

    });

如要進一步瞭解應用程式應如何回應其他回應代碼，請參閱「回應處理」一節。如果您使用 Kotlin 擴充功能，可以採用 Kotlin 協同程式，因此不需定義單獨的事件監聽器。

準備外部交易權杖

接著，您必須從 Play 結帳程式庫產生外部交易憑證。每當使用者透過外部連結 API 瀏覽外部網站時，系統都必須產生新的外部交易權杖。只要呼叫 createBillingProgramReportingDetailsAsync API，即可進行確認。應在使用者連結出去前立即產生權杖。

注意：請勿快取外部交易權杖，且每次使用者連結至外部時，都應產生新的權杖。

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the external transaction token locally. Pass it to the
        // external website when launchExternalLink is called.
    }
  })

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when launchExternalLink is called.
      }
  });

如果您使用 Kotlin 擴充功能，可以採用 Kotlin 協同程式，因此不需定義單獨的事件監聽器。

啟動外部連結

外部交易權杖準備就緒後，使用者可以呼叫 launchExternalLink 方法，在應用程式外連結至數位內容優惠或應用程式下載頁面。呼叫此 API 時，Google Play 可能會根據使用者的設定，向使用者顯示其他資訊對話方塊。

呼叫 launchExternalLink 方法時，必須透過 LaunchExternalLinkParams 提供外部連結的詳細資料。這個類別包含下列參數：

  • 連結 URI：提供數位內容或應用程式下載服務的外部網站連結。如要追蹤應用程式下載次數，請務必在 Play 管理中心註冊並核准這個連結。
  • 連結類型：提供給使用者的內容類型。
  • 啟動模式：指定連結的啟動方式。如要增加應用程式下載量，請務必將這個值設為 LAUNCH_IN_EXTERNAL_BROWSER_OR_APP。

  • 帳單方案 - 將此項設為 BillingProgram.EXTERNAL_CONTENT_LINK。

Kotlin

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
    object : LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(
        billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
}

billingClient.launchExternalLink(activity, params, listener)

Java

LaunchExternalLinkParams params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
  }

billingClient.launchExternalLink(activity, params, listener);

回應處理

發生錯誤時，方法 isBillingProgramAvailableAsync()、createBillingProgramReportingDetailsAsync() 和 onLaunchExternalLinkResponse() 可能會提供 BillingResponseCode (而非 BillingResponseCode.OK)。建議您按照下列方式處理這些回應代碼：

  • ERROR：這是內部錯誤。請勿繼續交易或開啟外部網站。再次呼叫 API 或在下次嘗試將使用者導向應用程式外部時呼叫 launchExternalLink()，即可重試。
  • FEATURE_NOT_SUPPORTED：目前裝置的 Play 商店不支援外部內容連結 API。請勿繼續交易或開啟外部網站。
  • USER_CANCELED：請勿繼續開啟外部網站。下次嘗試將使用者導向應用程式外部時，請再次呼叫 launchExternalLink()。
  • BILLING_UNAVAILABLE：無法透過外部內容連結完成交易，因此不應以本計畫名義繼續進行。這是因為使用者不在本計畫適用的國家/地區，或是您的帳戶未成功註冊加入計畫。如果原因是後者，請前往 Play 管理中心查看註冊狀態。
  • DEVELOPER_ERROR：要求出錯。請先使用偵錯訊息找出並修正錯誤，然後再繼續操作。
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE：這些是暫時性錯誤，應使用適當的重試政策處理。當出現 SERVICE_DISCONNECTED 時，請在重試前重新建立與 Google Play 的連線。

測試外部內容連結

授權測試人員可用於測試外部優惠整合。系統不會針對授權測試人員帳戶發起的交易開立月結單。如要進一步瞭解如何設定授權測試人員，請參閱「透過應用程式授權來測試應用程式內結帳服務」。

後續步驟

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