Banner Ads

• Prerequisites
• Loading Banner Ads in Your App
• Using the Delegate
• Refreshing Ads
• Sample Code

Banner ads usually appear at the top or bottom of your app’s screen. Adding one to your app takes just a few lines of code.

Prerequisites

Before integrating banner ads in your app:

1. Follow the steps in our Get Started guide to create an account on MoPub and integrate the SDK into your project.

For banner ads, it is essential that you added the necessary Activities to your AndroidManifest.xml file as instructed. Skip this step if you are integrating v5.10.0 or newer of the MoPub Android SDK. Relevant permissions and Activities are included in the SDK’s internal AndroidManifest.

   <activity android:name="com.mopub.common.MoPubBrowser"
             android:configChanges="keyboardHidden|orientation|screenSize" />

1. Create an ad unit in the Publisher UI (refer here) for instructions. You will need that ad unit’s ID.

Loading Banner Ads in Your App

Starting with MoPub SDK v5.8.0, you can specify a desired ad size, and the MoPub SDK will request an ad for that size. To do so, you can give a width and a height to your banner view in the XML, or pass in a recognized MoPub ad size constant (either in XML or in code). The latter takes precedence over the former in case multiple sizes are supplied to the MoPub SDK. If you do not pass in a MoPub ad size constant (either in XML or in code), we will default to using your banner view’s width and height. And if the banner view’s dimensions do not specify a numerical value (i.e. they use either match_parent or wrap_content), we will fall back to the width and height of its parent view.

1. Define a slot for your banner ad in your XML layout.

2. Load the ad into the banner slot.

Important: Please do not use publisher-provided overlays (such as close buttons) that are located with the ad placement and that subsequently cover the ad creative. Doing so is against MoPub Policy. If you have questions, please visit the Support Center and file a ticket for additional assistance.

Step 1. Define a Slot for Your Banner Ad in Your XML Layout

The MoPub SDK provides a custom View subclass, MoPubView, which handles requesting and loading ads. Start by including this XML block to your Activity’s or Fragment’s layout. We will fill in the details later:

<com.mopub.mobileads.MoPubView
    android:layout_width=""
    android:layout_height=""
    app:moPubAdSize=""></com.mopub.mobileads.MoPubView>

To fill out the above attributes, here are a few use cases to consider:

• If you know the width and height you would like to request an ad for, set them to a numerical value (something other than match_parent or wrap_content). When doing so, set app:moPubAdSize to match_view so we fill the entire view. If the banner view’s dimensions do not specify a numerical value (i.e. they use either match_parent or wrap_content), we will fall back to the width and height of its parent view.
• If you do not know or have the width and height, and you would like to use a recognized ad size constant, pass in a constant to app:moPubAdSize. Ad sizes constants are height-based, and you can refer to this list for the supported ones.
• If you are loading your banner ad programmatically and do not want to define an ad size here, you can pass an ad size dynamically as shown in the next step. Remember to remove the app:moPubAdSize attribute altogether in this case (i.e. do not leave it undefined). Note that, if there are multiple ad sizes passed in via XML and via code, the MoPub SDK will only consider the one passed in via code.

Step 2. Load an Ad Into the Banner Slot

Next, in your Activity or Fragment code, declare an instance variable for your MoPubView:

private MoPubView moPubView;

You should already have created an ad unit on MoPub’s site and received an Ad Unit ID. You’ll use it now to identify that ad unit in your app and request ads from MoPub that are relevant for your users.

In your Activity’s onCreate() or your Fragment’s onCreateView() method, set your MoPubView’s Ad Unit ID, then simply call loadAd() to fetch and display the ad:

...
moPubView = (MoPubView) findViewById(R.id.adview);
moPubView.setAdUnitId("xxxxxxxxxxx"); // Enter your Ad Unit ID from www.mopub.com
moPubView.setAdSize(MoPubAdSize); // Call this if you are not setting the ad size in XML or wish to use an ad size other than what has been set in the XML. Note that multiple calls to `setAdSize()` will override one another, and the MoPub SDK only considers the most recent one.
moPubView.loadAd(MoPubAdSize); // Call this if you are not calling setAdSize() or setting the size in XML, or if you are using the ad size that has not already been set through either setAdSize() or in the XML
moPubView.loadAd();
...

Note: Ad requests must be made on the main thread.

When the hosting Activity or Fragment is destroyed, be sure to also destroy the MoPubView by calling:

    moPubView.destroy();

Using the Delegate

MoPubView provides a listener interface, BannerAdListener, which includes a variety of optional callbacks you can use to be notified of events; for example, when an ad has successfully loaded, or when the ad is about to present or dismiss a modal view. BannerAdListener includes the following methods:

// Sent when the banner has successfully retrieved an ad.
public void onBannerLoaded(MoPubView banner);

// Sent when the banner has failed to retrieve an ad. You can use the MoPubErrorCode value to diagnose the cause of failure.
public void onBannerFailed(MoPubView banner, MoPubErrorCode errorCode);

// Sent when the user has tapped on the banner.
public void onBannerClicked(MoPubView banner);

// Sent when the banner has just taken over the screen.
public void onBannerExpanded(MoPubView banner);

// Sent when an expanded banner has collapsed back to its original size.
public void onBannerCollapsed(MoPubView banner);

To listen for events, you’ll need to implement the listener interface:

public class ExampleActivity extends Activity implements BannerAdListener {
  @Override
  public void onBannerLoaded(MoPubView banner) {
    Toast.makeText(getApplicationContext(),
      "Banner successfully loaded.", Toast.LENGTH_SHORT).show();
  }

  // ... other BannerAdListener methods ...
}

and pass your Activity to the MoPubView as it’s being created (see Step 2):

moPubView.setBannerAdListener(this);

Refreshing Ads

The MoPubView will automatically refresh your ad unit at a time interval that you set using the MoPub web interface. You can also programmatically toggle auto-refresh on a particular MoPubView using the setAutorefreshEnabled method.

Sample Code

For a complete example of how to add banner ads into your app, check out the MoPub sample app.