原生廣告是一種廣告素材資源,可透過平台內建的使用者介面元件向使用者顯示。這種類型會顯示與您已製作版面配置同類型的資料檢視,而且可採用符合使用者所見使用者體驗的視覺設計。在程式碼條款中,這表示當您載入原生廣告時,應用程式會收到內含其素材資源的 NativeAd
物件,而應用程式 (而非 Google Mobile Ads SDK) 負責顯示。
大致來說,成功導入原生廣告有兩個部分: 透過 SDK 載入廣告,並在您的應用程式中顯示廣告內容。 本頁會說明使用 SDK 載入 原生廣告的方式。
必要條件
- 請自行或 Firebase 的一部分匯入 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 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
接收回呼:
Java
.withAdListener(new AdListener() { // AdListener callbacks can be overridden here. })
Kotlin
.withAdListener(object : AdListener() { // AdListener callbacks can be overridden here. })
正在載入廣告
完成 AdLoader
的建構後,就可以用來載入廣告。
方法有兩種:loadAd()
和 loadAds()
。
loadAd()
方法會傳送單一廣告的請求:
loadAd()
- 這種方法會傳送單一廣告的要求。
Java
adLoader.loadAd(new AdRequest.Builder().build());
Kotlin
adLoader.loadAd(AdRequest.Builder().build())
loadAds()
方法會傳送多個廣告的要求 (最多 5 個):
Java
adLoader.loadAds(new AdRequest.Builder().build(), 3);
Kotlin
adLoader.loadAds(AdRequest.Builder().build(), 3)
這兩種方法都會使用 AdRequest
物件做為第一個參數。這與橫幅廣告和插頁式廣告所使用的相同 AdRequest
類別相同,您可以使用 AdRequest
類別的方法新增指定目標資訊,就像其他廣告格式一樣。
loadAds()
會使用額外的參數:SDK 嘗試針對請求載入的廣告數量。這個數字的長度上限為 5 個,且不保證 SDK 會傳回精確請求的廣告數量。如果呼叫 loadAds()
傳回多個廣告,這些廣告會有所不同。
呼叫 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 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);
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 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();
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 取代,再發布應用程式。
如要進一步瞭解 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
:
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 格式做好準備
上述第一個方法負責為原生廣告格式準備 AdLoader
。
forNativeAd()
- 呼叫這個方法可設定
AdLoader
來請求原生廣告。 廣告成功載入後,系統會呼叫事件監聽器物件的onNativeAdLoaded()
方法。
當 AdLoader
發出廣告請求時,Google 就會選取並傳回能提高發布商收益的廣告。
使用 AdListener 搭配 AdLoader
在建立上述 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()
方法會傳送單一廣告的請求:
loadAd()
- 這種方法會傳送單一廣告的要求。
Java
adLoader.loadAd(new AdRequest.Builder().build());
Kotlin
adLoader.loadAd(AdRequest.Builder().build())
loadAds()
方法會傳送多個廣告的要求 (最多 5 個):
Java
adLoader.loadAds(new AdRequest.Builder().build(), 3);
Kotlin
adLoader.loadAds(AdRequest.Builder().build(), 3)
這兩種方法都會使用 AdRequest
物件做為第一個參數。這與橫幅廣告和插頁式廣告所使用的相同 AdRequest
類別相同,您可以使用 AdRequest
類別的方法新增指定目標資訊,就像其他廣告格式一樣。
loadAds()
會使用額外的參數:SDK 嘗試針對請求載入的廣告數量。這個數字的長度上限為 5 個,且不保證 SDK 會傳回精確請求的廣告數量。如果呼叫 loadAds()
傳回多個廣告,這些廣告會有所不同。
呼叫 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 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);
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 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();
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 取代,再發布應用程式。
如要進一步瞭解 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
廣告載入完畢後,剩下的工作就是向使用者顯示廣告。 請參閱原生進階指南瞭解操作方式。