Skip to main content

​
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
ParameterTypeRequiredDescription
unitIdStringYUnit ID created in the Ad Control Console
listenerAdropBannerListenerNAd event listener

​
Properties

PropertyTypeDescription
creativeSizeCreativeSize?Ad creative size
adSizeSize?Banner view size setting

​
Methods

MethodReturn TypeDescription
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.

​
Callback Functions

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
  },
)

​
Callback Descriptions

CallbackDescription
onAdReceivedCalled when ad is received successfully
onAdClickedCalled when ad is clicked
onAdImpressionCalled when ad is displayed
onAdFailedToReceiveCalled when ad fails to load

​
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('Creative Width: ${metadata?['creativeSizeWidth']}');
  debugPrint('Creative Height: ${metadata?['creativeSizeHeight']}');
}
FieldTypeDescription
creativeIdStringCreative ID
txIdStringTransaction ID
campaignIdStringCampaign ID
destinationURLStringDestination URL
creativeSizeWidthdoubleCreative width
creativeSizeHeightdoubleCreative height

​
Ad Sizes

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

​
Common Banner Sizes

SizeTest Unit IDUsage
320 x 50PUBLIC_TEST_UNIT_ID_320_50Small banner
320 x 100PUBLIC_TEST_UNIT_ID_320_100Medium 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();
  }

  // ...
}

​
Full 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')),
            ),
          ],
        ),
      ),
    );
  }
}

​
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