設定應用程式開啟頁面廣告

將機器學習工作流程自動化

選取平台： Android iOS Unity Flutter Android (舊版)

應用程式開啟頁面廣告是一種廣告格式，適合想利用應用程式載入畫面營利的發布商。應用程式開啟頁面廣告會在使用者將應用程式切換至前景時出現，而且使用者隨時可以關閉。

詳情請參閱應用程式開啟頁面廣告指南。

本指南說明如何在 Android 應用程式中整合應用程式開啟頁面廣告。

事前準備

繼續操作前，請先執行下列工作：

  • 設定 GMA Next-Gen SDK。
  • 使用測試應用程式開啟頁面廣告單元 ID ca-app-pub-3940256099942544/9257395921。
    • 建構及測試應用程式時，請務必使用測試廣告，而非實際的正式廣告，如果未使用測試廣告單元 ID，Google 可能會停權您的帳戶。
    • 發布應用程式前，請將這個 ID 換成您的廣告單元 ID。
    • 如要進一步瞭解 GMA Next-Gen SDK 測試廣告，請參閱「啟用測試廣告」。

瞭解廣告預先載入

GMA Next-Gen SDK 中的廣告預先載入功能會自動載入及快取廣告。

預先載入廣告有以下好處：

  • 參照管理：維護參照，直到廣告顯示為止。
  • 自動重新載入：從快取擷取廣告時，載入新廣告。
  • 管理重試：如果廣告無法載入，系統會載入新廣告。
  • 到期處理：在廣告到期前重新整理廣告。
  • 快取最佳化：最佳化快取順序，放送最高優先順序的廣告。

開始預先載入廣告

如要開始預先載入廣告，請在應用程式啟動時呼叫一次 startPreload() 方法。呼叫 startPreload() 方法後，GMA Next-Gen SDK 會自動預先載入廣告，並重試預先載入設定的失敗要求。

以下範例說明如何開始預先載入廣告：

Kotlin

private fun startPreloading(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  AppOpenAdPreloader.start(adUnitId, preloadConfig);
}

將 AD_UNIT_ID 替換為廣告單元 ID。

上一個範例說明如何使用廣告單元 ID 做為預先載入 ID。預先載入 ID 是您建立的字串 ID，用於識別廣告預先載入設定。如果應用程式需要為同一個廣告單元 ID 設定多個指定目標，請傳遞自訂字串 ID。

取得並顯示預先載入的廣告

如要顯示廣告，請呼叫 pollAd() 方法。GMA Next-Gen SDK 會擷取可用的廣告，並在背景自動預先載入下一個廣告。如果沒有可用廣告，GMA Next-Gen SDK 就不會傳回任何廣告。

取得可用的廣告物件後，請呼叫 show 方法來顯示廣告。以下範例說明如何擷取及顯示預先載入的廣告：

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = AppOpenAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "App open ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "App open ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "App open ad recorded an impression.")
      }
    }
  ad.show(activity)
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  AppOpenAd ad = AppOpenAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "App open ad is not available.");
    return;
  }

  Log.d(TAG, "App open ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "App open ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(activity);
}

請在準備好顯示廣告之後，再呼叫 pollAd() 方法。如要讀取廣告回應資訊但不顯示，請參閱「讀取回應資訊」。

監聽廣告事件

顯示廣告前，請先監聽廣告事件。以下範例說明如何註冊廣告事件的回呼：

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = appOpenAd
  if (ad == null) {
    Log.e(TAG, "App open ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // App open ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // App open ad did dismiss.
        appOpenAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // App open ad failed to show.
        Log.e(TAG, "App open ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // App open ad did record an impression.
      }

      override fun onAdClicked() {
        // App open ad did record a click.
      }
    }
}

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (appOpenAd == null) {
    Log.e(TAG, "App open ad is not ready yet.");
    return;
  }

  appOpenAd.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // App open ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // App open ad did dismiss.
          appOpenAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // App open ad failed to show.
          Log.e(TAG, "App open ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // App open ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // App open ad did record a click.
        }
      });
}

選用：監聽預先載入事件

開始預先載入廣告時，請註冊預先載入事件，以便在廣告預先載入成功、預先載入失敗或廣告快取空間不足時收到通知。

以下範例說明如何註冊預先載入廣告事件：

Kotlin

private fun startPreloadingWithCallback(adUnitId: String) {
  val preloadCallback =
    object : PreloadCallback {
      override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
        Log.d(TAG, "App open preload ad $preloadId failed to load with error: ${adError.message}")
      }

      override fun onAdsExhausted(preloadId: String) {
        Log.i(TAG, "App open preload ad $preloadId is not available")
      }

      override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
        Log.i(TAG, "App open preload ad $preloadId is available")
      }
    }
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  AppOpenAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
}

Java

private void startPreloadingWithCallback(String adUnitId) {
  PreloadCallback preloadCallback =
      new PreloadCallback() {
        @Override
        public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
          Log.d(
              TAG,
              String.format(
                  "App open preload ad %s failed to load with error: %s",
                  preloadId, adError.getMessage()));
        }

        @Override
        public void onAdsExhausted(@NonNull String preloadId) {
          Log.i(TAG, String.format("App open preload ad %s is not available", preloadId));
        }

        @Override
        public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
          Log.i(TAG, String.format("App open preload ad %s is available", preloadId));
        }
      };
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  AppOpenAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
}

如果廣告無法載入，GMA Next-Gen SDK 會自動預先載入廣告，並重試預先載入設定的失敗要求。

選用：檢查廣告是否可用

如要瞭解廣告是否可用，請檢查廣告可用性。以下範例說明如何檢查預先載入的廣告是否可用：

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return AppOpenAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return AppOpenAdPreloader.isAdAvailable(adUnitId);
}

選用：設定緩衝區空間

緩衝區空間會控管記憶體中預先載入的廣告數量。根據預設，Google 會調整緩衝區大小，以平衡記憶體用量和廣告放送延遲。您可以設定自訂緩衝區空間，增加記憶體中保留的廣告數量。建議緩衝區大小最多為四。

以下範例說明如何將緩衝區空間設為四個預先載入的廣告：

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Four is the recommended maximum buffer size.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Four is the recommended maximum buffer size.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
  AppOpenAdPreloader.start(adUnitId, preloadConfig);
}

預先載入快取限制

GMA Next-Gen SDK 會對所有廣告單元和預先載入 ID 的預先載入廣告總數，強制執行應用程式範圍的限制：

  • 預設限制：Google 最多會在記憶體中保留 6 個預先載入的廣告。這項限制適用於所有格式和預先載入 ID。
  • 建議每個預先載入 ID 的緩衝區空間為 2 或 3。

選用：停止預先載入廣告

如果不需要在工作階段中再次顯示特定預先載入 ID 的廣告，可以停止預先載入廣告。如要停止載入特定預先載入 ID 的廣告，請使用預先載入 ID 呼叫 destroy() 方法。呼叫 destroy() 方法會從快取中移除與預先載入 ID 相關聯的所有預先載入廣告。

以下範例說明如何停止預先載入廣告：

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  AppOpenAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  AppOpenAdPreloader.destroy(adUnitId);
}

選用：閱讀回覆資訊

讀取下一個預先載入的廣告回應資訊，但不會從快取中移除廣告。

以下範例說明如何讀取下一個預先載入的廣告回應資訊：

Kotlin

val responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());

冷啟動和載入畫面

冷啟動是指應用程式從頭開始啟動，例如使用者初次開啟應用程式，或是應用程式在記憶體終止後啟動。在冷啟動期間，您沒有預先載入的應用程式開啟頁面廣告，因此無法立即顯示。

由於廣告請求延遲，使用者可能會在應用程式開啟頁面廣告顯示前與應用程式互動。為避免使用者體驗不佳，請務必在應用程式素材資源載入時，從載入畫面顯示冷啟動的應用程式開啟頁面廣告。如果素材資源載入完成，且使用者在廣告載入前已瀏覽主要內容，請勿顯示廣告。

在背景執行緒中載入應用程式素材資源，以便在廣告顯示期間持續載入。

最佳做法

請遵循下列應用程式開啟頁面廣告最佳做法：

  • 等使用者開啟應用程式數次後，再放送第一則應用程式開啟頁面廣告。
  • 只在使用者等待應用程式載入時顯示應用程式開啟頁面廣告。
  • 如果載入畫面在廣告顯示期間完成載入，請在廣告關閉回呼方法中關閉載入畫面。