android-guidelines | Banner Ads

Banner Ads consists of an image, either static or animated, along with a hyperlink that takes the user to a website or relevant app store. All types of apps can leverage banner ads for monetization.

Follow these simple steps and start monetizing with Banner ads:

Setting up a Banner Ad

  1. To display a banner ad, you need a banner placement ID.
  2. After adding your app, select BANNER AD to create a placement for ad type Banner.
  3. Once you successfully create the banner placement, the placement ID is available.

Adding a Banner Ad to your App

Creating a Banner Ad

Method 1: Adding a Banner in XML layout resource files

You can add a banner ad in your layout resource file in XML and reference it in your code as you would in a regular view.

The following snippet shows how to add a banner ad in XML. Note the inmobi ads namespace that you need to add to the top-level layout element to do so.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:ads="http://schemas.android.com/apk/lib/com.inmobi.ads"
    xmlns:tools="http://schemas.android.com/tools" 
android:layout_width="match_parent"
    android:layout_height="match_parent" android:paddingLeft="@dimen/activity_horizontal_margin"
    android:paddingRight="@dimen/activity_horizontal_margin"
    android:paddingTop="@dimen/activity_vertical_margin"
    android:paddingBottom="@dimen/activity_vertical_margin"
    android:orientation="vertical"
    tools:context="com.inmobi.samples.BannerXMLActivity">
    <TextView android:text="@string/banner_xml_message"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content" />
    <com.inmobi.ads.InMobiBanner
        android:layout_width="320dp"
        android:layout_height="50dp"
        android:id="@+id/banner"
        ads:placementId="1431977751489005"
        ads:refreshInterval="60"
    />
</LinearLayout>
	

Note: For banner XML integration, publishers using Android SDK 720 and onwards needs to append “plid-” to placementId TAG as following:

ads:placementId="plid-1431977751489005"
	

Now, you can reference the banner in your code:

InMobiBanner bannerAd = (InMobiBanner)findViewById(R.id.banner);
	

Once you have the banner instance, you can request for ads to be loaded as shown in the following sections.

Before you do that, call the InMobiSdk.init(Activity, String) method in your main activity or the activity where you are displaying banner ad to initialize the InMobi SDK.

Method 2: Adding a Banner in code

To add a banner ad in Android code, create an instance of InMobiBanner:

InMobiBanner bannerAd = new InMobiBanner(BannerAdsActivity.this, 1468078426600L);
	

Notes:

  • The InMobiBanner class is not thread-safe. A banner instance must be created on the UI thread.
  • Similarly, all methods on this instance must be called on the UI thread. Not doing so will lead to unpredictable behavior and may affect your ability to monetize with InMobi.

Once you have created a banner ad, you can add it to the view hierarchy:

RelativeLayout adContainer = (RelativeLayout) findViewById(R.id.ad_container);
RelativeLayout.LayoutParams bannerLp = new RelativeLayout.LayoutParams(640, 100);
bannerLp.addRule(RelativeLayout.ALIGN_PARENT_BOTTOM);
bannerLp.addRule(RelativeLayout.CENTER_HORIZONTAL);
adContainer.addView(bannerAd, bannerLayoutParams);
	

Note: You should specify the banner view dimensions in pixel units when setting the layout parameters for the banner ad. Also, it is a programming error to supply WRAP_CONTENT as the layout parameters for a banner ad. This constraint applies whether you create a banner in your XML layout resource file or in code.

If you are building for both phones and tablets, you can supply MATCH_PARENT as the layout parameters for the banner. The InMobi SDK will correctly compute the banner view dimensions and use them to fetch an ad from the InMobi Network.

Loading a Banner Ad

Loading a banner ad requires you to add the banner ad view to your view hierarchy before requesting for an ad on the InMobiBanner instance. Adding the view to the view hierarchy enables the InMobi SDK to correctly compute the banner view dimensions and to request for the best ad matching those dimensions from the network.

Once you have added InMobiBanner to the view hierarchy, you can call the load() method on the instance you just created to request for an ad.

Setting up Auto-refresh for your Banner Ad

The banner ads refresh automatically after the first time you requested for an ad by calling load() on an InMobiBanner instance. You can set up auto-refresh either while creating a banner in XML layout resource file, or later in code, by calling the setRefreshInterval(int) method on a banner ad.

The sample below shows how to do this in XML.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:ads="http://schemas.android.com/apk/lib/com.inmobi.ads"
    xmlns:tools="http://schemas.android.com/tools" 
android:layout_width="match_parent"
    android:layout_height="match_parent" android:paddingLeft="@dimen/activity_horizontal_margin"
    android:paddingRight="@dimen/activity_horizontal_margin"
    android:paddingTop="@dimen/activity_vertical_margin"
    android:paddingBottom="@dimen/activity_vertical_margin"
    android:orientation="vertical"
    tools:context="com.inmobi.samples.BannerXMLActivity">
    <TextView android:text="@string/banner_xml_message"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content" />
    <com.inmobi.ads.InMobiBanner
        android:layout_width="320dp"
        android:layout_height="50dp"
        android:id="@+id/banner"
        ads:placementId="plid-1431977751489005"
        ads:refreshInterval="60"
    />
</LinearLayout>
	

Animating Banner Ad Refreshes

You can choose an animation style that takes effect when a banner is refreshed. You can also choose to turn OFF any animation for banner refreshes. To do so, you can call the setAnimationType(InMobiBanner.AnimationType) method after obtaining a banner instance.

Note: The default animation is set to AnimationType.ROTATE_HORIZONTAL_AXIS. If you want to turn this off, call the setAnimationType method with the AnimationType.ANIMATION_OFF parameter.

Listening for Banner Ad Lifecycle Events

If you want to listen for key events in the banner lifecycle, you should implement the BannerAdListener interface. You can then set this listener using the setListener(BannerAdListener) method on the InMobiBanner instance. A brief description of each event is as follows.

    /**
* A listener for receiving notifications during the lifecycle of a banner ad.
*/
public abstract class BannerAdEventListener {
   /**
    * Called to notify that an ad was successfully loaded.
    * @param ad Represents the {@link InMobiBanner} ad which was loaded
    */
   public void onAdLoadSucceeded(InMobiBanner ad) {}

   /**
    * Called to notify that a request to load an ad failed.
    * @param ad Represents the {@link InMobiBanner} ad which failed to load
    * @param status Represents the {@link InMobiAdRequestStatus} status containing error reason
    */
   public void onAdLoadFailed(InMobiBanner ad, InMobiAdRequestStatus status) {}

   /**
    * Called to notify that the user interacted with the ad.
    * @param ad Represents the {@link InMobiBanner} ad on which user clicked
    * @param params Represents the click parameters
    */
   public void onAdClicked(InMobiBanner ad, Map params) {}

   /**
    * Called to notify that the banner ad was displayed
    * @param ad Represents the {@link InMobiBanner} ad which was displayed
    */
   public void onAdDisplayed(InMobiBanner ad) {}

   /**
    * Called to notify that the User is about to return to the application after closing the ad.
    * @param ad Represents the {@link InMobiBanner} ad which was closed
    */
   public void onAdDismissed(InMobiBanner ad) {}

   /**
    * Called to notify that the user is about to leave the application as a result of interacting with the ad.
    * @param ad Represents the {@link InMobiBanner} ad
    */
   public void onUserLeftApplication(InMobiBanner ad) {}

   /**
    * Called to notify that a reward was unlocked.
    * @param ad Represents the {@link InMobiBanner} ad for which rewards was unlocked
    * @param rewards Represents the rewards unlocked
    */
   public void onRewardsUnlocked(InMobiBanner ad, Map rewards) {}
  }
	

You can check the code samples for banner ad integrations on GitHub here.

Retrieving CreativeID

At times, there are rogue advertisers who escape all the ad quality checks and end up compromising the user experience on the app by showcasing either an irrelevant, distasteful or disrupting creative to the user. To combat such situations, you can retrieve the creativeID of the ad instance and report back to your InMobi point of contact with the encrypted creativeID.

mBannerAd.getCreativeId() // mBannerAd is an example instance.

Testing the Integration

  1. Configure the test mode on InMobi portal.

    Go to Tools - Diagnostics and switch Test Mode to either Global ON or Selective ON.

    If you are integrating an ad unit for the first time Set Test Mode to Global ON.
    If you want to selectively turn on test traffic for a set of devices·

    You already have a prior version of the SDK integrated for this particular ad unit and therefore you should restrict your testing to only few devices
    Set Test Mode to Selective ON.

    In the device section:

    1. In the Device ID box, type the device ID.
    2. In the Device Name box, set any name.
    3. Click Add Device to add the test device.

    If you already have a device configured, you can select the device and test mode would be enabled.

    Note: You MUST turn off the test mode before going live or else your app will fail to monetize.

    Now you are all set to get test ads.

    Getting the Device ID

    The device id is the Google Play Advertising ID (GPID). To get the device ID, configure the SDK to print debug logs to the console. You can do so by adding the following line to your Activity where you are integrating banner ads.

    InMobiSdk.setLogLevel(LogLevel.DEBUG);
    		

    The device ID will now be printed in debug logs in the DDMS console:

  2. You will also get feedback on the diagnostics tab on the ad unit and ad request and this can be particularly helpful during integration.

Helpful Debug Information

Once you have enabled debug logs as mentioned in step 1, SDK will print key logs to the DDMS console that provide useful information about the initialization and ad load lifecycle.

The following tables capture these logs.

SDK Initialization

Scenario Log Level Logs
Publisher passed null or empty account id Error Account id cannot be null or empty. Please provide a valid Account id.
Publisher passed a valid account id Debug InMobi SDK initialized with account id: <account id>
Publisher passed an invalid account Id Error Invalid account id passed to init. Please provide a valid account id.
Publisher didn't grant the mandatory permissions Debug Please grant the mandatory permissions : INTERNET & ACCESS_NETWORK_STATE, SDK could not be initialized.
Permissions granted to the SDK Debug Permissions granted to the SDK are : <List of permissions granted>
Newer version of SDK is available Debug A newer version (ver. 6.0.0) of the InMobi SDK is available! You are currently on an older version (ver. 5.3.1). Download the latest InMobi SDK from http://www.inmobi.com/products/sdk/#downloads

Common Ad Lifecycle Messages

Scenario Log Level Logs
Ad requested when no network available Error LogLevel Network not reachable currently. Please try again.
Ad requested when ad state is loading or available Error LogLevel An ad load is already in progress. Please wait for the load to complete before requesting for another ad (Placement id : <placement id> ).
Ad requested when ad is viewed by user Error LogLevel An ad is currently being viewed by the user. Please wait for the user to close the ad before requesting for another ad (Placement id : <placement id> ).
Publisher device Id Debug LogLevel Publisher device id is <Device Id>
Requested ad being returned from cache Returning ad from cache for the Placement Id - <Placement Id>
Requested ad being fetched from network Ad will be fetched from network for the Placement Id - <Placement Id>

Messages for Banner Ad Integrations

Scenario Log Level Logs
Publisher created a banner without initializing the SDK Error Please initialize the SDK before creating a Banner ad
Publisher created a banner with an invalid/null placement id Error
Publisher called load on a banner from IB/xml with improper placement id Error Placement id value supplied in XML layout is not valid. Banner creation failed.
For Banner created in XML, no placement id provided Error Placement id value is not supplied in XML layout. Banner creation failed.
Publisher called load on a banner Debug Fetching a Banner ad for placement id: <placement id>
Successfully fetched ad Debug Banner ad successfully fetched for placement id: <Placement id>
Failed to fetch the ad Debug Failed to fetch Banner ad for placement id:<Placement id> with error: <Status code / message>
Started loading the banner in a webview Debug Started loading Banner ad markup in the webview for placement id: <Placement id>
Banner successfully loaded in the webview Debug Successfully loaded Banner ad markup in the webview for placement id: <placement id>
Failed to load banner in the webview Debug NA
Banner refresh is initiated Debug Initiating Banner refresh for placement id: <placement id>
Invalid placement id Error Placement id value supplied in XML layout is not valid. Banner creation failed.
invalid refresh interval Debug Refresh interval value supplied in XML layout is not valid. Falling back to default value.
Null Context Error Context supplied as null, the ad unit can't be created.
Layout params not set Error The layout params of the banner must be set before calling load
Height or width set to WRAP_CONTENT Error The height or width of a Banner ad can't be WRAP_CONTENT
Height or width not set Error The height or width of the banner cannot be determined
Null listener Error Please pass a non-null listener to the banner.

In addition to logs printed by the SDK, you can also get feedback on the diagnostics tab on the ad unit and ad request, which can be particularly helpful during integration.

Advanced: Prefetching Banner Ads

InMobi SDK can prefetch banner ads to leverage each monetization opportunity in your app. The InMobi SDK allows you to create banner ad units that can be maintained in your Application subclass. Your app can then use the banner ad unit in the Activity where the monetization event will occur.

public class YourApplication extends Application {
    ... 
    private InMobiAdRequest mInMobiAdRequest;
    private BannerAdRequestListener mListener;
    Private InMobiBanner mBannerAd;
    ...
    public void onCreate() {
        mInMobiAdRequest = new InMobiAdRequest.Builder(PlacementId.YOUR_PLACEMENT_ID)
                .setSlotSize(320, 50).build();
        mListener = new InMobiBanner.BannerAdRequestListener() {
            @Override
            public void onAdRequestCompleted(InMobiAdRequestStatus status, InMobiBanner bannerAd) {
                if (status.getStatusCode() == NO_ERROR && bannerAd != null) {
                    mBannerAd = bannerAd;
                } 
            }
        };
        InMobiBanner.requestAd(this, mInMobiAdRequest, mListener);
        ...
    }
    public InMobiBanner getBannerAd() {
        return mBannerAd;
    }
}
	

In the Activity you are trying to monetize, you can then get an instance of this ad unit by calling the getBannerAd() method on your Application subclass.

To display the banner ad, request the ad unit to load the ad markup by calling load(Context), supplying the Activity instance where the ad will be rendered.