Banner Ads - Ad Control Help Center

Overview

Banner ads are rectangular ads displayed in a portion of the screen. They can be used in both UIKit and SwiftUI.

Key Features

Can be fixed at the top, bottom, or middle of the screen
Supports both image and video ads
Supports both UIKit and SwiftUI
Ad event handling through delegates

Use test unit ID in development environment: PUBLIC_TEST_UNIT_ID_320_100

UIKit Implementation

In UIKit environment, implement banner ads using the AdropBanner class.

Basic Implementation

import UIKit
import AdropAds

class ViewController: UIViewController {
    private var banner: AdropBanner?

    override func viewDidLoad() {
        super.viewDidLoad()

        // 1. Create banner instance
        banner = AdropBanner(unitId: "YOUR_UNIT_ID")

        // 2. Set delegate
        banner?.delegate = self

        // 3. Add to view hierarchy
        if let bannerView = banner {
            view.addSubview(bannerView)

            // 4. Setup Auto Layout
            bannerView.translatesAutoresizingMaskIntoConstraints = false
            NSLayoutConstraint.activate([
                bannerView.centerXAnchor.constraint(equalTo: view.centerXAnchor),
                bannerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor),
                bannerView.widthAnchor.constraint(equalToConstant: 320),
                bannerView.heightAnchor.constraint(equalToConstant: 100)
            ])
        }

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

    deinit {
        // 6. Release banner resources before deallocation
        banner?.destroy()
        banner = nil
    }
}

// MARK: - AdropBannerDelegate
extension ViewController: AdropBannerDelegate {
    func onAdReceived(_ banner: AdropBanner) {
        print("Banner ad received successfully")
    }

    func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {
        print("Banner ad failed to receive: \(errorCode)")
    }

    func onAdImpression(_ banner: AdropBanner) {
        print("Banner ad impression")
    }

    func onAdClicked(_ banner: AdropBanner) {
        print("Banner ad clicked")
    }
}

AdropBanner Initialization

String

required

Unit ID created in Ad Control Console

let banner = AdropBanner(unitId: "YOUR_UNIT_ID")

Load Ad

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

banner?.load()

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

Set Context ID

You can set a Context ID for contextual targeting.

// contextId is read-only — set via initializer
let banner = AdropBanner(unitId: "YOUR_UNIT_ID", contextId: "article_123")

SwiftUI Implementation

In SwiftUI environment, implement banner ads using AdropBannerRepresented.

Basic Implementation

import SwiftUI
import AdropAds

struct ContentView: View {
    @State private var represented = AdropBannerRepresented(unitId: "YOUR_UNIT_ID")

    var body: some View {
        VStack {
            Spacer()

            Text("Main Content")

            Spacer()

            // Banner ad
            represented
                .frame(width: 320, height: 100)
                .onAppear {
                    represented.banner.load()
                }
        }
    }
}

Delegate Handling

You can handle ad events through delegates.

import SwiftUI
import AdropAds

struct ContentView: View {
    @StateObject private var bannerDelegate = BannerDelegate()
    @State private var represented = AdropBannerRepresented(unitId: "YOUR_UNIT_ID")

    var body: some View {
        VStack {
            Spacer()

            if bannerDelegate.isLoaded {
                Text("Ad loaded successfully")
            }

            represented
                .frame(width: 320, height: 100)
                .onAppear {
                    represented.delegate = bannerDelegate
                    represented.banner.load()
                }
        }
    }
}

// Delegate implementation
class BannerDelegate: NSObject, ObservableObject, AdropBannerDelegate {
    @Published var isLoaded = false

    func onAdReceived(_ banner: AdropBanner) {
        print("Banner ad received successfully")
        isLoaded = true
    }

    func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {
        print("Banner ad failed to receive: \(errorCode)")
        isLoaded = false
    }

    func onAdImpression(_ banner: AdropBanner) {
        print("Banner ad impression")
    }

    func onAdClicked(_ banner: AdropBanner) {
        print("Banner ad clicked")
    }
}

Set Context ID

AdropBannerRepresented(
    unitId: "YOUR_UNIT_ID",
    contextId: "article_123"
)
.frame(width: 320, height: 100)

Objective-C Implementation

How to implement banner ads in Objective-C environment.

Basic Implementation

@import AdropAds;

@interface ViewController () <AdropBannerDelegate>
@property (nonatomic, strong) AdropBanner *banner;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // 1. Create banner instance
    self.banner = [[AdropBanner alloc] initWithUnitId:@"YOUR_UNIT_ID"];

    // 2. Set delegate
    self.banner.delegate = self;

    // 3. Add to view hierarchy
    [self.view addSubview:self.banner];

    // 4. Setup Auto Layout
    self.banner.translatesAutoresizingMaskIntoConstraints = NO;
    [NSLayoutConstraint activateConstraints:@[
        [self.banner.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
        [self.banner.bottomAnchor constraintEqualToAnchor:self.view.safeAreaLayoutGuide.bottomAnchor],
        [self.banner.widthAnchor constraintEqualToConstant:320],
        [self.banner.heightAnchor constraintEqualToConstant:100]
    ]];

    // 5. Load ad
    [self.banner load];
}

- (void)dealloc {
    [self.banner destroy];
    self.banner = nil;
}

#pragma mark - AdropBannerDelegate

- (void)onAdReceived:(AdropBanner *)banner {
    NSLog(@"Banner ad received successfully");
}

- (void)onAdFailedToReceive:(AdropBanner *)banner :(AdropErrorCode)errorCode {
    NSLog(@"Banner ad failed to receive: %ld", (long)errorCode);
}

- (void)onAdImpression:(AdropBanner *)banner {
    NSLog(@"Banner ad impression");
}

- (void)onAdClicked:(AdropBanner *)banner {
    NSLog(@"Banner ad clicked");
}

@end

Set Context ID

// contextId is read-only — set via initializer
AdropBanner *banner = [[AdropBanner alloc] initWithUnitId:@"YOUR_UNIT_ID" contextId:@"article_123"];

Delegate Methods

The AdropBannerDelegate protocol handles ad lifecycle events.

onAdReceived (Required)

Called when ad is received successfully.

func onAdReceived(_ banner: AdropBanner) {
    print("Banner ad received successfully")
    // Handle ad loading indicator, etc.
}

onAdFailedToReceive (Required)

Called when ad fails to load.

func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {
    print("Banner ad failed to receive: \(errorCode)")
    // Handle errors and display alternative content
}

AdropErrorCode

Error code indicating the type of error. See Reference for details.

onAdImpression (Optional)

Called when ad is displayed on screen.

func onAdImpression(_ banner: AdropBanner) {
    print("Banner ad impression")
    // Handle impression analytics logging, etc.
}

onAdClicked (Optional)

Called when user clicks on the ad.

func onAdClicked(_ banner: AdropBanner) {
    print("Banner ad clicked")
    // Handle click analytics logging, etc.
}

onAdVideoStart (Optional)

Called when a video ad starts playing.

func onAdVideoStart(_ banner: AdropBanner) {
    print("Banner video started")
    // Handle video start analytics logging, etc.
}

onAdVideoEnd (Optional)

Called when a video ad finishes playing.

func onAdVideoEnd(_ banner: AdropBanner) {
    print("Banner video ended")
    // Handle video end analytics logging, etc.
}

Closure Callbacks

As an alternative to delegates, you can use closure-based callbacks.

let banner = AdropBanner(unitId: "YOUR_UNIT_ID")

banner.onAdReceived = { banner in
    print("Banner ad received")
}

banner.onAdFailedToReceive = { banner, errorCode in
    print("Banner ad failed: \(errorCode)")
}

banner.onAdImpression = { banner in
    print("Banner ad impression")
}

banner.onAdClicked = { banner in
    print("Banner ad clicked")
}

banner.onAdVideoStart = { banner in
    print("Banner video started")
}

banner.onAdVideoEnd = { banner in
    print("Banner video ended")
}

If both a delegate and closures are set, both will be called.

Lifecycle Management

destroy()

When you no longer need the banner, call destroy() to release its resources — WebView, tracking, and any active video playback are torn down actively. destroy() is idempotent, so calling it multiple times is safe. The instance cannot be reused after destroy.

deinit {
    banner?.destroy()
    banner = nil
}

- (void)dealloc {
    [self.banner destroy];
    self.banner = nil;
}

Skipping destroy() when the view controller deallocates leaves the WebView and related resources uncollected, which can cause memory leaks and performance degradation — especially impactful for video banners.

Ad Sizes

Banner ads require view size to match the size set in the unit.

Size	Use Case
320 x 50	Small banner
320 x 100	Large banner
16:9 ratio	Video banner

UIKit

bannerView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
    bannerView.widthAnchor.constraint(equalToConstant: 320),
    bannerView.heightAnchor.constraint(equalToConstant: 100)
])

SwiftUI

represented
    .frame(width: 320, height: 100)
    .onAppear {
        represented.banner.load()
    }

Best Practices

1. Memory Management

Call destroy() when the view controller is deallocated to release banner resources.

deinit {
    banner?.destroy()
    banner = nil
}

2. Screen Visibility

Load ads when the banner is visible on screen.

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    banner?.load()
}

Keep a single AdropBanner instance and call load() on it whenever you need a new ad. Do not create a new AdropBanner for every refresh. Recreating the banner for each ad request allocates a new WKWebView and its associated WebContent process each time. Under frequent refresh conditions — especially with video banners — this accumulates resource usage and can degrade rendering performance.

class ViewController: UIViewController {
    private var banner: AdropBanner?

    override func viewDidLoad() {
        super.viewDidLoad()
        banner = AdropBanner(unitId: "YOUR_UNIT_ID")
        banner?.delegate = self
        // Add to view hierarchy...
        banner?.load()
    }

    func refreshAd() {
        // Reuse the existing instance
        banner?.load()
    }
}

func refreshAd() {
    // Do NOT allocate a new AdropBanner on every refresh
    banner?.destroy()
    banner = AdropBanner(unitId: "YOUR_UNIT_ID")
    banner?.delegate = self
    // ...add to view hierarchy again
    banner?.load()
}

onAdReceived fires again on each subsequent load() call, so your existing delegate handles the new ad automatically.

4. Error Handling

Implement appropriate error handling when ad loading fails.

func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {
    switch errorCode {
    case .ERROR_CODE_NETWORK:
        print("Network error: Check connection")
    case .ERROR_CODE_AD_NO_FILL:
        print("No available ads")
    default:
        print("Ad load failed: \(errorCode)")
    }

    // Hide ad area or display fallback content
    bannerContainerView.isHidden = true

    // Or show your own promotional banner
    showPromotionBanner()
}

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

let banner = AdropBanner(unitId: AdropUnitId.PUBLIC_TEST_UNIT_ID_320_100)

AdropBanner *banner = [[AdropBanner alloc] initWithUnitId: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()

[self.banner play];

pause()

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

banner?.pause()

[self.banner pause];

Example: Background/Foreground Handling

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    banner?.play()
}

override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    banner?.pause()
}

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

Custom Click Handling

You can take control of ad click behavior by using useCustomClick. When enabled, the SDK will not automatically open the destination URL on click, and you can handle it yourself.

useCustomClick

let banner = AdropBanner(unitId: "YOUR_UNIT_ID")
banner.useCustomClick = true
banner.delegate = self
banner.load()

When useCustomClick is true, the SDK will not open the destination URL automatically when the ad is clicked. The onAdClicked delegate callback will still fire, and you can use the open() method or handle navigation yourself.

open()

Opens the destination URL of the ad. Can optionally pass a custom URL.

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

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

// Open using in-app browser
banner?.open(nil, useInAppBrowser: true)

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(
    unitId: String,
    contextId: String = "",
    delegate: AdropBannerDelegate
)

[AdropBanner loadsWithUnitId:@"YOUR_UNIT_ID"
                   contextId:@""
                    delegate:delegate];

Usage

class ViewController: UIViewController {
    private var banners: [AdropBanner] = []

    override func viewDidLoad() {
        super.viewDidLoad()
        AdropBanner.loads(unitId: "YOUR_UNIT_ID", delegate: self)
    }
}

extension ViewController: AdropBannerDelegate {
    // Required single-load callbacks — unused on the batch path.
    func onAdReceived(_ banner: AdropBanner) { /* batch path */ }
    func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {}

    // Batch success — deliver up to 5 ready-to-use banners.
    func onAdsReceived(_ banners: [AdropBanner]) {
        self.banners = banners
        banners.forEach { banner in
            // Attach to your view hierarchy (UIScrollView, UIPageViewController, ...)
            stackView.addArrangedSubview(banner)
        }
    }

    // Batch failure
    func onAdsFailedToReceive(_ errorCode: AdropErrorCode) {
        print("Batch load failed: \(errorCode)")
    }

    // Click / impression / video callbacks still fire per instance.
    func onAdClicked(_ banner: AdropBanner) {
        print("Banner clicked")
    }

    func onAdImpression(_ banner: AdropBanner) {
        print("Banner impression")
    }
}

@interface ViewController () <AdropBannerDelegate>
@property (nonatomic, strong) NSArray<AdropBanner *> *banners;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    [AdropBanner loadsWithUnitId:@"YOUR_UNIT_ID" contextId:@"" delegate:self];
}

#pragma mark - AdropBannerDelegate

- (void)onAdReceived:(AdropBanner *)banner { /* batch path */ }
- (void)onAdFailedToReceive:(AdropBanner *)banner :(AdropErrorCode)errorCode {}

- (void)onAdsReceived:(NSArray<AdropBanner *> *)banners {
    self.banners = banners;
    for (AdropBanner *banner in banners) {
        [self.stackView addArrangedSubview:banner];
    }
}

- (void)onAdsFailedToReceive:(AdropErrorCode)errorCode {
    NSLog(@"Batch load failed: %ld", (long)errorCode);
}

- (void)onAdClicked:(AdropBanner *)banner {
    NSLog(@"Banner clicked");
}

- (void)onAdImpression:(AdropBanner *)banner {
    NSLog(@"Banner impression");
}

@end

Delegate Methods

Method	When it fires
`onAdsReceived(_:)`	Batch delivered. Each `AdropBanner` already has the delegate attached and ad data applied.
`onAdsFailedToReceive(_:)`	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.

Constants

Int

default:"5"

Upper bound on ads returned from a single loads(...) call.

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 the view hierarchy first, then call destroy() when the view controller deallocates.
onAdsReceived fires as soon as ad data is applied, matching the single load() contract — the creative paints shortly after you add the banner to a view hierarchy.
Hold strong references to the returned banners (e.g., store them on the view controller). If they deallocate before being attached, they’re silently dropped.

Backfill Ads

When backfill ads are enabled, backfill ads are automatically loaded when direct ads are unavailable. Use the isBackfilled property to check if the ad is a backfill ad.

class ViewController: UIViewController, AdropBannerDelegate {
    private var banner: AdropBanner?

    func onAdReceived(_ banner: AdropBanner) {
        if banner.isBackfilled {
            print("Backfill ad loaded")
        } else {
            print("Direct ad loaded")
        }
    }

    func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {
        switch errorCode {
        case .ERROR_CODE_AD_NO_FILL:
            print("No direct ad, requesting backfill...")
        case .ERROR_CODE_AD_BACKFILL_NO_FILL:
            print("No backfill ad available")
            // Hide ad area
            banner.isHidden = true
        default:
            print("Ad load failed: \(errorCode)")
        }
    }
}

@interface ViewController () <AdropBannerDelegate>
@property (nonatomic, strong) AdropBanner *banner;
@end

@implementation ViewController

- (void)onAdReceived:(AdropBanner *)banner {
    if (banner.isBackfilled) {
        NSLog(@"Backfill ad loaded");
    } else {
        NSLog(@"Direct ad loaded");
    }
}

- (void)onAdFailedToReceive:(AdropBanner *)banner :(AdropErrorCode)errorCode {
    if (errorCode == AdropErrorCodeAdNoFill) {
        NSLog(@"No direct ad, requesting backfill...");
    } else if (errorCode == AdropErrorCodeBackfillNoFill) {
        NSLog(@"No backfill ad available");
        // Hide ad area
        banner.hidden = YES;
    } else {
        NSLog(@"Ad load failed: %ld", (long)errorCode);
    }
}

@end

To use backfill ads, add the AdropAds-Backfill dependency. See Getting Started.

Next Steps

Native Ads

Implementing customizable native ads

Interstitial Ads

Implementing full-screen interstitial ads

Targeting Settings

Setting up user attributes and contextual targeting

Reference

Classes, delegates, error codes reference

​Overview

​Key Features

​UIKit Implementation

​Basic Implementation

​AdropBanner Initialization

​Load Ad

​Set Context ID

​SwiftUI Implementation

​Basic Implementation

​Delegate Handling

​Set Context ID

​Objective-C Implementation

​Basic Implementation

​Set Context ID

​Delegate Methods

​onAdReceived (Required)

​onAdFailedToReceive (Required)

​onAdImpression (Optional)

​onAdClicked (Optional)

​onAdVideoStart (Optional)

​onAdVideoEnd (Optional)

​Closure Callbacks

​Lifecycle Management

​destroy()

​Ad Sizes

​Common Banner Sizes

​UIKit

​SwiftUI

​Best Practices

​1. Memory Management

​2. Screen Visibility

​3. Reuse the Banner Instance

​4. Error Handling

​Test Unit IDs

​Usage Example

​Video Playback Control

​play()

​pause()

​Example: Background/Foreground Handling

​Custom Click Handling

​useCustomClick

​open()

​Batch Loading (loads)

​Signature

​Usage

​Delegate Methods

​Constants

​Constraints

​Backfill Ads

​Next Steps

Native Ads

Interstitial Ads

Targeting Settings

Reference

Overview

Key Features

UIKit Implementation

Basic Implementation

AdropBanner Initialization

Load Ad

Set Context ID

SwiftUI Implementation

Basic Implementation

Delegate Handling

Set Context ID

Objective-C Implementation

Basic Implementation

Set Context ID

Delegate Methods

onAdReceived (Required)

onAdFailedToReceive (Required)

onAdImpression (Optional)

onAdClicked (Optional)

onAdVideoStart (Optional)

onAdVideoEnd (Optional)

Closure Callbacks

Lifecycle Management

destroy()

Ad Sizes

Common Banner Sizes

UIKit

SwiftUI

Best Practices

1. Memory Management

2. Screen Visibility

3. Reuse the Banner Instance

4. Error Handling

Test Unit IDs

Usage Example

Video Playback Control

play()

pause()

Example: Background/Foreground Handling

Custom Click Handling

useCustomClick

open()

Batch Loading (loads)

Signature

Usage

Delegate Methods

Constants

Constraints

Backfill Ads

Next Steps