橫幅廣告

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

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

錨定自動調整橫幅廣告是固定顯示比例的廣告，而非一般固定大小的廣告。顯示比例與 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 版)