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_123")

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

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_123").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_123");

        // 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.

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

​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

Next Steps