Native Ads Advanced

Native Ads Advanced is currently in a limited beta release. If you're 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.

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, so they 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.

This guide shows you how to integrate Native Ads Advanced into an Android app.

Prerequisites

Import the Google Mobile Ads SDK, either by itself or as part of Firebase.

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, and so on.
        }
    })
    .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.

withNativeAdOptions()

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.

If you use setImageOrientation() to specify a preference for landscape or portrait image orientation, the SDK places images matching that orientation first in image asset arrays and places non-matching images after them. Since some ads only have one orientation available, publishers should make sure that their apps can handle both landscape and portrait images.

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.

setAdChoicesPlacement()

The AdChoices overlay is set to the top right corner by default. Apps can change which corner this overlay is rendered in by setting this property to one of the following:

ADCHOICES_TOP_LEFT
ADCHOICES_TOP_RIGHT
ADCHOICES_BOTTOM_RIGHT
ADCHOICES_BOTTOM_LEFT

setVideoOptions()

Apps can use this method to set options for video assets returned as part of a native ad. For more information, see the Native Video section later in this guide.

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.

Always test with test ads

The sample code above contains an ad unit ID and you're free to request ads with it. It's been specially configured to return test ads rather than production ads for every request, which makes it safe to use.

However, once you register an app in the AdMob UI and create your own ad unit IDs for use in your app, you'll need to explicitly configure your device as a test device when you're developing. This is extremely important. Testing with real ads (even if you never tap on them) is against AdMob policy and can cause your account to be suspended. See Test Ads for information on how you can make sure you always get test ads when developing.

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

AdChoices overlay

An AdChoices overlay is added to each ad view by the SDK. Leave space in your preferred corner of your native ad view for the automatically inserted AdChoices logo. Also, it's important that the AdChoices overlay be easily seen, so choose background colors and images appropriately. For more information on the overlay's appearance and function, see Native ads advanced field descriptions.

Code example

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

Create an instance of the correct ad view class.
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.
Register the MediaView, if one is being used.
Register the ad object with the ViewGroup class.

Here is an example function that displays a NativeAppInstallAd:

private void displayAppInstallAd(ViewGroup parent, NativeAppInstallAd ad) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    NativeAppInstallAdView adView = (NativeAppInstallAdView) inflater
            .inflate(R.layout.my_ad_layout, parent);

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

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

    // If the app is using a MediaView to display video, it should be instantiated and
    // passed to setMediaView. This view is a little different in that the asset is populated
    // automatically, so there's one less step.
    MediaView mediaView = (MediaView) adView.findViewById(R.id.ad_media);
    adView.setMediaView(mediaView);

    // Call the NativeAppInstallAdView's setNativeAd method to register the
    // NativeAdObject.
    adView.setNativeAd(ad);

    // 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);
NativeAppInstallAdView adView = (NativeAppInstallAdView) inflater
        .inflate(R.layout.my_ad_layout, parent);

In this example, we're inflating an XML layout that contains views for displaying an app install ad and then locating a reference to the NativeAppInstallAdView. Note that you could also reuse an existing NativeAppInstallAdView 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 views

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

TextView headlineView = (TextView) adView.findViewById(R.id.ad_headline);
headlineView.setText(ad.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 that the app will display.

Register the MediaView, if present

The MediaView is a special View designed to display video assets (it's covered in detail in the Native Video section below). Apps using a MediaView don't need to populate it with an asset, but must register it with the NativeAdView like this:

MediaView mediaView = (MediaView) adView.findViewById(R.id.ad_media);
adView.setMediaView(mediaView);

Register the ad object

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

adView.setNativeAd(ad);

Native video

In addition to images, text, and numbers, some native ads contain video assets. Not every ad includes a video asset, and apps are not required to display them.

To simplify the configuration and display of video, the Mobile Ads SDK provides the following video-related classes:

VideoOptions

The VideoOptions class allows apps to configure how native video assets should behave. VideoOptions objects should be assigned to a NativeAdOptions object that's used when constructing the AdLoader:

VideoOptions videoOptions = new VideoOptions.Builder()
        .setStartMuted(false)
        .build();

NativeAdOptions adOptions = new NativeAdOptions.Builder()
        .setVideoOptions(videoOptions)
        .build();

AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forAppInstallAd( ... )
        .forContentAd( ... )
        .withNativeAdOptions(adOptions)
        .build();

The VideoOptions.Builder class currently offers one method, setStartMuted(), which tells the SDK whether video assets should start in a muted state. The default value is true.

MediaView

Video assets are displayed to users via MediaView. This is a View that can be defined in an XML layout or constructed dynamically, and should be placed within the view hierarchy of a NativeAdView, just like any other asset view.

Unlike other asset views, however, apps do not need to manually populate a MediaView with its asset. The SDK handles this automatically:

If a video asset is available, it is buffered and starts playing inside the MediaView.
If the ad does not contain a video asset, the first image asset is downloaded and placed inside the MediaView instead.

While apps that don't intend to display video assets aren't required to include a MediaView in their layouts, it's recommended that they do.

VideoController

The VideoController class is used to retrieve information about video assets. Apps can get a reference to the controller from a NativeAppInstallAd by calling the getVideoController() method:

VideoController vc = myAppInstallAd.getVideoController();

This method always returns a VideoController object, even when no video asset is present in the ad.

VideoController offers these methods for querying video state:

hasVideoContent() - Returns true if the ad has a video asset, and false if it doesn't.
getAspectRatio() - Returns the aspect ratio of the video (width/height), or zero if no video asset is present.

Apps can also use the VideoController.VideoLifecycleCallbacks class to get notifications when events occur in the lifecycle of a video asset:

VideoController vc = nativeAppInstallAd.getVideoController();

vc.setVideoLifecycleCallbacks(new VideoController.VideoLifecycleCallbacks() {
    public void onVideoEnd() {
        // Here apps can take action knowing video playback is finished.
        // It's always a good idea to wait for playback to complete before
        // replacing or refreshing a native ad, for example.
        super.onVideoEnd();
    }
});

Destroy an ad

When you are done showing your native ad, you should destroy it so that the ad is properly garbage collected. This is especially important if you're using Native Video. Use the following code to destroy an ad:

if (nativeAd.getVideoController().hasVideoContent()) {
    adView.setMediaView(null);
    // Warning: If you are reusing this native ad view for another ad,
    // make sure to destroy the ad before configuring your new ad with the
    // view. Otherwise, this call to setNativeAd() will override the
    // setNativeAd() call you made with your new ad.
    adView.setNativeAd(nativeAd);
}
nativeAd.destroy();