原生廣告

原生廣告是一種廣告素材資源，可透過平台內建的使用者介面元件向使用者顯示。這種類型會顯示與您已製作版面配置同類型的資料檢視，而且可採用符合使用者所見使用者體驗的視覺設計。在程式碼條款中，這表示當您載入原生廣告時，應用程式會收到內含其素材資源的 NativeAd 物件，而應用程式 (而非 Google Mobile Ads SDK) 負責顯示。

大致來說，成功導入原生廣告有兩個部分： 透過 SDK 載入廣告，並在您的應用程式中顯示廣告內容。 本頁會說明使用 SDK 載入 原生廣告的方式。

必要條件

• 請自行或 Firebase 的一部分匯入 Google Mobile Ads SDK。

載入廣告

原生廣告會透過 AdLoader 類別載入，這個類別有專屬的 Builder 類別，可在建立時自訂。建立事件監聽器時，如果在 AdLoader 中加入事件監聽器，應用程式就能指定可接收的原生廣告類型。接著 AdLoader 就只會請求這些類型。

建立 AdLoader

以下程式碼示範如何建構可載入原生廣告的 AdLoader：

AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
        @Override
        public void onNativeAdLoaded(NativeAd NativeAd) {
            // Show the ad.
        }
    })
    .withAdListener(new AdListener() {
        @Override
        public void onAdFailedToLoad(LoadAdError adError) {
            // Handle the failure by logging, altering the UI, and so on.
        }
    })
    .withNativeAdOptions(new NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build();

val adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd { ad : NativeAd ->
        // Show the ad.
    }
    .withAdListener(object : AdListener() {
        override fun onAdFailedToLoad(adError: LoadAdError) {
            // Handle the failure by logging, altering the UI, and so on.
        }
    })
    .withNativeAdOptions(NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build()

為 NativeAd 格式做好準備

上述第一個方法負責為原生廣告格式準備 AdLoader。

forNativeAd()

呼叫這個方法可設定 AdLoader 來請求原生廣告。 廣告成功載入後，系統會呼叫事件監聽器物件的 onNativeAdLoaded() 方法。

當 AdLoader 發出廣告請求時，Google 就會選取並傳回能提高發布商收益的廣告。

使用 AdListener 搭配 AdLoader

在建立上述 AdLoader 時，withAdListener 函式會設定 AdListener。

此為選擇性步驟。此方法會使用 AdListener 做為唯一的參數，此參數會在廣告生命週期事件發生時，從 AdLoader 接收回呼：

.withAdListener(new AdListener() {
    // AdListener callbacks can be overridden here.
})

.withAdListener(object : AdListener() {
    // AdListener callbacks can be overridden here.
})

正在載入廣告

完成 AdLoader 的建構後，就可以用來載入廣告。 方法有兩種：loadAd() 和 loadAds()。

loadAd() 方法會傳送單一廣告的請求：

loadAd()

這種方法會傳送單一廣告的要求。

adLoader.loadAd(new AdRequest.Builder().build());

adLoader.loadAd(AdRequest.Builder().build())

loadAds() 方法會傳送多個廣告的要求 (最多 5 個)：

adLoader.loadAds(new AdRequest.Builder().build(), 3);

adLoader.loadAds(AdRequest.Builder().build(), 3)

這兩種方法都會使用 AdRequest 物件做為第一個參數。這與橫幅廣告和插頁式廣告所使用的相同 AdRequest 類別相同，您可以使用 AdRequest 類別的方法新增指定目標資訊，就像其他廣告格式一樣。

loadAds() 會使用額外的參數：SDK 嘗試針對請求載入的廣告數量。這個數字的長度上限為 5 個，且不保證 SDK 會傳回精確請求的廣告數量。如果呼叫 loadAds() 傳回多個廣告，這些廣告會有所不同。

呼叫 loadAd() 之後，系統會對上述定義的接聽程式方法發出單一回呼，以放送原生廣告物件或回報錯誤。

呼叫 loadAds() 之後，系統會發出多種回呼 (至少一個，且不得超過請求的廣告數量)。要求多個廣告的應用程式必須在回呼實作中呼叫 AdLoader.isLoading()，以確定載入程序是否已完成。

以下示範如何在 onNativeAdLoaded() 回呼中檢查 isLoading()：

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd ad) {
        ...
        // some code that displays the ad.
        ...
        if (adLoader.isLoading()) {
            // The AdLoader is still loading ads.
            // Expect more adLoaded or onAdFailedToLoad callbacks.
        } else {
            // The AdLoader has finished loading ads.
        }
    }
}).build();
adLoader.loadAds(new AdRequest.Builder().build(), 3);

lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd {
        ...
        // some code that displays the ad.
        ...
        if (adLoader.isLoading) {
            // The AdLoader is still loading ads.
            // Expect more adLoaded or onAdFailedToLoad callbacks.
        } else {
            // The AdLoader has finished loading ads.
        }
    }.build()
adLoader.loadAds(AdRequest.Builder().build(), 3)

清除所用資源

請務必在載入的原生廣告時使用 destroy() 方法。這樣做可以釋出使用率資源，並避免記憶體流失。

確實將 NativeAd 參照全數刪除於活動中的 onDestroy() 方法。

在 onNativeAdLoaded 回呼中，請務必銷毀所有即將淘汰的原生廣告。

另一項重要檢查是，如果活動已遭刪除，如果是的話，請針對傳回的廣告呼叫 destroy() 並立即傳回：

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd ad) {
        // If this callback occurs after the activity is destroyed, you
        // must call destroy and return or you may get a memory leak.
        // Note `isDestroyed()` is a method on Activity.
        if (isDestroyed()) {
            ad.destroy();
            return;
        }
        ...
    }
}).build();

lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd { nativeAd ->
        // If this callback occurs after the activity is destroyed, you
        // must call destroy and return or you may get a memory leak.
        // Note `isDestroyed` is a method on Activity.
        if (isDestroyed) {
            nativeAd.destroy()
            return@forNativeAd
        }
        ...
    }.build()

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

建構及測試應用程式時，請務必使用測試廣告，而非實際上線廣告。否則我們可能會將您的帳戶停權。

如要載入測試廣告，最簡單的方法就是使用 Android 原生進階專屬測試廣告單元 ID：

ca-app-pub-3940256099942544/2247696110

這種代碼經過特別設定，可針對每個請求傳回測試廣告，您可以在編寫、測試及偵錯時，在自己的應用程式中免費使用此功能。只要先以自己的廣告單元 ID 取代，再發布應用程式。

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

請求廣告的時機

顯示原生廣告的應用程式可以免費請求，但廣告會在實際顯示前就發出請求。在多數情況下，建議您這麼做。 例如，應用程式顯示已混合原生廣告的項目清單，其中可以載入整個清單的原生廣告，因為這類動作只會在使用者捲動檢視畫面後才顯示，有些則完全無法顯示。

影片廣告的硬體加速

為了讓影片廣告能在原生廣告視圖中順利顯示，您必須啟用硬體加速功能。

硬體加速功能預設為啟用，但部分應用程式可能會選擇停用。如果這適用於您的應用程式，建議您針對採用廣告的「活動」類別啟用硬體加速功能。

啟用硬體加速功能

如果您的應用程式在全域開啟硬體加速的情況下無法正常運作，你也可以針對個別活動控管應用程式。如要啟用或停用硬體加速功能，您可以使用 中 <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>

如要進一步瞭解控制硬體加速的方式，請參閱硬體加速指南。請注意，如果「活動」功能已停用，個別硬體檢視就無法為硬體加速啟用，因此「活動」本身必須啟用硬體加速功能。

顯示 NativeAd

廣告載入完畢後，剩下的工作就是向使用者顯示廣告。 請參閱原生進階指南瞭解操作方式。

原生廣告是一種廣告素材資源，可透過平台內建的使用者介面元件向使用者顯示。這種類型會顯示與您已製作版面配置同類型的資料檢視，而且可採用符合使用者所見使用者體驗的視覺設計。在程式碼條款中，這表示當您載入原生廣告時，應用程式會收到內含其素材資源的 NativeAd 物件，而應用程式 (而非 Google Mobile Ads SDK) 負責顯示。

大致來說，成功導入原生廣告有兩個部分： 透過 SDK 載入廣告，並在您的應用程式中顯示廣告內容。 本頁會說明使用 SDK 載入 原生廣告的方式。

必要條件

• 請自行或 Firebase 的一部分匯入 Google Mobile Ads SDK。

載入廣告

原生廣告會透過 AdLoader 類別載入，這個類別有專屬的 Builder 類別，可在建立時自訂。建立事件監聽器時，如果在 AdLoader 中加入事件監聽器，應用程式就能指定可接收的原生廣告類型。接著 AdLoader 就只會請求這些類型。

建立 AdLoader

以下程式碼示範如何建構可載入原生廣告的 AdLoader：

AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
        @Override
        public void onNativeAdLoaded(NativeAd NativeAd) {
            // Show the ad.
        }
    })
    .withAdListener(new AdListener() {
        @Override
        public void onAdFailedToLoad(LoadAdError adError) {
            // Handle the failure by logging, altering the UI, and so on.
        }
    })
    .withNativeAdOptions(new NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build();

val adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd { ad : NativeAd ->
        // Show the ad.
    }
    .withAdListener(object : AdListener() {
        override fun onAdFailedToLoad(adError: LoadAdError) {
            // Handle the failure by logging, altering the UI, and so on.
        }
    })
    .withNativeAdOptions(NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build()

為 NativeAd 格式做好準備

上述第一個方法負責為原生廣告格式準備 AdLoader。

forNativeAd()

呼叫這個方法可設定 AdLoader 來請求原生廣告。 廣告成功載入後，系統會呼叫事件監聽器物件的 onNativeAdLoaded() 方法。

當 AdLoader 發出廣告請求時，Google 就會選取並傳回能提高發布商收益的廣告。

使用 AdListener 搭配 AdLoader

在建立上述 AdLoader 時，withAdListener 函式會設定 AdListener。

此為選擇性步驟。此方法會使用 AdListener 做為唯一的參數，此參數會在廣告生命週期事件發生時，從 AdLoader 接收回呼：

.withAdListener(new AdListener() {
    // AdListener callbacks can be overridden here.
})

.withAdListener(object : AdListener() {
    // AdListener callbacks can be overridden here.
})

正在載入廣告

完成 AdLoader 的建構後，就可以用來載入廣告。 方法有兩種：loadAd() 和 loadAds()。

loadAd() 方法會傳送單一廣告的請求：

loadAd()

這種方法會傳送單一廣告的要求。

adLoader.loadAd(new AdRequest.Builder().build());

adLoader.loadAd(AdRequest.Builder().build())

loadAds() 方法會傳送多個廣告的要求 (最多 5 個)：

adLoader.loadAds(new AdRequest.Builder().build(), 3);

adLoader.loadAds(AdRequest.Builder().build(), 3)

這兩種方法都會使用 AdRequest 物件做為第一個參數。這與橫幅廣告和插頁式廣告所使用的相同 AdRequest 類別相同，您可以使用 AdRequest 類別的方法新增指定目標資訊，就像其他廣告格式一樣。

loadAds() 會使用額外的參數：SDK 嘗試針對請求載入的廣告數量。這個數字的長度上限為 5 個，且不保證 SDK 會傳回精確請求的廣告數量。如果呼叫 loadAds() 傳回多個廣告，這些廣告會有所不同。

呼叫 loadAd() 之後，系統會對上述定義的接聽程式方法發出單一回呼，以放送原生廣告物件或回報錯誤。

呼叫 loadAds() 之後，系統會發出多種回呼 (至少一個，且不得超過請求的廣告數量)。要求多個廣告的應用程式必須在回呼實作中呼叫 AdLoader.isLoading()，以確定載入程序是否已完成。

以下示範如何在 onNativeAdLoaded() 回呼中檢查 isLoading()：

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd ad) {
        ...
        // some code that displays the ad.
        ...
        if (adLoader.isLoading()) {
            // The AdLoader is still loading ads.
            // Expect more adLoaded or onAdFailedToLoad callbacks.
        } else {
            // The AdLoader has finished loading ads.
        }
    }
}).build();
adLoader.loadAds(new AdRequest.Builder().build(), 3);

lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd {
        ...
        // some code that displays the ad.
        ...
        if (adLoader.isLoading) {
            // The AdLoader is still loading ads.
            // Expect more adLoaded or onAdFailedToLoad callbacks.
        } else {
            // The AdLoader has finished loading ads.
        }
    }.build()
adLoader.loadAds(AdRequest.Builder().build(), 3)

清除所用資源

請務必在載入的原生廣告時使用 destroy() 方法。這樣做可以釋出使用率資源，並避免記憶體流失。

確實將 NativeAd 參照全數刪除於活動中的 onDestroy() 方法。

在 onNativeAdLoaded 回呼中，請務必銷毀所有即將淘汰的原生廣告。

另一項重要檢查是，如果活動已遭刪除，如果是的話，請針對傳回的廣告呼叫 destroy() 並立即傳回：

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd ad) {
        // If this callback occurs after the activity is destroyed, you
        // must call destroy and return or you may get a memory leak.
        // Note `isDestroyed()` is a method on Activity.
        if (isDestroyed()) {
            ad.destroy();
            return;
        }
        ...
    }
}).build();

lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd { nativeAd ->
        // If this callback occurs after the activity is destroyed, you
        // must call destroy and return or you may get a memory leak.
        // Note `isDestroyed` is a method on Activity.
        if (isDestroyed) {
            nativeAd.destroy()
            return@forNativeAd
        }
        ...
    }.build()

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

建構及測試應用程式時，請務必使用測試廣告，而非實際上線廣告。否則我們可能會將您的帳戶停權。

如要載入測試廣告，最簡單的方法就是使用 Android 原生進階專屬測試廣告單元 ID：

ca-app-pub-3940256099942544/2247696110

這種代碼經過特別設定，可針對每個請求傳回測試廣告，您可以在編寫、測試及偵錯時，在自己的應用程式中免費使用此功能。只要先以自己的廣告單元 ID 取代，再發布應用程式。

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

請求廣告的時機

顯示原生廣告的應用程式可以免費請求，但廣告會在實際顯示前就發出請求。在多數情況下，建議您這麼做。 例如，應用程式顯示已混合原生廣告的項目清單，其中可以載入整個清單的原生廣告，因為這類動作只會在使用者捲動檢視畫面後才顯示，有些則完全無法顯示。

影片廣告的硬體加速

為了讓影片廣告能在原生廣告視圖中順利顯示，您必須啟用硬體加速功能。

硬體加速功能預設為啟用，但部分應用程式可能會選擇停用。如果這適用於您的應用程式，建議您針對採用廣告的「活動」類別啟用硬體加速功能。

啟用硬體加速功能

如果您的應用程式在全域開啟硬體加速的情況下無法正常運作，你也可以針對個別活動控管應用程式。如要啟用或停用硬體加速功能，您可以使用 中 <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>

如要進一步瞭解控制硬體加速的方式，請參閱硬體加速指南。請注意，如果「活動」功能已停用，個別硬體檢視就無法為硬體加速啟用，因此「活動」本身必須啟用硬體加速功能。

顯示 NativeAd

廣告載入完畢後，剩下的工作就是向使用者顯示廣告。 請參閱原生進階指南瞭解操作方式。