Native ads are ad assets that are presented to users via UI components that are
native to the platform. They're shown using the same types of views with which
you're already building your layouts, and can be formatted to match the visual
design of the user experience in which they live. In coding terms, this means
that when a native ad loads, your app receives a
NativeAd
object that contains its assets, and the app (rather than the Google Mobile Ads
SDK) is then responsible for displaying them.
Broadly speaking, there are two parts to successfully implementing Native Ads: loading an ad via the SDK and displaying the ad content in your app. This page is concerned with using the SDK to load native ads.
Prerequisites
- Import the Google Mobile Ads SDK, either by itself or as part of Firebase.
Load an Ad
Native ads are loaded via the
AdLoader
class,
which has its own
Builder
class to customize it during creation. By adding listeners to the AdLoader
while building it, an app specifies which types of native ads it is ready to
receive. The AdLoader
then requests just those types.
Build an AdLoader
The following code demonstrates how to build an AdLoader
that can load
unified native ads:
Java
AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110") .forUnifiedNativeAd(new UnifiedNativeAd.OnUnifiedNativeAdLoadedListener() { @Override public void onUnifiedNativeAdLoaded(UnifiedNativeAd unifiedNativeAd) { // Show the ad. } }) .withAdListener(new AdListener() { @Override public void onAdFailedToLoad(int errorCode) { // 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") .forUnifiedNativeAd { ad : UnifiedNativeAd -> // Show the ad. } .withAdListener(object : AdListener() { override fun onAdFailedToLoad(errorCode: Int) { // 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()
Prepare for the UnifiedNativeAd format
The first method above is responsible for preparing the AdLoader
for the
UnifiedNativeAd format:
forUnifiedNativeAd()
- Calling this method configures the
AdLoader
to request unified native ads. When an ad has loaded successfully, the listener object'sonUnifiedNativeAdLoaded()
method is called.
When the AdLoader
makes an ad request, Google selects and returns the ad that
maximizes publisher yield.
Use AdListener with an AdLoader
During creation of the AdLoader
above, the
withAdListener
function sets an
AdListener
.
This is an optional step. The method takes an AdListener
as its lone
parameter, which receives callbacks from the AdLoader
when ad lifecycle
events take place:
Java
.withAdListener(new AdListener() { // AdListener callbacks like OnAdFailedToLoad, OnAdOpened, OnAdClicked and // so on, can be overridden here. })
Kotlin
.withAdListener(object : AdListener() { // AdListener callbacks like OnAdFailedToLoad, OnAdOpened, OnAdClicked and // so on, can be overridden here. })
There is one important difference between the way AdListener
objects work
with native ads and the way they work with banners and interstitials. Because
the AdLoader
has its own format-specific listeners
(i.e.,
UnifiedNativeAd.OnUnifiedNativeAdLoadedListener
)
to use when an ad has loaded, the
onAdLoaded()
method from AdListener
is not called when a native ad loads successfully.
Loading ads
Once you've finished building an AdLoader
, it's time to use it to load ads.
There are two methods available for this: loadAd()
and loadAds()
.
The loadAd()
method sends a request for a single ad:
loadAd()
- This method sends a request for a single ad.
Java
adLoader.loadAd(new AdRequest.Builder().build());
Kotlin
adLoader.loadAd(AdRequest.Builder().build())
The loadAds()
method sends a request for multiple ads (up to 5):
Java
adLoader.loadAds(new AdRequest.Builder().build(), 3);
Kotlin
adLoader.loadAds(AdRequest.Builder().build(), 3)
Both of these methods take a
AdRequest
object as their first parameter. This is the same
AdRequest
class used by banners and interstitials,
and you can use methods of the AdRequest
class to
add targeting information, just as
you would with other ad formats.
loadAds()
takes an additional parameter: the number of ads the SDK
should attempt to load for the request. This number is capped at a maximum of
five, and it's not guaranteed that the SDK will return the exact number of ads
requested. If multiple ads are returned by a call to loadAds()
, they will be
different from each other.
After a call to loadAd()
, a single callback will be made to the listener
methods defined above to deliver the native ad
object or report an error.
After a call to loadAds()
, multiple such callbacks will be made (at least one,
and no more than the number of ads requested). Apps requesting multiple ads
should call AdLoader.isLoading()
in their callback implementations to
determine whether the loading process has finished.
Here's an example showing how to check isLoading()
in the
onUnifiedNativeAdLoaded()
callback:
Java
final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110") .forUnifiedNativeAd(new UnifiedNativeAd.OnUnifiedNativeAdLoadedListener() { @Override public void onUnifiedNativeAdLoaded(UnifiedNativeAd 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") .forUnifiedNativeAd { ... // 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)
Always test with test ads
When building and testing your apps, make sure you use test ads rather than live, production ads. Failure to do so can lead to suspension of your account.
The easiest way to load test ads is to use our dedicated test ad unit ID for Native Advanced on Android:
ca-app-pub-3940256099942544/2247696110
It's been specially configured to return test ads for every request, and you're free to use it in your own apps while coding, testing, and debugging. Just make sure you replace it with your own ad unit ID before publishing your app.
For more information about how the Mobile Ads SDK's test ads work, see Test Ads.
When to request ads
Applications displaying native ads are free to request them in advance of when they'll actually be displayed. In many cases, this is the recommended practice. An app displaying a list of items with native ads mixed in, for example, can load native ads for the whole list, knowing that some will be shown only after the user scrolls the view and some may not be displayed at all.
Display a UnifiedNativeAd
Once you have loaded an ad, all that remains is to display it to your users. Head over to our Native Advanced guide to see how.