Skip to main content
Version: v1.1.0

AppLovin MAX

prebid_mobile_sdk_max puts Prebid demand inside AppLovin MAX mediation. Prebid's mediation ad units run the auction and hand the winning bid to the MAX ad through the Prebid MAX adapter; MAX renders the Prebid creative or a competing network's ad.

Install​

flutter pub add prebid_mobile_sdk prebid_mobile_sdk_max

Initialize the AppLovin SDK with your SDK key before loading any MAX ad. This package doesn't do it for you; for example, with applovin_max 4.0.0 or later (3.x pins AppLovin SDK 11, which Prebid's MAX adapters don't support):

await AppLovinMAX.initialize('YOUR_APPLOVIN_SDK_KEY');

Declare the SDK key natively as AppLovin requires: AppLovinSdkKey in ios/Runner/Info.plist and the applovin.sdk.key <meta-data> in AndroidManifest.xml. In the MAX dashboard, add Prebid as a custom network on your ad units, per Prebid's MAX integration guide.

iOS: turn Swift Package Manager off with applovin_max

applovin_max only supports CocoaPods, so it brings its own copy of the AppLovin SDK. With Swift Package Manager on, this package adds a second copy through Swift Package Manager and the iOS build fails with "Multiple commands produce AppLovinSDK.framework". Turn Swift Package Manager off for the app so every plugin uses CocoaPods:

pubspec.yaml
flutter:
config:
enable-swift-package-manager: false
import 'package:prebid_mobile_sdk_max/prebid_mobile_sdk_max.dart';

PrebidMaxBannerAd(
configId: 'prebid-demo-banner-320-50',
maxAdUnitId: 'YOUR_MAX_BANNER_AD_UNIT_ID',
width: 320,
height: 50,
listener: PrebidBannerAdListener(
onAdLoaded: () => debugPrint('MAX banner loaded'),
),
)

A 300×250 slot loads with MAX's MREC format; every other size uses the banner format. The parameters match the AdMob banner: autoLoad, controller, adPosition, impOrtbConfig, globalOrtbConfig, pbAdSlot, gpid, additionalSizes and refreshIntervalSeconds. Prebid clamps the refresh interval to 30–120 s on Android and 15–120 s on iOS, and null or 0 turns it off. MAX's own banner refresh is set in the MAX dashboard. controller.stopRefresh() stops both Prebid's bid refresh and MAX's banner auto-refresh.

adaptive: true makes the MAX view an adaptive banner (MAX extra parameter adaptive_banner = true). It spans the full available width at the height MAX computes for that width. width x height stays the Prebid request size, and MREC slots ignore adaptive:

PrebidMaxBannerAd(
configId: 'prebid-demo-banner-320-50',
maxAdUnitId: 'YOUR_MAX_BANNER_AD_UNIT_ID',
width: 320,
height: 50,
adaptive: true,
additionalSizes: const [Size(728, 90)],
listener: PrebidMaxBannerAdListener(
onAdExpanded: () => debugPrint('expanded'),
onAdCollapsed: () => debugPrint('collapsed'),
onAdDisplayFailed: (error) => debugPrint('display failed: $error'),
onAdRevenuePaid: (revenue) => debugPrint('${revenue.revenue} USD'),
),
)

adFormats sets the formats Prebid bids on, as on the core banner: {PrebidAdFormat.video} for an outstream video banner, or {PrebidAdFormat.banner, PrebidAdFormat.video} for a multiformat one. null keeps a display banner. videoParameters sends video signals on iOS only: Prebid Android's mediation banner has no video-parameters setter, so Android sends the SDK's defaults.

PrebidMaxBannerAd(
configId: 'prebid-demo-banner-300-250',
maxAdUnitId: 'YOUR_MAX_MREC_AD_UNIT_ID',
width: 300,
height: 250,
adFormats: const {PrebidAdFormat.banner, PrebidAdFormat.video},
videoParameters: const VideoParameters(mimes: ['video/mp4']),
)

Preloaded banner (feeds)​

PrebidMaxPreloadedBannerAd 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. The banner loads before any layout, so with adaptive: true it spans width instead of measuring the available width; set adaptiveWidth (for example the screen width) to span more while width stays the Prebid request size.

final ad = PrebidMaxPreloadedBannerAd(
configId: 'prebid-demo-banner-320-50',
maxAdUnitId: 'YOUR_MAX_BANNER_AD_UNIT_ID',
width: 320,
height: 50,
);
await ad.load();

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

Interstitial and rewarded​

late final PrebidMaxRewardedAd rewarded;

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

PrebidMaxInterstitialAd works the same way. Both take controls, videoParameters, impOrtbConfig, globalOrtbConfig, pbAdSlot and gpid. The interstitial takes isVideo, or adFormats (for example {PrebidAdFormat.banner, PrebidAdFormat.video}), which overrides isVideo. Set the interstitial's display minimum size with PrebidFullscreenControls(minSizePercentage: Size(30, 30)); rewarded ads have no minimum size or auto-close in Prebid's mediation units.

One rewarded ad per MAX ad unit

MAX shares one rewarded ad object per ad unit. Loading a second PrebidMaxRewardedAd on the same maxAdUnitId takes it over, and the previous one receives onAdFailed ("Replaced by another ad on the same MAX ad unit"). While an ad on that unit is on screen, the new load fails instead ("Another ad for this MAX ad unit is showing…"), so the visible ad keeps its reward: load the next one from onAdClosed.

Native​

PrebidMaxNativeAd(
configId: 'prebid-demo-banner-native-styles',
maxAdUnitId: 'YOUR_MAX_NATIVE_AD_UNIT_ID',
listener: PrebidMaxNativeAdListener(
onAdLoaded: () => debugPrint('native loaded'),
onAdImpression: () => debugPrint('impression'),
),
)

Rendered in MAX's native ad view. PrebidMaxNativeAdListener has onAdLoaded, onAdImpression, onAdClicked, onAdFailed and onAdRevenuePaid; nativeParameters works as on AdMob; impOrtbConfig, globalOrtbConfig, pbAdSlot and gpid (the last two sent in the imp JSON) apply on both platforms. width and height size the slot as on AdMob.

Events​

onAdImpression (banner, interstitial, rewarded, native) comes from MAX's revenue callback, which MAX fires when it records the impression. show() before the ad is loaded reports onAdFailed.

On Android, an ad that loads before PrebidMobile.initializeSdk completes reports onAdFailed ("The Prebid SDK is not initialized"). This applies to every format. Prebid Android drops such requests without calling back, so the load would otherwise never finish and MAX would never run its waterfall. Prebid iOS runs these requests, so iOS skips this check.

To get MAX-specific events, pass a MAX listener. Each one extends the core listener, so the core callbacks work as usual:

ListenerExtra callbacks
PrebidMaxBannerAdListeneronAdExpanded, onAdCollapsed, onAdDisplayFailed (also reported as onAdFailed), onAdRevenuePaid
PrebidMaxInterstitialAdListeneronAdDisplayFailed (followed by onAdFailed), onAdRevenuePaid
PrebidMaxRewardedAdListeneronAdDisplayFailed (followed by onAdFailed), onAdRevenuePaid
PrebidMaxNativeAdListeneronAdRevenuePaid

onAdRevenuePaid passes a PrebidMaxAdRevenue with revenue (in USD), revenuePrecision, networkName and placement.

Testing the adapter fallback​

PrebidMax.debugDropBidProbability is a testing-only hook. Leave it at 0 in production apps. Set it between 0 and 1 and the plugin withholds the Prebid bid from MAX, with that probability, after each auction. The Prebid adapter then finds no bid and MAX falls back to its waterfall. Prebid's internal test app runs its "Random" cases at 0.5:

PrebidMax.debugDropBidProbability = 0.5;

Banners read the value when they are created, and roll again on every Prebid refresh. Interstitials and rewarded ads read it on each loadAd(). Native ads ignore it. On Android the plugin sets the MAX local extra PrebidMaxMediationAdapter.EXTRA_RESPONSE_ID to "", as the test app does. Prebid iOS passes the bid itself rather than a response id, so on iOS the plugin clears the bid local extra (PBMMediationAdUnitBidKey).

Compatibility​

prebid_mobile_sdk_maxPrebid AndroidPrebid iOSAd SDK AndroidAd SDK iOSTested with
1.1.0latestOct 30, 20263.4.1>= 3.4.1, < 4.0applovin-sdk 13.1.0AppLovinSDK >= 13.0.0applovin_max ^4.6.4
1.0.0Oct 11, 20263.4.0>= 3.4.1, < 4.0applovin-sdk 13.1.0AppLovinSDK >= 13.0.0applovin_max ^4.6.4