Banner

Banner ads occupy a small portion of the user interface, usually at the bottom or the top of the screen.

To start using banners, just call create() using a valid placement id and a size. To show one in your app, you call its getView() method and add the view to the current view hierarchy.

Start loading a Banner

KotlinJava

XMediatorAds.startWith(
    activity = activity,
    appKey = appKey,
    initCallback = {
        val size = Banner.Size.Phone /* or Banner.Size.Tablet */
        XMediatorAds.Banner.create(BANNER_PLACEMENT_ID, size)
    }
)

XMediatorAds.startWith(activity, APP_KEY, initResult -> {
    Log.d("InitResult", initResult.toString());
    final Banner.Size size = Banner.Size.Phone.INSTANCE; /* or Banner.Size.Tablet.INSTANCE */
    XMediatorAds.getBanner().create(BANNER_PLACEMENT_ID, size)
    return Unit.INSTANCE;
});

When creating a banner, in addition to the placementId, you have to provide:

• size: Size of the banner. See Size for the available sizes.

Showing a banner

The most common practice is to add the banner view to the view hierarchy either:

• After creating the Banner instance.
• After the onLoaded(placementId,result) callback is called.

KotlinJava

fun showBanner(container: ViewGroup) {
    val view = XMediatorAds.Banner.getView(BANNER_PLACEMENT_ID)
    if (view == null) {
        Toast.makeText(activity, "Error showing banner, not created", Toast.LENGTH_SHORT).show()
    } else {
        val parentView = view.parent as? ViewGroup
        if (parentView == container) return

        // Optionally, set the ad space where the banner will be shown
        XMediatorAds.Banner.setAdSpace(BANNER_PLACEMENT_ID, "banner-ad-space")

        parentView?.removeView(view)
        container.addView(view)
    }
}

public void showBanner(ViewGroup container) {
    View view = XMediatorAds.getBanner().getView(BANNER_PLACEMENT_ID);
    if (view == null) {
        Toast.makeText(activity, "Error showing banner, not created", Toast.LENGTH_SHORT).show();
    } else {
        ViewGroup parentView = (ViewGroup) view.getParent();
        if (parentView == container) return;
        if (parentView != null) {

            // Optionally, set the ad space where the banner will be shown
            XMediatorAds.getBanner().setAdSpace(BANNER_PLACEMENT_ID, "banner-ad-space");

            parentView.removeView(view);
            container.addView(view);
        }
    }
}

Built-in features

Banner autorefresh

After being displayed for some time, our banner fires a Load() call automatically to refresh its contents. You can configure this time through our Admin tool for each one of your banners.

Banner retry

Our banner has a built in auto retry for failed loads attempts. This means that when a banner fails to load, it will retry again until it loads successfully. Time between each retry attemp will increase using an exponential backoff. You should not add any retry logic on your end, as it may interefere with our retry behaviour.

Additional settings

Register ad callbacks

Every ad callback indicates the placement id of the banner that triggered the event.

KotlinJava

XMediatorAds.Banner.addListener(object : BannerAds.Listener {

    override fun onImpression(placementId: String, impressionData: ImpressionData) {
        Log.d("Banner", "Banner impression ecpm: ${impressionData.ecpm}")
    }

    override fun onLoaded(placementId: String, loadResult: LoadResult) {
        Log.d("Banner", "Banner loaded")
    }

    override fun onClicked(placementId: String) {
        Log.d("Banner", "Banner clicked")
    }
})

XMediatorAds.getBanner().addListener(new BannerAds.Listener() {

    @Override
    public void onLoaded(@NonNull String placementId, @NonNull LoadResult loadResult) {
        Log.d("Banner", "Banner loaded");
    }

    @Override
    public void onImpression(@NonNull String placementId, @NonNull ImpressionData impressionData) {
        Log.d("Banner", "Banner impression ecpm: " + impressionData.getEcpm());
    }

    @Override
    public void onClicked(@NonNull String placementId) {
        Log.d("Banner", "Banner clicked");
    }
});

(Optional) Updating ad space

Before showing an ad, you can set an ad space name for the banner instance. This is useful for tracking purposes because it enables you to get performance insights for different ad spaces of your application.

KotlinJava

XMediatorAds.Banner.setAdSpace(BANNER_PLACEMENT_ID, "banner-ad-space")

XMediatorAds.getBanner().setAdSpace(BANNER_PLACEMENT_ID, "banner-ad-space");

(Optional) Manually refreshing a banner ad

Banner ads usually refresh their contents automatically, after a certain amount of time has passed. However, if you prefer to, you can manually refresh a banner's content by calling the load method:

KotlinJava

XMediatorAds.Banner.load("<placement-id>")

XMediatorAds.getBanner().load("<placement-id>");

Advanced use cases

This guide provides the recommended integration steps to show a banner ad using X3M, which covers most of the common scenarios. For advanced use cases, where manually handling the lifecycle of the ad object is needed, refer to this section.

Code example

BannerSample.kt

import android.app.Activity
import android.os.Bundle
import android.util.Log
import android.view.ViewGroup
import android.widget.Button
import android.widget.LinearLayout
import android.widget.Toast
import com.etermax.R
import com.etermax.xmediator.core.api.Banner
import com.etermax.xmediator.core.api.entities.ImpressionData
import com.etermax.xmediator.core.api.entities.LoadResult
import com.x3mads.android.xmediator.core.api.BannerAds
import com.x3mads.android.xmediator.core.api.XMediatorAds

class BannerSample : Activity() {
    private val appKey = "app_key"
    private val bannerPlacementId = "placement_id"

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_interstitial)
        findViewById<Button>(R.id.button_load).setOnClickListener {
            XMediatorAds.startWith(
                activity = this,
                appKey = appKey,
                initCallback = {
                    XMediatorAds.Banner.addListener(bannerListener)
                    XMediatorAds.Banner.create(bannerPlacementId, Banner.Size.Phone)
                }
            )
        }
        findViewById<Button>(R.id.button_show).setOnClickListener {
            val viewGroup = findViewById<LinearLayout>(R.id.bannerContainer) as ViewGroup
            showBanner(viewGroup)
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        XMediatorAds.Banner.removeListener(bannerListener)
    }
    private fun showBanner(container: ViewGroup) {
        val view = XMediatorAds.Banner.getView(bannerPlacementId)
        if (view == null) {
            Toast.makeText(this, "Error showing banner, not requested", Toast.LENGTH_SHORT).show()
        } else {
            val parentView = view.parent as? ViewGroup
            if (parentView == container) return
            parentView?.removeView(view)
            container.addView(view)
        }
    }

    private val bannerListener = object : BannerAds.Listener {

        override fun onLoaded(placementId: String, loadResult: LoadResult) {
            Log.d("SimplifyPresenter", "Banner loaded. Placement $placementId, result: $loadResult")
        }

        override fun onImpression(placementId: String, impressionData: ImpressionData) {
            Log.d("SimplifyPresenter", "Banner impression for placementId: $placementId, data: $impressionData")
        }

        override fun onClicked(placementId: String) {
            Log.d("SimplifyPresenter", "Banner clicked for placementId: $placementId")
        }
    }
}