Migrate to Banner Ad Units API

This guide explains how to transition to the LevelPlay Banner APIs (using an ad unit ID) from your current implementation, to load and display banner ads.

Before you start
  • The min supported SDK is 8.4.0. You can download the latest SDK here.
  • Make sure to initalize the SDK using LevelPlay Initalization API. Learn more here.
  • You can find the AdUnitID in LevelPlay dashboard. Learn more here.

Create Banner Ad Object and Set Size

The creation of the banner ad object should be done after receiving onInitSuccess callback.

// Create the banner view and set the ad unit id
LevelPlayBannerAdView levelPlayBanner = new LevelPlayBannerAdView(context, "adUnitId");
// Create the banner view and set the ad unit id
val levelPlayBanner = LevelPlayBannerAdView(context, "adUnitId")

Legacy Ad Unit (new) Dimensions in dp
ISBannerSize LevelPlayAdSize (Width X Height)
BANNER BANNER 320 x 50
LARGE LARGE 320 x 90
RECTANGLE MEDIUM_RECTANGLE 300 x 250
SMART Replaced by Adaptive Ad Size (see below) Automatically renders ads to adjust size and orientation for mobile & tablets

To create the ad size follow one of these options: 

Adaptive ad size that adjusts to the screen width (recommended):
This option returns BANNER or LEADERBOARD according to the device type.
Networks that supports adaptive feature (Google, Yandex) will return the a height based on their optimization logic.

 LevelPlayAdSize adSize = LevelPlayAdSize.createAdaptiveAdSize(context);
 val adSize = createAdaptiveAdSize(context)

Specific banner size:
This option allows you to set specifically a banner size: BANNER, LARGE, MEDIUM_RECTANGLE.

levelPlayBanner.setAdSize(LevelPlayAdSize.MEDIUM_RECTANGLE);
levelPlayBanner.setAdSize(LevelPlayAdSize.MEDIUM_RECTANGLE) 

Placements

We support placements in banners for reporting only. Placements should be set before the loadAd, to affect all reloaded ads.

// Set the placement name
levelPlayBanner.setPlacementName("placementName");
// Set the placement name
levelPlayBanner.setPlacementName("placementName")

Set Banner Listener

Implement the LevelPlayBannerAdViewListener in your code, instead of the listener LevelPlayBannerListener.

  • It is recommended to set the listener before loading the banner ad.
  • Please note that each banner ad should have its own listener implementation.
  • Callbacks run on the main thread.
levelPlayBanner.setBannerListener(new LevelPlayBannerAdViewListener() {
    @Override
    public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {
    // Ad was loaded successfully 
    }
    @Override
    public void onAdLoadFailed(@NonNull LevelPlayAdError error) {
    // Ad load failed
    }
    @Override
    public void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {
    // Ad was displayed and visible on screen
    }
    @Override
    public void onAdDisplayFailed(@NonNull LevelPlayAdInfo adInfo, @NonNull LevelPlayAdError error) {
    // Ad failed to be displayed on screen
    }
    @Override
    public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {
    // Ad was clicked
    }
    @Override
    public void onAdExpanded(@NonNull LevelPlayAdInfo adInfo) {
    // Ad is opened on full screen
    }
    @Override
    public void onAdCollapsed(@NonNull LevelPlayAdInfo adInfo) {
    // Ad is restored to its original size
    }
    @Override
    public void onAdLeftApplication(@NonNull LevelPlayAdInfo adInfo) 
    // User pressed on the ad and was navigated out of the app 
    }
});
levelPlayBanner.setBannerListener(object: LevelPlayBannerAdViewListener {
    override fun onAdLoaded(adInfo: LevelPlayAdInfo) {
    // Ad was loaded successfully 
    }
    override fun onAdLoadFailed(error: LevelPlayAdError) {
    // Ad load failed
    }
    override fun onAdDisplayed(adInfo: LevelPlayAdInfo) {
    // Ad was displayed and visible on screen
    }
    override fun onAdDisplayFailed(adInfo: LevelPlayAdInfo, error: LevelPlayAdError) {
    // Ad failed to be displayed on screen
    }
    override fun onAdClicked(adInfo: LevelPlayAdInfo) {
    // Ad was clicked
    }
    override fun onAdExpanded(adInfo: LevelPlayAdInfo) {
    // Ad is opened on full screen
    }
    override fun onAdCollapsed(adInfo: LevelPlayAdInfo) {
    // Ad is restored to its original size
    }
    override fun onAdLeftApplication(adInfo: LevelPlayAdInfo) {
    // User pressed on the ad and was navigated out of the app 
    }
})
Legacy Ad Unit (new)
Listener LevelPlayBannerListener LevelPlayBannerAdViewListener
Callbacks onAdLoaded onAdLoaded
onAdLoadFailed onAdLoadFailed
onAdClicked onAdClicked
onAdScreenPresented onAdExpanded
onAdScreenDismissed onAdCollapsed
onAdLeftApplication onAdLeftApplication
onAdDisplayed
onAdDisplayFailed

LevelPlay Ad Info

Ad Info

The AdInfo class returned by the banner listener callbacks has been replaced by LevelPlayAdInfo.

Learn more about its implementation and available fields here.

Load Banner Ad

To load a banner ad use loadAd instead of IronSource.loadBanner.

    // Load the banner ad
    levelPlayBanner.loadAd();
    
    // Load the banner ad
    levelPlayBanner.loadAd()
    

    Pause and Resume Banner Refresh 

    You can pause banner refresh in your code if the refresh value was defined in the platform. Use the following methods to stop the automatic refresh of the banner ad, or re-enable it after pausing. 

    Note:

    When the banner is displayed again, it will complete the time till refresh, from the time it was paused. 

    • pauseAutoRefresh – pauses auto-refresh of the banner ad.
    • resumeAutoRefresh – resumes auto-refresh of the banner ad after it has been paused.
    // Pause refresh
    levelPlayBanner.pauseAutoRefresh();
    // Resume refresh
    levelPlayBanner.resumeAutoRefresh();
    
    // Pause refresh
    levelPlayBanner.pauseAutoRefresh()
    // Resume refresh
    levelPlayBanner.resumeAutoRefresh()

    Destroy Banner Ad

    To destroy a banner, call the destroy method instead of IronSource.destroyBanner.

    A destroyed banner can no longer be shown again. To display more ads, create a new LevelPlayBannerAdView object. 

    levelPlayBanner.destroy()
    
    levelPlayBanner.destroy();
    

    Multiple Ad Unit Banner APIs

    Legacy Ad Unit (new)
    Banner Layout IronSourceBannerLayout LevelPlayBannerAdView 
    API loadBanner loadAd
    destroyBanner destroy
    loadBanner setPlacementName
    LevelPlayAdSize.getWidth
    LevelPlayAdSize.getHeight
    pauseAutoRefresh
    resumeAutoRefresh

    Full Implementation Example of Banner Ads

    Here is an example for creating and loading a banner ad using adaptive banner size.

    public void createAndLoadBanner() {
        // Create the banner view and set the ad unit id
        LevelPlayBannerAdView levelPlayBanner = new LevelPlayBannerAdView(context, "adUnitId");
        
        // Set the placement name (optional)
        levelPlayBanner.setPlacementName("placementName");
        
        // Create the adaptive ad size to support both adaptive, banner and leaderboard (recommended)  
        LevelPlayAdSize adSize = LevelPlayAdSize.createAdaptiveAdSize(context);
        
        // Required when using createAdaptiveAdSize()
        if (adSize != null) {
            levelPlayBanner.setAdSize(adSize);
        }
        
        // Add the banner view to the container
        ViewGroup adContainer = findViewById(android.R.id.adContainer);
        adContainer.addView(levelPlayBanner);
        
        // Load the banner ad
        levelPlayBanner.loadAd();
        
        // To get actual banner layout size (either custom/standard size or adaptive)
        height = adSize.getHeight();
        width = adSize.getWidth();
    }
    fun createAndLoadBanner() {
        // Create the banner view and set the ad unit id
        val levelPlayBanner = LevelPlayBannerAdView(context, "adUnitId")
        
        // Set the placement name
        levelPlayBanner.setPlacementName("placementName")
        
        // Create the adaptive ad size to support both adaptive, banner and leaderboard
        val adSize = createAdaptiveAdSize(context)
        
        // Required when using createAdaptiveAdSize()
        adSize?.let { levelPlayBanner.setAdSize(it) }
        
        // Add the banner view to the container
        val adContainer = findViewById<ViewGroup>(R.id.adContainer)
        adContainer.addView(levelPlayBanner)
        
        // Load the banner ad
        levelPlayBanner.loadAd()
        
        // Get width and height for the container
        val width = adSize?.getWidth()
        val height = adSize?.getHeight()
    }

    LevelPlay Mediation Demo App

    The Integration Demo application demonstrates how to integrate banner Ad Unit APIs in your app.

    Download Android Demo Application

    Done!

    You are now all set up to serve banner ads in your application using our new Multiple Ad Unit APIs.