Android Interstitial Ad Integration

Overview

Interstitial ads are full-screen ads displayed during app screen transitions, with the following characteristics:

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

Integration Steps

Refer to the InterstitialAdHelper in the demo.

1. Initialize the Interstitial Ad

Initialize an interstitial ad in an Activity or Fragment:

/**
 * Interstitial Ad Helper
 *
 * Responsible for interstitial ad loading, display, and lifecycle management
 * Uses the UjuAdObject factory method pattern to create the interstitial ad object
 *
 * @param activity Context Activity
 * @param logger Log printing tool
 */
class InterstitialAdHelper(private val activity: Activity, private val logger: PrintLogger) {

    /**
     * Interstitial ad object
     *
     * Uses UjuAdObject to uniformly manage interstitial ad loading, display, and destruction
     */
    private var interstitialAd: UjuAdObject? = null

    /**
     * Load an interstitial ad
     *
     * This method creates an ad config, initializes the interstitial ad object via the UjuAdObject 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
        // scenarioKey is an optional parameter for tracking ad display scenarios
        val adConfig = UjuAdConfig(
            placementId = DemoConfig.INTERSTITIAL_ID, // Interstitial ad placement ID
        )

        // Create the interstitial ad object via the UjuAdObject factory method
        interstitialAd = UjuAdObject.getInterstitialObject(activity, adConfig)

        // Set the ad listener to monitor various ad events
        interstitialAd?.setAdObjectListener(object : InterstitialAdObjectListener {
            /**
             * 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("Interstitial: onLoadSuccess")
            }

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

            /**
             * Ad display success callback
             */
            override fun onAdShow() {
                // Get ad info, log the ecpm value
                val ecpm = interstitialAd?.getAdInfo()?.ecpm
                logger.add("Interstitial: onAdShow: ecpm:$ecpm")
            }

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

            /**
             * Ad playback complete callback
             */
            override fun onAdPlayComplete() {
                // Log the ad playback complete event
                logger.add("Interstitial: onAdPlayComplete")
            }

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

            /**
             * Ad landing page closed callback
             */
            override fun onLpClosed() {
                // Log the landing page close event
                logger.add("Interstitial: onLpClosed")
            }

            /**
             * Ad closed callback
             */
            override fun onAdClosed() {
                // Destroy the ad object and release resources
                interstitialAd?.destroy()
                interstitialAd = null
                // Log the ad close event
                logger.add("Interstitial: onAdClosed")
            }
        })

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

    /**
     * Display the interstitial ad
     *
     * Before displaying, checks whether the ad is ready
     * Only calls show() when the ad state is ready
     */
    fun show() {
        // Check if the ad is ready
        if (interstitialAd?.isReady() == true) {
            // Ad is ready, display it
            interstitialAd?.show(activity)
        } else {
            // Ad not ready, log it
            logger.add("Interstitial: 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 interstitialAd != 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
        interstitialAd?.destroy()
        // Null out the ad object reference
        interstitialAd = null
    }
}

2. Display the Interstitial Ad

Display the interstitial ad at an appropriate time, such as game level completion, app launch, or page transition:

/**
 * Display the interstitial ad
 *
 * Checks if the ad is loaded; if loaded, displays it; otherwise reloads
 */
private fun showInterstitialAd() {
    if (interstitialAd != null && interstitialAd?.isReady() == true) {
        // Ad is loaded, display it
        interstitialAd?.show(activity)
    } else {
        // Ad not loaded, notify the user or reload
        Log.d("InterstitialAd", "Ad not loaded, reloading")
        interstitialAd?.load()
    }
}

3. Ad Display Timing

Interstitial ads are suitable for the following scenarios:

// Scenario 1: Game level complete
private fun onLevelComplete() {
    // Level complete logic
    // ...

    // Display the interstitial ad
    showInterstitialAd()
}

// Scenario 2: After app launch
private fun onAppStarted() {
    // App launch logic
    // ...

    // Delay displaying the interstitial ad to let the user see the app content first
    Handler(Looper.getMainLooper()).postDelayed({ showInterstitialAd() }, 3000)
}

// Scenario 3: Page transition
private fun onPageChanged() {
    // Page transition logic
    // ...

    // Display the interstitial ad
    showInterstitialAd()
}

4. UjuAdConfig Configuration

UjuAdConfig is used to configure ad parameters. Main parameters:

Parameter	Type	Required	Description
placementId	String	Yes	Placement ID, identifies the ad slot
scenarioKey	String	No	Ad display scenario key, used for scenario statistics

// Basic config (only set the placement ID)
val adConfig = UjuAdConfig(
    placementId = DemoConfig.INTERSTITIAL_ID,
)

// Full config (including scenario key)
val adConfig = UjuAdConfig(
    placementId = DemoConfig.INTERSTITIAL_ID,
    scenarioKey = "level_complete", // Optional, for scenario statistics
)

Best Practices

1. Ad Display Strategy

• Reasonable display frequency: Avoid overly frequent display that affects user experience
• Appropriate display timing: Show during natural pauses in user actions
• Preload strategy: Load ads in advance so they are ready when needed
• Frequency control: Set time interval or count limits for ad display

2. Optimization Tips

• Preload ads: Start loading ads at app launch
• Ad caching: Implement an ad caching mechanism to improve display speed
• Failure handling: Provide reasonable fallback options when ad loading fails
• User experience: Ensure ads do not affect core app functionality

3. Pitfalls to Avoid

• Do not force ads during critical user actions
• Do not display ads immediately at app launch (recommend delaying a few seconds)
• Do not set ad display intervals too short
• Do not display too many ads in a single user session

FAQ

Q: Why is the interstitial ad not showing?

A: Possible reasons:

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

Q: How to improve interstitial ad effectiveness?

A: Recommendations:

• Choose appropriate ad display timing
• Optimize ad loading and display strategy
• Ensure ads are relevant to app content
• Increase app user engagement
• Analyze ad performance data and continuously optimize

Q: Can interstitial ads be loaded on a background thread?

A: Yes, but note:

• Ad creation and loading must be done on the main thread
• Use Handler or AsyncTask to manage loading timing
• Ensure ads are displayed on the UI thread

Related Links

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