Native Ads

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

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, "/6499/example/native")
    .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, "/6499/example/native")
    .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()

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.

Load the native ad

Once you've finished building an AdLoader, call its loadAd() method to request an ad:

Java

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

Kotlin

adLoader.loadAd(PublisherAdRequest.Builder().build())

Note that AdLoaders use the same PublisherAdRequest class as banners and interstitials. You can use that class's methods to add targeting information just as you would with other ad types.

Cleaning up

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

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, "/6499/example/native")
        .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, "/6499/example/native")
    .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()

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.

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, you can 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 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.