Native Ads

Select platform: Android iOS Flutter Unity

Native ads are ad assets that are presented to users through 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 your app's visual design.

When a native ad loads, your app receives an ad 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 using the SDK and then displaying the ad content in your app.

This page shows how to use the SDK to load native ads. Tip: Learn more about native ads in our Native Ads Playbook.

You can also check out some customer success stories: case study 1, case study 2.

Prerequisites

• Complete the Get started guide.

Always test with test ads

When building and testing your apps, make sure you use test ads rather than live, production ads.

The easiest way to load test ads is to use our dedicated test ad unit ID for native ads on Android:

ca-app-pub-3940256099942544/2247696110

It's been specially configured to return test ads for every request, and you can 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 Google Mobile Ads SDK's test ads work, see Test ads.

Load ads

Native ads are loaded with the AdLoader class, which has its own Builder class to customize it during creation. By adding listeners to the AdLoader when 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 native ads:

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

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.

The forNativeAd() method is responsible for preparing the AdLoader for the NativeAd format. When an ad has loaded successfully, the listener object's onNativeAdLoaded() method is called.

Set up an AdListener with the AdLoader (optional)

When creating the AdLoader, the withAdListener function sets an AdListener for the loader. 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 can be overridden here.
})

Kotlin

.withAdListener(object : AdListener() {
    // AdListener callbacks can be overridden here.
})

Request ads

Tip: You can use ad load calls to build up a cache of preloaded ads before you intend to show them, so that ads can be shown with zero latency when needed. Since ads expire after an hour, you should clear this cache and reload with new ads every hour.

Once you've finished building an AdLoader, it's time to use it to request ads. There are two methods available for this: loadAd() and loadAds().

Key Point: The loadAds() method currently works only with Google ads. For mediated ads, use loadAd() instead.

loadAd()

This method sends a request for a single ad.

Java

adLoader.loadAd(new AdRequest.Builder().build());

Kotlin

adLoader.loadAd(AdRequest.Builder().build())

loadAds()

This method sends a request for multiple ads (up to five):

Java

adLoader.loadAds(new AdRequest.Builder().build(), 3);

Kotlin

adLoader.loadAds(AdRequest.Builder().build(), 3)

Both methods take an 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.

Load multiple ads (optional)

The loadAds() method takes an additional parameter: the number of ads the SDK should attempt to load for the request. This number is capped at five, and it's not guaranteed that the SDK will return the exact number of ads requested.

Returned Google ads will all be different from each other, though ads from reserved inventory or third-party buyers are not guaranteed to be unique.

Don't use the loadAds() method if you're using mediation, as requests for multiple native ads don't currently work for ad unit IDs that have been configured for mediation.

Callbacks

After a call to loadAd(), a single callback is made to the previously defined listener methods to deliver the native ad object or report an error.

After a call to loadAds(), multiple such callbacks are 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 onNativeAdLoaded() callback:

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)

Release resources

Be sure to use the destroy() method on loaded native ads. This releases 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 NativeAd references are destroyed in your activity's onDestroy() method.

In your onNativeAdLoaded 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")
        .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()

Best practices

Follow these rules when loading ads.

• Apps that use native ads in a list should precache the list of ads.

• When precaching ads, clear your cache and reload after one hour.

• Don't call loadAd() or loadAds() on an AdLoader until the first request finishes loading.

• Limit native ad caching to only what is needed. For example when precaching, only cache the ads that are immediately visible on the screen. Native ads have a large memory footprint, and caching native ads without destroying them results in excessive memory use.

• Destroy native ads when no longer in use.

Hardware acceleration for video ads

In order for video ads to show successfully in your native ad views, hardware acceleration must be enabled.

Hardware acceleration is enabled by default, but some apps may choose to disable it. If this applies to your app, we recommend enabling hardware acceleration for Activity classes that use ads.

Enabling hardware acceleration

If your app does not behave properly with hardware acceleration turned on globally, you can control it for individual activities as well. To enable or disable hardware acceleration, use the android:hardwareAccelerated attribute for the <application> and <activity> elements in your AndroidManifest.xml. The following example enables hardware acceleration for the entire app but disables it for one activity:

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

See the HW acceleration guide for more information about options for controlling hardware acceleration. Note that individual ad views cannot be enabled for hardware acceleration if the Activity is disabled, so the Activity itself must have hardware acceleration enabled.

Display your ad

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.