App open ad (SwiftUI)

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 an app open ad into an iOS app using SwiftUI. In addition to code examples and instructions, it provides recommendations on using this ad format and links to additional resources.

Appearance

App open ads display a Go to the app button so users know they are in your app and can close the ad. Here is an example of how the ad looks:

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.

Terms

• Cold start — launching the app when it is not in memory, creating a new app session.
• Warm start — bringing the app from background (when the app is suspended in memory) to foreground.

Implementation

1. Initialize the SDK when the app starts.
2. Add the .appOpenAd(request:onEvent:) modifier to the root View (for example, inside WindowGroup).
3. Control loading via Binding<AdRequest?>: a non-nil value starts loading.
4. After a successful load, the ad is shown automatically when the app enters the active state (foreground), while request has not been reset.
5. Handle lifecycle events in onEvent (AppOpenAdEvent).
6. After the ad is dismissed, a show error occurs, or a load error occurs, request is reset to nil — set a new AdRequest when the next load is needed (often in the scene phase change handler).

Key steps

1. Initialize the SDK when the app starts.

   // wait for SDK initialization before loading ads
   MobileAds.initializeSDK(completionHandler: completionHandler)
   

2. Attach the modifier to the root view and store the request state.

   You will need the ad unit ID obtained from the Yandex Advertising Network interface (AD_UNIT_ID).

   You can extend the ad request parameters via AdRequest 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.

   Example for iOS 14+ with ScenePhase (reload after request is reset to nil):

   import SwiftUI
   import YandexMobileAds
   
   @main
   struct MyApp: App {
       @State private var adRequest: AdRequest?
       @Environment(\.scenePhase) private var scenePhase
   
       var body: some Scene {
           WindowGroup {
               ContentView()
                   .appOpenAd(request: $adRequest) { event in
                       if case .didFailToLoad = event {
                           // if necessary — delayed retry, see recommendations below
                       }
                   }
           }
           .onChange(of: scenePhase) {
               if scenePhase == .active, adRequest == nil {
                   adRequest = AdRequest(adUnitID: "demo-appopenad-yandex")
               }
           }
       }
   }
   

   On iOS 13, instead of scenePhase, use the UIApplication.didBecomeActiveNotification notification or equivalent lifecycle logic to set a new AdRequest after nil.

3. Load and show events arrive in onEvent:

   .appOpenAd(request: $adRequest) { event in
       switch event {
       case .didLoad:
           // Ad is ready; display will occur on next foreground
           break
       case .didShow:
           break
       case .didDismiss:
           // request has already been reset by the modifier
           break
       case .didFailToShow:
           break
       case .didFailToLoad:
           // request has been reset; immediate retry in a loop is not recommended
           break
       case .didClick:
           break
       case .didTrackImpression(_):
           break
       }
   }
   

   Note

   If the ad has already been served, calling the show(from:) method will return a display error in AppOpenAdDelegate.appOpenAd(_:didFailToShowError:).

App open ad integration notes

1. Loading may take considerable time, so do not delay the cold start if the ad has not loaded.
2. Pre-load the ad in advance for subsequent display on warm start. While nil is passed in the binding, loading is not performed — set AdRequest when background preparation of the ad for display is needed.
3. It is not recommended to load App Open Ad and other ad formats simultaneously at app startup, as the app may be downloading required data at that moment. This can overload the device and internet connection, making ad loading slower.
4. If you receive an error in the .didFailToLoad event, do not attempt to immediately load a new ad in a loop. If you must retry, limit the number of reload attempts to avoid continuous failed requests and connection issues under restricted conditions.

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.

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

Verifying correct ad integration

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

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

YMAMobileAds.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. Do not show an app open ad before the loading screen (Splash screen).

   Showing a loading screen makes the app experience more pleasant and straightforward for the user. This prevents the user from being surprised or confused, as they will know exactly which app they opened. On this screen, you can also warn users about upcoming ads using a loading indicator or a text message telling the user that app content will resume after the ad.

2. If there is a delay between the ad request and its display, the user may briefly open your app and then unexpectedly see an ad unrelated to the content. This can negatively affect the user experience, so it is worth avoiding such situations. One option is to use a loading screen before displaying the main app content and to start showing the ad from that screen. If the app opens some content after the loading screen, it is better not to show the ad at that point.

3. Wait for new users to open the app and use it several times before showing an app open ad. Show the ad only to users who have met certain criteria in the app (for example, completed a certain level, opened the app a certain number of times, are not participating in reward offers, etc.). Do not show the ad immediately after app installation.

4. Regulate display frequency based on user behavior in the app. Do not show an ad on every cold/warm start.

5. Show the ad only if the app has been in the background for a certain period of time (for example, 30 seconds, 2 minutes, 15 minutes).

6. It is important that you conduct testing, as each app is unique and requires its own approach to maximize revenue without reducing retention or time spent in the app. User behavior and engagement can change over time, so it is recommended to periodically test app open ad display strategies in your app.

Additional resources

• Link to GitHub.