Native Ads Advanced

This feature is currently in a limited beta release. If you are interested in participating, reach out to your account manager to discuss the possibility. This feature will be made available to all publishers at the conclusion of the beta.

This guide shows you how to use the Google Mobile Ads SDK to implement AdMob Native Ads Advanced in an Android app as well as some important things to consider along the way. The techniques and code examples below apply to both Eclipse and Android Studio projects, so developers using either IDE can take advantage of this guide.

Prerequisites

This guide assumes some working knowledge of the Google Mobile Ads SDK. If you haven't already done so, consider running through Get Started in Android Studio.

What's Native Ads Advanced?

Native Ads Advanced is a format in which ad assets 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 SDK) is then responsible for displaying them.

There are two standard native ads advanced field descriptions: app install and content. App install ads are represented by NativeAppInstallAd, and content ads are represented by NativeContentAd. These objects contain the assets for the native ad.

Load an ad

Native Advanced ads are loaded via the AdLoader class, which has its own AdLoader.Builder class to customize it during creation. By adding listeners to the AdLoader while building it, an app specifies which types of ad formats 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 either an app install ad or a content ad in a single request:

AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110")
    .forAppInstallAd(new OnAppInstallAdLoadedListener() {
        @Override
        public void onAppInstallAdLoaded(NativeAppInstallAd appInstallAd) {
            // Show the app install ad.
        }
    })
    .forContentAd(new OnContentAdLoadedListener() {
        @Override
        public void onContentAdLoaded(NativeContentAd contentAd) {
            // Show the content ad.
        }
    })
    .withAdListener(new AdListener() {
        @Override
        public void onAdFailedToLoad(int errorCode) {
            // Handle the failure by logging, altering the UI, etc.
        }
    })
    .withNativeAdOptions(new NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build();

Prepare for the individual formats

The first methods above are responsible for preparing the AdLoader for a particular type of native ad:

forAppInstallAd()
Calling this method configures the AdLoader to request app install ads. When an ad has loaded successfully, the listener object's onAppInstallAdLoaded() method is called.
forContentAd()
This method works the same as forAppInstallAd(), but with content ads. When an ad has loaded successfully, the onContentAdLoaded() method is invoked on the listener object.

Even when the AdLoader has handlers for multiple native ad formats, the SDK only makes a single 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:

.withAdListener(new AdListener() {
  // AdListener callbacks like OnAdFailedToLoad, OnAdOpened, and so on,
  // can be overridden here.
})

There is one important difference between the way AdListeners work with Native Advanced ads and the way they work with banners and interstitials. Because the AdLoader has its own, format-specific listeners (NativeAppInstallAd.OnAppInstallAdLoadedListener, and so on) to use when an ad has loaded, the onAdLoaded() method of the AdListener is not called when a native ad loads successfully.

Options

The last function included in the creation of the AdLoader above is another optional method, withNativeAdOptions:

.withNativeAdOptions(new NativeAdOptions.Builder()
        // Methods in the NativeAdOptions.Builder class can be
        // used here to specify individual options settings.
        .build()
)

The NativeAdOptions object allows apps to set specific options used in making the request. Its NativeAdOptions.Builder class offers these methods to use when creating an instance:

setReturnUrlsForImageAssets()

Image assets for ads are returned via instances of NativeAd.Image, which holds a Drawable and a Uri. If this option is set to false (which is the default), the SDK fetches image assets automatically and populates both the Drawable and the Uri for you. If it's set to true, however, the SDK instead populates just the Uri field, allowing you to download the actual images at your discretion.

setImageOrientation()

Some creatives have multiple available images to match different device orientations. Calling this method with one of the NativeAdOptions orientation constants, ORIENTATION_PORTRAIT or ORIENTATION_LANDSCAPE, requests images in portrait or landscape orientation, respectively. If this method is not called, the default value of ORIENTATION_ANY is used. You can, of course, call this method with the ORIENTATION_ANY constant if you wish.

setRequestMultipleImages()

Some image assets contain a series of images rather than just one image. By setting this value to true, your app indicates that it's prepared to display all the images for any assets that have more than one image. By setting it to false (which is the default value), your app instructs the SDK to provide just the first image for any assets that contain a series.

If withNativeAdOptions() is not called at all when creating an AdLoader, the default value for each option is used.

Load the ad

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

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

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

A single AdLoader can make multiple requests, but only if they're done one at a time. When reusing an AdLoader, make sure you wait for each request to finish before calling loadAd again to begin the next. If you need to request multiple ads in parallel, you can always use multiple AdLoader objects.

When to request ads

Applications displaying Native Advanced ads are free to request them in advance of when they are actually displayed. In many cases, this is the recommended practice. An app displaying a list of items with ads mixed in, for example, can load ads for the whole list, even though the user must scroll the view before they can be shown, and some may not be displayed at all.

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

When an ad loads, the SDK invokes the listener for the corresponding ad format. Your app is then responsible for displaying the ad, though it doesn't necessarily have to do so immediately. To make displaying system-defined ad formats easier, the SDK offers some useful resources, as described below.

Ad view classes

For each of the system-defined formats, there is a corresponding ad view class: NativeAppInstallAdView for app install ads and NativeContentAdView for content ads. These ad view classes are ViewGroup that publishers should use as the roots for ads of the corresponding format. A single NativeContentAdView, for example, corresponds to a single content ad. Each view used to display that ad's assets (the ImageView that displays the screenshot asset, for instance) should be a child of the NativeContentAdView object.

The view hierarchy for a content ad that uses a RelativeLayout to display its asset views might look like this:

The ad view classes also provide methods used to register the view used for each individual asset, and a method to register the NativeAd object itself. Registering the views in this way allows the SDK to automatically handle tasks such as:

  • Recording clicks.
  • Recording impressions (when the first pixel is visible on the screen).
  • Displaying the AdChoices overlay.

Code example

These are the steps for displaying a system-defined native ad format:

  1. Create an instance of the correct ad view class.
  2. For each ad asset to be displayed:
    1. Populate the asset view with the asset in the ad object.
    2. Register the asset view with the ViewGroup class.
  3. Register the ad object with the ViewGroup class.

Here is an example function that displays a NativeContentAd:

private void displayContentAd(ViewGroup parent, NativeContentAd contentAd) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    NativeContentAdView adView = (NativeContentAdView) inflater
            .inflate(R.layout.my_content_ad, parent);

    // Locate the view that will hold the headline, set its text, and call the
    // NativeContentAdView's setHeadlineView method to register it.
    TextView headlineView = (TextView) adView.findViewById(R.id.contentad_headline);
    headlineView.setText(contentAd.getHeadline());
    adView.setHeadlineView(headlineView);

    ...
    // Repeat the above process for the other assets in the NativeContentAd using
    // additional view objects (Buttons, ImageViews, etc).
    ...

    // Call the NativeContentAdView's setNativeAd method to register the
    // NativeAdObject.
    adView.setNativeAd(contentAd);

    // Place the AdView into the parent.
    parent.addView(adView);
}

Here's a look at the individual tasks:

Inflate the layout

LayoutInflater inflater = (LayoutInflater) parent.getContext()
        .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
NativeContentAdView adView = (NativeContentAdView) inflater
        .inflate(R.layout.my_content_ad, parent);

In this example, we're inflating an XML layout that contains views for displaying a content ad, and then locating a reference to the NativeContentAdView that is its root element. This is a great way to get started, but note that you could also reuse an existing NativeContentAdView if there's one in your fragment or activity, or even create an instance dynamically without using a layout file.

Populate and register the asset view

This sample code locates the view used to display the headline, sets its text using the string asset provided by contentAd, and registers it with the NativeContentAdView object:

TextView headlineView = (TextView) adView.findViewById(R.id.contentad_headline);
headlineView.setText(contentAd.getHeadline());
adView.setHeadlineView(headlineView);

This process of locating the view, setting its value, and registering it with the ad view class should be repeated for each of the assets provided by the native ad object.

Register the ad object

This final step registers the ad object with the view that's responsible for displaying it:

adView.setNativeAd(contentAd);

Test your code

To help publishers test their implementations, we've made the following AdMob ad unit ID available for use:

ca-app-pub-3940256099942544/3986624511

Any requests you make to that ad unit are considered "test" requests and not counted against production statistics.

Send feedback about...

This page
Documentation feedback
AdMob by Google
AdMob by Google
Product feedback