Skip to main content
Version: v1.1.0

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​

  1. Add google_mobile_ads and call MobileAds.instance.initialize() at startup.
  2. Declare your Ad Manager app ID: GADApplicationIdentifier in ios/Runner/Info.plist and the com.google.android.gms.ads.APPLICATION_ID <meta-data> in AndroidManifest.xml.
  3. In Google Ad Manager, set up Prebid line items and creatives that target the hb_* keys.
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 a PrebidMultiformatAd) from GAM's onAdLoaded. 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 returns false otherwise. 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 next fetchDemand).
  • 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​

resultCodeMeaning
prebidDemandFetchSuccessA bid won; keywords are set.
prebidDemandNoBidsNo bid (also reported for an empty seat bid on Android).
prebidDemandTimedOutThe auction exceeded the timeout.
prebidDemandNoCachedBidsEvery bid was dropped for a failed cache entry (setFilterOutUncachedBids).
prebidNetworkError, prebidServerErrorThe request failed.
prebidInvalidAccountId, prebidInvalidConfigId, prebidInvalidSize, prebidServerURLInvalidConfiguration errors.
prebidSdkNotInitializedfetchDemand ran before initializeSdk completed (Android).
prebidInvalidContext, prebidInvalidAdObject, prebidInvalidNativeRequestRequest errors Prebid Android reports.
prebidUnknownError, prebidInvalidResponseStructure, prebidInternalSDKError, prebidWrongArguments, prebidNoVastTagInMediaData, prebidSDKMisuseSDK errors Prebid iOS reports.