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,
  AdropBannerListener? listener,
})

Parameters

Parameter	Type	Required	Description
`unitId`	`String`	Y	Unit ID created in the Ad Control Console
`listener`	`AdropBannerListener`	N	Ad event listener

Properties

Property	Type	Description
`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.

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

​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

Next Steps