Skip to main content

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​

SizeDescription
320x50Standard Banner
320x100Large Banner
300x250Medium 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,
)
  • height is 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 autoHeight the 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 width to use the full width of the parent, or set it for a fixed width.
  • fallbackHeight is 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: false to keep the space. On Android the slot keeps its space until the next ad fills it.

Props Reference​

EmpowerBannerAd​

PropTypeRequiredDefaultDescription
zoneIdStringYes—Zone ID for the banner placement
androidZoneIdString?NonullAndroid-specific zone ID (overrides zoneId)
iosZoneIdString?NonulliOS-specific zone ID (overrides zoneId)
widthdoubleNo320Width of the banner ad
heightdoubleNo50Height of the banner ad. With autoHeight, only used until the first ad arrives.
customParametersString?NonulliOS only. Custom targeting, such as 'category=sports&tags=a,b'. See Custom Targeting.
autoHeightboolNofalseiOS only. Resize the banner's height to the ad on display. See Multi-Size, Adaptive and Native Zones.
onAdSizeChangedFunction(Size, String)?NonulliOS only. Called with the ad's size and the zone ID whenever the ad's size changes.
onAdStatusChangedFunction(AdStatus, String)?NonullCalled when ad status changes
backgroundColorColorNoColor(0xFFF5F5F5)Background color when ad is not loaded

EmpowerNativeAd​

PropTypeRequiredDefaultDescription
zoneIdStringYesZone ID for the native placement
androidZoneIdString?NonullAndroid-specific zone ID (overrides zoneId)
iosZoneIdString?NonulliOS-specific zone ID (overrides zoneId)
widthdouble?NonullWidth of the slot. null uses the full width of the parent.
fallbackHeightdoubleNo250Height used until the zone's size is known, and when the zone has no native size
collapseOnCloseboolNotrueiOS only. Collapse the slot when the user closes the ad
onAdStatusChangedFunction(AdStatus, String)?NonullCalled when ad status changes
backgroundColorColorNoColor(0xFFF5F5F5)Background color when ad is not loaded
animationDurationDurationNo200 msDuration of the collapse and reopen animation

Best Practices​

  • Set explicit dimensions — Always provide width and height matching the expected ad size (320x50, 320x100, or 300x250). For a native zone use EmpowerNativeAd. For a multi-size or adaptive zone add autoHeight: true on iOS.
  • Load in visible areas — The widget loads the ad when it mounts. Don't place banner widgets off-screen
  • Handle failures gracefully — Use onAdStatusChanged to hide the banner container or show fallback content when status is failed
  • One zone ID per widget — Don't reuse the same zone ID for multiple banner widgets on the same screen

Ad Status Reference​

StatusDescription
AdStatus.initializingBanner is loading
AdStatus.readyBanner is loaded and displayed
AdStatus.failedBanner failed to load
AdStatus.willLeaveUser clicked the ad (leaving app)