原生廣告

選取平台： Android iOS Flutter Unity

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

原生廣告載入時，應用程式會收到包含資產的廣告物件，然後由應用程式 (而非 Google Mobile Ads SDK) 負責顯示這些資產。

大致來說，成功導入原生廣告需要兩個步驟：使用 SDK 載入廣告，然後在應用程式中顯示廣告內容。

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

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

必要條件

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

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

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

ca-app-pub-3940256099942544/2247696110

這項廣告單元已特別設定為針對每項要求傳回測試廣告，您可以在編寫程式碼、測試及偵錯時，在自己的應用程式中使用這項廣告單元。只要確定在發布應用程式前已將其替換為自己的廣告單元 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() 方法負責為 NativeAd 格式準備 AdLoader。廣告載入成功後，系統會呼叫事件監聽器物件的 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() 方法。這麼做可釋放已使用的資源，並防止記憶體流失。

請確認所有 NativeAd 參照項目都在活動的 onDestroy() 方法中刪除。

在 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>

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

顯示廣告

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