Banner
PrebidBannerAd is a widget that runs a Prebid auction and renders the winning creative in a native view. It starts at the requested size and resizes to the creative that wins.
PrebidBannerAd(
configId: 'prebid-demo-banner-320-50',
width: 320,
height: 50,
refreshIntervalSeconds: 30,
listener: PrebidBannerAdListener(
onAdLoaded: () => debugPrint('loaded'),
onAdDisplayed: () => debugPrint('on screen'),
onAdFailed: (error) => debugPrint('failed: $error'),
onAdClicked: () => debugPrint('clicked'),
onAdClosed: () => debugPrint('click-through closed'),
onAdExpired: () => debugPrint('bid expired before display'),
),
)
Parameters
| Parameter | Type | Description |
|---|---|---|
configId | String | Required. Stored impression ID on your Prebid Server. |
width, height | int | Required. Requested size in logical pixels. |
additionalSizes | List<Size>? | More sizes the slot accepts (multisize). |
refreshIntervalSeconds | int? | Auto-refresh interval. null or 0 disables refresh. |
autoLoad | bool | Load when the view is created (default true). |
controller | PrebidBannerAdController? | Load on demand and stop refresh. |
adFormats | Set<PrebidAdFormat>? | {PrebidAdFormat.banner, PrebidAdFormat.video} for a multiformat banner. Overrides isVideo. |
isVideo | bool | Request outstream video only. |
videoPlacementType | VideoPlacementType? | inBanner (default), inArticle or inFeed. |
videoParameters | VideoParameters? | Video signals. iOS only |
adPosition | PrebidAdPosition? | Position on screen (imp.banner.pos): header, footer, aboveTheFold, … |
pbAdSlot | String? | Prebid ad slot (imp.ext.data.pbadslot). |
gpid | String? | Global Placement ID (imp.ext.gpid), added to impOrtbConfig (a gpid already there wins). |
impOrtbConfig | String? | OpenRTB JSON merged into the impression, e.g. {"ext":{"gpid":"/1111/home"}}. |
globalOrtbConfig | String? | Request-level OpenRTB JSON for this ad unit only, merged over PrebidTargeting.setGlobalOrtbConfig. |
listener | PrebidBannerAdListener? | Lifecycle callbacks. |
videoListener | PrebidBannerVideoListener? | Outstream video playback callbacks. |
Prebid clamps the refresh interval to 30–120 seconds on Android and 15–120 seconds on iOS. Changing a parameter rebuilds the native view with the new configuration and loads it again; swapping the listener doesn't.
Multisize
PrebidBannerAd(
configId: 'prebid-demo-banner-multisize',
width: 320,
height: 50,
additionalSizes: const [Size(728, 90)],
)
Prebid requests every size and the widget adopts the winner's size once it renders.
Load on demand
final controller = PrebidBannerAdController();
PrebidBannerAd(
configId: 'prebid-demo-banner-320-50',
width: 320,
height: 50,
autoLoad: false,
controller: controller,
);
// Later, for example once the slot scrolls into view:
await controller.loadAd();
await controller.stopRefresh();
loadAd() is safe to call before the native view exists: the load runs when the view is created. stopRefresh() acts on the native view, so call it once the banner has loaded (onAdLoaded). The same controller works with the GAM, AdMob and MAX banners.
After each load, controller.winningBid holds the winning bid of a Prebid-rendered banner for analytics: price, bidder, size and targetingKeywords (null when the last load or refresh had no bid).
Preload a banner (feeds)
A PrebidBannerAd loads when its widget is built and is destroyed with it, so in a scrolling list a banner scrolled away and back runs a new auction. PrebidPreloadedBannerAd keeps the banner apart from the widgets that show it: load it before its slot is on screen, show it with PrebidPreloadedBannerAdView, and destroy it yourself.
final ad = PrebidPreloadedBannerAd(
configId: 'prebid-demo-banner-320-50',
width: 320,
height: 50,
refreshIntervalSeconds: 30,
listener: PrebidBannerAdListener(onAdLoaded: () => debugPrint('loaded')),
);
await ad.load(); // creates the banner; the auction runs and the creative renders off screen
// In the list item, as often as it is built:
PrebidPreloadedBannerAdView(ad: ad);
// When the screen goes away:
await ad.destroy();
- It takes the parameters of
PrebidBannerAd, withoutautoLoadandcontroller:load()loads it (again),stopRefresh()stops auto-refresh, andwinningBidandsizeare on the ad. - Prebid counts the impression when the creative is on screen, not when it loads, and refreshes it only while it is visible.
- The banner shows in one view at a time: a view built later takes it over, and the earlier one goes empty. Removing a view keeps the banner loaded.
- A view shows an empty slot of the requested size until the banner is loaded, and again after
destroy(); a laterload()starts afresh.
The GAM, AdMob and MAX packages have the same banner: PrebidGamPreloadedBannerAd, PrebidAdMobPreloadedBannerAd and PrebidMaxPreloadedBannerAd, each with its own view.
Outstream video
PrebidBannerAd(
configId: 'prebid-demo-video-outstream',
width: 300,
height: 250,
adFormats: const {PrebidAdFormat.video},
videoPlacementType: VideoPlacementType.inArticle,
videoListener: PrebidBannerVideoListener(
onVideoCompleted: () => debugPrint('video completed'),
onVideoMuted: () => debugPrint('muted'),
),
)
PrebidBannerVideoListener has onVideoCompleted, onVideoPaused, onVideoResumed, onVideoMuted and onVideoUnmuted.
On iOS, videoParameters sets every video signal on the banner (an explicit placement overrides videoPlacementType). Prebid Android's BannerView has no video-parameters setter, so Android sends the SDK's defaults plus the placement.
Events
| Callback | When |
|---|---|
onAdLoaded | The creative loaded. |
onAdDisplayed | The creative is on screen (the SDK's impression), which can be later than onAdLoaded. |
onAdFailed(String) | No bid, a network error or a render failure. |
onAdClicked | The user tapped the creative. |
onAdClosed | The click-through (in-app browser or modal) was dismissed. |
onAdExpired | The bid expired (bid.exp) before it was shown. |
onAdImpression | Mediation only: the AdMob and MAX banners report the ad SDK's impression. |