Native Ads

Key Point: Learn more about native ads in our Native Ads Playbook. For a complete walkthrough of an example project, visit our Codelab. Samples are available for Java and Kotlin. You can also check out some customer success stories: case study 1, case study 2.

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

Note: Make all calls to the Mobile Ads SDK on the main thread.

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(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")
    .forUnifiedNativeAd { ad : UnifiedNativeAd ->
        // 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()

Warning: Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged. If you must load an ad from onAdFailedToLoad(), limit ad load retries to avoid continuous failed ad requests in situations such as limited network connectivity.

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's onUnifiedNativeAdLoaded() 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().

Note: The loadAds() method currently works only with AdMob ads. For mediated ads, use loadAd() instead.

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)

Note: When reusing an AdLoader, make sure you wait for each request to finish before calling loadAd() or loadAds() again.

Cleaning up

Be sure to use the destroy() method on loaded native ads. This frees up utilized resources and prevents memory leaks.

Key Point: destroy() must be called on all ads, even if they weren't used or referenced.

Ensure that all UnifiedNativeAd references are destroyed in your activity's onDestroy() method.

In your onUnifiedNativeAdLoaded callback, make sure to destroy any existing native ads that will be dereferenced.

Another key check is if the activity is destroyed and if so, call destroy() on the returned ad and return immediately:

Java

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forUnifiedNativeAd(new UnifiedNativeAd.OnUnifiedNativeAdLoadedListener() {
    @Override
    public void onUnifiedNativeAdLoaded(UnifiedNativeAd 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")
    .forUnifiedNativeAd { unifiedNativeAd ->
        // 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) {
            unifiedNativeAd.destroy()
            return@forUnifiedNativeAd
        }
        ...
    }.build()

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.

Note: While prefetching ads is a great technique, it's important that publishers not keep old ads around too long without displaying them. Any ad objects that have been held for longer than an hour without being displayed should be discarded and replaced with new ads from a new request.

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.