Android Splash Ad Integration

Overview

Splash ads are full-screen ads displayed when the app starts, with the following characteristics:

• High exposure rate
• Suitable for app launch scenarios
• Strong visual impact
• Higher click-through and conversion rates

Integration Steps

Refer to the SplashAdHelper in the demo.

1. Create the Splash Ad Activity

Use the splash ad helper class:

/**
 * Splash Ad Helper
 *
 * Responsible for splash ad loading, display, and lifecycle management
 *
 * @param activity Context Activity
 * @param logger Log printing tool
 */
class SplashAdHelper(private val activity: Activity, private val logger: PrintLogger) {

    /**
     * Splash ad object
     *
     * Used to manage splash ad loading, display, and destruction
     */
    private var splashAd: UjuAdObject? = null

    /**
     * Load a splash ad
     *
     * This method creates an ad config, initializes the splash ad object via the factory method,
     * sets the ad listener, and finally calls load() to start loading the ad
     */
    fun load() {
        // Create the ad config object, set the placement ID and scenario key
        val adConfig = UjuAdConfig(
            placementId = DemoConfig.SPLASH_ID, // Splash ad placement ID, required
            scenarioKey = DemoConfig.SCENARIO_KEY // Scenario key, for scenario statistics (optional)
        )

        // Create the splash ad object via the factory method
        splashAd = UjuAdObject.getSplashObject(activity, adConfig)

        // Set the ad listener to monitor various ad events
        splashAd?.setAdObjectListener(object : SplashAdObjectListener {
            /**
             * Ad load success callback
             *
             * @param placementId Placement ID
             */
            override fun onLoadSuccess(placementId: String) {
                // Ad loaded successfully, can now display; recommend checking isReady before showing
                logger.add("Splash: onLoadSuccess")
            }

            /**
             * Ad display success callback
             */
            override fun onAdShow() {
                // Get the price after the ad is displayed
                val ecpm = splashAd?.getAdInfo()?.ecpm
                logger.add("Splash: onAdShow: ecpm:$ecpm")
            }

            /**
             * Ad display error callback
             *
             * @param error Error information
             */
            override fun onAdError(
                error: UjuException
            ) {
                // Log the ad error
                logger.add("Splash: onAdError：${error.message}")
            }

            /**
             * Ad clicked callback
             */
            override fun onAdClicked() {
                // Log the ad click event
                logger.add("Splash: onAdClicked")
            }

            /**
             * Ad closed callback
             */
            override fun onAdClosed() {
                // Log the ad close event
                logger.add("Splash: onAdClosed")

                // Destroy the ad object and release resources
                splashAd?.destroy()
                splashAd = null
            }

            /**
             * Ad load failure callback
             *
             * @param error Error information
             * @param placementId Placement ID
             */
            override fun onLoadError(
                error: UjuException,
                placementId: String
            ) {
                // Log the load error
                logger.add("Splash: onLoadError: ${error.message}")
            }
        })

        // Start loading the ad
        splashAd?.load()
        // Log the load ad event
        logger.add("Splash: load, placementId:${adConfig.placementId}")
    }

    /**
     * Display the splash ad
     *
     * Before displaying, checks whether the ad is ready
     * Only calls show() when the ad state is ready
     *
     * @param viewGroup ViewGroup to hold the ad
     */
    fun show(viewGroup: ViewGroup) {
        // Check if the ad is ready
        if (splashAd?.isReady() == true) {
            // Ad is ready, display it
            splashAd?.show(activity, viewGroup)
        } else {
            // Ad not ready, log it
            logger.add("Splash: ad not ready")
        }
    }

    /**
     * Check if the ad is loaded
     *
     * @return true means the ad object has been created, false means not created
     * Note: This method only checks whether the ad object exists, not whether it is ready
     * To check if the ad can be displayed, use the isReady() method
     */
    fun isLoaded(): Boolean {
        return splashAd != null
    }

    /**
     * Destroy the ad object
     *
     * Call this method when the ad is no longer needed to destroy the ad object and release resources
     */
    fun destroy() {
        // Destroy the ad object
        splashAd?.destroy()
        // Null out the ad object reference
        splashAd = null
    }
}

2. Create the Splash Ad Layout

Create the activity_splash.xml layout file:

<!-- activity_splash.xml -->
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@drawable/splash_background">

    <!-- App logo -->
    <ImageView
        android:id="@+id/app_logo"
        android:layout_width="80dp"
        android:layout_height="80dp"
        android:layout_centerInParent="true"
        android:src="@drawable/app_logo"
        android:visibility="visible"/>

    <!-- Ad container -->
    <FrameLayout
        android:id="@+id/splash_ad_container"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:visibility="visible"/>

    <!-- Skip button -->
    <Button
        android:id="@+id/skip_button"
        android:layout_width="wrap_content"
        android:layout_height="36dp"
        android:layout_alignParentRight="true"
        android:layout_alignParentTop="true"
        android:layout_marginTop="40dp"
        android:layout_marginRight="20dp"
        android:background="@drawable/skip_button_bg"
        android:text="Skip"
        android:textColor="@android:color/white"
        android:textSize="14sp"
        android:paddingHorizontal="16dp"
        android:onClick="onSkipClicked"/>
</RelativeLayout>

3. Configure AndroidManifest.xml

Register the splash ad Activity in AndroidManifest.xml:

<activity
    android:name=".SplashActivity"
    android:theme="@style/SplashTheme"
    android:screenOrientation="portrait">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

<activity
    android:name=".MainActivity"
    android:theme="@style/AppTheme"/>

4. Create the Style File

Create the splash theme in styles.xml:

<style name="SplashTheme" parent="Theme.AppCompat.NoActionBar">
    <item name="android:windowBackground">@drawable/splash_background</item>
    <item name="android:windowFullscreen">true</item>
    <item name="android:windowContentOverlay">@null</item>
    <item name="android:windowActionBar">false</item>
    <item name="android:windowNoTitle">true</item>
</style>

Advanced Configuration

1. Custom Skip Button

// Custom skip button
val skipButton = findViewById<Button>(R.id.skip_button)
skipButton.setOnClickListener {
    // Go to the main page
    gotoMainActivity()
}

2. Load Parameters

// In SplashAdHelper's load method, you can add custom data via adConfig
val adConfig = UjuAdConfig(
    placementId = DemoConfig.SPLASH_ID, // Splash ad placement ID
    // Scenario key, for scenario statistics (optional)
    scenarioKey = DemoConfig.SCENARIO_KEY,
    // Custom data, passed through to the ad server (optional)
    customData = mapOf(
        "app_version" to "1.0.0",
        "device_type" to "phone"
    )
)

3. Ad Timeout Handling

// Handle ad timeout in SplashAdHelper's setAdObjectListener
override fun onAdError(error: UjuException) {
    logger.add("Splash: onAdError：${error.message}")
    // Ad error handling, including timeout
    gotoMainActivity()
}

// Or set timeout handling in the Activity
private val SPLASH_TIMEOUT = 3000L // 3-second timeout

// Set a timeout task in onCreate
handler.postDelayed({
    // Timeout handling
    gotoMainActivity()
}, SPLASH_TIMEOUT)

Best Practices

1. Splash Ad Optimization

• Set a reasonable timeout: 3-5 seconds recommended
• Provide a skip button: Allow users to skip the ad
• Preload strategy: Start loading the ad before app launch
• Failure handling: Ensure the app can enter the main page normally when ad loading fails

2. User Experience Optimization

• Maintain brand consistency: The splash ad UI should match the app style
• Avoid over-marketing: Do not display too much promotional info in the splash ad
• Optimize loading speed: Ensure the splash ad can load and display quickly
• Frequency control: Reasonably control the splash ad display frequency

3. Pitfalls to Avoid

• Do not set the ad timeout too long
• Do not display content unrelated to the app in the splash ad
• Do not affect the normal app launch speed
• Do not add complex interactions to the splash ad

FAQ

Q: Why is the splash ad not showing?

A: Possible reasons:

• Incorrect ad unit ID
• Network connection issue
• Insufficient ad inventory
• Ad loading timeout
• Device restrictions

Q: How to improve splash ad effectiveness?

A: Recommendations:

• Design an attractive splash UI
• Choose appropriate ad creatives
• Optimize ad loading and display strategy
• Ensure ads are relevant to app content
• Increase app user engagement

Q: Can splash ads be used in a Fragment?

A: Not recommended. Splash ads should be used in a standalone Activity, which can:

• Better control the app launch flow
• Avoid interaction conflicts with other screens
• Improve ad display success rate

Code Example

Complete Splash Ad Integration Example

Using the SplashAdHelper class above, you can easily integrate a splash ad in the splash Activity:

class SplashActivity : AppCompatActivity() {

    private lateinit var splashAdHelper: SplashAdHelper
    private val SPLASH_DISPLAY_TIME = 3000 // 3 seconds
    private lateinit var handler: Handler
    private lateinit var gotoMainRunnable: Runnable

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_splash)

        handler = Handler(Looper.getMainLooper())
        gotoMainRunnable = { gotoMainActivity() }

        // Initialize the splash ad helper
        splashAdHelper = SplashAdHelper(this, object : PrintLogger {
            override fun add(message: String) {
                Log.d("SplashAd", message)
            }
        })

        // Load the splash ad
        splashAdHelper.load()

        // Delay displaying the ad to ensure it is loaded
        handler.postDelayed({ showSplashAd() }, 500)
    }

    private fun showSplashAd() {
        // Get the ad container
        val adContainer = findViewById<ViewGroup>(R.id.splash_ad_container)
        // Display the ad
        splashAdHelper.show(adContainer)

        // Set the skip button click event
        findViewById<Button>(R.id.skip_button).setOnClickListener {
            // Go to the main page
            gotoMainActivity()
        }
    }

    private fun gotoMainActivity() {
        // Remove delayed tasks
        handler.removeCallbacks(gotoMainRunnable)

        // Go to the main page
        val intent = Intent(this, MainActivity::class.java)
        startActivity(intent)
        finish()
    }

    override fun onDestroy() {
        super.onDestroy()
        // Clean up resources
        handler.removeCallbacks(gotoMainRunnable)
        splashAdHelper.destroy()
    }
}

Related Links

• Android Initialization
• Banner Ad
• Rewarded Video Ad
• Native Ad
• Interstitial Ad