Interstitial

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

Table of contents

1. Overview
2. Configuring the SDK
3. Creating a placement
4. Loading an interstitial using a manager
5. Showing an interstitial
6. Listening to ad audio events
7. 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 Equativ 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.InterstitialManagerListener 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 Equativ 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 once, as soon as possible.

Ideally call it in the onCreate() method of your Application class. For instance:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Configure Equativ Display SDK
        SASConfiguration.configure(this)
    }
}

Any ad call performed before calling the configure() method will fail by throwing an 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 (more info in the API documentation).

val adPlacement = SASAdPlacement(SITE_ID, PAGE_ID, FORMAT_ID, OPTIONAL_KEYWORD_TARGETING)

You can add several information to your ad placements in order to increase the monetization.

For instance you can provide a Seller Defined Audience object, or a Supply Chain Object if your are an inventory reseller.

Note that for testing purposes, it is possible to instantiate a generic ad placement that will always deliver an ad from a particular type. You will find more information on the dedicated section here.

Don’t forget to remove all test placements before releasing your app!

Loading an interstitial using a manager

Interstitial ads are 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.InterstitialManagerListener on the SASInterstitialManager instance is mandatory (contrary to banner integration).

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

// Creation of the SASInterstitialManager
val interstitialManager = SASInterstitialManager(activity, adPlacement)

// Creation and setup of the InterstitialManagerListener
interstitialManager.interstitialManagerListener = object : SASInterstitialManager.InterstitialManagerListener {
    override fun onInterstitialAdLoaded(adInfo: SASAdInfo) {
        Log.i("Sample", "Interstitial loading completed");
    }

    override fun onInterstitialAdFailedToLoad(exception: Exception) {
        Log.i("Sample", "Interstitial loading has failed with exception: $exception");
    }

    override fun onInterstitialAdShown() {
        Log.i("Sample", "Interstitial was shown");
    }

    override fun onInterstitialAdFailedToShow(exception: Exception) {
        Log.i("Sample", "Interstitial has failed to show with exception: $exception");
    }

    override fun onInterstitialAdClosed() {
        Log.i("Sample", "Interstitial was closed");
    }

    override fun onInterstitialAdClicked() {
        Log.i("Sample", "Interstitial was clicked");
    }
}

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 :

interstitialManager.loadAd()

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 SASException of type PENDING_AD_LOADING in the onInterstitialAdFailedToLoad method of the SASInterstitialManager.InterstitialManagerListener .

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 getAdStatus getter, giving you the current SASAdStatus of the intersitial manager.

if (interstitialManager.getAdStatus() == SASAdStatus.READY) {
    interstitialManager.show()
} else {
    // The interstitial manager's ad is either still loading, or not available. 
}

Note that the show method can fail and trigger the 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 current interstitial manager instance can be reused if the ad placement remains the same.

Listening to ad audio events

You can listen to ad audio events (as well as other interstitial manager events) by implementing the SASInterstitialManager.InterstitialManagerListener interface on the interstitial manager.

interstitialManager.interstitialManagerListener = object : SASInterstitialManager.InterstitialManagerListener {
    override fun onInterstitialAdAudioStart() {
        Log.i(TAG, "Interstitial video ad will start to play audio")

        // Equativ Display SDK is notifying your app that it will play audio.
        // You could optionally pause music depending on your apps design.
    }

    override fun onInterstitialAdAudioStop() {
        Log.i(TAG, "Interstitial video ad did stop to play audio")

        // Equativ Display SDK is notifying your app that it has stopped playing audio.
        // Depending on your apps design, you could resume music here.
    }
}

All video ads start muted and require user interaction to toggle audio.

Disposing of an interstitial manager

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

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