橫幅廣告

橫幅廣告是佔用部分應用程式版面的矩形廣告。使用者與應用程式互動時，這類廣告會顯示在畫面頂端或底部，或是在使用者捲動畫面時且內嵌於內容中顯示。橫幅廣告經過一段時間就會自動重新整理。詳情請參閱「橫幅廣告總覽」。

本指南將說明如何開始使用錨定自動調整橫幅廣告，這種廣告會根據您指定的廣告寬度，針對每部裝置調整廣告大小，藉此提高成效。

錨定自動調整橫幅廣告是固定顯示比例的廣告，而非一般固定大小的廣告。顯示比例與 320x50 業界標準相似。指定可用的完整寬度後，系統就會傳回廣告，並以該寬度的最佳高度顯示。同一部裝置的不同要求，最佳高度不會有所變動，廣告重新整理時，周圍的檢視畫面也不需要移動。

必要條件

• 完成入門指南。

請務必使用測試廣告進行測試

建構及測試應用程式時，請務必使用測試廣告，而非實際的正式版廣告。否則可能導致帳戶停權。

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

/21775744923/example/adaptive-banner

這項廣告單元已特別設定為針對每項要求傳回測試廣告，您可以在編寫程式碼、測試及偵錯時，在自己的應用程式中使用這項廣告單元。只要確定在發布應用程式前已將其替換為您自己的廣告單元 ID 即可。

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

在版面配置中新增 AdManagerAdView

您可以透過決定廣告大小來建立橫幅廣告。操作步驟如下：

1. 建立全寬錨定自動調整廣告尺寸：

   Java

   // Get the ad size with screen width.
   public AdSize getAdSize() {
     DisplayMetrics displayMetrics = getResources().getDisplayMetrics();
     int adWidthPixels = displayMetrics.widthPixels;
   
     if (VERSION.SDK_INT >= VERSION_CODES.R) {
       WindowMetrics windowMetrics = this.getWindowManager().getCurrentWindowMetrics();
       adWidthPixels = windowMetrics.getBounds().width();
     }
   
     float density = displayMetrics.density;
     int adWidth = (int) (adWidthPixels / density);
     return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth);
   }
   MyActivity.java
   

   Kotlin

   // Get the ad size with screen width.
   private val adSize: AdSize
     get() {
       val displayMetrics = resources.displayMetrics
       val adWidthPixels =
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
           val windowMetrics: WindowMetrics = this.windowManager.currentWindowMetrics
           windowMetrics.bounds.width()
         } else {
           displayMetrics.widthPixels
         }
       val density = displayMetrics.density
       val adWidth = (adWidthPixels / density).toInt()
       return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth)
     }
   MyActivity.kt
   

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

   Java

   // Create a new ad view.
   adView = new AdManagerAdView(this);
   adView.setAdUnitId(AD_UNIT);
   adView.setAdSize(getAdSize());
   
   // 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
   adView.setAdSize(adSize)
   this.adView = adView
   
   // Replace ad container with new ad view.
   binding.adViewContainer.removeAllViews()
   binding.adViewContainer.addView(adView)
   MyActivity.kt
   

載入廣告

AdManagerAdView 就位後，下一步就是載入廣告。您可以使用 AdManagerAdView 類別中的 loadAd() 方法完成這項操作。這個方法會採用 AdManagerAdRequest 參數，該參數會儲存單一廣告請求的執行階段資訊，例如指定目標資訊。

重點： 請在主執行緒上對 Mobile Ads SDK 發出所有呼叫。

以下是載入廣告的範例：

Java

// Start loading the ad in the background.
AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder().build();
adView.loadAd(adRequest);
MyActivity.java

Kotlin

// Start loading the ad in the background.
val adRequest = AdManagerAdRequest.Builder().build()
adView.loadAd(adRequest)
MyActivity.kt

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

提示：您可以在要顯示預先載入的廣告之前，使用廣告載入呼叫建立快取，這樣一來，在需要時就能立即顯示廣告。由於廣告會在一小時後到期，因此您應每小時清除快取，並重新載入新的廣告。

重新整理廣告

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

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

廣告事件

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

Java

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(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.
    }
});

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.
    }
}

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。如要這樣做，請在載入廣告前為手動曝光啟用 AdManagerAdRequest：

Java

AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder()
    .setManualImpressionsEnabled(true)
    .build();

Kotlin

val adRequest = AdManagerAdRequest.Builder()
    .setManualImpressionsEnabled(true)
    .build()

確定廣告已成功傳回並顯示在畫面上後，您可以手動記錄曝光：

Java

{ ad_view }.recordManualImpression();

Kotlin

AdManagerAdView.recordManualImpression()

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

應用程式事件

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

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

Java

public interface AppEventListener {
  void onAppEvent(String name, String info);
}

Kotlin

interface AppEventListener {
    fun onAppEvent(name: String, info: String)
}

當廣告中發生應用程式事件時，系統會呼叫 void onAppEvent(String name, String info)。這個介面可由活動或任何其他物件實作：

Java

import com.google.android.gms.ads.admanager.*;

public class BannerExample extends Activity implements AppEventListener {
}

Kotlin

import com.google.android.gms.ads.admanager.*

class BannerExample : Activity(), AppEventListener {
}

然後傳遞至 AdManagerAdView：

Java

AdManagerAdView.setAppEventListener(this);

Kotlin

AdManagerAdView.appEventListener = this

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

Java

@Override
public void onAppEvent(String name, String info) {
  if ("color".equals(name)) {
    if ("green".equals(info)) {
      // Set background color to green.
    } else if ("blue".equals(info)) {
      // Set background color to blue.
    } else {
      // Set background color to black.
    }
  }
}

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.
            }
        }
    }
}

以下是傳送顏色應用程式事件訊息至事件監聽器的對應廣告素材：

<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

其他資源

GitHub 上的範例

• 錨定自動調整橫幅廣告範例：Java | Kotlin

• 進階功能示範：Java | Kotlin

後續步驟

可收合橫幅廣告

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

內嵌自動調整橫幅廣告

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

探索其他主題

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