Native Ads

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.

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:

/21775744923/example/native

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:

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .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();

val adLoader = AdLoader.Builder(this, "/21775744923/example/native}")
    .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()

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:

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

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

Request ads

Once you've finished building an AdLoader, it's time to use it to request ads. Use the loadAd() method which takes an AdManagerAdRequest object as its first parameter. This is the same AdManagerAdRequest class used by banners and interstitials, and you can use methods of the AdManagerAdRequest class to add targeting information, just as you would with other ad formats.

loadAd()

This method sends a request for a single ad.

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

adLoader.loadAd(AdManagerAdRequest.Builder().build())

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.

Release resources

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

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:

final AdLoader adLoader = new AdLoader.Builder(this, "/21775744923/example/native")
        .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();

lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "/21775744923/example/native")
    .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() 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.