原生廣告

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

原生廣告是由平台原生的使用者介面元件向使用者顯示。系統會透過您正在建構版面配置的相同檢視畫面類型來顯示這些格式,並以符合其所在使用者體驗的視覺設計。在程式碼術語中,這表示當原生廣告載入時,應用程式會收到包含其素材資源的 NativeAd 物件,而應用程式 (而非 Google Mobile Ads SDK) 會負責顯示它們。

普遍來說,要成功導入原生廣告有兩部分: 使用 SDK 載入廣告,然後在應用程式中顯示廣告素材。

本頁涉及使用 SDK 載入原生廣告

必要條件

實作

原生廣告會載入 AdLoader 類別,並擁有專屬的 Builder 類別,可在建立期間進行自訂。建構事件時,只要在 AdLoader 中加入事件監聽器,應用程式便可指定準備好接收的原生廣告類型。接著,AdLoader 只會要求這些類型。

建立 AdLoader

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

Java

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

Kotlin

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 格式做好準備

上述第一個方法負責為 NativeAd 格式準備 AdLoader

forNativeAd()
呼叫此方法會設定 AdLoader 以要求原生廣告。系統成功載入廣告後,就會呼叫事件監聽器物件的 onNativeAdLoaded() 方法。

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

使用 AdLoader 設定 AdListener (選用)

在上述 AdLoader 建立期間,withAdListener 函式會設定 AdListener。此方法使用 AdListener 做為唯一的參數,並在廣告生命週期事件發生時,從 AdLoader 接收回呼:

Java

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

Kotlin

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

載入廣告

建立 AdLoader 後,即可開始使用這項資訊載入廣告。方法有兩種:loadAd()loadAds()

loadAd()
這個方法會傳送單一廣告的要求。 :

Java

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

Kotlin

adLoader.loadAd(AdRequest.Builder().build())
loadAds()
這個方法會傳送多個廣告 (最多五個) 的要求:

Java

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

Kotlin

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

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

loadAds() 會使用其他參數:SDK 應針對要求載入的廣告數量。此上限為 5 個,並不保證 SDK 會傳回確切的廣告數量。

系統傳回的 Google 廣告彼此完全不同。預訂廣告空間或第三方買方的廣告 (包括為刊登序列中介服務或出價設定的買方) 則不保證是唯一的。

回呼

呼叫 loadAd() 後,系統會為先前定義的監聽器方法發出單一回呼,以傳遞原生廣告物件或回報錯誤。

呼叫 loadAds() 後,系統將發出多次這類回呼 (至少一個,且不超過要求的廣告數量)。要求多個廣告的應用程式應在回呼實作中呼叫 AdLoader.isLoading(),以判斷載入程序是否已完成。

以下範例說明如何檢查 onNativeAdLoaded() 回呼中的 isLoading()

Java

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd nativeAd) {
        ...
        // 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);

Kotlin

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() 方法。以便釋出使用率資源,並避免記憶體流失。

確認活動的 onDestroy() 方法會刪除所有 NativeAd 參照。

onNativeAdLoaded 回呼中,請務必刪除任何即將停用的現有原生廣告。

另一項關鍵檢查是如果活動已遭刪除,然後對傳回的廣告呼叫 destroy() 並立即傳回:

Java

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd 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;
        }
        ...
    }
}).build();

Kotlin

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 換成自己的廣告單元 ID。

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

請求廣告的時機

顯示原生廣告的應用程式可選擇是否要在實際顯示前預先請求。在多數情況下,這是建議的建議做法。舉例來說,應用程式中顯示含有原生廣告的項目清單 (例如混合原生廣告) 時,可以載入整個清單的原生廣告,但只會在使用者捲動檢視畫面後才顯示部分廣告,而部分廣告素材完全無法顯示。

影片廣告的硬體加速

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

硬體加速功能預設為啟用,但部分應用程式可能會選擇停用。針對應用程式,建議您為使用廣告的活動類別啟用硬體加速功能。

啟用硬體加速功能

如果應用程式在全域開啟硬體加速後無法正常運作,您也可以只為個別活動控制應用程式。如要啟用或停用硬體加速功能,您可以針對 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>

如要進一步瞭解控制硬體加速選項,請參閱 HW 加速指南。請注意,如果「活動」已停用,就無法針對硬體加速啟用個別廣告瀏覽作業,因此「活動」本身必須啟用硬體加速功能。

顯示 NativeAd

載入廣告後,剩下的就要向使用者顯示。 請前往原生進階指南查看操作說明。

,

原生廣告是由平台原生的使用者介面元件向使用者顯示。系統會透過您正在建構版面配置的相同檢視畫面類型來顯示這些格式,並以符合其所在使用者體驗的視覺設計。在程式碼術語中,這表示當原生廣告載入時,應用程式會收到包含其素材資源的 NativeAd 物件,而應用程式 (而非 Google Mobile Ads SDK) 會負責顯示它們。

普遍來說,要成功導入原生廣告有兩部分: 使用 SDK 載入廣告,然後在應用程式中顯示廣告素材。

本頁涉及使用 SDK 載入原生廣告

必要條件

實作

原生廣告會載入 AdLoader 類別,並擁有專屬的 Builder 類別,可在建立期間進行自訂。建構事件時,只要在 AdLoader 中加入事件監聽器,應用程式便可指定準備好接收的原生廣告類型。接著,AdLoader 只會要求這些類型。

建立 AdLoader

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

Java

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

Kotlin

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 格式做好準備

上述第一個方法負責為 NativeAd 格式準備 AdLoader

forNativeAd()
呼叫此方法會設定 AdLoader 以要求原生廣告。系統成功載入廣告後,就會呼叫事件監聽器物件的 onNativeAdLoaded() 方法。

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

使用 AdLoader 設定 AdListener (選用)

在上述 AdLoader 建立期間,withAdListener 函式會設定 AdListener。此方法使用 AdListener 做為唯一的參數,並在廣告生命週期事件發生時,從 AdLoader 接收回呼:

Java

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

Kotlin

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

載入廣告

建立 AdLoader 後,即可開始使用這項資訊載入廣告。方法有兩種:loadAd()loadAds()

loadAd()
這個方法會傳送單一廣告的要求。 :

Java

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

Kotlin

adLoader.loadAd(AdRequest.Builder().build())
loadAds()
這個方法會傳送多個廣告 (最多五個) 的要求:

Java

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

Kotlin

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

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

loadAds() 會使用其他參數:SDK 應針對要求載入的廣告數量。此上限為 5 個,並不保證 SDK 會傳回確切的廣告數量。

系統傳回的 Google 廣告彼此完全不同。預訂廣告空間或第三方買方的廣告 (包括為刊登序列中介服務或出價設定的買方) 則不保證是唯一的。

回呼

呼叫 loadAd() 後,系統會為先前定義的監聽器方法發出單一回呼,以傳遞原生廣告物件或回報錯誤。

呼叫 loadAds() 後,系統將發出多次這類回呼 (至少一個,且不超過要求的廣告數量)。要求多個廣告的應用程式應在回呼實作中呼叫 AdLoader.isLoading(),以判斷載入程序是否已完成。

以下範例說明如何檢查 onNativeAdLoaded() 回呼中的 isLoading()

Java

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd nativeAd) {
        ...
        // 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);

Kotlin

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() 方法。以便釋出使用率資源,並避免記憶體流失。

確認活動的 onDestroy() 方法會刪除所有 NativeAd 參照。

onNativeAdLoaded 回呼中,請務必刪除任何即將停用的現有原生廣告。

另一項關鍵檢查是如果活動已遭刪除,然後對傳回的廣告呼叫 destroy() 並立即傳回:

Java

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd 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;
        }
        ...
    }
}).build();

Kotlin

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 換成自己的廣告單元 ID。

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

請求廣告的時機

顯示原生廣告的應用程式可選擇是否要在實際顯示前預先請求。在多數情況下,這是建議的建議做法。舉例來說,應用程式中顯示含有原生廣告的項目清單 (例如混合原生廣告) 時,可以載入整個清單的原生廣告,但只會在使用者捲動檢視畫面後才顯示部分廣告,而部分廣告素材完全無法顯示。

影片廣告的硬體加速

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

硬體加速功能預設為啟用,但部分應用程式可能會選擇停用。針對應用程式,建議您為使用廣告的活動類別啟用硬體加速功能。

啟用硬體加速功能

如果應用程式在全域開啟硬體加速後無法正常運作,您也可以只為個別活動控制應用程式。如要啟用或停用硬體加速功能,您可以針對 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>

如要進一步瞭解控制硬體加速選項,請參閱 HW 加速指南。請注意,如果「活動」已停用,就無法針對硬體加速啟用個別廣告瀏覽作業,因此「活動」本身必須啟用硬體加速功能。

顯示 NativeAd

載入廣告後,剩下的就要向使用者顯示。 請前往原生進階指南查看操作說明。