Skip to content

Advanced Interstitial API

Warning

This is the documentation for the Advanced API. Most developers should use our Simplified API, which comes with several built-in features such as:

  • automatic ad loading

  • retries for failed requests

See the documentation for the Simplified API here:

An interstitial ad is a fullscreen format, usually skippable after the first few seconds of its display. Because of this, it's commonly used in transitions of the app or game, such as completing a level or navigating to a different screen.

Create an Interstitial instance

val interstitial = Interstitial.create(
    activity = yourActivity,
    placementId = "<placement-id>"
)

Interstitial interstitial = Interstitial.create(
    this, 
    "<placement-id>"
);

Register ad callbacks

interstitial.listener = object : Interstitial.Listener {

    // Load callbacks

    override fun onLoaded(loadResult: LoadResult) {
        Log.d("Interstitial", "Loaded!")
    }

    override fun onFailedToLoad(loadError: LoadError, loadResult: LoadResult?) {
        Log.d("Interstitial", "Failed to load. Reason: ${loadError.message}")
    }

    // Show callbacks

    override fun onFailedToShow(showError: ShowError) {
        // If you need to resume your app's flow, make sure to do it here and in the onDismissed callback
        Log.d("Interstitial", "Failed to show. Reason: ${showError.message}")
    }

    override fun onImpression(impressionData: ImpressionData) {
        Log.d("Interstitial", "Impression with revenue: ${impressionData.revenue}")
    }

    override fun onShowed() {
        Log.d("Interstitial", "Was shown!")
    }

    override fun onDismissed() {
        // If you need to resume your app's flow, make sure to do it here and in the onFailedToShow callback
        Log.d("Interstitial", "Was dismissed!")
    }
}

interstitial.setListener(new Interstitial.Listener() {

    @Override
    public void onPrebiddingFinished(@NonNull PrebiddingResults result) {
        Log.d("InterstitialSample", "Prebidding finished");
    }

    @Override
    public void onLoaded(@NonNull LoadResult loadResult) {
        Log.d("InterstitialSample", "Loaded!");
    }

    @Override
    public void onFailedToLoad(@NonNull LoadError loadError, @Nullable LoadResult loadResult) {
        Log.d("InterstitialSample", "Failed to load. Reason: " + loadError.getMessage());
    }

    @Override
    public void onFailedToShow(@NonNull ShowError showError) {
        // If you need to resume your app's flow, make sure to do it here and in the onDismissed callback
        Log.d("InterstitialSample", "Failed to show. Reason: " + showError.getMessage());
    }

    @Override
    public void onShowed() {
        Log.d("InterstitialSample", "Was shown!");
    }

    @Override
    public void onClicked() {
        Log.d("InterstitialSample", "Was clicked!");
    }

    @Override
    public void onImpression(@NonNull ImpressionData impressionData) {
        Log.d("InterstitialSample", "Impression with revenue: " + impressionData.getRevenue());
    }

    @Override
    public void onDismissed() {
        // If you need to resume your app's flow, make sure to do it here and in the onFailedToShow callback
        Log.d("InterstitialSample", "Was dismissed!");
    }
});

Load an ad

interstitial.load()

interstitial.load();

Load an ad (with custom properties)

interstitial.load(
    buildCustomProperties { 
        addString("game_mode", "classic")
    }
)

interstitial.load(
    new CustomProperties.Builder()
            .addString("game_mode", "classic")
            .build()
);

Show an ad

if (interstitial.isReady) {
    yourActivity.runOnUiThread {
        interstitial.show(yourActivity, "interstitial-ad-space")
    }
}

if (interstitial.isReady()) {
    yourActivity.runOnUiThread(new Runnable() {
        @Override
        public void run() {
            interstitial.show(yourActivity, "interstitial-ad-space");
        }
    });
}

Destroy an ad

interstitial.destroy()

interstitial.destroy();

Code example

InterstitialSample.kt 
import android.os.Bundle
import android.util.Log
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import com.etermax.xmediator.core.api.Interstitial
import com.etermax.xmediator.core.api.entities.ImpressionData
import com.etermax.xmediator.core.api.entities.LoadError
import com.etermax.xmediator.core.api.entities.LoadResult
import com.etermax.xmediator.core.api.entities.ShowError
import com.example.yourapp.R

class InterstitialSample : AppCompatActivity() {

    private var interstitial: Interstitial? = null

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

        findViewById<Button>(R.id.button_load).setOnClickListener {
            Log.d("InterstitialSample", "Load button clicked")

            // Dispose previous interstitial instance
            interstitial?.destroy()

            // Create an interstitial instance
            interstitial = Interstitial.create(
                activity = this,
                placementId = "<placement-id>"
            )

            // Setup callbacks
            interstitial?.listener = object : Interstitial.Listener {
                override fun onLoaded(loadResult: LoadResult) {
                    Log.d("InterstitialSample", "Loaded!")
                }

                override fun onFailedToLoad(loadError: LoadError, loadResult: LoadResult?) {
                    Log.d("InterstitialSample", "Failed to load. Reason: ${loadError.message}")
                }

                override fun onFailedToShow(showError: ShowError) {
                    // If you need to resume your app's flow, make sure to do it here and in the onDismissed callback
                    Log.d("InterstitialSample", "Failed to show. Reason: ${showError.message}")
                }

                override fun onImpression(impressionData: ImpressionData) {
                    Log.d("InterstitialSample", "Impression with revenue: ${impressionData.revenue}")
                }

                override fun onShowed() {
                    Log.d("InterstitialSample", "Was shown!")
                }

                override fun onDismissed() {
                    // If you need to resume your app's flow, make sure to do it here and in the onFailedToShow callback
                    Log.d("InterstitialSample", "Was dismissed!")
                }
            }

            // Request an ad
            interstitial?.load()
        }

        findViewById<Button>(R.id.button_is_ready).setOnClickListener {
            Log.d("InterstitialSample", "Check Is Ready button clicked")
            val isReady = interstitial?.isReady
            Log.d("InterstitialSample", "interstitial.isReady = $isReady")
        }

        findViewById<Button>(R.id.button_show).setOnClickListener {
            Log.d("InterstitialSample", "Show button clicked")
            this.runOnUiThread {
                interstitial?.show(this)
            }
        }
    }

}