Interstitial ad

Interstitial advertising is a full-screen ad format embedded within the app content during natural pauses, such as transitioning between game levels or completing a target action.

When an app shows an interstitial ad, the user has a choice: either tap the ad and go to the advertiser's website, or close the ad and return to the app.

Interstitial ads capture the user's full attention on the ad, which is why their CPM is higher.

Appearance

This guide shows how to integrate interstitial ads into an Android app using the Jetpack Compose extension. In addition to code examples and instructions, it provides recommendations on using this ad format and links to additional resources.

Prerequisite

1. Follow the SDK integration steps described in Quick start.
2. Initialize your ad SDK in advance.
3. Make sure you're running the latest Yandex Mobile Ads SDK version. If you're using mediation, make sure you're also running the latest version of the unified build.

To use the Compose extension, add the dependency to build.gradle.kts:

dependencies {
    implementation("com.yandex.android:mobileads:8.0.0")
    implementation("com.yandex.android:mobileads-compose:8.0.0")

    // Compose BOM (minimum 2024.01.00)
    implementation(platform("androidx.compose:compose-bom:2025.03.00"))
}

Implementation

Key steps for integrating interstitial ads:

• Use rememberInterstitialAdLoader() to create an ad loader.
• Load the ad via the suspend function loadAd() and handle the InterstitialAdLoadResult.
• Register a listener for ad event callbacks InterstitialAdEventListener.
• Show the InterstitialAd.

Interstitial ad integration notes

1. All Yandex Mobile Ads SDK method calls must be made from the main thread.

2. If you receive an error in InterstitialAdLoadResult.Failure, do not attempt to load a new ad immediately. If you must retry, limit the number of reload attempts to avoid continuous failed requests and connection issues under restricted conditions.

3. It is recommended to keep a strong reference to the ad throughout the lifetime of the screen where the ad interaction occurs, to prevent garbage collection.

4. When a composable leaves the composition tree, cancelLoading() is called automatically — there is no need to explicitly release loader resources.

Loading ads

To load an interstitial ad, use rememberInterstitialAdLoader(). Loading is performed via the suspend function loadAd(), which returns InterstitialAdLoadResult.

To load an ad, you will need the ad unit ID obtained from the Yandex Advertising Network interface (adUnitId).

You can extend the ad request parameters via AdRequestConfiguration.Builder() by passing user interest data, page context data, location, or other additional data. Additional contextual data in the request can significantly improve ad quality. For more information, see Ad targeting.

The following example shows how to load an interstitial ad:

import com.yandex.mobile.ads.common.AdRequestConfiguration
import com.yandex.mobile.ads.compose.rememberInterstitialAdLoader
import com.yandex.mobile.ads.interstitial.InterstitialAdLoadResult

@Composable
fun MyScreen(activity: Activity) {
    var interstitialAd by remember { mutableStateOf<InterstitialAd?>(null) }

    val loader = rememberInterstitialAdLoader()

    LaunchedEffect(Unit) {
        val adRequestConfiguration = AdRequestConfiguration.Builder("your-ad-unit-id").build()
        when (val result = loader.loadAd(adRequestConfiguration)) {
            is InterstitialAdLoadResult.Success -> interstitialAd = result.ad
            is InterstitialAdLoadResult.Failure -> {
                // Ad failed to load with AdRequestError.
                // Attempting to load a new ad from here is strongly discouraged.
            }
        }
    }
}

If you serve ads through Adfox, then after the banner ad response, the campaignId, bannerId, and placeId data can be accessed from the interstitialAdLoader objects using the adAttributes property of the AdAttributes type.

Showing the ad

Interstitial ads should be displayed during natural pauses in app usage. A good example is between game levels or after completing a target action, such as after a file download completes.

Before showing the ad, set the ad event listener InterstitialAdEventListener.

@Composable
fun MyScreen(activity: Activity) {
    var interstitialAd by remember { mutableStateOf<InterstitialAd?>(null) }

    val loader = rememberInterstitialAdLoader()

    LaunchedEffect(Unit) {
        val adRequestConfiguration = AdRequestConfiguration.Builder("your-ad-unit-id").build()
        when (val result = loader.loadAd(adRequestConfiguration)) {
            is InterstitialAdLoadResult.Success -> interstitialAd = result.ad
            is InterstitialAdLoadResult.Failure -> {
                // Ad failed to load with AdRequestError.
            }
        }
    }

    LaunchedEffect(interstitialAd) {
        interstitialAd?.apply {
            setAdEventListener(object : InterstitialAdEventListener {
                override fun onAdShown() {
                    // Called when ad is shown.
                }
                override fun onAdFailedToShow(adError: AdError) {
                    // Called when an InterstitialAd failed to show.
                    loadInterstitialAd()
                }
                override fun onAdDismissed() {
                    // Called when ad is dismissed.
                    // Now you can preload the next interstitial ad.
                    loadInterstitialAd()
                }
                override fun onAdClicked() {
                    // Called when a click is recorded for an ad.
                }
                override fun onAdImpression(impressionData: ImpressionData?) {
                    // Called when an impression is recorded for an ad.
                }
            })
            show(activity)
        }
    }
}

Testing interstitial ad integration

Using demo ad units for ad testing

We recommend using test ads to test your interstitial ad integration and your app itself.

For guaranteed return of test ads for every ad request, we have created a special demo ad placement ID. Use it to check your ad integration.

Demo adUnitId: demo-interstitial-yandex.

You can find the list of available demo ad placement IDs in the Demo ad units for testing section.

Testing ad integration

You can check your interstitial ad integration using the SDK's built-in analyzer.

The tool makes sure your interstitial ads are integrated properly and outputs a detailed report to the log. To view the report, search for the “YandexAds” keyword in the Logcat tool used for Android application debugging.

adb logcat -v brief '*:S YandexAds'

If the integration is successful, you will see the following message:

adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type interstitital was integrated successfully

If you're having problems integrating interstitial ads, you'll get a detailed report on the issues and recommendations for how to fix them.

Additional resources

• Link to GitHub.