Banner ads

Banner ads occupy a spot within an app's layout, either at the top or bottom of the device screen. They stay on screen while users are interacting with the app, and can refresh automatically after a certain period of time. If you're new to mobile advertising, they're a great place to start.

This guide shows you how to integrate banner ads from Ad Manager into an Android app. In addition to code snippets and instructions, it also includes information about sizing banners properly and links to additional resources.

Prerequisites

• Complete the Get started guide.

Add AdManagerAdView to the layout

The first step toward displaying a banner is to place AdManagerAdView in the layout for the Activity or Fragment in which you'd like to display it. The easiest way to do this is to add one to the corresponding XML layout file. Here's an example that shows an activity's AdManagerAdView:

# main_activity.xml
<com.google.android.gms.ads.admanager.AdManagerAdView
    xmlns:ads="http://schemas.android.com/apk/res-auto"
    android:id="@+id/adManagerAdView"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_centerHorizontal="true"
    android:layout_alignParentBottom="true"
    ads:adSize="BANNER"
    ads:adUnitId="/6499/example/banner">
</com.google.android.gms.ads.admanager.AdManagerAdView>

Note the following required attributes:

• ads:adSize: Set this to the ad size you'd like to use. If you don't want to use the standard size defined by the constant, you can set a custom size instead. See the banner size section for details.

• ads:adUnitId: Set this to the unique identifier given to the ad unit in your app where ads are to be displayed. If you show banner ads in different activities, each would require an ad unit.

You can alternatively create AdManagerAdView programmatically:

Java

AdManagerAdView adView = new AdManagerAdView(this);

adView.setAdSizes(AdSize.BANNER);

adView.setAdUnitId("/6499/example/banner");
// TODO: Add adView to your view hierarchy.

Kotlin

val adView = AdManagerAdView(this)

adView.adSizes = AdSize.BANNER

adView.adUnitId = "/6499/example/banner"
// TODO: Add adView to your view hierarchy.

Warning: Make sure you set the ad size and ad unit ID in the same manner—set both in XML or both programmatically.

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 Android banners:

/6499/example/banner

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 Mobile Ads SDK's test ads work, see Test Ads.

Load an ad

Once the AdManagerAdView is in place, the next step is to load an ad. That's done with the loadAd() method in the AdManagerAdView class. It takes an AdManagerAdRequest parameter, which holds runtime information, such as targeting info, about a single ad request.

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

Here's an example that shows how to load an ad in the onCreate() method of an Activity:

MainActivity (excerpt)

Java

package ...

import ...
import com.google.android.gms.ads.admanager.AdManagerAdRequest;
import com.google.android.gms.ads.admanager.AdManagerAdView;

public class MainActivity extends AppCompatActivity {
    private AdManagerAdView mAdManagerAdView;

    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        mAdManagerAdView = findViewById(R.id.adManagerAdView);
        AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder().build();
        mAdManagerAdView.loadAd(adRequest);
    }
}

Kotlin

package ...

import ...
import com.google.android.gms.ads.admanager.AdManagerAdRequest
import com.google.android.gms.ads.admanager.AdManagerAdView

class MainActivity : AppCompatActivity() {

    lateinit var mAdManagerAdView : AdManagerAdView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        mAdManagerAdView = findViewById(R.id.adManagerAdView)
        val adRequest = AdManagerAdRequest.Builder().build()
        mAdManagerAdView.loadAd(adRequest)
    }
}

If your ad fails to load, you don't need to explicitly request another one as long as you've configured your ad unit to refresh; the Google Mobile Ads SDK respects any refresh rate you specified in the Ad Manager web interface. If you haven't enabled refresh, you will need to issue a new request.

That's it! Your app is now ready to display banner ads.

Ad events

To further customize the behavior of your ad, you can hook onto a number of events in the ad's lifecycle: loading, opening, closing, and so on. You can listen for these events through the AdListener class.

To use an AdListener with AdManagerAdView, call the setAdListener() method:

Java

mAdManagerAdView.setAdListener(new AdListener() {
    @Override
    public void onAdClicked() {
      // Code to be executed when the user clicks on an ad.
    }

    @Override
    public void onAdClosed() {
      // Code to be executed when the user is about to return
      // to the app after tapping on an ad.
    }

    @Override
    public void onAdFailedToLoad(LoadAdError adError) {
      // Code to be executed when an ad request fails.
    }

    @Override
    public void onAdImpression() {
      // Code to be executed when an impression is recorded
      // for an ad.
    }

    @Override
    public void onAdLoaded() {
      // Code to be executed when an ad finishes loading.
    }

    @Override
    public void onAdOpened() {
      // Code to be executed when an ad opens an overlay that
      // covers the screen.
    }
});

Kotlin

mAdManagerAdView.adListener = object: AdListener() {
    override fun onAdClicked() {
      // Code to be executed when the user clicks on an ad.
    }

    override fun onAdClosed() {
      // Code to be executed when the user is about to return
      // to the app after tapping on an ad.
    }

    override fun onAdFailedToLoad(adError : LoadAdError) {
      // Code to be executed when an ad request fails.
    }

    override fun onAdImpression() {
      // Code to be executed when an impression is recorded
      // for an ad.
    }

    override fun onAdLoaded() {
      // Code to be executed when an ad finishes loading.
    }

    override fun onAdOpened() {
      // Code to be executed when an ad opens an overlay that
      // covers the screen.
    }
}

Each of the overridable methods in AdListener corresponds to an event in the lifecycle of an ad.

Overridable methods
onAdClicked()	The onAdClicked() method is invoked when a click is recorded for an ad.
onAdClosed()	The onAdClosed() method is invoked when a user returns to the app after viewing an ad's destination URL. Your app can use it to resume suspended activities or perform any other work necessary to make itself ready for interaction.
onAdFailedToLoad()	The onAdFailedToLoad() method is the only one that includes a parameter. The error parameter of type LoadAdError describes what error occurred. For more information, refer to the Debugging Ad Load Errors documentation.
onAdImpression()	The onAdImpression() method is invoked when an impression is recorded for an ad.
onAdLoaded()	The onAdLoaded() method is executed when an ad has finished loading. If you want to delay adding the AdManagerAdView to your activity or fragment until you're sure an ad will be loaded, for example, you can do so here.
onAdOpened()	The onAdOpened() method is invoked when an ad opens an overlay that covers the screen.

Banner sizes

The size of the container in which you place your ad must be at least as big as the banner. If your container has padding, that effectively decreases the size of your container. In the event that the container cannot fit the banner ad, the banner will not appear, and you will get this warning in the logs:

W/Ads: Not enough space to show ad. Needs 320x50 dp, but only has 288x495 dp.

The table below lists the standard banner sizes.

Size in dp (WxH)	Description	Availability	AdSize constant
320x50	Banner	Phones and tablets	BANNER
320x100	Large banner	Phones and tablets	LARGE_BANNER
300x250	IAB medium rectangle	Phones and tablets	MEDIUM_RECTANGLE
468x60	IAB full-size banner	Tablets	FULL_BANNER
728x90	IAB leaderboard	Tablets	LEADERBOARD
Provided width x Adaptive height	Adaptive banner	Phones and tablets	N/A
Screen width x 32|50|90	Smart banner	Phones and tablets	SMART_BANNER

Note: Adaptive banners are intended to replace Smart banners.

To define a custom banner size, set your desired AdSize as shown:

Java

AdSize adSize = new AdSize(300, 50);

Kotlin

val adSize = AdSize(300, 50)

Custom ad size

In addition to the standard ad units, Ad Manager lets you serve any sized ad unit into an app. The ad size (width, height) defined for an ad request should match the dimensions of the ad view, AdManagerAdView in the following example, displayed on the app:

Java

// Define custom AdSize of 250x250 for AdManagerAdView

AdSize customAdSize = new AdSize(250, 250);
AdManagerAdView adView = new AdManagerAdView(this);
adView.setAdSizes(customAdSize);

Kotlin

// Define custom AdSize of 250x250 for AdManagerAdView

val customAdSize = AdSize(250, 250)
val adView = AdManagerAdView(this)
adView.setAdSizes(customAdSize)

See the Ad Manager Multiple Ad Sizes example for an implementation of custom ad size in the Android API Demo app.

Multiple ad sizes

Ad Manager lets you specify multiple ad sizes, which could be eligible to serve in an AdManagerAdView. Before implementing this feature in the SDK, create a line item targeting the same ad unit which is associated with different size creatives.

In your app, simply pass multiple AdSize parameters into setAdSizes:

Java

AdManagerAdView adView = new AdManagerAdView(this);
adView.setAdSizes(AdSize.BANNER, new AdSize(120, 20), new AdSize(250, 250));

Kotlin

val adView = AdManagerAdView(this)
adView.setAdSizes(AdSize.BANNER, AdSize(120, 20), AdSize(250, 250))

If AdManagerAdView changes size at refresh time, your layout should be able to automatically adapt to the new size. The AdManagerAdView will default to the size passed in the first parameter until the next ad returns.

You can also specify multiple ad sizes using the ads:adSizes attribute in your XML layout file:

<com.google.android.gms.ads.admanager.AdManagerAdView
   android:id="@+id/multiple_ad_sizes_view"
   android:layout_width="wrap_parent"
   android:layout_height="wrap_content"
   android:layout_alignParentBottom="true"
   android:layout_centerHorizontal="true"
   ads:adSizes="BANNER,120x20,250x250"
   ads:adUnitId="AD_UNIT_ID" />

See the Ad Manager Multiple Ad Sizes example for an implementation of multiple ad sizes in the Android API Demo app.

Manual impression counting

Manual impression counting is compatible only with direct-sold and house campaigns with creatives trafficked directly in Ad Manager. It should not be used for backfill or third-party networks ads. For more details, see Counting impressions and clicks.

You can manually send impression pings to Ad Manager if you have special conditions for when an impression should be recorded. To do this, enable an AdManagerAdRequest for manual impressions before loading an ad:

Java

AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder()
    .setManualImpressionsEnabled(true)
    .build();

Kotlin

val adRequest = AdManagerAdRequest.Builder()
    .setManualImpressionsEnabled(true)
    .build()

When you determine that an ad has been successfully returned and is on-screen, you can manually record an impression:

Java

mAdManagerAdView.recordManualImpression();

Kotlin

mAdManagerAdView.recordManualImpression()

Key Point: Impressions are normally fired when the onAdLoaded() callback is invoked. You should only consider using this feature if you want to record impressions at a different point in time.

App events

App events let you create ads that can send messages to their app code. The app can then take actions based on these messages.

You can listen for Ad Manager specific app events using AppEventListener. These events can occur at any time during the ad's lifecycle, even before onAdLoaded() is called.

Java

public interface AppEventListener {
  void onAppEvent(String name, String info);
}

Kotlin

interface AppEventListener {
    fun onAppEvent(name: String, info: String)
}

void onAppEvent(String name, String info) is called when an app event occurs in an ad. This interface can be implemented by your activity or any other object:

Java

import com.google.android.gms.ads.admanager.*;

public class BannerExample extends Activity implements AppEventListener {
}

Kotlin

import com.google.android.gms.ads.admanager.*

class BannerExample : Activity(), AppEventListener {
}

and then passed to the AdManagerAdView:

Java

mAdManagerAdView.setAppEventListener(this);

Kotlin

mAdManagerAdView.appEventListener = this

Here is an example showing how to change the background color of your app depending on an app event with a name of color:

Java

@Override
public void onAppEvent(String name, String info) {
  if ("color".equals(name)) {
    if ("green".equals(info) {
      // Set background color to green.
    } else if ("blue".equals(info) {
      // Set background color to blue.
    } else {
      // Set background color to black.
    }
  }
}

Kotlin

override fun onAppEvent(name: String?, info: String?) {
    if (name == "color") {
        when (info) {
            "green" -> {
                // Set background color to green.
            }
            "blue" -> {
                // Set background color to blue.
            }
            else -> {
                // Set background color to black.
            }
        }
    }
}

And, here is the corresponding creative that sends color app event messages to the Listener:

<html>
<head>
  <script src="//www.gstatic.com/afma/api/v1/google_mobile_app_ads.js"></script>
  <script>
    document.addEventListener("DOMContentLoaded", function() {
      // Send a color=green event when ad loads.
      admob.events.dispatchAppEvent("color", "green");

      document.getElementById("ad").addEventListener("click", function() {
        // Send a color=blue event when ad is clicked.
        admob.events.dispatchAppEvent("color", "blue");
      });
    });
  </script>
  <style>
    #ad {
      width: 320px;
      height: 50px;
      top: 0px;
      left: 0px;
      font-size: 24pt;
      font-weight: bold;
      position: absolute;
      background: black;
      color: white;
      text-align: center;
    }
  </style>
</head>
<body>
  <div id="ad">Carpe diem!</div>
</body>
</html>

See the Ad Manager App Events example for an implementation of app events in the Android API Demo app.

Hardware acceleration for video ads

In order for video ads to show successfully in your banner 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, you can 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 Hardware 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.

Additional resources

Examples on GitHub

• Minimal implementation of banner ads example: Java | Kotlin

• Advanced features demo: Java | Kotlin

Mobile Ads Garage video tutorials

• Banner implementation
• Banner best practices

Next steps

Explore the following topics:

• User privacy
• Optimized SDK initialization and ad loading (beta)