Banner Ads
Banner ads are rectangular ads that occupy a portion of your app's layout. They can refresh automatically and stay on screen while users interact with your app.
Each ad format uses a Zone ID to identify the ad placement. Zone IDs are configured in the Empower dashboard.
Note: All ad status callbacks are optional. The SDK handles ad loading and display automatically. Use callbacks only if you need to track ad states for analytics, UI updates, or custom logic.
Supported Sizes
| Size | Description |
|---|---|
| 320x50 | Standard Banner |
| 320x100 | Large Banner |
| 300x250 | Medium Rectangle (MREC) |
Quick Start
import 'package:empower_mobile_ads/empower_mobile_ads.dart';
class HomeScreen extends StatelessWidget {
Widget build(BuildContext context) {
return Scaffold(
body: Column(
children: [
Expanded(child: Text('Your Content')),
// Standard Banner
EmpowerBannerAd(
zoneId: 'YOUR_BANNER_ZONE_ID',
width: 320,
height: 50,
),
],
),
);
}
}
Zone ID Options
Zone IDs can be specified in three ways:
Single Zone ID (Same for Both Platforms)
EmpowerBannerAd(
zoneId: 'YOUR_ZONE_ID',
width: 320,
height: 50,
)
Per-Platform Zone IDs
EmpowerBannerAd(
zoneId: '', // fallback
androidZoneId: 'ANDROID_ZONE_ID',
iosZoneId: 'IOS_ZONE_ID',
width: 320,
height: 50,
)
Using Platform Check
import 'dart:io';
EmpowerBannerAd(
zoneId: Platform.isAndroid ? 'ANDROID_ZONE_ID' : 'IOS_ZONE_ID',
width: 320,
height: 50,
)
Listening to Banner Status (Optional)
Track banner status for analytics or UI updates:
import 'package:empower_mobile_ads/empower_mobile_ads.dart';
class BannerWithStatus extends StatelessWidget {
Widget build(BuildContext context) {
return EmpowerBannerAd(
zoneId: 'YOUR_ZONE_ID',
width: 320,
height: 50,
onAdStatusChanged: (AdStatus status, String zoneId) {
switch (status) {
case AdStatus.ready:
print('Banner loaded for zone: $zoneId');
break;
case AdStatus.failed:
print('Banner failed for zone: $zoneId');
break;
case AdStatus.willLeave:
print('User clicked the ad');
break;
default:
break;
}
},
);
}
}
ListView Usage
When displaying banners inside a ListView, use fixed dimensions and explicit zone IDs to ensure proper rendering:
import 'package:flutter/material.dart';
import 'package:empower_mobile_ads/empower_mobile_ads.dart';
const bannerPosition = 5; // Show banner after 5th item
class FeedWithBanner extends StatelessWidget {
final List<String> items;
const FeedWithBanner({required this.items});
Widget build(BuildContext context) {
final totalItems = items.length + 1; // +1 for banner
return ListView.builder(
itemCount: totalItems,
itemBuilder: (context, index) {
if (index == bannerPosition) {
return Center(
child: Padding(
padding: const EdgeInsets.symmetric(vertical: 8),
child: EmpowerBannerAd(
zoneId: 'YOUR_ZONE_ID',
width: 300,
height: 250,
),
),
);
}
final itemIndex = index > bannerPosition ? index - 1 : index;
return ListTile(title: Text(items[itemIndex]));
},
);
}
}
Sticky Banner
To display a sticky banner pinned to the bottom of the screen:
import 'package:flutter/material.dart';
import 'package:empower_mobile_ads/empower_mobile_ads.dart';
class StickyBannerExample extends StatelessWidget {
Widget build(BuildContext context) {
return Scaffold(
body: Column(
children: [
Expanded(
child: Center(child: Text('Your app content')),
),
// Sticky banner at bottom
SafeArea(
top: false,
child: Container(
color: Colors.white,
alignment: Alignment.center,
decoration: const BoxDecoration(
border: Border(
top: BorderSide(color: Color(0xFFDDDDDD), width: 0.5),
),
),
child: EmpowerBannerAd(
zoneId: 'YOUR_ZONE_ID',
width: 320,
height: 50,
),
),
),
],
),
);
}
}
Tip: Place the sticky banner widget outside your navigation stack (e.g., in a wrapper
Scaffold) so it persists across all screens.
Multi-Size, Adaptive and Native Zones (iOS)
Some zones fill at a size you cannot know ahead of time: a multi-size zone (for example 320x50 or 320x100), an adaptive zone, or a zone with native ads. With a fixed height the ad is either cropped or leaves empty space. Set autoHeight: true and the banner takes the height of the ad on display:
EmpowerBannerAd(
zoneId: 'YOUR_ZONE_ID',
width: 320,
height: 50, // used until the first ad arrives
autoHeight: true,
)
heightis used until the first ad arrives. After that, the banner resizes whenever the ad's size changes, for example when a refresh fills a different size.- Without
autoHeightthe banner keeps the size you give it, as before.
To size the slot yourself, use onAdSizeChanged:
EmpowerBannerAd(
zoneId: 'YOUR_ZONE_ID',
width: 320,
height: _slotHeight,
onAdSizeChanged: (size, zoneId) => setState(() => _slotHeight = size.height),
)
Custom Targeting (iOS)
Pass key-value targeting with customParameters. It is sent with every request of the banner.
EmpowerBannerAd(
zoneId: 'YOUR_ZONE_ID',
width: 320,
height: 50,
customParameters: 'category=sports&tags=football,league',
)
- Separate pairs with
&, and separate multiple values of one key with,. - Keys may contain letters, digits and
_, up to 20 characters. A pair whose key breaks this rule, or that has no value, is skipped.
Native Ads
A zone that serves native ads needs more room than a 320x50 banner, and Empower sets its size for each zone. Use EmpowerNativeAd for these zones on both platforms. It asks the SDK for the zone's size at the width it gets and takes that height, so the ad is not cropped.
EmpowerNativeAd(
zoneId: 'YOUR_NATIVE_ZONE_ID',
fallbackHeight: 250, // used until the zone's size is known
)
- Leave out
widthto use the full width of the parent, or set it for a fixed width. fallbackHeightis used until the zone's size is known, and when the zone has no native size.- On iOS the widget collapses to zero height when the user closes the ad with its close button, and opens again when the next ad fills the zone. Set
collapseOnClose: falseto keep the space. On Android the slot keeps its space until the next ad fills it.
Props Reference
EmpowerBannerAd
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
zoneId | String | Yes | — | Zone ID for the banner placement |
androidZoneId | String? | No | null | Android-specific zone ID (overrides zoneId) |
iosZoneId | String? | No | null | iOS-specific zone ID (overrides zoneId) |
width | double | No | 320 | Width of the banner ad |
height | double | No | 50 | Height of the banner ad. With autoHeight, only used until the first ad arrives. |
customParameters | String? | No | null | iOS only. Custom targeting, such as 'category=sports&tags=a,b'. See Custom Targeting. |
autoHeight | bool | No | false | iOS only. Resize the banner's height to the ad on display. See Multi-Size, Adaptive and Native Zones. |
onAdSizeChanged | Function(Size, String)? | No | null | iOS only. Called with the ad's size and the zone ID whenever the ad's size changes. |
onAdStatusChanged | Function(AdStatus, String)? | No | null | Called when ad status changes |
backgroundColor | Color | No | Color(0xFFF5F5F5) | Background color when ad is not loaded |
EmpowerNativeAd
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
zoneId | String | Yes | Zone ID for the native placement | |
androidZoneId | String? | No | null | Android-specific zone ID (overrides zoneId) |
iosZoneId | String? | No | null | iOS-specific zone ID (overrides zoneId) |
width | double? | No | null | Width of the slot. null uses the full width of the parent. |
fallbackHeight | double | No | 250 | Height used until the zone's size is known, and when the zone has no native size |
collapseOnClose | bool | No | true | iOS only. Collapse the slot when the user closes the ad |
onAdStatusChanged | Function(AdStatus, String)? | No | null | Called when ad status changes |
backgroundColor | Color | No | Color(0xFFF5F5F5) | Background color when ad is not loaded |
animationDuration | Duration | No | 200 ms | Duration of the collapse and reopen animation |
Best Practices
- Set explicit dimensions — Always provide
widthandheightmatching the expected ad size (320x50, 320x100, or 300x250). For a native zone useEmpowerNativeAd. For a multi-size or adaptive zone addautoHeight: trueon iOS. - Load in visible areas — The widget loads the ad when it mounts. Don't place banner widgets off-screen
- Handle failures gracefully — Use
onAdStatusChangedto hide the banner container or show fallback content when status isfailed - One zone ID per widget — Don't reuse the same zone ID for multiple banner widgets on the same screen
Ad Status Reference
| Status | Description |
|---|---|
AdStatus.initializing | Banner is loading |
AdStatus.ready | Banner is loaded and displayed |
AdStatus.failed | Banner failed to load |
AdStatus.willLeave | User clicked the ad (leaving app) |