Interstitial

This page explains how to use the Smart Display SDK to display an interstitial ad in your application.

Overview
Configuring the SDK
Creating a placement
Loading an interstitial using a manager
Showing an interstitial
Disposing of an interstitial manager

Overview

Interstitials are loaded and displayed using a SASInterstitialManager instance.

To load and display an interstitial ad you need:

A fully configured Smart Display SDK.
An instance of SASAdPlacement that will be used to perform ad calls to the delivery engine.
An instance of SASInterstitialManager to load an ad for the specified placement and show the interstitial if an ad was successfully loaded.
An object implementing the SASInterstitialManager.InterstitialListener listener to monitor interstitial ads lifecycle events.

The next sections describe in details how to load and show an interstitial ad.

You can also refer to the samples if you need a full runnable project.

Configuring the SDK

The Smart Display SDK needs to be configured with your own site ID and base URL before making any ad calls. You will have to call the method configure() of the SASConfiguration shared instance to do so.

This method must be called at least once, as soon as possible.
Ideally call it in the onCreate() method of your Application class. For instance:


public class MyApplication extends MultiDexApplication {
  @Override
  public void onCreate() {
    super.onCreate();

    // 123456 is used as an example, be sure to use your own siteID
    SASConfiguration.getSharedInstance().configure(this, 123456);
  }


class MyApplication : MultiDexApplication() {
  @Override
  public void onCreate() {
    super.onCreate()

    // 123456 is used as an example, be sure to use your own siteID
    SASConfiguration.getSharedInstance().configure(this, 123456)
  }

Any subsequent valid call to the configure() method will update the current configuration with the newly supplied parameters.

Note: Any ad call performed before calling the configure() method will fail by throwing a IllegalStateException.

Creating a placement

You will need an ad placement to perform an ad call. A placement identifies a part of your inventory where you want to display ads.

Creating an ad placement is done by instantiating a SASAdPlacement object using mandatory parameters site ID, page ID, format ID and an optional keyword targeting String that and can be null (more info in the API documentation).


  SASAdPlacement adPlacement = new SASAdPlacement(SOME_SITE_ID, SOME_PAGE_ID, SOME_FORMAT_ID, SOME_KEYWORD_TARGETING);


  val adPlacement = SASAdPlacement(SOME_SITE_ID, SOME_PAGE_ID, SOME_FORMAT_ID, SOME_KEYWORD_TARGETING)

Note that for testing purposes, it is possible to instantiate a generic ad placement that will always deliver an ad from a particular type. This is done by using one of the constants of the SASAdPlacement class.

Warning: Don't forget to remove any test placement before releasing your app.

Loading an interstitial using a manager

Unlike older versions of the Smart Display SDK, interstitial ads are now handled using an interstitial manager which enables a two steps process : load the ad then show it at your convenience.

The interstitial manager is also attached to a unique placement object passed at instantiation time.

The separation of the load and show steps also means that setting a SASInterstitialManager.InterstitialListener on the SASInterstitialManager instance is mandatory (contrary to banner integration).

To load an interstitial, start by creating a new SASInterstitialManager instance using the ad placement defined earlier and an Object implementing the SASInterstitialManager.InterstitialListener interface:


SASInterstitialManager mInterstitialManager = new SASInterstitialManager(this, adPlacement);

SASInterstitialManager.InterstitialListener interstitialListener = new SASInterstitialManager.InterstitialListener() {

  @Override
  public void onInterstitialAdLoaded(SASInterstitialManager interstitialManager, SASAdElement adElement) {
    Log.i("Sample", "Interstitial loading completed");
  }

  @Override
  public void onInterstitialAdFailedToLoad(SASInterstitialManager interstitialManager, Exception e) {
    Log.i("Sample", "Interstitial loading failed (" + e.getMessage() + ")");
  }

  @Override
  public void onInterstitialAdShown(SASInterstitialManager interstitialManager) {
    Log.i("Sample", "Interstitial was shown");
  }

  @Override
  public void onInterstitialAdFailedToShow(SASInterstitialManager interstitialManager, Exception e) {
    Log.i("Sample", "Interstitial failed to show (" + e.getMessage() + ")");
  }

  @Override
  public void onInterstitialAdClicked(SASInterstitialManager interstitialManager) {
    Log.i("Sample", "Interstitial was clicked");
  }

  @Override
  public void onInterstitialAdDismissed(SASInterstitialManager interstitialManager) {
    Log.i("Sample", "Interstitial was dismissed");
  }

  @Override
  public void onInterstitialAdVideoEvent(SASInterstitialManager interstitialManager, int videoEvent) {
    Log.i("Sample", "Video event " + videoEvent + " was triggered on Interstitial");
  }

};

mInterstitialManager.setInterstitialListener(interstitialListener);


// The SASInterstitialManager instance
private val interstitialManager by lazy {
  SASInterstitialManager(this, SASAdPlacement(SOME_SITE_ID, SOME_PAGE_ID, SOME_FORMAT_ID, SOME_KEYWORD_TARGETING))
}

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

  // Setup the interstitial manager listener
  interstitialManager.interstitialListener = object : SASInterstitialManager.InterstitialListener {
    override fun onInterstitialAdLoaded(interstitialManager: SASInterstitialManager?, adElement: SASAdElement?) {
      Log.i("Sample", "Interstitial loading completed.")
    }

    override fun onInterstitialAdFailedToLoad(interstitialManager: SASInterstitialManager?, e: Exception?) {
      Log.i("Sample", "Interstitial failed to load.")
    }

    override fun onInterstitialAdShown(interstitialManager: SASInterstitialManager?) {
      Log.i("Sample", "Interstitial was shown.")
    }

    override fun onInterstitialAdFailedToShow(interstitialManager: SASInterstitialManager?, e: Exception?) {
      Log.i("Sample", "Interstitial failed to show: $e")
    }

    override fun onInterstitialAdDismissed(interstitialManager: SASInterstitialManager?) {
      Log.i("Sample", "Interstitial was dismissed.")
    }

    override fun onInterstitialAdClicked(interstitialManager: SASInterstitialManager?) {
      Log.i("Sample", "Interstitial was clicked.")
    }

    override fun onInterstitialAdVideoEvent(interstitialManager: SASInterstitialManager?, event: Int) {
      Log.i("Sample", "Video event $event was triggered on Interstitial.")
    }
  }
}

There are methods of the listener interface that you can leave empty, but you should at least implement the two methods onInterstitialAdLoaded and onInterstitialAdFailedToLoad used to check if an interstitial ad has been loaded or if it has failed to load.

This will notify you if the interstitial can be shown or if you need to try another load ad call.

Finally, to actually trigger the interstitial ad loading process, call the loadAd() method of the SASInterstitialManager:


mInterstitialManager.loadAd();


interstitialManager.loadAd()

Note 1: the loadAd() method of the SASInterstitialManager executes the ad loading task asynchronously in a different thread from the calling thread. Therefore, if the loadAd() method is called while a previous ad call is being performed and has not finished yet, it will fail with a SASPendingRequestException in the onInterstitialAdFailedToLoad() method of the SASInterstitialManager.InterstitialListener.

Note 2: a consequence of the ad call being performed on a thread different from the main thread (also known as UI thread) is that the onInterstitialAdLoaded() and onInterstitialAdFailedToLoad() methods of the SASInterstitialManager.InterstitialListener are NOT executed from the main thread. Any code in these methods that needs to be run from the main thread MUST be wrapped in a Runnable object which will be executed on the main thread. This can be done using a Handler on the main Thread.


Handler mainLooperHandler = new Handler(Looper.getMainLooper());
mainLooperHandler.post(new Runnable() {
  @Override
  public void run() {
    // execute you UI sensitive code here
  }
});


  Handler(Looper.getMainLooper()).post {
  // execute you UI sensitive code here
}

Showing an interstitial

When the interstitial manager has successfully loaded an ad, you can show it when needed using the show() method.

It is also possible to check the current status of an interstitial manager at any time using the adStatus property.


SASAdStatus adStatus = mInterstitialManager.getAdStatus();
if (adStatus == SASAdStatus.READY) {
  mInterstitialManager.show();
} else if (adStatus == SASAdStatus.NOT_AVAILABLE || adStatus == SASAdStatus.EXPIRED) {
  // The interstitial isn't ready or is maybe expired
}


val adStatus: SASAdStatus = interstitialManager.adStatus
if (adStatus == SASAdStatus.READY) {
  interstitialManager.show()
} else if (adStatus == SASAdStatus.NOT_AVAILABLE || adStatus == SASAdStatus.EXPIRED) {
  // The interstitial isn't ready or is maybe expired
}

Note that the show() method can fail and trigger the SASInterstitialManager.InterstitialListener onInterstitialAdFailedToShow method, providing details about the error in the Exception parameter.

When an interstitial ad has been shown, it is discarded and a new one must be loaded again (the same interstitial manager should be reused if the ad placement does not change).

Disposing of an interstitial manager

Once you are done using an interstitial manager, typically when its hosting Activity is being destroyed, you should call the onDestroy() method of the SASInterstitialManager to release the resources it was using.


/**
 * Overriden from Activity class
 */
@Override
protected void onDestroy() {
  mInterstitialManager.onDestroy();
  super.onDestroy();
}


/**
* Overriden from Activity class
*/
override fun onDestroy() {
  interstitialManager.interstitialListener = null
  interstitialManager.onDestroy()
  super.onDestroy()
}