橫幅廣告

選取平台： Android iOS Unity Flutter

橫幅廣告 是佔用應用程式版面配置一部分的矩形廣告。錨定自動調整橫幅廣告是固定長寬比的廣告，使用者與應用程式互動時，這類廣告會固定顯示在畫面頂端或底部。

本指南說明如何在 Android 應用程式中載入錨定自動調整橫幅廣告。

必要條件

• 完整閱讀入門指南。
• 選用：如要查看橫幅廣告導入範例，請選取下列其中一個範例應用程式：
  • Java、Kotlin 或 Jetpack Compose 錨定自動調整橫幅廣告範例。
  • Java 或 Kotlin 進階功能示範。

請一律使用測試廣告進行測試

建構及測試應用程式時，請務必使用測試廣告，而非實際的正式廣告；違反者帳戶將可能遭到停權。

如要載入測試廣告，最簡單的方法是使用 Android 橫幅廣告專用的測試廣告單元 ID：

/21775744923/example/adaptive-banner

這個 ID 經過特別設定，可針對每項要求傳回測試廣告。您編寫程式碼、測試及偵錯時，可以在自己的應用程式中使用。但請務必留意，在發布應用程式前，將這個 ID 換成您自己的廣告單元 ID。

如要進一步瞭解 Google Mobile Ads SDK 測試廣告的運作方式，請參閱「啟用測試廣告」。

定義廣告檢視畫面

XML 版面配置

在版面配置 XML 檔案中新增檢視區塊，做為錨定式自適應橫幅廣告的容器：

<!-- Ad view container that fills the width of the screen and adjusts its
    height to the content of the ad. -->
<FrameLayout
        android:id="@+id/ad_view_container"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_centerInParent="true"
        android:layout_alignParentBottom="true" />

Jetpack Compose

1. 加入 JetpackComposeDemo/compose-util 模組。這個模組包含用於撰寫 AdView 物件和資產的輔助程式。

2. 從 compose-util 模組撰寫 BannerAd 類別：

// Place the ad view at the bottom of the screen.
Column(modifier = modifier.fillMaxSize(), verticalArrangement = Arrangement.Bottom) {
  Box(modifier = modifier.fillMaxWidth()) { AdManagerBannerAd(adView, modifier) }
}
AdManagerBannerScreen.kt

設定廣告大小

將 AdSize 設為錨定自動調整橫幅廣告類型，並指定寬度：

Java

// Request an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, 360));
MyActivity.java

Kotlin

// Request an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, 360))
MainActivity.kt

Jetpack Compose

// Set the adaptive banner ad size with a given width.
val adSize = AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(LocalContext.current, 360)
adView.setAdSize(adSize)
AdManagerBannerScreen.kt

在版面配置中新增 AdManagerAdView

使用廣告大小建立 AdManagerAdView，加入應用程式的版面配置：

Java

// Create a new ad view.
adView = new AdManagerAdView(this);
adView.setAdUnitId(AD_UNIT);
// Request an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, 360));

// Replace ad container with new ad view.
adContainerView.removeAllViews();
adContainerView.addView(adView);
MyActivity.java

Kotlin

// Create a new ad view.
val adView = AdManagerAdView(this)
adView.adUnitId = AD_UNIT_ID
// Request an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, 360))
this.adView = adView

// Replace ad container with new ad view.
binding.adViewContainer.removeAllViews()
binding.adViewContainer.addView(adView)
MyActivity.kt

Jetpack Compose

val adView = remember { AdManagerAdView(context) }

// Setup and load the adview.
// Set the unique ID for this specific ad unit.
adView.adUnitId = ADMANANGER_ADAPTIVE_BANNER_AD_UNIT_ID

// Set the adaptive banner ad size with a given width.
val adSize = AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(LocalContext.current, 360)
adView.setAdSize(adSize)

// Place the ad view at the bottom of the screen.
Column(modifier = modifier.fillMaxSize(), verticalArrangement = Arrangement.Bottom) {
  Box(modifier = modifier.fillMaxWidth()) { AdManagerBannerAd(adView, modifier) }
}
AdManagerBannerScreen.kt

載入廣告

AdManagerAdView就位後，下一步是載入廣告。這項作業是透過 AdManagerAdView 類別的 loadAd() 方法完成。這個函式會採用 AdManagerAdRequest 參數，其中包含單一廣告請求的指定目標資訊等執行階段資訊。

重點： 請在主要執行緒上，對 Google Mobile Ads SDK 進行所有呼叫。

以下範例說明如何載入廣告：

Java

AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder().build();
adView.loadAd(adRequest);
MyActivity.java

Kotlin

val adRequest = AdRequest.Builder().build()
adView.loadAd(adRequest)
MainActivity.kt

如果成功，您的應用程式就能顯示橫幅廣告。

提示： 您可以在打算顯示廣告前，使用廣告載入呼叫建立預先載入的廣告快取，以便在需要時以零延遲顯示廣告。 廣告會在 1 小時後過期，因此您應每小時清除快取並重新載入新廣告。

重新整理廣告

如果您已將廣告單元設為重新整理，廣告載入失敗時，就不必再次要求廣告。Google Mobile Ads SDK 會遵守您在 Ad Manager 使用者介面中指定的任何重新整理頻率。如果尚未啟用重新整理功能，請發出新的要求。如要進一步瞭解廣告單元重新整理，例如設定重新整理頻率，請參閱「行動應用程式內廣告的重新整理頻率」。

注意： 在 Ad Manager 使用者介面中設定重新整理頻率時，只有在橫幅顯示於畫面上時，系統才會自動重新整理。

發布廣告資源

使用完橫幅廣告後，您可以釋放橫幅廣告的資源。

如要釋放廣告的資源，請從檢視區塊階層中移除廣告，並捨棄所有參照：

Java

public void destroyBanner() {
  // Remove banner from view hierarchy.
  if (adView != null) {
    View parentView = (View) adView.getParent();
    if (parentView instanceof ViewGroup) {
      ((ViewGroup) parentView).removeView(adView);
    }

    // Destroy the banner ad resources.
    adView.destroy();
  }

  // Drop reference to the banner ad.
  adView = null;
}
BannerSnippets.java

Kotlin

fun destroyBanner() {
  // Remove banner from view hierarchy.
  val parentView = adView?.parent
  if (parentView is ViewGroup) {
    parentView.removeView(adView)
  }

  // Destroy the banner ad resources.
  adView?.destroy()

  // Drop reference to the banner ad.
  adView = null
}
BannerSnippets.kt

廣告事件

您可以監聽廣告生命週期中的多項事件，包括載入、廣告曝光和點擊，以及廣告開啟和關閉事件。建議您在載入橫幅前設定回呼。

Java

if (adView != null) {
  adView.setAdListener(
      new AdListener() {
        @Override
        public void onAdClicked() {
          // Code to be executed when the user clicks on an ad.
        }

        @Override
        public void onAdClosed() {
          // Code to be executed when the user is about to return
          // to the app after tapping on an ad.
        }

        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          // Code to be executed when an ad request fails.
        }

        @Override
        public void onAdImpression() {
          // Code to be executed when an impression is recorded
          // for an ad.
        }

        @Override
        public void onAdLoaded() {
          // Code to be executed when an ad finishes loading.
        }

        @Override
        public void onAdOpened() {
          // Code to be executed when an ad opens an overlay that
          // covers the screen.
        }
      });
}
BannerSnippets.java

Kotlin

adView?.adListener =
  object : AdListener() {
    override fun onAdClicked() {
      // Code to be executed when the user clicks on an ad.
    }

    override fun onAdClosed() {
      // Code to be executed when the user is about to return
      // to the app after tapping on an ad.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      // Code to be executed when an ad request fails.
    }

    override fun onAdImpression() {
      // Code to be executed when an impression is recorded
      // for an ad.
    }

    override fun onAdLoaded() {
      // Code to be executed when an ad finishes loading.
    }

    override fun onAdOpened() {
      // Code to be executed when an ad opens an overlay that
      // covers the screen.
    }
  }
BannerSnippets.kt

AdListener 中每個可覆寫的方法，都對應廣告生命週期中的一個事件。

可覆寫的方法
onAdClicked()	系統記錄廣告的點擊次數時，會呼叫 onAdClicked() 方法。
onAdClosed()	使用者查看廣告的到達網頁網址後返回應用程式時，系統會叫用 onAdClosed() 方法。應用程式可使用此方法繼續執行暫停的活動，或執行任何其他必要工作，讓應用程式準備好進行互動。
onAdFailedToLoad()	onAdFailedToLoad() 方法是唯一包含參數的方法。LoadAdError 類型的錯誤參數會說明發生了什麼錯誤。詳情請參閱「偵錯廣告載入錯誤」說明文件。
onAdImpression()	系統記錄廣告曝光時，會叫用 onAdImpression() 方法。
onAdLoaded()	廣告載入完成時，系統會執行 onAdLoaded() 方法。如果您想延後將 AdManagerAdView 新增至活動或片段，直到確定廣告會載入為止 (例如)，您可以在這裡執行這項操作。
onAdOpened()	當廣告開啟涵蓋整個畫面的重疊廣告時，系統會叫用 onAdOpened() 方法。

影片廣告的硬體加速功能

如要讓影片廣告順利顯示在橫幅廣告檢視畫面中，請務必啟用硬體加速。

硬體加速功能預設為啟用，但部分應用程式可能會選擇停用。如果您的應用程式符合上述情況，建議為使用廣告的 Activity 類別啟用硬體加速功能。

啟用硬體加速功能

如果全域開啟硬體加速時，您的應用程式無法正常運作，也可以個別控制各項活動。如要啟用或停用硬體加速，可以針對 AndroidManifest.xml 中的 <application> 和 <activity> 元素使用 android:hardwareAccelerated 屬性。以下範例為整個應用程式啟用硬體加速，但針對一項活動停用此功能：

<application android:hardwareAccelerated="true">
    <!-- For activities that use ads, hardwareAcceleration should be true. -->
    <activity android:hardwareAccelerated="true" />
    <!-- For activities that don't use ads, hardwareAcceleration can be false. -->
    <activity android:hardwareAccelerated="false" />
</application>

如要進一步瞭解如何控制硬體加速的選項，請參閱硬體加速指南。請注意，如果活動已停用，就無法為個別廣告檢視畫面啟用硬體加速，因此活動本身必須啟用硬體加速。

以人工方式計算曝光次數

手動計算曝光功能只適用於直接銷售和內部廣告活動，且廣告素材必須直接在 Ad Manager 投放。請勿用於候補廣告或第三方聯播網廣告。詳情請參閱「計算曝光和點擊次數」。

如果曝光次數的記錄時機有特殊條件，您可以手動將曝光呼叫傳送至 Ad Manager：

Java

if (adManagerAdView != null) {
  adManagerAdView.setManualImpressionsEnabled(true);
}
BannerSnippets.java

Kotlin

adManagerAdView?.setManualImpressionsEnabled(true)
BannerSnippets.kt

判斷廣告已成功傳回並顯示在畫面上後，即可手動記錄曝光：

Java

if (adManagerAdView != null) {
  adManagerAdView.recordManualImpression();
}
BannerSnippets.java

Kotlin

adManagerAdView?.recordManualImpression()
BannerSnippets.kt

重點： 系統通常會在叫用 onAdLoaded() 回呼時觸發曝光。只有在想在不同時間點記錄曝光次數時，才應考慮使用這項功能。

應用程式事件

您可以運用應用程式事件，建立可將訊息傳送至應用程式程式碼的廣告。應用程式隨後就能根據這些訊息採取行動。

您可以使用 AppEventListener 監聽 Ad Manager 專屬的應用程式事件。這些事件可能在廣告生命週期的任何時間發生，甚至在呼叫 onAdLoaded() 之前。

在 AdManagerAdView 上設定 AppEventListener：

Java

if (adManagerAdView != null) {
  adManagerAdView.setAppEventListener(this);
}
BannerSnippets.java

Kotlin

adManagerAdView?.appEventListener = this
BannerSnippets.kt

以下範例說明如何根據名為「color」的應用程式事件，變更應用程式的背景顏色：

Java

@Override
public void onAppEvent(@NonNull String name, @NonNull String info) {
  if (name.equals("color")) {
    switch (info) {
      case "green":
        // Set background color to green.
        break;
      case "blue":
        // Set background color to blue.
        break;
      default:
        // Set background color to black.
        break;
    }
  }
}
BannerSnippets.java

Kotlin

override fun onAppEvent(name: String, info: String) {
  if (name == "color") {
    when (info) {
      "green" -> {
        // Set background color to green.
      }
      "blue" -> {
        // Set background color to blue.
      }
      else -> {
        // Set background color to black.
      }
    }
  }
}
BannerSnippets.kt

以下是相應的廣告素材，會將顏色應用程式事件訊息傳送至接聽程式：

<html>
<head>
  <script src="//www.gstatic.com/afma/api/v1/google_mobile_app_ads.js"></script>
  <script>
    document.addEventListener("DOMContentLoaded", function() {
      // Send a color=green event when ad loads.
      admob.events.dispatchAppEvent("color", "green");

      document.getElementById("ad").addEventListener("click", function() {
        // Send a color=blue event when ad is clicked.
        admob.events.dispatchAppEvent("color", "blue");
      });
    });
  </script>
  <style>
    #ad {
      width: 320px;
      height: 50px;
      top: 0px;
      left: 0px;
      font-size: 24pt;
      font-weight: bold;
      position: absolute;
      background: black;
      color: white;
      text-align: center;
    }
  </style>
</head>
<body>
  <div id="ad">Carpe diem!</div>
</body>
</html>

如要在 API 示範應用程式中導入應用程式事件，請參閱 Ad Manager 應用程式事件範例。

Java Kotlin JetpackCompose

後續步驟

可收合橫幅廣告

可收合橫幅廣告一開始會以較大的重疊廣告顯示，並提供按鈕，可將廣告收合為較小尺寸。建議您使用這項功能，進一步提升成效。詳情請參閱可收合橫幅廣告。

自動調整內嵌橫幅廣告

與錨定自動調整橫幅廣告相比，自動調整內嵌橫幅廣告更大、更高。自動調整橫幅廣告的高度可變，甚至可與裝置螢幕一樣高。如果應用程式在可捲動內容中放送橫幅廣告，建議使用內嵌自動調整橫幅廣告，而非錨定自動調整橫幅廣告。詳情請參閱內嵌自適應橫幅。

探索其他主題

• 使用者隱私權
• 最佳化 SDK 初始化和廣告載入程序 (Beta 版)