Skip to main content
Version: v1.0.0

Google Ad Manager

prebid_mobile_sdk_gam wraps Prebid's GAM event handlers. Prebid runs the auction, Google Ad Manager runs its own with the Prebid bid as a line item, and the winner renders: the Prebid creative or the GAM ad. Unlike the Original API, the widgets make the GAM request for you.

Install​

flutter pub add prebid_mobile_sdk prebid_mobile_sdk_gam

The package bundles the Google Mobile Ads SDK, which crashes at startup without an app ID:

  • Android: <meta-data android:name="com.google.android.gms.ads.APPLICATION_ID" android:value="ca-app-pub-…"/> in AndroidManifest.xml.
  • iOS: GADApplicationIdentifier in ios/Runner/Info.plist.

Initialize Google Mobile Ads once at startup (for example MobileAds.instance.initialize() from google_mobile_ads 8.0.0 or later; 7.x pins Google Mobile Ads iOS 12, which Prebid's GAM event handlers don't support), then configure Prebid line items targeting the hb_* keys in Ad Manager.

import 'package:prebid_mobile_sdk_gam/prebid_mobile_sdk_gam.dart';

PrebidGamBannerAd(
configId: 'prebid-demo-banner-320-50',
gamAdUnitId: '/21808260008/prebid_oxb_320x50_banner',
width: 320,
height: 50,
customTargeting: const {'section': 'home'},
listener: PrebidBannerAdListener(
onAdLoaded: () => debugPrint('GAM banner loaded'),
),
)

PrebidGamBannerAd takes the core banner parameters (additionalSizes, adFormats, isVideo, videoPlacementType, videoParameters iOS only, adPosition, pbAdSlot, impOrtbConfig, globalOrtbConfig, refreshIntervalSeconds, autoLoad, controller, videoListener) plus:

ParameterDescription
gamAdUnitIdRequired. Your Ad Manager ad unit path.
customTargetingKey-values added to the GAM request; Prebid's hb_* keys win on conflict.

Every size (width × height and additionalSizes) is a valid GAM ad size. The slot resizes to the creative that renders, whether the Prebid bid or GAM's own ad won.

Preloaded banner (feeds)​

PrebidGamPreloadedBannerAd loads a banner before its slot is on screen and keeps it across the views showing it, so a banner in a scrolling list isn't re-auctioned each time it scrolls back. It takes the parameters above, without autoLoad and controller; see Preload a banner for the lifecycle.

final ad = PrebidGamPreloadedBannerAd(
configId: 'prebid-demo-banner-320-50',
gamAdUnitId: '/21808260008/prebid_oxb_320x50_banner',
width: 320,
height: 50,
);
await ad.load();

PrebidGamPreloadedBannerAdView(ad: ad); // in the list item
await ad.destroy(); // when the screen goes away

Interstitial and rewarded​

late final PrebidGamInterstitialAd interstitial;

interstitial = PrebidGamInterstitialAd(
configId: 'prebid-demo-display-interstitial-320-480',
gamAdUnitId: '/21808260008/prebid_oxb_html_interstitial',
listener: PrebidInterstitialAdListener(
onAdLoaded: () => interstitial.show(),
onAdClosed: () => interstitial.destroy(),
),
);
await interstitial.loadAd();
late final PrebidGamRewardedAd rewarded;

rewarded = PrebidGamRewardedAd(
configId: 'prebid-demo-video-rewarded-320-480',
gamAdUnitId: '/21808260008/prebid_oxb_rewarded_video',
listener: PrebidRewardedAdListener(
onAdLoaded: () => rewarded.show(),
onUserEarnedReward: (reward) => debugPrint('${reward.count} ${reward.type}'),
onAdClosed: () => rewarded.destroy(),
),
);
await rewarded.loadAd();

Both take customTargeting, controls (supportSKOverlay included iOS only), videoParameters, impOrtbConfig, globalOrtbConfig and pbAdSlot (on iOS sent in the imp JSON, since Prebid iOS has no setter on these units); the interstitial also takes isVideo (request a video creative) and adFormats (a multiformat interstitial; overrides isVideo). The lifecycle matches the core fullscreen ads, with isLoaded to check readiness: show() on an ad that isn't loaded reports onAdFailed ("The ad is not loaded").

Android only Prebid Android drops a request made before the Prebid SDK finished initializing, so a banner, interstitial or rewarded ad loaded that early reports onAdFailed ("The Prebid SDK is not initialized") instead of never answering; the native ad reports onFetchDemandFailed('prebidSdkNotInitialized') and still requests the GAM ad.

Set the GPID of a fullscreen ad through impOrtbConfig, e.g. '{"ext":{"gpid":"/1111/interstitial"}}'.

Native​

GAM native follows Prebid's Original API flow: Prebid runs the auction, GAM returns a custom-format or a unified native ad, and Prebid looks for its winning bid in it.

PrebidGamNativeAd(
configId: 'prebid-demo-banner-native-styles',
gamAdUnitId: '/21808260008/apollo_custom_template_native_ad_unit',
customFormatId: '11934135',
listener: PrebidGamNativeAdListener(
onNativeAdLoaded: () => debugPrint('Prebid native rendered'),
onPrimaryAdWinCustom: () => debugPrint('GAM custom format won'),
onPrimaryAdWinUnified: () => debugPrint('GAM unified native won'),
onAdImpression: () => debugPrint('impression'),
),
)
CallbackWhen
onFetchDemandSuccess / onFetchDemandFailed(reason)The Prebid auction returned a bid / no bid or failed; reason is the result code, e.g. prebidDemandNoBids or prebidDemandTimedOut (the same strings as the core package), or prebidSdkNotInitialized Android only. The GAM request runs either way.
onCustomAdLoaded / onUnifiedAdLoadedGAM returned a custom-format / unified native ad.
onPrimaryAdFailed(String)The GAM request failed.
onNativeAdLoadedA Prebid native creative was found and rendered.
onPrimaryAdWinCustom / onPrimaryAdWinUnifiedNo Prebid creative: the GAM ad renders.
onAdImpressionFor a Prebid creative, Prebid's own impression tracker request succeeded (reported once). That differs from the core PrebidNativeAdView, whose impression is viewability-based. For a GAM unified ad, the Google Mobile Ads impression.
onAdClickedThe rendered ad was clicked.
onAdExpiredThe Prebid bid expired before an impression.

Without customFormatId, only unified native ads are requested. nativeParameters (NativeParameters) sets the requested assets, event trackers, context and request options; unset, it requests title, icon, main image, sponsored, description and call to action with impression trackers, in the social, general social and in-feed context.

ParameterDescription
customTargetingKey-values added to the GAM request; Prebid's hb_* keys win on conflict.
gpidThe Global Placement ID (imp.ext.gpid).
pbAdSlotPrebid ad slot (imp.ext.data.pbadslot).
impOrtbConfigImpression-level OpenRTB JSON merged into the imp.
globalOrtbConfigRequest-level OpenRTB JSON for this ad unit only.

Compatibility​

prebid_mobile_sdk_gamPrebid AndroidPrebid iOSAd SDK AndroidAd SDK iOSTested with
1.1.0latestOct 30, 20263.4.1>= 3.4.1, < 4.0play-services-ads 25.5.0Google-Mobile-Ads-SDK >= 13.0.0google_mobile_ads ^9.1.0
1.0.0Oct 11, 20263.4.0>= 3.4.1, < 4.0play-services-ads 25.5.0Google-Mobile-Ads-SDK >= 13.0.0google_mobile_ads ^9.1.0