Contact usContact us

Interstitial Ad Unit’s API

This guide explains how to integrate the LevelPlay APIs available to use starting from SDK 8.4.0 (aka LevelPlay APIs), using an ad unit ID as a waterfall identifier, to load and display interstitial ads.

⚡ Before you start APIs introduced in this article should be used instead of the integration methods currently in use (ironSource init, ironSource load interstitial, interstitial listeners)

There was no change in the APIs supporting rewarded ads, and it should continue to work as is, after SDK initialization

The advanced settings and regulations settings have not been changed, and they are supported before or after initializing the LevelPlay SDK.

Step 1:  Locate the ad unit ID in the LevelPlay platform

To load and display interstitial ads, you need to use the ad unit ID available in LevelPlay mediation platform:

In your LevelPlay account, navigate to Setup → Ad Units

Copy the interstitial’s ad unit ID and integrate it into your code

Step 2: Initializing the ironSource SDK

To initialize the ironSource SDK, follow these steps:

Define the list of ad formats to initialize in the session. This should include all the ad formats that you would like to use in LevelPlay, integrating the ironSource APIs (supported for SDK < 8.1.0).

Implement callbacks for initialization success and failure.

Call LevelPlay init API using the appkey, ad formats, and user ID if relevant.

    // Init the SDK when implementing the Multiple Ad Units Interstitial API, and Rewarded & Banner using legacy APIs 
    List<LevelPlay.AdFormat> legacyAdFormats = Arrays.asList(LevelPlay.AdFormat.BANNER, LevelPlay.AdFormat.REWARDED);

    LevelPlayInitRequest initRequest = new LevelPlayInitRequest.Builder(appKey)
                .withLegacyAdFormats(legacyAdFormats)
                .build();
       LevelPlayInitListener initListener = new LevelPlayInitListener() {
            @Override
            public void onInitFailed(@NonNull LevelPlayInitError error) {
            }
            @Override
            public void onInitSuccess(LevelPlayConfiguration configuration) {
            }
        };
        LevelPlay.init(context, initRequest, initListener);

    // Init the SDK when implementing the Multiple Ad Units Interstitial API, and Rewarded & Banner using legacy APIs 
 
    val legacyAdFormats =    listOf(LevelPlay.AdFormat.INTERSTITIAL,LevelPlay.AdFormat.REWARDED)
    val initRequest = LevelPlayInitRequest.Builder("AppKey")
        .withLegacyAdFormats(legacyAdFormats)
	 .withUserId("UserId")
        .build()
    LevelPlay.init(context, initRequest, object: LevelPlayInitListener {
        override fun onInitSuccess(configuration: LevelPlayConfiguration) {
            //load banner ad
        }
        override fun onInitFailed(error: LevelPlayInitError) {
        }
    })

LevelPlay Init Listeners

OnInitSuccess – triggered when the initialization is completed successfully. After you receive this indication, you can create and load the ad.

OnInitFailed – the configuration was not retrieved successfully and ads cannot be loaded. It is recommended to try and initialize the ironSource SDK later (when internet connection is available, or when the failure reason is resolved)

Step 3: Create interstitial and register to events

Once you receive the OnInitSuccess callback you can create an ad unit using the relevant Ad Unit ID, as defined in the LevelPlay platform (step #1). Set the interstitial listener for the interstitial ad unit created, to get informed of ad delivery.

  mInterstitialAd = new LevelPlayInterstitialAd("adUnitId"); 
  mInterstitialAd.setListener(this);
 
  // 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 onAdDisplayFailed(@NonNull LevelPlayAdError error, @NonNull 
 LevelPlayAdInfo adInfo) {}
  @Override public void onAdClosed(@NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {} 
  @Override
  public void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) {}

  mInterstitialAd = new LevelPlayInterstitialAd("adUnitId"); 
  mInterstitialAd.setListener(this);

  // 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 interstitial Listeners

OnAdLoaded – Provided when the ad is successfully loaded

OnAdLoadFailed – Provided when the ad fails to load. Ad Unit information is included

OnAdDisplayed – Provided when the ad is displayed. This is equivalent to an impression

OnAdDisplayFailed (optional) – Provided when the ad fails to be displayed

OnAdClicked (optional) – Provided when the user clicks on the ad

OnAdClosed – Provided when the ad is closed

OnAdInfoChanged (optional) – Provided when the ad info is updated. Available when another ad has loaded, and includes a higher CPM/Rate

Step 4: Load interstitial ad

Once you receive the OnInitSuccess callback, you are ready to load an interstitial ad. This should be done using the method:

   // Load or reload the ad
   mInterstitialAd.loadAd();
   // Load or reload the ad
   mInterstitialAd.loadAd()

Note: For SDK 8.3.0 when calling LoadAd after the ad was already loaded (before displaying it), LevelPlay will not trigger another mediation load. This means that if you want a refreshed ad, you should either show the ad, or destroy the object. This should be changed in SDK 8.4.0.

Step 5: Show interstitial ad

You can show an interstitial ad after you receive onAdLoaded callback, using the showAd APIs.
Using this API you are required to share Activity. If you are using placements you should share their name as part of the API, as described below.

    // Show ad without placement 
    mInterstitialAd.showAd(this);
    // Show ad with placement 
    mInterstitialAd.showAd(this, placementName);

    // Show ad without placement 
    mInterstitialAd.showAd(this)
    // Show ad with placement 
    mInterstitialAd.showAd(this, placementName)

Check ad 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)
    }

Once the ad was displayed successfully to the player, you can load another ad, repeating step #4. There is no need to create a new ad entity, when loading a single ad at a time.

Implementation example

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 placmentName) {
    // 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 Ad Info

Ad Info

Learn more about LevelPlay Ad Info implementation and available fields here.