Popup Ads - Ad Control Help Center

Overview

Popup Ads are an ad format that appears on screen at specific moments. They can be displayed at desired timings such as app launch, content load completion, or specific event triggers. Users can close them by tapping the close button or selecting “Don’t show today.”

Features

Popup form displayed at center or bottom of screen
Image and video ad support
Close, dim (background) click, and “Don’t show today” options
Customizable background color and text colors
Non-intrusive yet effective ad experience

Use test unit IDs in development. See the Test Unit IDs section.

Implementation Steps

Implement popup ads in 4 steps:

Initialize - Create AdropPopupAd instance
Set Listeners - Set listeners to receive ad and close events
Load Ad - Request and receive ad
Show Ad - Display ad on screen

Basic Implementation

Basic Usage

import io.adrop.ads.popupAd.AdropPopupAd
import io.adrop.ads.popupAd.AdropPopupAdListener
import io.adrop.ads.popupAd.AdropPopupAdCloseListener
import io.adrop.ads.model.AdropErrorCode

class MainActivity : AppCompatActivity() {
    private var popupAd: AdropPopupAd? = null

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

        // Load popup ad
        loadPopupAd()
    }

    // 1. Initialize and load ad
    private fun loadPopupAd() {
        popupAd = AdropPopupAd(this, "YOUR_POPUP_UNIT_ID")
        popupAd?.popupAdListener = popupAdListener
        popupAd?.closeListener = popupCloseListener
        popupAd?.load()
    }

    // 2. Show ad
    private fun showPopupAd() {
        popupAd?.let { ad ->
            if (ad.isLoaded) {
                ad.show(this)
            }
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        popupAd?.destroy()
    }
}

Implementing Listeners

// Ad listener implementation
private val popupAdListener = object : AdropPopupAdListener {
    // Ad received successfully (Required)
    override fun onAdReceived(ad: AdropPopupAd) {
        Log.d("Adrop", "Popup ad received")
        // Show ad when ready
        showPopupAd()
    }

    // Ad failed to receive (Required)
    override fun onAdFailedToReceive(ad: AdropPopupAd, errorCode: AdropErrorCode) {
        Log.d("Adrop", "Popup ad failed to receive: $errorCode")
    }

    // Ad impression (Optional)
    override fun onAdImpression(ad: AdropPopupAd) {
        Log.d("Adrop", "Popup ad impression")
    }

    // Ad clicked (Optional)
    override fun onAdClicked(ad: AdropPopupAd) {
        Log.d("Adrop", "Popup ad clicked")
    }

    // Just before popup ad is displayed (Optional)
    override fun onAdWillPresentFullScreen(ad: AdropPopupAd) {
        Log.d("Adrop", "Popup ad will present")
    }

    // Just after popup ad is displayed (Optional)
    override fun onAdDidPresentFullScreen(ad: AdropPopupAd) {
        Log.d("Adrop", "Popup ad presented")
    }

    // Just before popup ad is closed (Optional)
    override fun onAdWillDismissFullScreen(ad: AdropPopupAd) {
        Log.d("Adrop", "Popup ad will dismiss")
    }

    // Just after popup ad is closed (Optional)
    override fun onAdDidDismissFullScreen(ad: AdropPopupAd) {
        Log.d("Adrop", "Popup ad dismissed")
        // Preload next ad
        loadPopupAd()
    }

    // Popup ad failed to show (Optional)
    override fun onAdFailedToShowFullScreen(ad: AdropPopupAd, errorCode: AdropErrorCode) {
        Log.d("Adrop", "Popup ad failed to show: $errorCode")
    }
}

// Close listener implementation
private val popupCloseListener = object : AdropPopupAdCloseListener {
    // Close button clicked (Optional)
    override fun onClosed(ad: AdropPopupAd) {
        Log.d("Adrop", "Popup ad close button clicked")
    }

    // Dim (background) clicked (Optional)
    override fun onDimClicked(ad: AdropPopupAd) {
        Log.d("Adrop", "Popup ad dim area clicked")
    }

    // "Don't show today" clicked (Optional)
    override fun onTodayOffClicked(ad: AdropPopupAd) {
        Log.d("Adrop", "Don't show today selected")
        // Save today's date to control next display
        val prefs = getSharedPreferences("adrop_prefs", Context.MODE_PRIVATE)
        prefs.edit().putLong("last_popup_hidden_date", System.currentTimeMillis()).apply()
    }
}

Customization

You can customize the appearance of popup ads.

Setting Background and Text Colors

private fun loadPopupAd() {
    popupAd = AdropPopupAd(this, "YOUR_POPUP_UNIT_ID")
    popupAd?.popupAdListener = popupAdListener
    popupAd?.closeListener = popupCloseListener

    // Set background color (dim area)
    popupAd?.backgroundColor = Color.parseColor("#CC000000")

    // "Don't show today" text color
    popupAd?.hideForTodayTextColor = Color.WHITE

    // Close button text color
    popupAd?.closeTextColor = Color.WHITE

    // CTA button text color
    popupAd?.ctaTextColor = Color.BLUE

    popupAd?.load()
}

Customization Options

Property	Type	Description	Default
`backgroundColor`	`Int?`	Popup background (dim) color	Black (0.8 opacity)
`hideForTodayTextColor`	`Int?`	”Don’t show today” text color	White
`closeTextColor`	`Int?`	Close button text color	White
`ctaTextColor`	`Int?`	CTA button text color	System default

Custom Click Handling

To handle ad clicks with custom processing instead of opening the default browser, use the useCustomClick property.

private fun loadPopupAd() {
    popupAd = AdropPopupAd(this, "YOUR_POPUP_UNIT_ID")

    // Enable custom click handling
    popupAd?.useCustomClick = true

    popupAd?.popupAdListener = object : AdropPopupAdListener {
        override fun onAdReceived(ad: AdropPopupAd) {
            showPopupAd()
        }

        override fun onAdFailedToReceive(ad: AdropPopupAd, errorCode: AdropErrorCode) {
            Log.d("Adrop", "Ad failed to receive: $errorCode")
        }

        override fun onAdClicked(ad: AdropPopupAd) {
            // Custom click handling
            Log.d("Adrop", "Ad clicked: ${ad.destinationURL}")

            // Open with custom URL
            popupAd?.open("https://your-custom-url.com")

            // Or open with in-app browser
            // openInAppBrowser(ad.destinationURL)
        }
    }

    popupAd?.load()
}

Ad Properties

The following properties are available on the popup ad object:

unitId

String

Ad unit ID

isLoaded

Boolean

Whether ad is loaded

creativeId

String

Currently displayed ad creative ID

destinationURL

String

URL to navigate to when ad is clicked

txId

String

Transaction ID (for ad impression tracking)

campaignId

String

Campaign ID

Listener Methods

AdropPopupAdListener (Ad Events)

Required Methods

onAdReceived

(AdropPopupAd) -> Unit

Called when ad is received successfully. You can call show() at this point to display the ad.

onAdFailedToReceive

(AdropPopupAd, AdropErrorCode) -> Unit

Called when ad fails to load. The error code indicates the cause of failure.

Optional Methods

onAdImpression

(AdropPopupAd) -> Unit

Called when ad impression is recorded.

onAdClicked

(AdropPopupAd) -> Unit

Called when user clicks the ad.

onAdWillPresentFullScreen

(AdropPopupAd) -> Unit

Called just before popup ad is displayed.

onAdDidPresentFullScreen

(AdropPopupAd) -> Unit

Called just after popup ad is displayed on screen.

onAdWillDismissFullScreen

(AdropPopupAd) -> Unit

Called just before popup ad is closed.

onAdDidDismissFullScreen

(AdropPopupAd) -> Unit

Called just after popup ad is closed. This is a good time to preload the next ad.

onAdFailedToShowFullScreen

(AdropPopupAd, AdropErrorCode) -> Unit

Called when ad fails to show. The error code indicates the cause of failure.

AdropPopupAdCloseListener (Close Events)

All methods are optional.

onClosed

(AdropPopupAd) -> Unit

Called when user clicks the close button.

onDimClicked

(AdropPopupAd) -> Unit

Called when user clicks outside the popup (dim area).

onTodayOffClicked

(AdropPopupAd) -> Unit

Called when user selects “Don’t show today.” You can save the date in this callback to not show ads for the day.

Implementing “Don’t Show Today”

Here’s how to properly handle when a user selects “Don’t show today.”

Implementation Using SharedPreferences

class PopupAdManager(private val context: Context) {
    private val prefs = context.getSharedPreferences("adrop_prefs", Context.MODE_PRIVATE)
    private val todayOffKey = "popup_ad_today_off_date"
    private var popupAd: AdropPopupAd? = null

    // Check if ad can be shown today
    fun canShowAdToday(): Boolean {
        val lastHiddenDate = prefs.getLong(todayOffKey, 0L)
        if (lastHiddenDate == 0L) return true

        val calendar = Calendar.getInstance()
        calendar.timeInMillis = lastHiddenDate
        val hiddenDay = calendar.get(Calendar.DAY_OF_YEAR)
        val hiddenYear = calendar.get(Calendar.YEAR)

        calendar.timeInMillis = System.currentTimeMillis()
        val currentDay = calendar.get(Calendar.DAY_OF_YEAR)
        val currentYear = calendar.get(Calendar.YEAR)

        // Can show if saved date is not today
        return hiddenDay != currentDay || hiddenYear != currentYear
    }

    // Load and show ad
    fun loadAndShowAd(activity: Activity, unitId: String) {
        if (!canShowAdToday()) {
            Log.d("Adrop", "Not showing ad today")
            return
        }

        popupAd?.destroy()
        popupAd = AdropPopupAd(activity, unitId)
        popupAd?.popupAdListener = popupAdListener
        popupAd?.closeListener = popupCloseListener
        popupAd?.load()
    }

    private val popupAdListener = object : AdropPopupAdListener {
        override fun onAdReceived(ad: AdropPopupAd) {
            // Auto-show after receiving ad
            if (context is Activity) {
                ad.show(context)
            }
        }

        override fun onAdFailedToReceive(ad: AdropPopupAd, errorCode: AdropErrorCode) {
            Log.d("Adrop", "Ad failed to receive: $errorCode")
        }
    }

    private val popupCloseListener = object : AdropPopupAdCloseListener {
        override fun onTodayOffClicked(ad: AdropPopupAd) {
            // Save today's date
            prefs.edit().putLong(todayOffKey, System.currentTimeMillis()).apply()
            Log.d("Adrop", "Not showing popup ad today")
        }
    }

    fun destroy() {
        popupAd?.destroy()
        popupAd = null
    }
}

Usage Example

class MainActivity : AppCompatActivity() {
    private lateinit var popupAdManager: PopupAdManager

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

        popupAdManager = PopupAdManager(this)

        // Show popup ad at app start
        popupAdManager.loadAndShowAd(this, "YOUR_POPUP_UNIT_ID")
    }

    override fun onDestroy() {
        super.onDestroy()
        popupAdManager.destroy()
    }
}

Popup ads are available in two types:

Type	Description	Position
`POPUP_BOTTOM`	Bottom popup	Slides up from bottom of screen
`POPUP_CENTER`	Center popup	Displayed at center of screen

Popup type is configured when creating the ad unit in the Adrop console. No separate specification is needed in code.

Best Practices

1. Appropriate Display Timing

Popup ads are effective when displayed at these moments:

// Good example: At app launch
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    loadAndShowPopupAd()
}

// Good example: When content load completes
fun onContentLoaded() {
    if (shouldShowPopupAd()) {
        showPopupAd()
    }
}

// Good example: When specific event completes
fun onAchievementUnlocked() {
    showPopupAd()
}

// Bad example: When user is working
fun onUserTyping() {
    showPopupAd() // Degrades user experience
}

2. Respect “Don’t Show Today”

If a user selects “Don’t show today,” always honor it.

fun shouldShowPopupAd(): Boolean {
    // Check "Don't show today"
    if (!canShowAdToday()) {
        return false
    }

    // Check other conditions
    return true
}

3. Frequency Limiting

Don’t show popup ads too frequently.

class PopupAdFrequencyManager(private val context: Context) {
    private val prefs = context.getSharedPreferences("adrop_prefs", Context.MODE_PRIVATE)
    private val lastShownKey = "popup_ad_last_shown"
    private val minimumInterval = 3600000L // 1 hour (milliseconds)

    fun canShowAd(): Boolean {
        // Check "Don't show today"
        if (!canShowAdToday()) {
            return false
        }

        // Check minimum time interval
        val lastShown = prefs.getLong(lastShownKey, 0L)
        if (lastShown == 0L) return true

        val currentTime = System.currentTimeMillis()
        return currentTime - lastShown >= minimumInterval
    }

    fun recordAdShown() {
        prefs.edit().putLong(lastShownKey, System.currentTimeMillis()).apply()
    }

    private fun canShowAdToday(): Boolean {
        // Refer to "Don't show today" implementation above
        return true
    }
}

4. Preload Ads

Preload ads for better user experience.

class MainActivity : AppCompatActivity() {
    private var popupAd: AdropPopupAd? = null
    private var isAdReady = false

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

        // Preload
        preloadPopupAd()
    }

    private fun preloadPopupAd() {
        popupAd = AdropPopupAd(this, "YOUR_POPUP_UNIT_ID")
        popupAd?.popupAdListener = object : AdropPopupAdListener {
            override fun onAdReceived(ad: AdropPopupAd) {
                isAdReady = true
            }

            override fun onAdFailedToReceive(ad: AdropPopupAd, errorCode: AdropErrorCode) {
                Log.d("Adrop", "Ad failed to receive: $errorCode")
            }
        }
        popupAd?.load()
    }

    fun showPopupAdIfReady() {
        if (isAdReady) {
            popupAd?.show(this)
        }
    }
}

5. Landscape Mode Handling

Popup ads are only supported in portrait mode. In landscape mode, onAdFailedToShowFullScreen is called.

private val popupAdListener = object : AdropPopupAdListener {
    override fun onAdReceived(ad: AdropPopupAd) {
        // Show only in portrait mode
        if (resources.configuration.orientation == Configuration.ORIENTATION_PORTRAIT) {
            ad.show(this@MainActivity)
        }
    }

    override fun onAdFailedToShowFullScreen(ad: AdropPopupAd, errorCode: AdropErrorCode) {
        if (errorCode == AdropErrorCode.ERROR_CODE_LANDSCAPE_UNSUPPORTED) {
            Log.d("Adrop", "Popup ads are only supported in portrait mode")
        }
    }

    override fun onAdFailedToReceive(ad: AdropPopupAd, errorCode: AdropErrorCode) {
        Log.d("Adrop", "Ad failed to receive: $errorCode")
    }
}

Test Unit IDs

Use the following test unit IDs during development and testing.

Ad Type	Test Unit ID
Popup (Bottom Image)	`PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM`
Popup (Center Image)	`PUBLIC_TEST_UNIT_ID_POPUP_CENTER`
Popup Video (Bottom 16:9)	`PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM_VIDEO_16_9`
Popup Video (Bottom 9:16)	`PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM_VIDEO_9_16`
Popup Video (Center 16:9)	`PUBLIC_TEST_UNIT_ID_POPUP_CENTER_VIDEO_16_9`
Popup Video (Center 9:16)	`PUBLIC_TEST_UNIT_ID_POPUP_CENTER_VIDEO_9_16`

Test Ad Usage Example

// Separate test and production environments
val popupUnitId = if (BuildConfig.DEBUG) {
    "PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM"
} else {
    "YOUR_PRODUCTION_UNIT_ID"
}

popupAd = AdropPopupAd(this, popupUnitId)

Be sure to use the actual unit ID created in the Adrop console for production deployment.

Complete Example

import android.graphics.Color
import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import io.adrop.ads.model.AdropErrorCode
import io.adrop.ads.popupAd.AdropPopupAd
import io.adrop.ads.popupAd.AdropPopupAdCloseListener
import io.adrop.ads.popupAd.AdropPopupAdListener

class PopupAdActivity : AppCompatActivity() {
    private var popupAd: AdropPopupAd? = null

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

        // Load and show ad on button click
        findViewById<Button>(R.id.btn_show_popup).setOnClickListener {
            loadPopupAd()
        }
    }

    private fun loadPopupAd() {
        // Cleanup existing ad
        popupAd?.destroy()

        // Create popup ad
        popupAd = AdropPopupAd(this, "YOUR_POPUP_UNIT_ID")

        // Customization
        popupAd?.apply {
            backgroundColor = Color.parseColor("#CC000000")
            hideForTodayTextColor = Color.WHITE
            closeTextColor = Color.WHITE
            ctaTextColor = Color.BLUE
            useCustomClick = false
        }

        // Set listeners
        popupAd?.popupAdListener = object : AdropPopupAdListener {
            override fun onAdReceived(ad: AdropPopupAd) {
                Log.d("Adrop", "Popup ad received")
                showPopupAd()
            }

            override fun onAdFailedToReceive(ad: AdropPopupAd, errorCode: AdropErrorCode) {
                Log.d("Adrop", "Popup ad failed to receive: $errorCode")
            }

            override fun onAdImpression(ad: AdropPopupAd) {
                Log.d("Adrop", "Popup ad impression")
                Log.d("Adrop", "txId: ${ad.txId}, campaignId: ${ad.campaignId}")
            }

            override fun onAdClicked(ad: AdropPopupAd) {
                Log.d("Adrop", "Popup ad clicked: ${ad.destinationURL}")
            }

            override fun onAdDidPresentFullScreen(ad: AdropPopupAd) {
                Log.d("Adrop", "Popup ad presented")
            }

            override fun onAdDidDismissFullScreen(ad: AdropPopupAd) {
                Log.d("Adrop", "Popup ad dismissed")
                // Preload next ad
                loadPopupAd()
            }

            override fun onAdFailedToShowFullScreen(ad: AdropPopupAd, errorCode: AdropErrorCode) {
                Log.d("Adrop", "Popup ad failed to show: $errorCode")
            }
        }

        popupAd?.closeListener = object : AdropPopupAdCloseListener {
            override fun onClosed(ad: AdropPopupAd) {
                Log.d("Adrop", "Close button clicked")
            }

            override fun onDimClicked(ad: AdropPopupAd) {
                Log.d("Adrop", "Dim area clicked")
            }

            override fun onTodayOffClicked(ad: AdropPopupAd) {
                Log.d("Adrop", "Don't show today selected")
                saveHiddenDate()
            }
        }

        // Load ad
        popupAd?.load()
    }

    private fun showPopupAd() {
        popupAd?.let { ad ->
            if (ad.isLoaded) {
                ad.show(this)
            }
        }
    }

    private fun saveHiddenDate() {
        val prefs = getSharedPreferences("adrop_prefs", MODE_PRIVATE)
        prefs.edit().putLong("last_popup_hidden_date", System.currentTimeMillis()).apply()
    }

    override fun onDestroy() {
        super.onDestroy()
        popupAd?.destroy()
    }
}

Troubleshooting

Ad Not Displaying

onAdReceived is not called

Verify SDK is initialized
Check if unit ID is correct
Check network connection status
Verify production setting during Adrop SDK initialization

onAdFailedToReceive is called

Check error code to identify cause
Use test unit ID in test environment
Retry later if ad inventory is insufficient
ERROR_CODE_AD_HIDE_FOR_TODAY: “Don’t show today” is active

Nothing happens after calling show()

Verify show() is called after onAdReceived callback
Check if Activity is in valid state
Check isLoaded property to verify ad is loaded
Verify in portrait mode (landscape is not supported)

Ad doesn't show in landscape mode

Popup ads are only supported in portrait mode. When show() is called in landscape mode, onAdFailedToShowFullScreen is called with ERROR_CODE_LANDSCAPE_UNSUPPORTED error code.

”Don’t Show Today” Not Working

// Verify date comparison logic
fun isToday(timestamp: Long): Boolean {
    val calendar = Calendar.getInstance()
    val today = calendar.apply {
        timeInMillis = System.currentTimeMillis()
    }

    val targetDay = Calendar.getInstance().apply {
        timeInMillis = timestamp
    }

    return today.get(Calendar.YEAR) == targetDay.get(Calendar.YEAR) &&
           today.get(Calendar.DAY_OF_YEAR) == targetDay.get(Calendar.DAY_OF_YEAR)
}

// Usage
fun canShowAdToday(): Boolean {
    val prefs = getSharedPreferences("adrop_prefs", Context.MODE_PRIVATE)
    val lastHiddenDate = prefs.getLong("last_popup_hidden_date", 0L)

    return lastHiddenDate == 0L || !isToday(lastHiddenDate)
}

Getting Started

SDK installation and initialization

Interstitial Ads

Implement interstitial ads

Rewarded Ads

Implement rewarded ads

Banner Ads

Implement banner ads

SDK Guide

AI

Android

iOS

React Native

Flutter

Web

REST API

​Overview

​Features

​Implementation Steps

​Basic Implementation

​Basic Usage

​Implementing Listeners

​Customization

​Setting Background and Text Colors

​Customization Options

​Custom Click Handling

​Ad Properties

​Listener Methods

​AdropPopupAdListener (Ad Events)

​Required Methods

​Optional Methods

​AdropPopupAdCloseListener (Close Events)

​Implementing “Don’t Show Today”

​Implementation Using SharedPreferences

​Usage Example

​Popup Types

​Best Practices

​1. Appropriate Display Timing

​2. Respect “Don’t Show Today”

​3. Frequency Limiting

​4. Preload Ads

​5. Landscape Mode Handling

​Test Unit IDs

​Test Ad Usage Example

​Complete Example

​Troubleshooting

​Ad Not Displaying

​”Don’t Show Today” Not Working

​Related Documentation

Getting Started

Interstitial Ads

Rewarded Ads

Banner Ads

Overview

Features

Implementation Steps

Basic Implementation

Basic Usage

Implementing Listeners

Customization

Setting Background and Text Colors

Customization Options

Custom Click Handling

Ad Properties

Listener Methods

AdropPopupAdListener (Ad Events)

Required Methods

Optional Methods

AdropPopupAdCloseListener (Close Events)

Implementing “Don’t Show Today”

Implementation Using SharedPreferences

Usage Example

Popup Types

Best Practices

1. Appropriate Display Timing

2. Respect “Don’t Show Today”

3. Frequency Limiting

4. Preload Ads

5. Landscape Mode Handling

Test Unit IDs

Test Ad Usage Example

Complete Example

Troubleshooting

Ad Not Displaying

”Don’t Show Today” Not Working

Related Documentation