Banner

Banner ads are rectangular image or text ads that occupy a space inside the application layout. They stay on screen while the users interact with the app and can automatically refresh after a certain period of time. If you are new in mobile advertising, they are an excellent choice to start.

Integration

There are two ways to integrate a banner: using code or adding the banner view inside a layout. Below we show some examples for both methods:

Layout XML

<com.wortise.ads.banner.BannerAd
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:adSize="HEIGHT_50"
    app:adUnitId="Wortise Ad Unit ID" />

The widget has support for the following parameters:

Parameter	Type	Required	Description
app:adUnitId	String	Yes	The ad unit ID to assign to the banner
app:adSize	AdSize	No	Maximum size (height) for the banner. The possible values for this parameter are declared in the AdSize class
app:autoRefreshTime	Integer	No	Value in seconds that represents the time that must elapse to load a new banner ad

Code

Kotlin

class MainActivity : Activity() {

    private var bannerAd: BannerAd? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        bannerAd = BannerAd(this).also {
          it.adSize = AdSize.HEIGHT_50
          it.adUnitId = "<Ad Unit ID de Wortise>"

          // For example, we add the BannerAd into a FrameLayout
          val frameLayout = findViewById<FrameLayout>(R.id.frame)
          frameLayout.addView(it)

          it.loadAd()
        }
    }

    override fun onDestroy() {
        ...
        bannerAd?.destroy()
    }

    override fun onPause() {
        ...
        bannerAd?.pause()
    }

    override fun onResume() {
        ...
        bannerAd?.resume()
    }
}

Java

public class MainActivity extends Activity {

    private BannerAd mBannerAd;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        ...
        mBannerAd = new BannerAd(this);
        mBannerAd.setAdSize(AdSize.HEIGHT_50);
        mBannerAd.setAdUnitId("Wortise Ad Unit ID");

        // For example, we add the BannerAd into a FrameLayout
        FrameLayout frameLayout = findViewById(R.id.frame);
        frameLayout.addView(mAdView);

        mBannerAd.loadAd();
    }

    @Override
    public void onDestroy() {
        ...
        mBannerAd.destroy();
    }

    @Override
    public void onPause() {
        ...
        mBannerAd.pause();
    }

    @Override
    public void onResume() {
        ...
        mBannerAd.resume();
    }
}

The BannerAd class providers the following methods to configure the instance:

Method	Required	Description
setAdUnitId(String)	Yes	Assigns an ad unit to the banner
setAdSize(AdSize)	No	Maximum size (height) for the banner. The possible values for this parameter are declared in the AdSize class
setAutoRefreshTime(long)	No	Value in milliseconds that represents the time that must elapse to load a new banner ad
setAutoRefreshTime(long, TimeUnit)	No	Same as previous method, but lets you specify the time unit of the passed value

Adaptive banners

Adaptive banners are a new banner format where the size of the ads is adapted according to the device and the app user-interface, in order to maximize performance.

Currently there is support for two kind of adaptive banners:

Anchored

This kind of banner is designed to replace the traditional 320x50 banners and be positioned at the top or bottom of the screen.

To use this format, the following code must be used to configure an adaptive size:

Kotlin

// You need to specify the banner width
val adSize = AdSize.getAnchoredAdaptiveBannerAdSize(context, width)
bannerAd.adSize = adSize

Java

// You need to specify the banner width
AdSize adSize = AdSize.getAnchoredAdaptiveBannerAdSize(context, width);
mBannerAd.setAdSize(adSize);

Alternatively, this other option can be implemented to let the SDK calculate the banner width, where the BannerAd instance itself or the View that will contain it should be passed:

Caution

In this option, it is highly recommended that the View passed to the method is already added to the app’s layout, so that the SDK can correctly calculate all the dimensions.

Kotlin

val adSize = AdSize.getAnchoredAdaptiveBannerAdSize(view)
bannerAd.adSize = adSize

Java

AdSize adSize = AdSize.getAnchoredAdaptiveBannerAdSize(view);
mBannerAd.setAdSize(adSize);

Inline

This other kind of banner, in comparison to the anchored, is designed to have a variable height and be positioned inside a scrolling content.

In this case, the following code must be used to configure a proper adaptive size:

Kotlin

val maxHeight = 200

// You need to specify the banner width. The maximum height is an
// optional parameter
val adSize = AdSize.getInlineAdaptiveBannerAdSize(context, width, maxHeight)
bannerAd.adSize = adSize

Java

int maxHeight = 200;

// You need to specify the banner width. The maximum height is an
// optional parameter
AdSize adSize = AdSize.getInlineAdaptiveBannerAdSize(
    context, width, maxHeight
);
mBannerAd.setAdSize(adSize);

Alternatively, this other option can be implemented to let the SDK calculate the banner width, where the BannerAd instance itself or the View that will contain it should be passed:

Caution

In this option, it is highly recommended that the View passed to the method is already added to the app’s layout, so that the SDK can correctly calculate all the dimensions.

Kotlin

val maxHeight = 200

val adSize = AdSize.getInlineAdaptiveBannerAdSize(view, maxHeight)
bannerAd.adSize = adSize

Java

int maxHeight = 200;

AdSize adSize = AdSize.getInlineAdaptiveBannerAdSize(view, maxHeight);
mBannerAd.setAdSize(adSize);

Collapsible banners

Collapsible banners are anchored banners that are initially shown as a larger overlay, with a button that collapses them to their declared size. They are meant to improve the performance of anchored banners without taking up more space permanently.

To request one, pass a RequestParameters instance with the desired position to the loadAd method:

Kotlin

val parameters = RequestParameters(
    collapsible = CollapsiblePosition.BOTTOM
)

bannerAd.loadAd(parameters)

Java

RequestParameters parameters = new RequestParameters();
parameters.setCollapsible(CollapsiblePosition.BOTTOM);

mBannerAd.loadAd(parameters);

The position determines where the expanded ad is anchored, and it must match the position of the banner inside the app layout:

Value	Description
CollapsiblePosition.BOTTOM	The banner is placed at the bottom of the screen
CollapsiblePosition.TOP	The banner is placed at the top of the screen

Note

Collapsible banners require an anchored adaptive size, so make sure the banner has been configured as explained in the Anchored section.

Caution

The collapsible format is only requested for the first ad of a BannerAd instance. When the banner refreshes, the following ads are requested as regular anchored banners.

Listener setup

A listener can be set to any BannerAd instance to receive the events that happen during its lifecycle. For this, you need to implement the BannerAd.Listener interface as shown in the example below:

Kotlin

bannerAd.listener = object : BannerAd.Listener() {

    override fun onBannerClicked(ad: BannerAd) {
        // Invoked when the ad has been clicked
    }

    override fun onBannerFailedToLoad(ad: BannerAd, error: AdError) {
        // Invoked when the ad could not be loaded
        // (because of an error or no fill)
    }

    override fun onBannerImpression(ad: BannerAd) {
        // Invoked when the ad has generated an impression
    }

    override fun onBannerLoaded(ad: BannerAd) {
        // Invoked when the ad has been loaded
    }

    override fun onBannerRevenuePaid(ad: BannerAd,
                                     data: RevenueData) {
        // Invoked when the ad has generated revenue
    }
}

Java

mBannerAd.setListener(new BannerAd.Listener() {
    @Override
    public void onBannerClicked(@NonNull BannerAd ad) {
        // Invoked when the ad has been clicked
    }

    @Override
    public void onBannerFailedToLoad(@NonNull BannerAd ad,
                                     @NonNull AdError error) {
        // Invoked when the ad could not be loaded
        // (because of an error or no fill)
    }

    @Override
    public void onBannerImpression(@NonNull BannerAd ad) {
        // Invoked when the ad has generated an impression
    }

    @Override
    public void onBannerLoaded(@NonNull BannerAd ad) {
        // Invoked when the ad has been loaded
    }

    @Override
    public void onBannerRevenuePaid(@NonNull BannerAd ad,
                                     @NonNull RevenueData data) {
        // Invoked when the ad has generated revenue
    }
});