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. Tip: Learn more about native ads in our Native Ads Playbook.
You can also check out some customer success stories: case study 1, case study 2.
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:
ca-app-pub-3940256099942544/2247696110
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:
Java
AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110")
.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();
Kotlin
val adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110}")
.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:
Java
.withAdListener(new AdListener() {
// AdListener callbacks can be overridden here.
})
Kotlin
.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.
There are two methods available for this: loadAd()
and loadAds()
.
loadAd()
This method sends a request for a single ad.
Java
adLoader.loadAd(new AdRequest.Builder().build());
Kotlin
adLoader.loadAd(AdRequest.Builder().build())
loadAds()
This method sends a request for multiple ads (up to five):
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.
Load multiple ads (optional)
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 five, and it's
not guaranteed that the SDK will return the exact number of ads requested.
Returned Google ads will all be different from each other, though ads from reserved inventory or third-party buyers are not guaranteed to be unique.
Don't use the loadAds()
method if you're using mediation, as requests for
multiple native ads don't currently work for ad unit IDs that have been
configured for mediation.
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.
After a call to loadAds()
, multiple such callbacks are 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
onNativeAdLoaded()
callback:
Java
final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
.forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
@Override
public void onNativeAdLoaded(NativeAd nativeAd) {
...
// some code that displays the ad.
...
if (adLoader.isLoading()) {
// The AdLoader is still loading ads.
// Expect more adLoaded or onAdFailedToLoad callbacks.
} else {
// The AdLoader has finished loading ads.
}
}
}).build();
adLoader.loadAds(new AdRequest.Builder().build(), 3);
Kotlin
lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
.forNativeAd {
...
// some code that displays the ad.
...
if (adLoader.isLoading) {
// The AdLoader is still loading ads.
// Expect more adLoaded or onAdFailedToLoad callbacks.
} else {
// The AdLoader has finished loading ads.
}
}.build()
adLoader.loadAds(AdRequest.Builder().build(), 3)
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:
Java
final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
.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();
Kotlin
lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
.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()
orloadAds()
on anAdLoader
until the first request finishes loading.
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.