App open ads

App open ads are a special ad format for monetizing your app load screens. These ads can be closed at any time and are designed to be served when users bring your app to the foreground, either at launch or when returning to it from the background.

This guide shows how to integrate app open ads into Compose Multiplatform apps. In addition to code examples and instructions, it contains format-specific recommendations and links to additional resources.

Alert

App open ads can only be placed in an app with a vertical orientation. For a horizontal orientation, ads won't be served.

Appearance

App open ads include a Go to the app button so users know they're in your app and can close the ad. Here's an example of what an ad looks like:

Prerequisite

  1. Follow the process in Quick start to integrate the Yandex Mobile Ads Compose Multiplatform Plugin.
  2. Make sure you're running the latest Yandex Mobile Ads Compose Multiplatform Plugin version. If you're using mediation, make sure you're running the latest version of the unified build.

Terms and definitions

  • Cold start — starting the app when it is not in RAM, creating a new app session.
  • Hot start — bringing the app from background (paused in RAM) to foreground.

Implementation

  1. Create the ad loader with rememberAppOpenAdLoader().
  2. Load the ad through the suspend function loadAd().
  3. Optionally set AppOpenAdEventListener on the loaded ad before calling show().
  4. Show the ad using show().

Main steps

  1. Create an AppOpenAdLoader ad loader

    @Composable
fun AppOpenRoot() {
    val loader = rememberAppOpenAdLoader()
    // ...
}

  2. Configure the ad request.

    val adUnitId = "demo-appopenad-yandex" // Replace with "R-M-XXXXXX-Y"
val request = AdRequest(adUnitId = adUnitId)

    adUnitId is a unique identifier issued in the Yandex Advertising Network interface and looks like R-M-XXXXXX-Y.

    Tip

    For testing, you can use the demo ad unit "demo-appopenad-yandex". Before publishing, replace it with your real ad unit id.

    You can expand the ad request through AdRequest (targeting, parameters, preferredTheme, and other fields). Delivering additional contextual data in the request can significantly improve your ad quality. Read more in the Ad Targeting section.

  3. Load the ad in a coroutine tied to your UI scope. On load failure, loadAd throws AdLoadException from com.yandex.mobile.ads.kmp.common.

    val scope = rememberCoroutineScope()
var appOpenAd by remember { mutableStateOf<AppOpenAd?>(null) }
var isLoading by remember { mutableStateOf(false) }

fun loadAppOpen() {
    isLoading = true
    scope.launch {
        try {
            val ad = loader.loadAd(request)
            appOpenAd = ad
            isLoading = false
        } catch (e: AdLoadException) {
            isLoading = false
            // Load error: e.error (AdRequestError). Unbounded retries are discouraged.
        }
    }
}

  4. Decide when to show the ad. In Compose Multiplatform you typically use AndroidX Lifecycle to track the app lifecycle.

  5. Register listeners for user-visible events.

    val ad = appOpenAd ?: return
ad.setAdEventListener(
    object : AppOpenAdEventListener {
        override fun onAdShown() {
            // Called when an ad is shown.
        }

        override fun onAdFailedToShow(adError: AdError) {
            // Called when an ad failed to show.
            appOpenAd = null
            // Preload the next ad if appropriate.
        }

        override fun onAdDismissed() {
            // Called when an ad is dismissed.
            appOpenAd = null
            // Preload the next ad if appropriate.
        }

        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.
        }
    },
)
ad.show()

  6. After show(), keep the AppOpenAd instance only while it is on screen. When dismissal callbacks fire, drop the reference before loading another creative.

  7. If you no longer need the loaded ad, clear the nullable reference so the object can be collected.

    appOpenAd = null

Full code example

The public sample app uses a dedicated screen for load and show controls. The pattern below mirrors that flow in a single composable for reference:

@Composable
fun AppOpenSample(adUnitId: String) {
    val loader = rememberAppOpenAdLoader()
    val scope = rememberCoroutineScope()
    var appOpenAd by remember { mutableStateOf<AppOpenAd?>(null) }
    var isLoading by remember { mutableStateOf(false) }

    Column {
        Button(
            onClick = {
                isLoading = true
                scope.launch {
                    try {
                        appOpenAd = loader.loadAd(AdRequest(adUnitId = adUnitId))
                    } catch (e: AdLoadException) {
                        // Load error: e.error (AdRequestError). Unbounded retries are discouraged.
                    }
                    isLoading = false
                }
            },
            enabled = !isLoading,
        ) {
            Text(if (isLoading) "Loading..." else "Load app open")
        }

        Button(
            onClick = { appOpenAd?.show() },
            enabled = appOpenAd != null,
        ) {
            Text("Show app open")
        }
    }
}

Wire load/show calls into your real lifecycle entry points instead of buttons when you move to production.

Features of app open ad integration

  1. Loading can take a while, so don't increase cold start time if the ad hasn't loaded.
  2. Pre-load the ad for subsequent display during hot starts.
  3. We discourage loading app open ads and other ad formats in parallel during app launch: the app may be downloading operational data at that time, which together with ads can overload the device and network and lengthen load.
  4. If loading returns an error, don't try to load a new ad again immediately. If you must, limit the number of retries — that will help avoid constant unsuccessful requests when limitations arise.

Testing app open ad integration

Using demo ad units for ad testing

We recommend using test ads to test your integration for app open ads and your app itself.

To guarantee that test ads are returned for every ad request, we created a special demo ad placement ID. Use it to check your ad integration.

Demo adUnitId: demo-appopenad-yandex.

Warning

Before publishing your app in the store, make sure to replace the demo ad placement ID with a real one obtained from the Yandex Advertising Network interface.

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 integration of app open ads using the SDK's built-in analyzer.

The tool makes sure your app open 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 for Android app debugging.

adb logcat -v brief '*:S YandexAds'

If the integration is successful, you'll see this message:

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

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

Using demo ad units for ad testing

We recommend using test ads to test your integration for app open ads and your app itself.

To guarantee that test ads are returned for every ad request, we created a special demo ad placement ID. Use it to check your ad integration.

Demo adUnitId: demo-appopenad-yandex.

Warning

Before publishing your app in the store, make sure to replace the demo ad placement ID with a real one obtained from the Yandex Advertising Network interface.

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

Testing ad integration

You can test your ad integration using the native Console tool.

To view detailed logs, call the YandexAds class's enableLogging method.

YandexAds.enableLogging()

To view SDK logs, go to the Console tool and set Subsystem = com.mobile.ads.ads.sdk. You can also filter logs by category and error level.

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

Recommendations

  1. Don't show an ad before the splash screen. A splash screen makes the app easier to use: users are sure they opened the right app.

    On the same screen you can warn that an ad is coming. Use a loading indicator or a short message that content will continue after the ad.

  2. Account for delay between the request and the ad display.

    If there is a delay, users may see an ad that doesn't match the context. One approach is to use a splash screen before the main content and start the ad from there. If the app opens straight into content after splash, it's better not to show the ad.

  3. Don't show an ad immediately after install. Wait until new users have opened the app and used it several times.

    Show ads only to users who meet criteria you define — for example, completed a level, opened the app a certain number of times, or are not in a rewarded-offer flow.

  4. Don't show an ad on every cold or hot start. Tune frequency based on how people use your app.

  5. Show an ad only if the app stayed in the background for a minimum time (for example, 30 seconds, 2 minutes, or 15 minutes).

  6. Test continuously. Each app needs its own approach to maximize revenue. User behavior changes, so revisit your ad display strategy periodically.

Additional resources

Full integration samples:

Previous
Rewarded ads
Next
Ad targeting in YAN