Skip to main content
Version: v1.1.0

Native

PrebidNativeAd runs the auction and parses the native response. PrebidNativeAdView renders it in a native view and registers it with Prebid, so impressions and clicks are tracked.

class NativeSlot extends StatefulWidget {
const NativeSlot({super.key});


State<NativeSlot> createState() => _NativeSlotState();
}

class _NativeSlotState extends State<NativeSlot> {
var _loaded = false;
late final PrebidNativeAd _ad = PrebidNativeAd(
configId: 'prebid-demo-banner-native-styles',
listener: PrebidNativeAdListener(
onAdLoaded: (response) => setState(() => _loaded = true),
onAdFailed: (error) => debugPrint('native failed: $error'),
onAdImpression: () => debugPrint('impression'),
onAdClicked: () => debugPrint('click'),
),
)..loadAd();


void dispose() {
_ad.destroy();
super.dispose();
}


Widget build(BuildContext context) =>
_loaded ? PrebidNativeAdView(ad: _ad) : const SizedBox.shrink();
}

The view lays out the main image, icon, sponsored line, title, body and call to action, and grows to the rendered height. Reloading the ad (loadAd() again) shows the new ad in the view already on screen.

Requested assets​

The native request is a NativeParameters, which every native ad takes as nativeParameters: this one, the Original API units and the GAM, AdMob and MAX native ads. Without assets, the ad requests title, main image, icon, sponsored, description and call to action (NativeParameters.defaultAssets):

PrebidNativeAd(
configId: 'your-config-id',
nativeParameters: const NativeParameters(
assets: [
NativeAsset.title(length: 90, required: true),
NativeAsset.image(imageType: NativeImageType.main, widthMin: 300, heightMin: 150, required: true),
NativeAsset.image(imageType: NativeImageType.icon, width: 50, height: 50),
NativeAsset.data(dataType: NativeDataType.sponsored, required: true),
NativeAsset.data(dataType: NativeDataType.desc),
NativeAsset.data(dataType: NativeDataType.ctaText),
NativeAsset.data(dataType: NativeDataType.rating),
],
eventTrackers: [
NativeEventTracker(
eventType: NativeEventType.impression,
methods: [NativeEventTrackingMethod.image, NativeEventTrackingMethod.js],
),
],
context: NativeContextType.socialCentric,
contextSubType: NativeContextSubType.social,
placementType: NativePlacementType.inFeed,
),
);
NativeParameters fieldDescription
assetsNativeAsset.title, .image and .data entries.
eventTrackersImpression / viewability trackers to request.
context, contextSubType, placementTypeWhere the ad appears (OpenRTB Native 1.2).
placementCountNumber of identical placements (plcmtcnt).
sequence, assetUrlSupport, dUrlSupport, privacy, extNative request seq, aurlsupport, durlsupport, privacy and ext.

PrebidNativeAd itself also takes gpid, pbAdSlot, impOrtbConfig and globalOrtbConfig (impression-level and per-unit request-level OpenRTB JSON).

NativeAsset.image also takes mimes, the image types your layout can show. Every asset takes an ext for its title, img or data object and an assetExt for the asset itself, and NativeEventTracker takes an ext; assetExt and the tracker ext are sent on Android only, since Prebid iOS has no field for them. The GAM, AdMob and MAX native widgets send the same fields.

NativeAsset.image(
imageType: NativeImageType.main,
mimes: ['image/jpeg', 'image/png'],
ext: {'aspectratios': ['1.91:1']},
)

If a creative references assets by ID, call PrebidMobile.setShouldAssignNativeAssetId(true) so the request numbers them sequentially.

Reading the response​

onAdLoaded receives a PrebidNativeAdResponse, for apps that build their own layout or log the ad:

FieldContent
title, text, sponsoredBy, callToActionThe main text assets.
iconUrl, imageUrlIcon and main image URLs.
clickUrlThe click-through URL.
privacyUrlThe AdChoices link, when the bid has one.
titles, images, dataAssetsEvery asset of each kind (PrebidNativeImage.type, PrebidNativeData.type). On iOS, PrebidNativeImage.width and height give the size the bid declares, to keep the aspect ratio in your own layout; Prebid Android doesn't keep it.
dataOf(NativeDataType)The values of one data type, e.g. dataOf(NativeDataType.rating).

Impressions and clicks are only tracked for an ad shown through PrebidNativeAdView: the native layout above, or your own layout in PrebidNativeAdView.custom.

Your own layout​

PrebidNativeAdView.custom shows your Flutter widgets and still lets Prebid track the ad: a transparent native view under your layout is registered for the impression, and a tap on the layout reports a click (Prebid fires the click trackers and opens the click URL). Buttons that handle their own taps, such as the call to action, call performClick():

PrebidNativeAdView.custom(
ad: _ad,
child: Column(
children: [
Image.network(response.imageUrl ?? ''),
Text(response.title ?? ''),
FilledButton(
onPressed: _ad.performClick,
child: Text(response.callToAction ?? 'Open'),
),
],
),
);

The widget takes your layout's size.

Impressions​

onAdImpression follows the IAB viewability rule Prebid applies before it fires the impression trackers: at least half of the view on screen for one second. It fires once per loaded ad, also when the bid carries no impression trackers. "On screen" includes Flutter's own clipping: a view half scrolled under an app bar or out of a list's viewport counts as half visible.

CallbackWhen
onAdLoaded(PrebidNativeAdResponse)The native response was parsed.
onAdFailed(String)No bid, a parse error, or the SDK isn't initialized.
onAdImpressionThe view was viewable for one second.
onAdClickedThe user tapped an asset of the view.
onAdExpiredThe bid expired before it was shown; the view stays empty. Load again.

Original API native​

To let your ad server render native demand (GAM custom native formats), use PrebidNativeAdUnit or the GAM native widget.

When a native bid wins an Original API auction and you render it yourself, load it from its cache id instead of running a second auction, then show it as above:

final response = await PrebidMultiformatAd(...).fetchDemand();
if (response.winningFormat == 'native') {
await _ad.loadFromCacheId(response.nativeAdCacheId!);
}