Banner Ads - Ad Control Help Center

Overview

Banner ads are rectangular ads displayed in a portion of the screen. They can be easily implemented using the AdropBannerView widget.

Key Features

Can be fixed at the top, bottom, or middle of the screen
Supports image and video ads
Handle ad events through callbacks
Provides ad metadata (creative ID, campaign ID, etc.)

Use the test unit ID for development: PUBLIC_TEST_UNIT_ID_320_100

AdropBannerView

Constructor

AdropBannerView({
  required String unitId,
  String? contextId,
  AdropBannerListener? listener,
})

Parameters

Parameter	Type	Required	Description
`unitId`	`String`	Y	Unit ID created in the Ad Control Console
`contextId`	`String`	N	Context ID for contextual targeting (1.17.0+)
`listener`	`AdropBannerListener`	N	Ad event listener

Properties

Property	Type	Description
`contextId`	`String?`	Context ID passed to the constructor
`creativeSize`	`CreativeSize?`	Ad creative size
`adSize`	`Size?`	Banner view size setting

Methods

Method	Return Type	Description
`load()`	`Future<void>`	Loads the ad
`dispose()`	`Future<void>`	Releases resources

Basic Usage

import 'package:flutter/material.dart';
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

class BannerExample extends StatefulWidget {
  const BannerExample({super.key});

  @override
  State<BannerExample> createState() => _BannerExampleState();
}

class _BannerExampleState extends State<BannerExample> {
  bool isLoaded = false;
  late AdropBannerView bannerView;

  @override
  void initState() {
    super.initState();

    bannerView = AdropBannerView(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (unitId, metadata) {
          debugPrint('Banner ad received: $unitId');
          setState(() {
            isLoaded = true;
          });
        },
        onAdClicked: (unitId, metadata) {
          debugPrint('Banner ad clicked: $unitId');
        },
        onAdImpression: (unitId, metadata) {
          debugPrint('Banner ad impression: $unitId');
        },
        onAdFailedToReceive: (unitId, errorCode) {
          debugPrint('Banner ad failed: $unitId, $errorCode');
          setState(() {
            isLoaded = false;
          });
        },
      ),
    );

    // Load ad
    bannerView.load();
  }

  @override
  void dispose() {
    bannerView.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Banner Ad Example')),
      body: Column(
        children: [
          // Main content
          Expanded(
            child: Center(
              child: const Text('Main Content'),
            ),
          ),
          // Banner ad
          if (isLoaded)
            SizedBox(
              width: MediaQuery.of(context).size.width,
              height: 80,
              child: bannerView,
            ),
        ],
      ),
    );
  }
}

AdropBannerListener

A listener that handles banner ad events.

Callbacks

AdropBannerListener(
  onAdReceived: (String unitId, Map<String, dynamic>? metadata) {
    // Ad received successfully
  },
  onAdClicked: (String unitId, Map<String, dynamic>? metadata) {
    // Ad clicked
  },
  onAdImpression: (String unitId, Map<String, dynamic>? metadata) {
    // Ad impression
  },
  onAdFailedToReceive: (String unitId, AdropErrorCode errorCode) {
    // Ad failed to receive
  },
  onAdVideoStart: (String unitId) {
    // Video ad started playing
  },
  onAdVideoEnd: (String unitId) {
    // Video ad finished playing
  },
)

Callback Descriptions

Callback	Description
`onAdReceived`	Called when ad is received successfully
`onAdClicked`	Called when ad is clicked
`onAdImpression`	Called when ad is displayed
`onAdFailedToReceive`	Called when ad fails to load
`onAdVideoStart`	Called when video ad starts playing
`onAdVideoEnd`	Called when video ad finishes playing

Metadata

You can receive metadata in the onAdReceived, onAdClicked, and onAdImpression callbacks.

onAdReceived: (unitId, metadata) {
  debugPrint('Creative ID: ${metadata?['creativeId']}');
  debugPrint('Transaction ID: ${metadata?['txId']}');
  debugPrint('Campaign ID: ${metadata?['campaignId']}');
  debugPrint('Destination URL: ${metadata?['destinationURL']}');
  debugPrint('Browser Target: ${metadata?['browserTarget']}');
}

Field	Type	Description
`creativeId`	`String`	Creative ID
`txId`	`String`	Transaction ID
`campaignId`	`String`	Campaign ID
`destinationURL`	`String`	Destination URL
`browserTarget`	`int?`	Browser target (0: external, 1: internal)

Creative size is accessed via bannerView.creativeSize?.width and bannerView.creativeSize?.height, not through metadata.

Ad Sizes

Banner ads require specifying container size according to the unit settings.

Size	Test Unit ID	Usage
320 x 50	`PUBLIC_TEST_UNIT_ID_320_50`	Small banner
320 x 100	`PUBLIC_TEST_UNIT_ID_320_100`	Medium banner

Fixed Size Usage

SizedBox(
  width: 320,
  height: 100,
  child: bannerView,
)

Fit to Screen Width

SizedBox(
  width: MediaQuery.of(context).size.width,
  height: 80,
  child: bannerView,
)

Size Configuration

You can explicitly set the banner view size using the adSize property.

@override
void initState() {
  super.initState();

  bannerView = AdropBannerView(
    unitId: 'YOUR_UNIT_ID',
    listener: AdropBannerListener(
      onAdReceived: (unitId, metadata) {
        setState(() {
          isLoaded = true;
        });
      },
    ),
  );

  // Set size after context is ready
  WidgetsBinding.instance.addPostFrameCallback((_) {
    bannerView.adSize = Size(
      MediaQuery.of(context).size.width,
      80,
    );
  });
}

Error Handling

Implement proper error handling when ad loading fails.

class _BannerExampleState extends State<BannerExample> {
  bool isLoaded = false;
  AdropErrorCode? errorCode;
  late AdropBannerView bannerView;

  @override
  void initState() {
    super.initState();

    bannerView = AdropBannerView(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (unitId, metadata) {
          setState(() {
            isLoaded = true;
            errorCode = null;
          });
        },
        onAdFailedToReceive: (unitId, error) {
          setState(() {
            isLoaded = false;
            errorCode = error;
          });
        },
      ),
    );

    bannerView.load();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        if (isLoaded)
          SizedBox(
            width: MediaQuery.of(context).size.width,
            height: 80,
            child: bannerView,
          )
        else if (errorCode != null)
          Text('Ad load failed: ${errorCode?.code}'),
      ],
    );
  }

  @override
  void dispose() {
    bannerView.dispose();
    super.dispose();
  }
}

Best Practices

1. Release Resources

Always call dispose() when the banner view is no longer needed.

@override
void dispose() {
  bannerView.dispose();
  super.dispose();
}

2. Refresh Ads

You can refresh ads as needed.

void refreshAd() {
  setState(() {
    isLoaded = false;
  });
  bannerView.load();
}

3. Conditional Rendering

Hide the banner area or show a placeholder until the ad loads.

Widget buildBanner() {
  if (isLoaded) {
    return SizedBox(
      width: MediaQuery.of(context).size.width,
      height: 80,
      child: bannerView,
    );
  } else if (isLoading) {
    return const SizedBox(
      height: 80,
      child: Center(child: CircularProgressIndicator()),
    );
  } else {
    return const SizedBox.shrink();
  }
}

4. Managing Multiple Banners

When using multiple banners, manage each state separately.

class _MultiBannerState extends State<MultiBanner> {
  late AdropBannerView topBanner;
  late AdropBannerView bottomBanner;
  bool isTopLoaded = false;
  bool isBottomLoaded = false;

  @override
  void initState() {
    super.initState();

    topBanner = AdropBannerView(
      unitId: 'TOP_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (_, __) => setState(() => isTopLoaded = true),
      ),
    );

    bottomBanner = AdropBannerView(
      unitId: 'BOTTOM_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (_, __) => setState(() => isBottomLoaded = true),
      ),
    );

    topBanner.load();
    bottomBanner.load();
  }

  @override
  void dispose() {
    topBanner.dispose();
    bottomBanner.dispose();
    super.dispose();
  }

  // ...
}

Complete Example

import 'package:flutter/material.dart';
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

class BannerAdPage extends StatefulWidget {
  const BannerAdPage({super.key});

  @override
  State<BannerAdPage> createState() => _BannerAdPageState();
}

class _BannerAdPageState extends State<BannerAdPage> {
  static const double bannerHeight = 80;
  bool isLoaded = false;
  bool isLoading = false;
  AdropErrorCode? errorCode;
  late AdropBannerView bannerView;

  @override
  void initState() {
    super.initState();

    bannerView = AdropBannerView(
      unitId: 'PUBLIC_TEST_UNIT_ID_320_100', // Test unit ID
      listener: AdropBannerListener(
        onAdReceived: (unitId, metadata) {
          debugPrint('Ad received successfully');
          debugPrint('Creative ID: ${metadata?['creativeId']}');
          debugPrint('Campaign ID: ${metadata?['campaignId']}');
          debugPrint('Creative size: ${bannerView.creativeSize?.width}x${bannerView.creativeSize?.height}');
          setState(() {
            isLoaded = true;
            isLoading = false;
            errorCode = null;
          });
        },
        onAdClicked: (unitId, metadata) {
          debugPrint('Ad clicked: ${metadata?['destinationURL']}');
        },
        onAdImpression: (unitId, metadata) {
          debugPrint('Ad impression: ${metadata?['creativeId']}');
        },
        onAdFailedToReceive: (unitId, error) {
          debugPrint('Ad failed: $error');
          setState(() {
            isLoaded = false;
            isLoading = false;
            errorCode = error;
          });
        },
      ),
    );

    WidgetsBinding.instance.addPostFrameCallback((_) {
      bannerView.adSize = Size(
        MediaQuery.of(context).size.width,
        bannerHeight,
      );
    });
  }

  void loadAd() {
    setState(() {
      isLoading = true;
      errorCode = null;
    });
    bannerView.load();
  }

  @override
  void dispose() {
    bannerView.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Banner Ad Example'),
      ),
      body: SafeArea(
        child: Column(
          children: [
            // Load button
            Padding(
              padding: const EdgeInsets.all(16),
              child: ElevatedButton(
                onPressed: isLoading ? null : loadAd,
                child: Text(isLoading ? 'Loading...' : 'Load Banner Ad'),
              ),
            ),

            // Status display
            if (errorCode != null)
              Padding(
                padding: const EdgeInsets.all(16),
                child: Text(
                  'Error: ${errorCode?.code}',
                  style: const TextStyle(color: Colors.red),
                ),
              ),

            // Main content
            const Expanded(
              child: Center(
                child: Text('Main Content Area'),
              ),
            ),

            // Banner ad
            Container(
              width: MediaQuery.of(context).size.width,
              height: bannerHeight,
              color: Colors.grey[200],
              child: isLoaded
                  ? bannerView
                  : isLoading
                      ? const Center(child: CircularProgressIndicator())
                      : const Center(child: Text('Ad Area')),
            ),
          ],
        ),
      ),
    );
  }
}

Backfill Ads

When backfill ads are enabled, backfill ads are automatically loaded when direct ads are unavailable. Backfill ad loading is handled automatically by the SDK. You can handle backfill-related errors using the backfillNoFill error code.

bannerView = AdropBannerView(
  unitId: 'YOUR_UNIT_ID',
  listener: AdropBannerListener(
    onAdReceived: (unitId, metadata) {
      debugPrint('Ad loaded');
      setState(() {
        isLoaded = true;
      });
    },
    onAdFailedToReceive: (unitId, errorCode) {
      switch (errorCode) {
        case AdropErrorCode.adNoFill:
          debugPrint('No direct ad available');
          break;
        case AdropErrorCode.backfillNoFill:
          debugPrint('No backfill ad available either');
          // Hide ad area
          break;
        default:
          debugPrint('Ad load failed: ${errorCode.code}');
      }
    },
  ),
);

Banner ad metadata only includes the creativeId, txId, campaignId, destinationURL, and browserTarget fields. Backfill ads cannot be distinguished through metadata. You can detect backfill ad failures using the backfillNoFill error code.

To use backfill ads, add the backfill dependency to native platforms. See Getting Started.

Preloading Backfill Ads (preload)

Starting with SDK 1.17.0, you can use AdropBannerView.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

You need adrop_ads_flutter 1.17.0 or later and, on the native platforms, the backfill dependency 1.17.0 or later. See Getting Started.
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

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. preload() completes when preloading succeeds. Any other result (including ERROR_CODE_AD_PRELOAD_SKIPPED) is delivered as a PlatformException whose code is the error code string. If you don’t handle it, even SKIPPED, which is a normal result, is reported as an unhandled asynchronous error, so wrap the call in try/catch or attach .catchError.

import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

// Call right before you open the screen that contains the banner.
Future<void> preloadFeedBanner() async {
  try {
    await AdropBannerView.preload(
      unitId: 'YOUR_UNIT_ID',
      adSize: const Size(320, 50), // 320x50 if omitted
    );
    debugPrint('Preload complete');
  } on PlatformException catch (e) {
    // ERROR_CODE_AD_PRELOAD_SKIPPED is a normal result.
    // Don't call preload again right away here.
    final errorCode = AdropErrorCode.getByCode(e.code);
    debugPrint('Not preloaded: ${errorCode.code}');
  }
}

If you don’t need the result, you can call it like this.

AdropBannerView.preload(unitId: 'YOUR_UNIT_ID', adSize: const Size(320, 50))
    .catchError((_) {});

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

final bannerView = AdropBannerView(unitId: 'YOUR_UNIT_ID');
bannerView.adSize = const Size(320, 50); // Size passed to preload
bannerView.load();

When a Preloaded Ad Is Used

Same unit ID and same size: The adSize of the AdropBannerView you load() 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.
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, the call completes without a new request; if one is still being fetched, the call gets 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, 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().
What completion means: When preload() completes, it means preloading has finished. A load() that was waiting for that result may have already used the ad.

Failure Codes

Error Code	Code String	Description
`preloadSkipped`	`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.
`adNoFill`	`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. On iOS, preload also ends with this code when the device isn’t in the target countries.
`backfillNoFill`	`ERROR_CODE_AD_BACKFILL_NO_FILL`	No backfill ad is available.
`internal`	`ERROR_CODE_INTERNAL`	The request was interrupted (for example, on Android, the Activity finished while the ad was being fetched) or an internal error occurred. Call preload again later.
`initialize`	`ERROR_CODE_INITIALIZE`	The SDK isn’t initialized. On Android, preload also ends with this code when the device isn’t in the target countries.
`invalidUnit`	`ERROR_CODE_INVALID_UNIT`	The unit ID is empty.

Don’t call preload again right away inside catch. 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

Popup Ads

Implement popup-style ads

Reference

View types, methods, and error codes

​Overview

​Key Features

​AdropBannerView

​Constructor

​Properties

​Methods

​Basic Usage

​AdropBannerListener

​Callbacks

​Callback Descriptions

​Metadata

​Ad Sizes

​Common Banner Sizes

​Fixed Size Usage

​Fit to Screen Width

​Size Configuration

​Error Handling

​Best Practices

​1. Release Resources

​2. Refresh Ads

​3. Conditional Rendering

​4. Managing Multiple Banners

​Complete Example

​Backfill Ads

​Preloading Backfill Ads (preload)

​Requirements

​Usage

​When a Preloaded Ad Is Used

​Failure Codes

​Next Steps

Native Ads

Interstitial Ads

Popup Ads

Reference

Overview

Key Features

AdropBannerView

Constructor

Properties

Methods

Basic Usage

AdropBannerListener

Callbacks

Callback Descriptions

Metadata

Ad Sizes

Common Banner Sizes

Fixed Size Usage

Fit to Screen Width

Size Configuration

Error Handling

Best Practices

1. Release Resources

2. Refresh Ads

3. Conditional Rendering

4. Managing Multiple Banners

Complete Example

Backfill Ads

Preloading Backfill Ads (preload)

Requirements

Usage

When a Preloaded Ad Is Used

Failure Codes

Next Steps