Interstitial integration for Android

Facilitate the integration of interstitial ads in your ironSource Android app by initializing the ad unit, setting a listener, loading the ad, checking its availability, and displaying it at appropriate moments.

Read time 11 minutes

The Unity LevelPlay Interstitial is a full-screen ad unit, usually served at natural transition points during the app lifecycle. 

Prerequisites
Prerequisites

  • Ensure that you have correctly integrated the ironSource SDK into your application. Integration is outlined here.
  • Ensure that you initialize the SDK using LevelPlay Initialization API.
  • Find the AdUnitID in LevelPlay dashboard.

Create Interstitial Ad Object
Create Interstitial Ad Object

The creation of the interstitial ad object must be performed after receiving the onInitSuccess callback.

The object is a reusable instance that can handle multiple loads and shows throughout the session. After creation, it should be used to load and show ads for the same ad unit.

For more advanced implementations, you may create multiple interstitial ad objects if necessary.

LevelPlayInterstitialAd mInterstitialAd = new LevelPlayInterstitialAd("adUnitId");

val mInterstitialAd = LevelPlayInterstitialAd("adUnitId")

Set Interstitial Listener
Set Interstitial Listener

Implement the LevelPlayInterstitialAdListener in your code to get informed of ad delivery. 

  • It is recommended to set the listener before loading the interstitial ad.
  • Each interstitial ad should have its own listener implementation.
  • Callbacks run on the main thread.
// Create the interstitial ad object
LevelPlayInterstitialAd mInterstitialAd = new LevelPlayInterstitialAd("adUnitId");
mInterstitialAd.setListener(new LevelPlayInterstitialAdListener() {
    @Override
    public void onAdLoaded(LevelPlayAdInfo levelPlayAdInfo) {
        // Ad was loaded successfully
    }
    @Override
    public void onAdLoadFailed(LevelPlayAdError levelPlayAdError) {
        // Ad load failed 
    }
    @Override
    public void onAdDisplayed(LevelPlayAdInfo levelPlayAdInfo) {
        // Ad was displayed and visible on screen
    }
    @Override
    public void onAdDisplayFailed(LevelPlayAdError levelPlayAdError, LevelPlayAdInfo levelPlayAdInfo) {
        // Ad fails to be displayed
        // Optional
    }
    @Override
    public void onAdClicked(LevelPlayAdInfo levelPlayAdInfo) {
        // Ad was clicked
        // Optional
    }
    @Override
    public void onAdClosed(LevelPlayAdInfo levelPlayAdInfo) {
        // Ad was closed
        // Optional
    }
    @Override
    public void onAdInfoChanged(LevelPlayAdInfo levelPlayAdInfo) {
        // Called after the ad info is updated. Available when another interstitial ad has loaded, and includes a higher CPM/Rate
        // Optional
    }
});

// Create the interstitial ad object 
val mInterstitialAd = LevelPlayInterstitialAd("adUnitId")
mInterstitialAd.setListener(object : LevelPlayInterstitialAdListener {
    override fun onAdLoaded(levelPlayAdInfo: LevelPlayAdInfo) {
        // Ad was loaded successfully
    }
    override fun onAdLoadFailed(levelPlayAdError: LevelPlayAdError) {
        // Ad load failed
    }
    override fun onAdDisplayed(levelPlayAdInfo: LevelPlayAdInfo) {
        // Ad was displayed and visible on screen
    }
    override fun onAdDisplayFailed(levelPlayAdError: LevelPlayAdError, levelPlayAdInfo: LevelPlayAdInfo) {
        // Ad fails to be displayed
        // Optional
    }
    override fun onAdClicked(levelPlayAdInfo: LevelPlayAdInfo) {
        // Ad was clicked
        // Optional
    }
    override fun onAdClosed(levelPlayAdInfo: LevelPlayAdInfo) {
        // Ad was closed
        // Optional
    }
    override fun onAdInfoChanged(levelPlayAdInfo: LevelPlayAdInfo) {
        // Called after the ad info is updated. Available when another interstitial ad has loaded, and includes a higher CPM/Rate
        // Optional
    }
})

LevelPlay Ad Info
LevelPlay Ad Info

The LevelPlayAdInfo parameter includes information about the loaded ad.

Learn more about its implementation and available fields here.

Load Interstitial Ad
Load Interstitial Ad

To load an interstitial ad use loadAd.

mInterstitialAd.loadAd();

mInterstitialAd.loadAd()

Show Interstitial Ad
Show Interstitial Ad

Show an interstitial ad after you receive the onAdLoaded callback using the LevelPlayInterstitialAdListener APIs.

  • It is required to share Activity. 
  • If using placements, pass the placement name in the showAd API as shown in the Placements section below.
  • After the ad has been successfully displayed to the user, you can load another ad by repeating the loading step. 
public void showInterstitialAd() {
    // Check that ad is ready
    if (mInterstitialAd.isAdReady()) {
        // Show ad 
        mInterstitialAd.showAd(this);
    }
}

fun showInterstitialAd() {
    // Check that ad is ready
    if (mInterstitialAd.isAdReady()) {
        // Show ad
        mInterstitialAd.showAd(this)
    }
}

Check Ad is Ready
Check Ad is Ready

To avoid show failures, and to make sure the ad could be displayed correctly, we recommend using the following API before calling the showAd API.

isAdReady – returns true if ad was loaded successfully and ad unit is not capped, or false otherwise.

isPlacementCapped – returns true when a valid placement is capped. If the placement is not valid, or not capped, this API will return false.

// Check that ad is ready and that the placement is not capped 
if (mInterstitialAd.isAdReady() && !LevelPlayInterstitialAd.isPlacementCapped(placementName)) {
    mInterstitialAd.showAd(this, placementName);
}

// Check that ad is ready and that the placement is not capped
if (mInterstitialAd.isAdReady() && !LevelPlayInterstitialAd.isPlacementCapped(placementName)) {
    mInterstitialAd.showAd(this, placementName)
}

Placements
Placements

We support placements pacing and capping for interstitial on the LevelPlay dashboard. 

If placements are set up for interstitial ads, call the showAd method to serve the ad for a specific placement.

public void showInterstitialAdWithPlacement() {
    // Check that ad is ready and that the placement is not capped 
    if (mInterstitialAd.isAdReady() && !LevelPlayInterstitialAd.isPlacementCapped(placementName)) {
        // Show ad with placement 
        mInterstitialAd.showAd(this, placementName);
    }
}

fun showInterstitialAdWithPlacement(placementName: String) {
    // Check that ad is ready and that the placement is not capped
    if (mInterstitialAd.isAdReady() && !LevelPlayInterstitialAd.isPlacementCapped(placementName)) {
        // Show ad with placement
        mInterstitialAd.showAd(this, placementName)
    }
}

Full Implementation Example of Interstitial Ads
Full Implementation Example of Interstitial Ads

public class InterstitialAdActivity extends Activity implements LevelPlayInterstitialAdListener { 
    private LevelPlayInterstitialAd mInterstitialAd;
    void createInterstitialAd() { 
        mInterstitialAd = new LevelPlayInterstitialAd("adUnitId"); 
        mInterstitialAd.setListener(this); 
    } 
    void loadInterstitialAd() { 
        // Used to load or reload the ad 
        mInterstitialAd.loadAd(); 
    } 
    void showInterstitialAd() { 
        if (mInterstitialAd.isAdReady()) { 
            mInterstitialAd.showAd(this); 
        }
    }
    void showInterstitialAd(@NonNull String placementName) { 
        // Check that ad is ready and that the placement is not capped 
        if (mInterstitialAd.isAdReady() && !LevelPlayInterstitialAd.isPlacementCapped(placementName)) { 
            mInterstitialAd.showAd(this, placementName); 
        } 
    }
 
    // LevelPlayInterstitialAdListener methods 
    @Override 
    public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {} 
    @Override 
    public void onAdLoadFailed(@NonNull LevelPlayAdError error) {} 
    @Override 
    public void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {} 
    @Override 
    public void onAdClosed(@NonNull LevelPlayAdInfo adInfo) {} 
    @Override 
    public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {} 
    @Override 
    public void onAdDisplayFailed(@NonNull LevelPlayAdError error, @NonNull LevelPlayAdInfo adInfo) {} 
    @Override 
    public void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) {} 
}

class InterstitialAdActivity : Activity(), LevelPlayInterstitialAdListener {
    private lateinit var mInterstitialAd: LevelPlayInterstitialAd
    fun createInterstitialAd() {
        mInterstitialAd = LevelPlayInterstitialAd("adUnitId")
        mInterstitialAd.setListener(this)
    }
    fun loadInterstitialAd() {
        mInterstitialAd.loadAd()
    }
    fun showInterstitialAd() {
        if (mInterstitialAd.isAdReady()) {
            mInterstitialAd.showAd(this)
        }
    }
    fun showInterstitialAd(placementName: String) {
        // Check that ad is ready and that the placement is not capped 
        if (mInterstitialAd.isAdReady() && !LevelPlayInterstitialAd.isPlacementCapped(placementName)) {
            mInterstitialAd.showAd(this, placementName)
        }
    }
    // LevelPlayInterstitialAdListener methods
    override fun onAdLoaded(adInfo: LevelPlayAdInfo) {}
    override fun onAdLoadFailed(error: LevelPlayAdError) {}
    override fun onAdInfoChanged(adInfo: LevelPlayAdInfo) {}
    override fun onAdDisplayed(adInfo: LevelPlayAdInfo) {}
    override fun onAdDisplayFailed(error: LevelPlayAdError, adInfo: LevelPlayAdInfo) {}
    override fun onAdClicked(adInfo: LevelPlayAdInfo) {}
    override fun onAdClosed(adInfo: LevelPlayAdInfo) {}
}

LevelPlay Mediation Demo App
LevelPlay Mediation Demo App

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

Download Android Demo Application

Verify your integration with our Integration Test Suite.

Next steps
Next steps

Follow our integration guides to integrate additional Interstitial Ad networks or configure additional ad formats: