Native Ads Advanced

Note: Native Ads Advanced is currently in a limited release. If you're
interested in participating, reach out to your account manager to discuss the
possibility.

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.

Prerequisites

Load an ad

Note: Make all calls to the Mobile Ads SDK on the main thread.

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:

Kotlin

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.

Setting options

withNativeAdOptions()

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

Java

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

Kotlin

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

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.

Loading ads

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

Note:
The loadAds() method currently works only with AdMob ads. For mediated ads,
use loadAd() instead.

The loadAd() method sends a request for a single ad:

Java

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

Kotlin

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

The loadAds() method sends a request for multiple ads (up to 5):

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.

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 a
maximum of 5, and it's not guaranteed that the SDK will return the exact
number of ads requested. If multiple ads are returned by a call to loadAds(),
they will be different from each other.

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

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

Note: When reusing an AdLoader, make sure you wait for each request to
finish before calling loadAd() or loadAds() again.

Always test with test ads

When building and testing your apps, make sure you use test ads rather than
live, production ads. Failure to do so can lead to suspension of your account.

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

ca-app-pub-3940256099942544/2247696110

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

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.

Note: 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.

Java

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 = adView.findViewById<TextView%>(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);
}

Kotlin

fun displayAppInstallAd(parent: ViewGroup, ad: NativeAppInstallAd) {
// Inflate a layout and add it to the parent ViewGroup.
val inflater = parent.getContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
as LayoutInflater
val adView = inflater.inflate(R.layout.my_ad_layout, parent) as NativeAppInstallAdView
// Locate the view that will hold the headline, set its text, and use the
// NativeAppInstallAdView's headlineView property to register it.
val headlineView = adView.findViewById<TextView>(R.id.ad_headline)
headlineView.text = ad.headline
adView.headlineView = 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
// assign to the mediaView property. This view is a little different in that the asset
// is populated automatically, so there's one less step.
val mediaView = adView.findViewById<MediaView>(R.id.ad_media)
adView.mediaView = mediaView
// Call the NativeAppInstallAdView's setNativeAd method to register the
// NativeAdObject.
adView.setNativeAd(ad)
// Place the AdView into the parent.
parent.addView(adView)
}

Kotlin

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:

Kotlin

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:

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.

This autopopulation of the MediaView with an available image asset does not
always work when using mediation. Because not all mediation adapters guarantee
that they'll create a media view for every ad, it's possible for a blank one to
be returned for mediated ads. Publishers using mediation should check the
hasVideoContent() function of an ad's VideoController, to see if it contains
a video asset, before displaying the MediaView. If there is no video content,
publishers should display an image view that they populate manually with a
relevant image.

Here's a snippet from the NativeAdvancedExample
that shows/hides the relevant views according to whether the ad has video
content:

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 going to
reuse the NativeAdView that's showing it. Use the following code to destroy an ad: