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,
})
| 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.
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
| 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 |
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']}');
}
| Field | Type | Description |
|---|
creativeId | String | Creative ID |
txId | String | Transaction ID |
campaignId | String | Campaign ID |
destinationURL | String | Destination URL |
creativeSizeWidth | double | Creative width |
creativeSizeHeight | double | Creative height |
Ad Sizes
Banner ads require specifying container size according to the unit settings.
Common Banner Sizes
| 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();
}
// ...
}
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
