原生廣告

選取平台： Android iOS Flutter Unity

原生廣告是透過平台原生 UI 元件向使用者顯示的廣告素材資源。系統會使用您已用於建構版面配置的相同檢視畫面類型顯示這些廣告，並可設定格式來配合應用程式的視覺設計。

載入原生廣告時，應用程式會收到含有廣告素材的廣告物件，並由應用程式 (而非 Google Mobile Ads SDK) 負責顯示廣告素材。

廣義來說，成功導入原生廣告的流程分為兩個部分： 使用 SDK 載入廣告，然後在應用程式中顯示廣告內容。

本頁面說明如何使用 SDK 載入原生廣告。提示：如要進一步瞭解原生廣告，請參閱原生廣告教戰手冊。

您也可以參考一些客戶成功案例： 案例研究 1、 案例研究 2。

必要條件

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

建構及測試應用程式時，請務必使用測試廣告，而非實際的正式廣告。

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

ca-app-pub-3940256099942544/2247696110

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

如要進一步瞭解 Google Mobile Ads 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.
        }
    })
    .withNativeAdOptions(NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build()

forNativeAd() 方法負責準備 AdLoader，以 NativeAd 格式呈現。廣告載入成功後，系統會呼叫接聽程式物件的 onNativeAdLoaded() 方法。

使用 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 應嘗試為要求載入的廣告數量。這個數字上限為五，且 SDK 不保證會傳回所要求的確切廣告數量。

系統傳回的 Google 廣告都會彼此不同，但無法保證預訂廣告空間或第三方買家的廣告是獨一無二。

如果您使用中介服務，請勿使用 loadAds() 方法，因為目前針對已設定中介服務的廣告單元 ID，系統無法處理多個原生廣告的要求。

回呼

呼叫 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()

最佳做法

載入廣告時，請遵守下列規則。

  • 在清單中使用原生廣告的應用程式，應預先快取廣告清單。

  • 預先快取廣告時，請清除快取，並在一小時後重新載入。

  • 在第一個要求載入完成前，請勿在 AdLoader 上呼叫 loadAd() 或 loadAds()。

  • 限制原生廣告快取，只快取必要的項目。舉例來說，預先快取時，只快取螢幕上立即顯示的廣告。原生廣告的記憶體用量很大，如果快取原生廣告而不加以銷毀，就會導致記憶體用量過高。

  • 不再使用原生廣告時，請將其銷毀。

影片廣告的硬體加速功能

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

硬體加速功能預設為啟用，但部分應用程式可能會選擇停用。如果您的應用程式符合上述情況，建議為使用廣告的 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>

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

顯示廣告

載入廣告後，您只需要向使用者顯示廣告即可。 如要瞭解如何操作，請參閱原生進階指南。