Original API
In the Original API, Prebid only runs the auction. It returns targeting keywords (hb_pb, hb_bidder, hb_cache_id, …) that you add to your Google Ad Manager request; a Prebid line item targeting those keys serves the Prebid Universal Creative when the bid wins.
The plugin doesn't depend on google_mobile_ads: add it to your app and wire the handoff yourself.
Setup
- Add
google_mobile_adsand callMobileAds.instance.initialize()at startup. - Declare your Ad Manager app ID:
GADApplicationIdentifierinios/Runner/Info.plistand thecom.google.android.gms.ads.APPLICATION_ID<meta-data>inAndroidManifest.xml. - In Google Ad Manager, set up Prebid line items and creatives that target the
hb_*keys.
Banner
import 'package:google_mobile_ads/google_mobile_ads.dart';
import 'package:prebid_mobile_sdk/prebid_mobile_sdk.dart';
final unit = PrebidBannerAdUnit(
configId: 'your-config-id',
sizes: const [Size(300, 250)],
adPosition: PrebidAdPosition.aboveTheFold,
);
final bid = await unit.fetchDemand();
final banner = AdManagerBannerAd(
adUnitId: '/1234567/your-ad-unit',
sizes: [AdSize.mediumRectangle],
request: AdManagerAdRequest(customTargeting: bid.targetingKeywords ?? const {}),
listener: AdManagerBannerAdListener(
onAdLoaded: (_) => unit.activateImpressionTracker(),
onAdFailedToLoad: (ad, error) => ad.dispose(),
),
);
await banner.load();
Render it with AdWidget(ad: banner) inside a SizedBox of the requested size. A won Prebid banner isn't resized dynamically: request the size of your GAM ad unit.
PrebidBidResponse has resultCode (prebidDemandFetchSuccess, prebidDemandNoBids, …), isSuccess and targetingKeywords. Send the GAM request even without a bid, so direct-sold demand can still serve.
Interstitial
final unit = PrebidInterstitialAdUnit(
configId: 'your-config-id',
sizes: const [Size(320, 480)],
videoParameters: const VideoParameters(mimes: ['video/mp4']),
trackImpression: true,
);
final bid = await unit.fetchDemand();
await AdManagerInterstitialAd.load(
adUnitId: '/1234567/your-interstitial',
request: AdManagerAdRequest(customTargeting: bid.targetingKeywords ?? const {}),
adLoadCallback: AdManagerInterstitialAdLoadCallback(
onAdLoaded: (ad) => ad.show(),
onAdFailedToLoad: (error) {},
),
);
Pass sizes for display, videoParameters for video, or both. minSizePercentage requests display with a minimum size, with or without sizes. A unit with none of them throws an ArgumentError.
Rewarded
final unit = PrebidRewardedAdUnit(
configId: 'your-config-id',
videoParameters: const VideoParameters(
mimes: ['video/mp4'],
size: Size(320, 480),
),
);
final bid = await unit.fetchDemand();
await RewardedAd.loadWithAdManagerAdRequest(
adUnitId: '/1234567/your-rewarded',
adManagerRequest: AdManagerAdRequest(customTargeting: bid.targetingKeywords ?? const {}),
rewardedAdLoadCallback: RewardedAdLoadCallback(
onAdLoaded: (ad) => ad.show(onUserEarnedReward: (_, reward) {}),
onAdFailedToLoad: (error) {},
),
);
A rewarded video interstitial (instl and Prebid's rewarded flag). trackImpression lets Prebid record the impression when the ad server shows the Prebid creative.
Native
final unit = PrebidNativeAdUnit(
configId: 'your-config-id',
nativeParameters: const NativeParameters(
assets: [
NativeAsset.title(length: 90, required: true),
NativeAsset.image(imageType: NativeImageType.main, required: true),
],
context: NativeContextType.contentCentric,
placementType: NativePlacementType.inFeed,
),
);
final bid = await unit.fetchDemand(); // also bid.nativeAdCacheId
nativeParameters is the same NativeParameters as PrebidNativeAd's; unset assets request NativeParameters.defaultAssets.
For GAM's custom native formats rendered through Prebid, the GAM native widget does the whole flow.
Multiformat
PrebidMultiformatAd asks for banner, video and native demand in a single request:
final ad = PrebidMultiformatAd(
configId: 'your-config-id',
bannerSizes: const [Size(300, 250)],
videoParameters: const VideoParameters(mimes: ['video/mp4']),
nativeParameters: const NativeParameters(assets: [NativeAsset.title(length: 90)]),
);
final bid = await ad.fetchDemand();
debugPrint('${bid.winningFormat}'); // banner, video or native
PrebidMultiformatBidResponse adds winningFormat, nativeAdCacheId, exp, topBidFiltered and events (the win and impression URLs, when Prebid Server sends them). A native win shows with PrebidNativeAd.loadFromCacheId.
More request options: bannerApi (banner API frameworks, e.g. MRAID), interstitialMinSizePercentage for an interstitial request (also without bannerSizes), gpid and adPosition. Native demand is requested when nativeParameters is set. PrebidBannerAdUnit takes bannerApi too. Every single-format unit (PrebidBannerAdUnit, PrebidInterstitialAdUnit, PrebidRewardedAdUnit, PrebidNativeAdUnit) takes gpid too, and its PrebidBidResponse carries exp, topBidFiltered and events.
A full-screen ad is often loaded long before it shows. Both result types carry receivedAt, expiresAt (receivedAt plus exp) and isExpired: when the bid has expired, fetch demand again instead of loading your ad server's ad with stale keywords.
if (response.isExpired) response = await adUnit.fetchDemand();
Every unit also takes pbAdSlot, impOrtbConfig and a per-unit globalOrtbConfig. On Android they apply to a single-format request, which runs on Prebid's matching ad unit (banner, interstitial, rewarded video or native); a PrebidMultiformatAd asking for two or more formats runs on Prebid Android's multiformat ad unit, which has no setters for them. Request-wide OpenRTB set with PrebidTargeting.setGlobalOrtbConfig applies to every request.
For video, set VideoParameters.size (imp.video.w / h): many bidders reject an Original API video request without a player size.
Auto-refresh
final unit = PrebidBannerAdUnit(
configId: 'your-config-id',
sizes: const [Size(320, 50)],
onDemandRefreshed: (bid) {
// Reload the GAM banner with bid.targetingKeywords.
},
);
await unit.fetchDemand();
await unit.setAutoRefreshInterval(60); // 30–120 s
await unit.stopAutoRefresh();
await unit.resumeAutoRefresh();
await unit.destroy();
Prebid re-runs the auction on the interval and onDemandRefreshed receives each result; reload your GAM ad with the new keywords. Intervals are clamped to 30–120 seconds on both platforms.
Impression tracking
Prebid can fire the bid's impression URL (burl) when GAM shows the Prebid creative:
- Banner: call
unit.activateImpressionTracker()(activateBannerImpressionTracker()on aPrebidMultiformatAd) from GAM'sonAdLoaded. It looks for the Google Mobile Ads banner in the window (a Flutter widget can't hand over the native view), so it needs exactly one GMA banner on screen and returnsfalseotherwise. On iOS the current bid is tracked; Prebid Android attaches the view when an auction starts, so on Android tracking applies from the next auction (auto-refresh or the nextfetchDemand). - Interstitial: create the unit with
trackImpression: true.
Creative size
A multisize GAM banner renders at the size of the GAM line item, not of the Prebid creative inside it. Once GAM's onAdLoaded fires, findPrebidCreativeSize() reads the creative's size from the rendered ad so you can resize the banner; it returns null when the creative isn't a Prebid one. Like the impression tracker, it needs exactly one Google Mobile Ads banner on screen.
final size = await ad.findPrebidCreativeSize();
if (size != null) setState(() => _bannerSize = size);
SKAdNetwork iOS only
For SKAdNetwork bids rendered by GAM: activateBannerSKAdNetwork() (from GAM's onAdLoaded), activateInterstitialSKAdNetwork(), activateSKOverlay() / dismissSKOverlay(), and supportSKOverlay: true on an interstitial PrebidMultiformatAd. They do nothing on Android.
Result codes
resultCode | Meaning |
|---|---|
prebidDemandFetchSuccess | A bid won; keywords are set. |
prebidDemandNoBids | No bid (also reported for an empty seat bid on Android). |
prebidDemandTimedOut | The auction exceeded the timeout. |
prebidDemandNoCachedBids | Every bid was dropped for a failed cache entry (setFilterOutUncachedBids). |
prebidNetworkError, prebidServerError | The request failed. |
prebidInvalidAccountId, prebidInvalidConfigId, prebidInvalidSize, prebidServerURLInvalid | Configuration errors. |
prebidSdkNotInitialized | fetchDemand ran before initializeSdk completed (Android). |
prebidInvalidContext, prebidInvalidAdObject, prebidInvalidNativeRequest | Request errors Prebid Android reports. |
prebidUnknownError, prebidInvalidResponseStructure, prebidInternalSDKError, prebidWrongArguments, prebidNoVastTagInMediaData, prebidSDKMisuse | SDK errors Prebid iOS reports. |