Interstitial

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.

To start using interstitial ads, just call load() using a valid placement id and then use one of the available present() functions when you need it to be displayed.

Start loading an ad

KotlinJava

XMediatorAds.startWith(
    activity = activity,
    appKey = APP_KEY,
    initCallback = {
        XMediatorAds.Interstitial.load(INTERSTITIAL_PLACEMENT_ID)
    }
)

XMediatorAds.startWith(activity, APP_KEY,  initResult -> {
    Log.d("InitResult", initResult.toString());
    XMediatorAds.getInterstitial().load(INTERSTITIAL_PLACEMENT_ID);
    return null;
});

Showing an ad

Calling isReady() will return if there's an interstitial available to be shown, regardless of its placement id. If multiple ads with different placement ids were previously loaded, the SDK will try to show the best one available.

KotlinJava

if (XMediatorAds.Interstitial.isReady()) {
    activity.runOnUiThread {
        XMediatorAds.Interstitial.show(activity, "interstitial-ad-space")
    }
}

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

Showing an ad with placementId

When the app needs to present an ad for a specific placement id, isReady(placementId) and show(placementId) can be alternatively used.

KotlinJava

if (XMediatorAds.Interstitial.isReady(INTERSTITIAL_PLACEMENT_ID)) {
    activity.runOnUiThread {
        XMediatorAds.Interstitial.show(INTERSTITIAL_PLACEMENT_ID, activity, "interstitial-ad-space")
    }
}

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

Built-in features

Auto loading

Dismissed or failed to show ads will automatically trigger a new load request.

Auto retry

Failed to load ads will make a retry attempts, with an exponential backoff.

Additional settings

Register ad callbacks

Every ad callback indicates the placement id of the interstitial ad that triggered the event.

KotlinJava

private val interstitialListener = object : InterstitialAds.Listener {
    override fun onLoaded(placementId: String, loadResult: LoadResult) {
        Log.d("Presenter", "Interstitial loaded. Placement $placementId, result: $loadResult")
    }

    override fun onShowed(placementId: String) {
        Log.d("Presenter", "Interstitial shown: $placementId.")
    }

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

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

    override fun onImpression(placementId: String, impressionData: ImpressionData) {
        Log.d("Presenter", "Interstitial impression for placementId: $placementId, data: $impressionData")
    }

    override fun onClicked(placementId: String) {
        Log.d("Presenter", "Interstitial clicked for placementId: $placementId")
    }
}
XMediatorAds.Interstitial.addListener(interstitialListener)

XMediatorAds.getInterstitial().addListener(new InterstitialAds.Listener() {
    @Override
    public void onLoaded(@NonNull String placementId, @NonNull LoadResult loadResult) {
        Log.d("Presenter", "Interstitial loaded. Placement" + placementId + ", result: " + loadResult);
    }

    @Override
    public void onShowed(@NonNull String placementId) {
        Log.d("Presenter", "Interstitial shown. Placement " + placementId);
    }

    @Override
    public void onFailedToShow(@NonNull String placementId, @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("Presenter", "Interstitial shown. Placement " + placementId + " error: " + showError);
    }

    @Override
    public void onDismissed(@NonNull String placementId) {
        // If you need to resume your app's flow, make sure to do it here and in the onFailedToShow callback
        Log.d("Presenter", "Interstitial onDismissed. Placement " + placementId);
    }

    @Override
    public void onImpression(@NonNull String placementId, @NonNull ImpressionData impressionData) {
        Log.d("Presenter", "Interstitial onImpression. Placement " + placementId + " ecpm: " + impressionData.getEcpm());
    }

    @Override
    public void onClicked(@NonNull String placementId) {
        Log.d("Presenter", "Interstitial onClicked. Placement " + placementId);
    }
});

Advanced use cases

This guide provides the recommended integration steps to show an interstitial ad using X3M, which covers most of the common scenarios. For advanced use cases, where manually handling the lifecycle of the ad object is needed, refer to this section.

Code example

InterstitialSample.kt

import android.app.Activity
import android.os.Bundle
import android.util.Log
import android.widget.Button
import com.etermax.R
import com.etermax.xmediator.core.api.entities.ImpressionData
import com.etermax.xmediator.core.api.entities.LoadResult
import com.etermax.xmediator.core.api.entities.ShowError
import com.x3mads.android.xmediator.core.api.InterstitialAds
import com.x3mads.android.xmediator.core.api.XMediatorAds

class InterstitialSample : Activity() {
    private val appKey = "app_key"
    private val interstitialPlacementId = "placement_id"

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_interstitial)
        XMediatorAds.Interstitial.addListener(listener = interstitialListener)
        findViewById<Button>(R.id.button_load).setOnClickListener {
            XMediatorAds.startWith(
                activity = this,
                appKey = appKey,
                initCallback = {
                    XMediatorAds.Interstitial.load(interstitialPlacementId)
                }
            )
        }
        findViewById<Button>(R.id.button_show).setOnClickListener {
            if(XMediatorAds.Interstitial.isReady(interstitialPlacementId)){
                this.runOnUiThread {
                    XMediatorAds.Interstitial.show(interstitialPlacementId, this)
                }
            }
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        XMediatorAds.Interstitial.removeListener(listener = interstitialListener)
    }

    private val interstitialListener = object : InterstitialAds.Listener {
        override fun onLoaded(placementId: String, loadResult: LoadResult) {
            Log.d("SimplifyPresenter", "Interstitial loaded. Placement $placementId, result: $loadResult")
        }

        override fun onShowed(placementId: String) {
            Log.d("SimplifyPresenter", "Interstitial shown: $placementId.")
        }

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

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

        override fun onImpression(placementId: String, impressionData: ImpressionData) {
            Log.d("SimplifyPresenter", "Interstitial impression for placementId: $placementId, data: $impressionData")
        }

        override fun onClicked(placementId: String) {
            Log.d("SimplifyPresenter", "Interstitial clicked for placementId: $placementId")
        }
    }
}