Skip to content

Advanced Banner API

Warning

This is the documentation for the Advanced API. Most developers should use our Simplified API, which comes with several built-in features such as:

  • automatic ad loading

  • retries for failed requests

See the documentation for the Simplified API here:

Banner ads occupy a small portion of the user interface, usually at the bottom or the top of the screen. To show one in your app, you access its view property and add it to the current view hierarchy.

Create a Banner instance

val size = Banner.Size.Phone /* or Banner.Size.Tablet */
val banner = Banner.create(activity, "<placement-id>", size)

final Banner.Size size = Banner.Size.Phone.INSTANCE; /* or Banner.Size.Tablet.INSTANCE */
final Banner banner = Banner.create(activity, "<placement-id>", size);

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

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

Register ad callbacks

banner.listener = object : Banner.Listener {
    override fun onPrebiddingFinished(result: PrebiddingResults) {
        Log.d("Banner", "Banner client-side bidding finished!")
    }

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

    override fun onFailedToLoad(loadError: LoadError, loadResult: LoadResult?) {
        Log.d("Banner", "Banner failed to load. Reason: ${loadError.message}")
    }

    // Impression Callback
    override fun onImpression(impressionData: ImpressionData) {
        Log.d("Banner", "Banner impression, with revenue: ${impressionData.revenue}")
    }
}

banner.setListener(new Banner.Listener() {
    @Override
    public void onPrebiddingFinished(@NonNull PrebiddingResults result) {
        Log.d("Banner", "Banner client-side bidding finished!");
    }

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

    @Override
    public void onFailedToLoad(@NonNull LoadError loadError, @Nullable LoadResult loadResult) {
        Log.d("Banner", "Banner failed to load. Reason: " + loadError.getMessage());
    }

    // Impression Callback
    @Override
    public void onImpression(@NonNull ImpressionData impressionData) {
        Log.d("Banner", "Banner impression, with revenue: " + impressionData.getRevenue());
    }

    @Override
    public void onClicked() {
    }

    @Override
    public void onNetworkImpression(@NonNull LoadResult loadResult) {
    }

    @Override
    public void onShowed() {
    }

    @Override
    public void onFailedToShow(@NonNull ShowError showError) {
    }

    @Override
    public void onDismissed() {
    }
});

Load an ad

banner.load()

banner.load();

Load an ad (with custom properties)

banner.load(
    buildCustomProperties {
        addString("game_mode", "classic")
    }
)

banner.load(
    new CustomProperties.Builder()
        .addString("game_mode", "classic")
        .build()
);

Displaying the banner

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

  • After creating the Banner instance.
  • After the onLoaded(loadResult) listener callback is called.
val bannerContainer = findViewById<ViewGroup>(R.id.bannerContainer)
val bannerView = banner.view

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

bannerContainer.addView(bannerView)

ViewGroup bannerContainer = findViewById(R.id.bannerContainer);
View bannerView = banner.getView();

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

bannerContainer.addView(bannerView);

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.

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.

Code example

BannerSample.kt 
import android.os.Bundle
import android.util.Log
import android.view.ViewGroup
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import com.etermax.xmediator.core.api.Banner
import com.etermax.xmediator.core.api.entities.ImpressionData
import com.etermax.xmediator.core.api.entities.LoadError
import com.etermax.xmediator.core.api.entities.LoadResult
import com.example.yourapp.R

class BannerSample : AppCompatActivity() {

    private var banner: Banner? = null

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

        findViewById<Button>(R.id.button_load).setOnClickListener {
            Log.d("BannerSample", "Load button clicked")

            // Dispose previous banner instance
            banner?.destroy()
            findViewById<ViewGroup>(R.id.banner_container).removeAllViews()

            // Create an banner instance
            banner = Banner.create(
                activity = this,
                placementId = "3-15/28",
                size = Banner.Size.Phone,
            )

            // Add banner to view hierarchy
            findViewById<ViewGroup>(R.id.banner_container).addView(banner?.view)

            // Setup callbacks
            banner?.listener = object : Banner.Listener {
                override fun onLoaded(loadResult: LoadResult) {
                    Log.d("BannerSample", "Loaded!")
                }

                override fun onFailedToLoad(loadError: LoadError, loadResult: LoadResult?) {
                    Log.d("BannerSample", "Failed to load. Reason: ${loadError.message}")
                }

                override fun onImpression(impressionData: ImpressionData) {
                    Log.d("BannerSample", "Impression with revenue: ${impressionData.revenue}")
                }
            }

            // Request an ad
            banner?.load()
        }
    }
}