Banner Ads - Ad Control Help Center

Overview

Banner ads are rectangular ads displayed in a portion of the screen. They can be implemented using both XML layout and code.

Key Features

Can be fixed at the top, bottom, or middle of the screen
Supports image and video ads
Supports both XML layout and programmatic implementation
Handle ad events through listeners

Use test unit ID during development: PUBLIC_TEST_UNIT_ID_320_100

XML Layout Implementation

Define AdropBanner in XML layout and load it in Activity or Fragment.

1. Define XML Layout

Place AdropBanner in a FrameLayout or other container.

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <!-- Main content -->
    <TextView
        android:id="@+id/content"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Main Content"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent" />

    <!-- Banner ad container -->
    <FrameLayout
        android:id="@+id/banner_container"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent">

        <io.adrop.ads.banner.AdropBanner
            android:id="@+id/adrop_banner"
            android:layout_width="320dp"
            android:layout_height="100dp"
            android:layout_gravity="center"
            app:adrop_unit_id="YOUR_UNIT_ID" />

    </FrameLayout>

</androidx.constraintlayout.widget.ConstraintLayout>

2. Load in Activity

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import io.adrop.ads.banner.AdropBanner
import io.adrop.ads.banner.AdropBannerListener
import io.adrop.ads.model.AdropErrorCode

class MainActivity : AppCompatActivity() {
    private var banner: AdropBanner? = null

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

        // 1. Find banner view defined in XML
        banner = findViewById(R.id.adrop_banner)

        // 2. Set listener
        banner?.listener = object : AdropBannerListener {
            override fun onAdReceived(banner: AdropBanner) {
                println("Banner ad received successfully")
            }

            override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
                println("Banner ad failed to receive: $errorCode")
            }

            override fun onAdImpression(banner: AdropBanner) {
                println("Banner ad impression")
            }

            override fun onAdClicked(banner: AdropBanner) {
                println("Banner ad clicked")
            }
        }

        // 3. Load ad
        banner?.load()
    }

    override fun onDestroy() {
        super.onDestroy()
        // 4. Release memory
        banner?.destroy()
        banner = null
    }
}

import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import io.adrop.ads.banner.AdropBanner;
import io.adrop.ads.banner.AdropBannerListener;
import io.adrop.ads.model.AdropErrorCode;
import org.jetbrains.annotations.NotNull;

public class MainActivity extends AppCompatActivity {
    private AdropBanner banner;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // 1. Find banner view defined in XML
        banner = findViewById(R.id.adrop_banner);

        // 2. Set listener
        banner.setListener(new AdropBannerListener() {
            @Override
            public void onAdReceived(@NotNull AdropBanner banner) {
                System.out.println("Banner ad received successfully");
            }

            @Override
            public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
                System.out.println("Banner ad failed to receive: " + errorCode);
            }

            @Override
            public void onAdImpression(@NotNull AdropBanner banner) {
                System.out.println("Banner ad impression");
            }

            @Override
            public void onAdClicked(@NotNull AdropBanner banner) {
                System.out.println("Banner ad clicked");
            }
        });

        // 3. Load ad
        banner.load();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        // 4. Release memory
        if (banner != null) {
            banner.destroy();
            banner = null;
        }
    }
}

XML Attributes

Attribute	Description	Required
`app:adrop_unit_id`	Ad unit ID	O
`app:adrop_context_id`	Context ID for contextual targeting
`android:layout_width`	Banner width (dp)	O
`android:layout_height`	Banner height (dp)	O

Programmatic Implementation

Create AdropBanner instance directly in code and add it to the view.

import android.os.Bundle
import android.widget.FrameLayout
import androidx.appcompat.app.AppCompatActivity
import io.adrop.ads.banner.AdropBanner
import io.adrop.ads.banner.AdropBannerListener
import io.adrop.ads.model.AdropErrorCode

class MainActivity : AppCompatActivity() {
    private var banner: AdropBanner? = null

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

        // 1. Create banner instance
        banner = AdropBanner(this, "YOUR_UNIT_ID").apply {
            // 2. Set listener
            listener = object : AdropBannerListener {
                override fun onAdReceived(banner: AdropBanner) {
                    println("Banner ad received successfully")
                }

                override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
                    println("Banner ad failed to receive: $errorCode")
                }

                override fun onAdImpression(banner: AdropBanner) {
                    println("Banner ad impression")
                }

                override fun onAdClicked(banner: AdropBanner) {
                    println("Banner ad clicked")
                }
            }
        }

        // 3. Add to view hierarchy
        val container = findViewById<FrameLayout>(R.id.banner_container)
        val params = FrameLayout.LayoutParams(
            FrameLayout.LayoutParams.MATCH_PARENT,
            FrameLayout.LayoutParams.WRAP_CONTENT
        )
        container.addView(banner, params)

        // 4. Load ad
        banner?.load()
    }

    override fun onDestroy() {
        super.onDestroy()
        // 5. Release memory
        banner?.destroy()
        banner = null
    }
}

import android.os.Bundle;
import android.widget.FrameLayout;
import androidx.appcompat.app.AppCompatActivity;
import io.adrop.ads.banner.AdropBanner;
import io.adrop.ads.banner.AdropBannerListener;
import io.adrop.ads.model.AdropErrorCode;
import org.jetbrains.annotations.NotNull;

public class MainActivity extends AppCompatActivity {
    private AdropBanner banner;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // 1. Create banner instance (unitId is required in constructor)
        banner = new AdropBanner(this, "YOUR_UNIT_ID");

        // 2. Set listener
        banner.setListener(new AdropBannerListener() {
            @Override
            public void onAdReceived(@NotNull AdropBanner banner) {
                System.out.println("Banner ad received successfully");
            }

            @Override
            public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
                System.out.println("Banner ad failed to receive: " + errorCode);
            }

            @Override
            public void onAdImpression(@NotNull AdropBanner banner) {
                System.out.println("Banner ad impression");
            }

            @Override
            public void onAdClicked(@NotNull AdropBanner banner) {
                System.out.println("Banner ad clicked");
            }
        });

        // 3. Add to view hierarchy
        FrameLayout container = findViewById(R.id.banner_container);
        FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(
            FrameLayout.LayoutParams.MATCH_PARENT,
            FrameLayout.LayoutParams.WRAP_CONTENT
        );
        container.addView(banner, params);

        // 4. Load ad
        banner.load();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        // 5. Release memory
        if (banner != null) {
            banner.destroy();
            banner = null;
        }
    }
}

AdropBanner Initialization

Constructor

Context

required

Activity or Application Context

val banner = AdropBanner(context, "YOUR_UNIT_ID")

AdropBanner banner = new AdropBanner(context, "YOUR_UNIT_ID");

Set Unit ID

String

required

Unit ID created in Ad Control Console

banner.setUnitId("YOUR_UNIT_ID")

banner.setUnitId("YOUR_UNIT_ID");

Load Ad

Call load() method after adding the banner to the screen to request ads.

banner.load()

banner.load();

Call load() when the banner is visible on screen. Loading when not visible may result in inaccurate impression measurement.

Listener Implementation

The AdropBannerListener interface handles ad lifecycle events.

onAdReceived (Required)

Called when ad is successfully received.

override fun onAdReceived(banner: AdropBanner) {
    println("Banner ad received successfully")
    // Hide loading indicator, etc.
}

@Override
public void onAdReceived(@NotNull AdropBanner banner) {
    System.out.println("Banner ad received successfully");
    // Hide loading indicator, etc.
}

onAdFailedToReceive (Required)

Called when ad fails to receive.

override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
    println("Banner ad failed to receive: $errorCode")
    // Handle error and show fallback content
}

@Override
public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
    System.out.println("Banner ad failed to receive: " + errorCode);
    // Handle error and show fallback content
}

AdropErrorCode

Code indicating error type. See Reference for details.

onAdImpression (Optional)

Called when ad is displayed on screen.

override fun onAdImpression(banner: AdropBanner) {
    println("Banner ad impression")
    // Log impression analytics, etc.
}

@Override
public void onAdImpression(@NotNull AdropBanner banner) {
    System.out.println("Banner ad impression");
    // Log impression analytics, etc.
}

onAdClicked (Required)

Called when user clicks the ad.

override fun onAdClicked(banner: AdropBanner) {
    println("Banner ad clicked")
    // Log click analytics, etc.
}

@Override
public void onAdClicked(@NotNull AdropBanner banner) {
    System.out.println("Banner ad clicked");
    // Log click analytics, etc.
}

onAdVideoStart (Optional)

Called when video playback starts in a video banner ad.

override fun onAdVideoStart(banner: AdropBanner) {
    println("Banner video started")
}

@Override
public void onAdVideoStart(@NotNull AdropBanner banner) {
    System.out.println("Banner video started");
}

onAdVideoEnd (Optional)

Called when video playback ends in a video banner ad.

override fun onAdVideoEnd(banner: AdropBanner) {
    println("Banner video ended")
}

@Override
public void onAdVideoEnd(@NotNull AdropBanner banner) {
    System.out.println("Banner video ended");
}

Context ID Setting

You can set Context ID for contextual targeting.

// contextId is read-only — set via constructor
val banner = AdropBanner(this, "YOUR_UNIT_ID", "article_sports")

// contextId is read-only — set via constructor
AdropBanner banner = new AdropBanner(this, "YOUR_UNIT_ID", "article_sports");

Context ID must be set before loading the ad.

Lifecycle Management

destroy()

Always call destroy() to release resources when the banner is no longer used.

override fun onDestroy() {
    super.onDestroy()
    banner?.destroy()
    banner = null
}

@Override
protected void onDestroy() {
    super.onDestroy();
    if (banner != null) {
        banner.destroy();
        banner = null;
    }
}

Memory leaks may occur if destroy() is not called.

Ad Sizes

Banner ads should have view size matching the unit settings.

Size	Usage
320 x 50	Small banner
320 x 100	Medium banner
16:9 ratio	Video banner

Specify Size in XML

<io.adrop.ads.banner.AdropBanner
    android:id="@+id/adrop_banner"
    android:layout_width="320dp"
    android:layout_height="100dp"
    app:adrop_unit_id="YOUR_UNIT_ID" />

Specify Size in Code

val params = FrameLayout.LayoutParams(
    dpToPx(320), // width
    dpToPx(100)   // height
)
container.addView(banner, params)

// Utility function to convert dp to px
fun dpToPx(dp: Int): Int {
    val density = resources.displayMetrics.density
    return (dp * density).toInt()
}

FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(
    dpToPx(320), // width
    dpToPx(100)   // height
);
container.addView(banner, params);

// Utility function to convert dp to px
private int dpToPx(int dp) {
    float density = getResources().getDisplayMetrics().density;
    return (int) (dp * density);
}

Test Unit IDs

Use the following test unit IDs during development and testing.

Ad Type	Test Unit ID	Size
Banner (320x50)	`PUBLIC_TEST_UNIT_ID_320_50`	320 x 50
Banner (320x100)	`PUBLIC_TEST_UNIT_ID_320_100`	320 x 100
Carousel Banner	`PUBLIC_TEST_UNIT_ID_CAROUSEL`	Variable
Banner Video (16:9)	`PUBLIC_TEST_UNIT_ID_BANNER_VIDEO_16_9`	16:9 ratio
Banner Video (9:16)	`PUBLIC_TEST_UNIT_ID_BANNER_VIDEO_9_16`	9:16 ratio

Usage Example

val banner = AdropBanner(this, "PUBLIC_TEST_UNIT_ID_320_100")

AdropBanner banner = new AdropBanner(this, "PUBLIC_TEST_UNIT_ID_320_100");

<io.adrop.ads.banner.AdropBanner
    android:id="@+id/adrop_banner"
    android:layout_width="320dp"
    android:layout_height="100dp"
    app:adrop_unit_id="PUBLIC_TEST_UNIT_ID_320_100" />

Video Playback Control

For video banner ads, you can manually control video playback using play() and pause().

play()

Resumes video playback. Call this when the banner becomes visible again — for example, after a popup is dismissed or the app returns from the background.

banner?.play()

banner.play();

pause()

Pauses video playback. Call this when the banner is hidden by a popup or the app enters the background.

banner?.pause()

banner.pause();

Example: Background/Foreground Handling

override fun onResume() {
    super.onResume()
    banner?.play()
}

override fun onPause() {
    super.onPause()
    banner?.pause()
}

@Override
protected void onResume() {
    super.onResume();
    if (banner != null) {
        banner.play();
    }
}

@Override
protected void onPause() {
    super.onPause();
    if (banner != null) {
        banner.pause();
    }
}

play() and pause() only affect video banner ads. They have no effect on image banners.

Custom Click Handling

By default, the SDK automatically opens the destination URL when a user clicks the banner ad. If you want to handle click events yourself (e.g., to show a confirmation dialog or track analytics before opening), you can use useCustomClick.

Boolean

default:"false"

When true, the SDK will not automatically open the destination URL on click. Only the onAdClicked event is fired. You must call open() manually to open the destination.

// 1. Enable custom click handling
banner?.useCustomClick = true

// 2. Handle click in listener
banner?.listener = object : AdropBannerListener {
    override fun onAdClicked(banner: AdropBanner) {
        // Perform custom logic (e.g., show dialog, log analytics)
        println("Ad clicked — opening destination")
        banner.open()
    }

    // ... other listener methods
}

// 1. Enable custom click handling
banner.setUseCustomClick(true);

// 2. Handle click in listener
banner.setListener(new AdropBannerListener() {
    @Override
    public void onAdClicked(@NotNull AdropBanner banner) {
        // Perform custom logic (e.g., show dialog, log analytics)
        System.out.println("Ad clicked — opening destination");
        banner.open();
    }

    // ... other listener methods
});

open()

Opens the ad’s destination URL. You can also pass a custom URL to open instead.

// Open the default destination URL
banner?.open()

// Open a custom URL
banner?.open("https://example.com")

// Open the default destination URL
banner.open();

// Open a custom URL
banner.open("https://example.com");

open() only works when useCustomClick is set to true. If useCustomClick is false (default), the SDK handles URL opening automatically.

Best Practices

1. Memory Management

Always release the banner when Activity or Fragment is destroyed.

override fun onDestroy() {
    super.onDestroy()
    banner?.destroy()
    banner = null
}

@Override
protected void onDestroy() {
    super.onDestroy();
    if (banner != null) {
        banner.destroy();
        banner = null;
    }
}

2. Screen Visibility

Load ads when the banner is visible on screen.

override fun onResume() {
    super.onResume()
    banner?.load()
}

@Override
protected void onResume() {
    super.onResume();
    if (banner != null) {
        banner.load();
    }
}

3. Error Handling

Implement proper error handling when ad load fails.

override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
    when (errorCode) {
        AdropErrorCode.ERROR_CODE_NETWORK -> {
            println("Network error: Check connection")
        }
        AdropErrorCode.ERROR_CODE_AD_NO_FILL -> {
            println("No ads available")
        }
        else -> {
            println("Ad load failed: $errorCode")
        }
    }
}

@Override
public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
    if (errorCode == AdropErrorCode.ERROR_CODE_NETWORK) {
        System.out.println("Network error: Check connection");
    } else if (errorCode == AdropErrorCode.ERROR_CODE_AD_NO_FILL) {
        System.out.println("No ads available");
    } else {
        System.out.println("Ad load failed: " + errorCode);
    }
}

4. Using in RecyclerView

Properly manage banners in ViewHolder when using in RecyclerView.

class BannerViewHolder(view: View) : RecyclerView.ViewHolder(view) {
    private val banner: AdropBanner = view.findViewById(R.id.adrop_banner)

    fun bind() {
        banner.listener = object : AdropBannerListener {
            // Implement listener
        }
        banner.load()
    }

    fun recycle() {
        banner.destroy()
    }
}

// In adapter
override fun onViewRecycled(holder: BannerViewHolder) {
    holder.recycle()
}

class BannerViewHolder extends RecyclerView.ViewHolder {
    private AdropBanner banner;

    public BannerViewHolder(View view) {
        super(view);
        banner = view.findViewById(R.id.adrop_banner);
    }

    public void bind() {
        banner.setListener(new AdropBannerListener() {
            // Implement listener
        });
        banner.load();
    }

    public void recycle() {
        banner.destroy();
    }
}

// In adapter
@Override
public void onViewRecycled(BannerViewHolder holder) {
    holder.recycle();
}

Complete Example

Kotlin Example

import android.os.Bundle
import android.view.View
import android.widget.FrameLayout
import android.widget.ProgressBar
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import io.adrop.ads.banner.AdropBanner
import io.adrop.ads.banner.AdropBannerListener
import io.adrop.ads.model.AdropErrorCode

class BannerActivity : AppCompatActivity() {
    private var banner: AdropBanner? = null
    private lateinit var progressBar: ProgressBar

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

        progressBar = findViewById(R.id.progress_bar)
        setupBanner()
    }

    private fun setupBanner() {
        // 1. Create banner instance
        // contextId is set via constructor (read-only property)
        banner = AdropBanner(this, "YOUR_UNIT_ID", "article_sports").apply {
            // 2. Set listener
            listener = object : AdropBannerListener {
                override fun onAdReceived(banner: AdropBanner) {
                    println("Banner ad received successfully")
                    progressBar.visibility = View.GONE
                }

                override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
                    println("Banner ad failed to receive: $errorCode")
                    progressBar.visibility = View.GONE

                    // Handle based on error
                    when (errorCode) {
                        AdropErrorCode.ERROR_CODE_NETWORK -> {
                            showToast("Please check network connection")
                        }
                        AdropErrorCode.ERROR_CODE_AD_NO_FILL -> {
                            println("No ads available")
                        }
                        else -> {
                            showToast("Unable to load ad")
                        }
                    }
                }

                override fun onAdImpression(banner: AdropBanner) {
                    println("Banner ad impression")
                }

                override fun onAdClicked(banner: AdropBanner) {
                    println("Banner ad clicked")
                }
            }
        }

        // 3. Add to view hierarchy
        val container = findViewById<FrameLayout>(R.id.banner_container)
        val params = FrameLayout.LayoutParams(
            dpToPx(320),
            dpToPx(100)
        )
        container.addView(banner, params)

        // 4. Load ad
        progressBar.visibility = View.VISIBLE
        banner?.load()
    }

    private fun dpToPx(dp: Int): Int {
        val density = resources.displayMetrics.density
        return (dp * density).toInt()
    }

    private fun showToast(message: String) {
        Toast.makeText(this, message, Toast.LENGTH_SHORT).show()
    }

    override fun onDestroy() {
        super.onDestroy()
        // 5. Release memory
        banner?.destroy()
        banner = null
    }
}

Java Example

import android.os.Bundle;
import android.view.View;
import android.widget.FrameLayout;
import android.widget.ProgressBar;
import android.widget.Toast;
import androidx.appcompat.app.AppCompatActivity;
import io.adrop.ads.banner.AdropBanner;
import io.adrop.ads.banner.AdropBannerListener;
import io.adrop.ads.model.AdropErrorCode;
import org.jetbrains.annotations.NotNull;

public class BannerActivity extends AppCompatActivity {
    private AdropBanner banner;
    private ProgressBar progressBar;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_banner);

        progressBar = findViewById(R.id.progress_bar);
        setupBanner();
    }

    private void setupBanner() {
        // 1. Create banner instance (with context ID)
        banner = new AdropBanner(this, "YOUR_UNIT_ID", "article_sports");

        // 2. Set listener
        banner.setListener(new AdropBannerListener() {
            @Override
            public void onAdReceived(@NotNull AdropBanner banner) {
                System.out.println("Banner ad received successfully");
                progressBar.setVisibility(View.GONE);
            }

            @Override
            public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
                System.out.println("Banner ad failed to receive: " + errorCode);
                progressBar.setVisibility(View.GONE);

                // Handle based on error
                if (errorCode == AdropErrorCode.ERROR_CODE_NETWORK) {
                    showToast("Please check network connection");
                } else if (errorCode == AdropErrorCode.ERROR_CODE_AD_NO_FILL) {
                    System.out.println("No ads available");
                } else {
                    showToast("Unable to load ad");
                }
            }

            @Override
            public void onAdImpression(@NotNull AdropBanner banner) {
                System.out.println("Banner ad impression");
            }

            @Override
            public void onAdClicked(@NotNull AdropBanner banner) {
                System.out.println("Banner ad clicked");
            }
        });

        // 3. Add to view hierarchy
        FrameLayout container = findViewById(R.id.banner_container);
        FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(
            dpToPx(320),
            dpToPx(100)
        );
        container.addView(banner, params);

        // 4. Load ad
        progressBar.setVisibility(View.VISIBLE);
        banner.load();
    }

    private int dpToPx(int dp) {
        float density = getResources().getDisplayMetrics().density;
        return (int) (dp * density);
    }

    private void showToast(String message) {
        Toast.makeText(this, message, Toast.LENGTH_SHORT).show();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        // 5. Release memory
        if (banner != null) {
            banner.destroy();
            banner = null;
        }
    }
}

XML Layout

activity_banner.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <TextView
        android:id="@+id/title"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Banner Ad Example"
        android:textSize="24sp"
        android:textStyle="bold"
        android:layout_marginTop="32dp"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent" />

    <ProgressBar
        android:id="@+id/progress_bar"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:visibility="gone"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

    <FrameLayout
        android:id="@+id/banner_container"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_margin="16dp"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

Batch Loading (loads)

Use AdropBanner.loads() to request multiple banner ads in a single batched call. This is useful for building carousels, paginated feeds, or prefetching a pool of ads.

Signature

AdropBanner.loads(
    context: Context,
    unitId: String,
    contextId: String? = null,
    listener: AdropBannerListener,
)

AdropBanner.loads(context, "YOUR_UNIT_ID", null, listener);

Usage

AdropBanner.loads(
    context = this,
    unitId = "YOUR_UNIT_ID",
    contextId = null,
    listener = object : AdropBannerListener {
        // Batch success — deliver up to 5 ready-to-use banners
        override fun onAdsReceived(banners: List<AdropBanner>) {
            banners.forEach { banner ->
                // Attach to your view hierarchy (ViewPager2, RecyclerView, etc.)
                container.addView(banner)
            }
        }

        // Batch failure
        override fun onAdsFailedToReceive(errorCode: AdropErrorCode) {
            println("Batch load failed: $errorCode")
        }

        // Single-load callbacks are NOT invoked on this path.
        override fun onAdReceived(banner: AdropBanner) { /* batch path */ }
        override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {}

        // Click / impression / video callbacks still fire per instance.
        override fun onAdClicked(banner: AdropBanner) {
            println("Banner clicked: ${banner.creativeId}")
        }

        override fun onAdImpression(banner: AdropBanner) {
            println("Banner impression: ${banner.creativeId}")
        }
    },
)

AdropBanner.loads(this, "YOUR_UNIT_ID", null, new AdropBannerListener() {
    @Override
    public void onAdsReceived(@NotNull List<AdropBanner> banners) {
        for (AdropBanner banner : banners) {
            container.addView(banner);
        }
    }

    @Override
    public void onAdsFailedToReceive(@NotNull AdropErrorCode errorCode) {
        System.out.println("Batch load failed: " + errorCode);
    }

    // Required single-load callbacks — unused on the batch path.
    @Override
    public void onAdReceived(@NotNull AdropBanner banner) { }

    @Override
    public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) { }

    @Override
    public void onAdClicked(@NotNull AdropBanner banner) {
        System.out.println("Banner clicked: " + banner.getCreativeId());
    }

    @Override
    public void onAdImpression(@NotNull AdropBanner banner) {
        System.out.println("Banner impression: " + banner.getCreativeId());
    }
});

Listener Callbacks

Callback	When it fires
`onAdsReceived(banners)`	Batch delivered. Each `AdropBanner` already has the listener attached and its ad data applied.
`onAdsFailedToReceive(errorCode)`	Request rejected, network failure, or no fillable ads were returned (`ERROR_CODE_AD_NO_FILL`).
`onAdClicked` / `onAdImpression` / `onAdVideoStart` / `onAdVideoEnd`	Fire on each returned banner just like a single `load()`.

The singular onAdReceived / onAdFailedToReceive callbacks are not invoked on the loads() path. Use onAdsReceived / onAdsFailedToReceive as the sole batch signals.

Constraints

Maximum 5 ads per call. If the server returns more, only the first 5 are delivered.
Backfill is not applied. If no direct ads fill, onAdsFailedToReceive is called with ERROR_CODE_AD_NO_FILL regardless of backfill configuration.
Do not call destroy() inside onAdsReceived. Attach each banner to a view hierarchy first, then destroy() on the parent Activity.onDestroy() (or equivalent).
onAdsReceived fires as soon as ad data is applied, matching the single load() contract — the creative paints shortly after attachment.

Backfill Ads

When backfill ads are enabled, backfill ads are automatically loaded when no direct ads are available. You can check if an ad is a backfill ad using the isBackfilled property.

banner.listener = object : AdropBannerListener {
    override fun onAdReceived(banner: AdropBanner) {
        if (banner.isBackfilled) {
            println("Backfill ad loaded")
        } else {
            println("Direct ad loaded")
        }
    }

    override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
        when (errorCode) {
            AdropErrorCode.ERROR_CODE_AD_NO_FILL -> {
                println("No direct ad, requesting backfill...")
            }
            AdropErrorCode.ERROR_CODE_AD_BACKFILL_NO_FILL -> {
                println("Backfill ad also not available")
            }
            else -> {
                println("Ad load failed: $errorCode")
            }
        }
    }
}

banner.setListener(new AdropBannerListener() {
    @Override
    public void onAdReceived(@NotNull AdropBanner banner) {
        if (banner.isBackfilled()) {
            System.out.println("Backfill ad loaded");
        } else {
            System.out.println("Direct ad loaded");
        }
    }

    @Override
    public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
        if (errorCode == AdropErrorCode.ERROR_CODE_AD_NO_FILL) {
            System.out.println("No direct ad, requesting backfill...");
        } else if (errorCode == AdropErrorCode.ERROR_CODE_AD_BACKFILL_NO_FILL) {
            System.out.println("Backfill ad also not available");
        } else {
            System.out.println("Ad load failed: " + errorCode);
        }
    }
});

To use backfill ads, you must add the io.adrop:adrop-ads-backfill dependency.

Preloading Backfill Ads (preload)

Starting with SDK 1.17.0, you can use AdropBanner.preload() to preload a backfill banner ad. When a banner that you load() with the same unit ID and the same size gets no direct ad and falls back to a backfill ad, it displays the preloaded ad right away instead of requesting a backfill ad again. load() still requests a direct ad first, regardless of preload. If a direct ad is displayed, the preloaded ad is kept as is. If you don’t call preload, the behavior is the same as before.

Requirements

Both io.adrop:adrop-ads and io.adrop:adrop-ads-backfill must be 1.17.0 or later.
Preload fetches a backfill ad only when the server has told the app that there are no direct ads to show right now. Otherwise, it ends with ERROR_CODE_AD_PRELOAD_SKIPPED without requesting a backfill ad. This is a normal result in apps that have direct ad campaigns.
Right after the app is installed, right after you change the App Key, and right after you switch to a different user with setUID, preload ends with ERROR_CODE_AD_PRELOAD_SKIPPED until the server response arrives.
With test unit IDs, preload always ends with ERROR_CODE_AD_PRELOAD_SKIPPED.

Usage

Pass the Activity that will display the banner as context, and call preload right before you open the screen that contains the banner. A preloaded ad is discarded after 30 minutes if it isn’t used, so call preload only for banners you’re about to display. You don’t need to wait for the result before calling load(). If the ad is still being fetched, load() waits for that result and uses it.

import io.adrop.ads.banner.AdropBanner
import io.adrop.ads.banner.AdropBannerListener
import io.adrop.ads.model.AdropErrorCode
import io.adrop.ads.model.CreativeSize

AdropBanner.preload(
    context = this, // Activity that will display the banner
    unitId = "YOUR_UNIT_ID",
    adSize = CreativeSize(320.0, 50.0), // 320x50 if omitted
    listener = object : AdropBannerListener {
        override fun onAdPreloadReceived(unitId: String, contextId: String?) {
            println("Preload complete: $unitId")
        }

        override fun onAdPreloadFailedToReceive(unitId: String, contextId: String?, errorCode: AdropErrorCode) {
            // ERROR_CODE_AD_PRELOAD_SKIPPED is a normal result.
            // Don't call preload again right away here.
            println("Not preloaded: $errorCode")
        }

        // Not called for preload.
        override fun onAdReceived(banner: AdropBanner) {}
        override fun onAdClicked(banner: AdropBanner) {}
        override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {}
    },
)

import io.adrop.ads.banner.AdropBanner;
import io.adrop.ads.banner.AdropBannerListener;
import io.adrop.ads.model.AdropErrorCode;
import io.adrop.ads.model.CreativeSize;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

AdropBanner.preload(this, "YOUR_UNIT_ID", null, new CreativeSize(320.0, 50.0), new AdropBannerListener() {
    @Override
    public void onAdPreloadReceived(@NotNull String unitId, @Nullable String contextId) {
        System.out.println("Preload complete: " + unitId);
    }

    @Override
    public void onAdPreloadFailedToReceive(@NotNull String unitId, @Nullable String contextId, @NotNull AdropErrorCode errorCode) {
        // ERROR_CODE_AD_PRELOAD_SKIPPED is a normal result.
        // Don't call preload again right away here.
        System.out.println("Not preloaded: " + errorCode);
    }

    // Not called for preload.
    @Override
    public void onAdReceived(@NotNull AdropBanner banner) { }

    @Override
    public void onAdClicked(@NotNull AdropBanner banner) { }

    @Override
    public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) { }
});

To use the preloaded ad, set the adSize of the banner you load() to the same size you passed to preload.

val banner = AdropBanner(this, "YOUR_UNIT_ID")
banner.adSize = CreativeSize(320.0, 50.0) // Size passed to preload
container.addView(banner)
banner.load()

AdropBanner banner = new AdropBanner(this, "YOUR_UNIT_ID", null);
banner.setAdSize(new CreativeSize(320.0, 50.0)); // Size passed to preload
container.addView(banner);
banner.load();

When a Preloaded Ad Is Used

Same unit ID and same size: The adSize of the banner you load() (or, if you haven’t set it, the size of the view as laid out on screen, in dp) must match the size you passed to preload. If the size differs, the preloaded ad is kept as is, and load() requests a backfill ad as usual.
Same Activity: A preloaded ad isn’t used by a banner created with a different Activity from the one you passed to preload (for example, if you preload in a splash Activity and call load() in the main Activity). When the Activity you passed to preload finishes, the preloaded ad is discarded as well.
Used only once: A preloaded ad is gone once a single load() uses it. To preload again, call preload again.
Lifetime and count: An ad that isn’t used within 30 minutes is discarded. Only 1 ad is kept per unit and size, and banners keep up to 5 different unit/size combinations. When there are more than 5, ads are discarded starting with the one received first.
Calling again: Calling preload again with the same unit and size doesn’t make a new request. If an ad has already been preloaded, onAdPreloadReceived is called without a new request; if one is still being fetched, you get that load’s result (success or failure). You can’t use preload to refresh an ad. However, if the user consent status has changed in the meantime, or if you call it with a different Activity, the existing ad is discarded and a new one is fetched.
Consent status changes: If the user consent status changes after an ad is preloaded, that ad isn’t used by load().

Result Callbacks

The following callbacks have been added to AdropBannerListener. Both are optional to implement, and each time you call preload, one of the two is called once on the main thread. No other listener callbacks are called for preload.

Callback	When it fires
`onAdPreloadReceived(unitId, contextId)`	When preloading has finished. A `load()` that was waiting for that result may have already used the ad.
`onAdPreloadFailedToReceive(unitId, contextId, errorCode)`	When the ad couldn’t be preloaded

contextId returns the value you passed to preload as is. It isn’t used to select a preloaded ad.

Failure Codes

Error Code	Description
`ERROR_CODE_AD_PRELOAD_SKIPPED`	No backfill ad was requested because direct ads may be shown, or because that hasn’t been confirmed yet. This is a normal result, so call preload again right before you open the next screen.
`ERROR_CODE_AD_NO_FILL`	The backfill dependency (1.17.0 or later) is missing, backfill isn’t configured for the unit, or the SDK hasn’t received that configuration yet. Call preload again a little later. If the backfill dependency is missing, preload keeps ending with this code.
`ERROR_CODE_AD_BACKFILL_NO_FILL`	No backfill ad is available.
`ERROR_CODE_INTERNAL`	The request was interrupted (for example, the Activity you passed to preload finished while the ad was being fetched) or an internal error occurred. Call preload again later.
`ERROR_CODE_INITIALIZE`	The SDK isn’t initialized. Preload also ends with this code on devices that aren’t in the target countries of `Adrop.initialize()`.
`ERROR_CODE_INVALID_UNIT`	The unit ID is empty.

Don’t call preload again right away inside the failure callback. If the result doesn’t change — for example, when the backfill dependency is missing — the calls repeat endlessly. Call it again later, such as before you open the next screen.

Next Steps

Native Ads

Implement customizable native ads that match your UI

Interstitial Ads

Implement full-screen interstitial ads

Targeting

Set up user attributes and contextual targeting

Reference

View classes, listeners, and error codes

​Overview

​Key Features

​XML Layout Implementation

​1. Define XML Layout

​2. Load in Activity

​XML Attributes

​Programmatic Implementation

​AdropBanner Initialization

​Constructor

​Set Unit ID

​Load Ad

​Listener Implementation

​onAdReceived (Required)

​onAdFailedToReceive (Required)

​onAdImpression (Optional)

​onAdClicked (Required)

​onAdVideoStart (Optional)

​onAdVideoEnd (Optional)

​Context ID Setting

​Lifecycle Management

​destroy()

​Ad Sizes

​Common Banner Sizes

​Specify Size in XML

​Specify Size in Code

​Test Unit IDs

​Usage Example

​Video Playback Control

​play()

​pause()

​Example: Background/Foreground Handling

​Custom Click Handling

​open()

​Best Practices

​1. Memory Management

​2. Screen Visibility

​3. Error Handling

​4. Using in RecyclerView

​Complete Example

​Kotlin Example

​Java Example

​XML Layout

​Batch Loading (loads)

​Signature

​Usage

​Listener Callbacks

​Constraints

​Backfill Ads

​Preloading Backfill Ads (preload)

​Requirements

​Usage

​When a Preloaded Ad Is Used

​Result Callbacks

​Failure Codes

​Next Steps

Native Ads

Interstitial Ads

Targeting

Reference

Overview

Key Features

XML Layout Implementation

1. Define XML Layout

2. Load in Activity

XML Attributes

Programmatic Implementation

AdropBanner Initialization

Constructor

Set Unit ID

Load Ad

Listener Implementation

onAdReceived (Required)

onAdFailedToReceive (Required)

onAdImpression (Optional)

onAdClicked (Required)

onAdVideoStart (Optional)

onAdVideoEnd (Optional)

Context ID Setting

Lifecycle Management

destroy()

Ad Sizes

Common Banner Sizes

Specify Size in XML

Specify Size in Code

Test Unit IDs

Usage Example

Video Playback Control

play()

pause()

Example: Background/Foreground Handling

Custom Click Handling

open()

Best Practices

1. Memory Management

2. Screen Visibility

3. Error Handling

4. Using in RecyclerView

Complete Example

Kotlin Example

Java Example

XML Layout

Batch Loading (loads)

Signature

Usage

Listener Callbacks

Constraints

Backfill Ads

Preloading Backfill Ads (preload)

Requirements

Usage

When a Preloaded Ad Is Used

Result Callbacks

Failure Codes

Next Steps