Skip to main content

Overview

Splash ads are displayed on the splash screen when the app launches. The ad appears alongside your app logo, providing a natural user experience.

Features

  • Natural ad exposure at app launch
  • Maintains brand image with app logo
  • Fixed ad size: 360dp × 270dp (Android), 360px × 270px (iOS)
  • Supports image ads
Use the test unit ID during development: PUBLIC_TEST_UNIT_ID_SPLASH

Implementation

Splash ads in Flutter apps are implemented through native platform configurations. Since splash ads display before the Flutter engine fully initializes, they must be configured at the native Android and iOS level.
Flutter apps use native splash screens that appear before Flutter loads. Adrop splash ads integrate with this native splash flow.

Android Configuration

Step 1: Configure strings.xml

Add the following settings to android/app/src/main/res/values/strings.xml.
android/app/src/main/res/values/strings.xml
<resources>
    <!-- App name -->
    <string name="app_name">My App</string>

    <!-- Splash ad unit ID -->
    <string name="adrop_splash_ad_unit_id" translatable="false">YOUR_SPLASH_UNIT_ID</string>

    <!-- Activity to navigate to after splash ends -->
    <string name="adrop_splash_ad_next_activity" translatable="false">com.yourcompany.yourapp.MainActivity</string>
</resources>
Use PUBLIC_TEST_UNIT_ID_SPLASH instead of YOUR_SPLASH_UNIT_ID for testing.

Step 2: Add Splash Logo Image

Add your app logo to the android/app/src/main/res/drawable/ folder.
android/app/src/main/res/drawable/splash_logo.png
Recommended size: 288dp × 288dp (@2x: 576px, @3x: 864px)

Step 3: Configure AndroidManifest.xml

Set AdropSplashAdActivity as the launcher activity.
android/app/src/main/AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:name="${applicationName}"
        android:label="@string/app_name"
        android:icon="@mipmap/ic_launcher">

        <!-- Splash Ad Activity -->
        <activity
            android:name="io.adrop.ads.splash.AdropSplashAdActivity"
            android:theme="@style/LaunchTheme"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <!-- Main Activity (Flutter) -->
        <activity
            android:name=".MainActivity"
            android:exported="false"
            android:launchMode="singleTop"
            android:taskAffinity=""
            android:theme="@style/LaunchTheme"
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
            android:hardwareAccelerated="true"
            android:windowSoftInputMode="adjustResize">
            <meta-data
                android:name="io.flutter.embedding.android.NormalTheme"
                android:resource="@style/NormalTheme" />
        </activity>

    </application>
</manifest>
android:exported="true" is required for AdropSplashAdActivity. Make sure to remove the launcher intent-filter from MainActivity.

Step 4: Configure Splash Theme

Add or update the splash theme in android/app/src/main/res/values/styles.xml.
android/app/src/main/res/values/styles.xml
<resources>
    <!-- Launch theme with splash screen -->
    <style name="LaunchTheme" parent="Theme.SplashScreen">
        <item name="windowSplashScreenBackground">@android:color/white</item>
        <item name="windowSplashScreenAnimatedIcon">@drawable/splash_logo</item>
        <item name="postSplashScreenTheme">@style/NormalTheme</item>
    </style>

    <!-- Normal theme -->
    <style name="NormalTheme" parent="Theme.MaterialComponents.DayNight.NoActionBar">
        <item name="android:windowBackground">?android:colorBackground</item>
    </style>
</resources>

Step 5: Customize Layout (Optional)

To use a custom layout, create activity_adrop_splash_ad.xml in android/app/src/main/res/layout/.
android/app/src/main/res/layout/activity_adrop_splash_ad.xml
<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="#ffffff"
    android:paddingHorizontal="24dp"
    android:fitsSystemWindows="true">

    <!-- App logo (center) -->
    <ImageView
        android:src="@drawable/splash_logo"
        android:layout_width="288dp"
        android:layout_height="288dp"
        android:scaleType="fitXY"
        android:layout_centerInParent="true"/>

    <!-- Ad area (bottom) - Required -->
    <ImageView
        android:id="@+id/adrop_splash_ad_image"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_centerHorizontal="true"
        android:layout_alignParentBottom="true"/>
</RelativeLayout>
An ImageView with android:id="@+id/adrop_splash_ad_image" is required. The ad will be displayed in this view.

Step 6: Configure Display Duration (Optional)

To change the default display duration, create android/app/src/main/res/values/integers.xml.
android/app/src/main/res/values/integers.xml
<resources>
    <!-- Ad request timeout (milliseconds, 500~3000) -->
    <integer name="adrop_splash_ad_request_timeout">1000</integer>

    <!-- Ad display duration (milliseconds, 500~3000) -->
    <integer name="adrop_splash_ad_max_timeout">2000</integer>
</resources>

Step 7: Implement AdropSplashAd Listener (Optional)

To receive splash ad events, set up a listener in your Application class.
import android.app.Application
import io.adrop.ads.Adrop
import io.adrop.ads.splash.AdropSplashAd
import io.adrop.ads.splash.AdropSplashAdListener
import io.adrop.ads.model.AdropErrorCode

class MainApplication : Application() {
    private lateinit var splashAd: AdropSplashAd

    override fun onCreate() {
        super.onCreate()

        // Initialize SDK
        Adrop.initialize(this, production = false)

        // Configure splash ad
        splashAd = AdropSplashAd(this) { splashAd ->
            // shouldSkip: Determines whether to skip splash ad
            // Return true to skip the ad and go directly to the main screen
            checkShouldSkipSplash()
        }

        splashAd.splashAdListener = object : AdropSplashAdListener {
            override fun onAdReceived(ad: AdropSplashAd) {
                println("Splash ad received successfully")
            }

            override fun onAdFailedToReceive(ad: AdropSplashAd, errorCode: AdropErrorCode) {
                println("Failed to receive splash ad: $errorCode")
            }

            override fun onAdImpression(ad: AdropSplashAd) {
                println("Splash ad impression")
            }

            override fun onAdClose(ad: AdropSplashAd, impressed: Boolean) {
                println("Splash ad closed - impressed: $impressed")
            }
        }
    }

    private fun checkShouldSkipSplash(): Boolean {
        // Example: Skip splash when entering via deep link or under certain conditions
        return false
    }
}
When shouldSkip returns true, the ad is not loaded and navigates immediately to the main screen.

iOS Configuration

Step 1: Configure AppDelegate

Update your ios/Runner/AppDelegate.swift to display splash ads.
ios/Runner/AppDelegate.swift
import UIKit
import Flutter
import AdropAds

@main
@objc class AppDelegate: FlutterAppDelegate {
    var splashAdViewController: AdropSplashAdViewController?

    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        GeneratedPluginRegistrant.register(with: self)

        // Initialize Adrop SDK
        Adrop.initialize(production: false)

        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

Step 2: Configure SceneDelegate (iOS 13+)

For apps using SceneDelegate, update ios/Runner/SceneDelegate.swift.
ios/Runner/SceneDelegate.swift
import UIKit
import Flutter
import AdropAds

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(
        _ scene: UIScene,
        willConnectTo session: UISceneSession,
        options connectionOptions: UIScene.ConnectionOptions
    ) {
        guard let windowScene = (scene as? UIWindowScene) else { return }

        window = UIWindow(windowScene: windowScene)

        #if DEBUG
        let splashUnitId = "PUBLIC_TEST_UNIT_ID_SPLASH"
        #else
        let splashUnitId = "YOUR_PRODUCTION_SPLASH_UNIT_ID"
        #endif

        // Create splash ad view controller
        let splashViewController = AdropSplashAdViewController(
            unitId: splashUnitId,
            logoImage: UIImage(named: "splash_logo")
        )
        splashViewController.delegate = self
        splashViewController.displayDuration = 3.0

        window?.rootViewController = splashViewController
        window?.makeKeyAndVisible()
    }
}

// MARK: - AdropSplashAdDelegate
extension SceneDelegate: AdropSplashAdDelegate {
    func onAdClose(impressed: Bool) {
        print("Splash ad closed - impressed: \(impressed)")
    }

    func onAdReceived(_ ad: AdropSplashAd) {
        print("Splash ad received")
    }

    func onAdFailedToReceive(_ ad: AdropSplashAd, _ errorCode: AdropErrorCode) {
        print("Splash ad failed: \(errorCode)")
    }

    func onAdImpression(_ ad: AdropSplashAd) {
        print("Splash ad impression")
    }
}

Step 3: Add Logo Image

Add your app logo to the iOS assets:
  1. Open Xcode and navigate to Runner/Assets.xcassets
  2. Add a new Image Set named splash_logo
  3. Add your logo images (@1x, @2x, @3x)
Recommended size: 200×200 ~ 300×300 points

Step 4: Configure Info.plist (Optional)

If using SceneDelegate, ensure your Info.plist has the scene configuration:
ios/Runner/Info.plist
<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <false/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>UIWindowSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>Default Configuration</string>
                <key>UISceneDelegateClassName</key>
                <string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

AdropSplashAdDelegate

MethodRequiredDescription
onAdClose(impressed:)OptionalCalled when splash ad closes. impressed indicates if ad was displayed
onAdReceived(_:)OptionalCalled when ad is received successfully
onAdFailedToReceive(_:_:)OptionalCalled when ad fails to receive
onAdImpression(_:)OptionalCalled when ad impression is recorded

Best Practices

1. Set Appropriate Timers

Configure reasonable timeout values for better user experience.
<!-- Android: integers.xml -->
<integer name="adrop_splash_ad_request_timeout">1000</integer>
<integer name="adrop_splash_ad_max_timeout">2000</integer>
// iOS
splashViewController.displayDuration = 3.0

2. Optimize Logo Image

Prepare your app logo in appropriate sizes to minimize loading time. Android:
drawable-mdpi/splash_logo.png    (192px × 192px)
drawable-hdpi/splash_logo.png    (288px × 288px)
drawable-xhdpi/splash_logo.png   (384px × 384px)
drawable-xxhdpi/splash_logo.png  (576px × 576px)
drawable-xxxhdpi/splash_logo.png (768px × 768px)
iOS:
splash_logo@1x.png  (200px × 200px)
splash_logo@2x.png  (400px × 400px)
splash_logo@3x.png  (600px × 600px)

3. Handle Failures Gracefully

Ensure the app starts normally even when ad loading fails.
func onAdFailedToReceive(_ ad: AdropSplashAd, _ errorCode: AdropErrorCode) {
    print("Ad load failed: \(errorCode)")
    // AdropSplashAdViewController automatically calls onAdClose
}

4. Distinguish Test/Production Environments

#if DEBUG
let splashUnitId = "PUBLIC_TEST_UNIT_ID_SPLASH"
let isProduction = false
#else
let splashUnitId = "YOUR_PRODUCTION_SPLASH_UNIT_ID"
let isProduction = true
#endif

Adrop.initialize(production: isProduction)

Testing

Test Unit ID

Use the test unit ID during development.
PUBLIC_TEST_UNIT_ID_SPLASH
Make sure to use the actual unit ID created in the Adrop console for production releases. No ad revenue is generated with test unit IDs.

Troubleshooting

  • Verify that AdropSplashAdActivity is set as LAUNCHER in AndroidManifest.xml
  • Check android:exported="true" setting
  • Verify SDK initialization is complete
  • Ensure adrop_service.json is in the android/app/src/main/assets folder
  • Verify window.rootViewController is set correctly
  • Check if SceneDelegate is configured in Info.plist
  • Ensure SDK initialization is complete
  • Verify adrop_service.json is added to the Xcode project
  • Check network connection status
  • Verify the unit ID is correct
  • Confirm production: false setting in test environment
  • Check error code in onAdFailedToReceive
  • Verify adrop_splash_ad_next_activity is set correctly (Android)
  • Check onAdClose delegate implementation (iOS)
  • Ensure FlutterViewController is created properly
  • Verify filename is exactly activity_adrop_splash_ad.xml
  • Check that ImageView with @+id/adrop_splash_ad_image exists
  • Clean build and re-run (Build > Clean Project > Rebuild)

Next Steps