From 58806ca1ff00a8a0ed07720b8be880319527556c Mon Sep 17 00:00:00 2001 From: Postindustria Date: Mon, 30 Mar 2026 16:43:06 +0300 Subject: [PATCH 1/6] Documentation for Next-Gen SDK support - Add documentation for prebid-rendering integration - Add documentation for original api integration --- _data/sidebar.yml | 16 + .../android-sdk-integration-nextgen.md | 344 ++++++++++++++++++ ...id-sdk-integration-nextgen-original-api.md | 66 ++++ .../nextgen-bidding-only-html-banner.md | 138 +++++++ ...extgen-bidding-only-interstitial-banner.md | 88 +++++ ...nextgen-bidding-only-interstitial-video.md | 116 ++++++ ...n-bidding-only-multiformat-interstitial.md | 81 +++++ .../nextgen-bidding-only-multiformat.md | 267 ++++++++++++++ .../nextgen-bidding-only-native-in-app.md | 262 +++++++++++++ .../nextgen-bidding-only-native-in-webview.md | 169 +++++++++ .../nextgen-bidding-only-rewarded-video.md | 101 +++++ .../nextgen-bidding-only-video-outstream.md | 121 ++++++ 12 files changed, 1769 insertions(+) create mode 100644 prebid-mobile/modules/rendering/android-sdk-integration-nextgen.md create mode 100644 prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.md create mode 100644 prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-html-banner.md create mode 100644 prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-banner.md create mode 100644 prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-video.md create mode 100644 prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat-interstitial.md create mode 100644 prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat.md create mode 100644 prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-native-in-app.md create mode 100644 prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-native-in-webview.md create mode 100644 prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-rewarded-video.md create mode 100644 prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-video-outstream.md diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 4b5d6df225..deaa1c05f1 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -912,6 +912,22 @@ sectionTitle: subgroup: 3 +- sbSecId: 2 + title: Google Next-Gen SDK Bidding-Only Integration + link: /prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 3 + +- sbSecId: 2 + title: Google Next-Gen SDK Prebid-Rendered Integration + link: /prebid-mobile/modules/rendering/android-sdk-integration-nextgen.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 3 + - sbSecId: 2 title: AdMob link: /prebid-mobile/modules/rendering/android-sdk-integration-admob.html diff --git a/prebid-mobile/modules/rendering/android-sdk-integration-nextgen.md b/prebid-mobile/modules/rendering/android-sdk-integration-nextgen.md new file mode 100644 index 0000000000..4c41742219 --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-integration-nextgen.md @@ -0,0 +1,344 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering Google Next-Gen SDK Integration +description: Prebid Mobile Rendering Modules Google Next-Gen SDK integration +sidebarType: 2 + +--- + +# Prebid SDK Android with the Google Next-Gen SDK Prebid-Rendered Integration Method +{:.no_toc} + +- TOC +{:toc} + +{% include mobile/intro-prebid-rendered.md platform="android" %} + +## Event Handlers + +First, a little bit of setup is needed. + +### Integrate Event Handlers + +The Prebid SDK supplies a set of classes called the 'Next-Gen Event Handlers' that wrap the Next-Gen Ad Views and manage them in the In-App Bidding flow. These classes are provided in the form of a library that can be added to the app via Gradle: + +Root `build.gradle`: + +```text +allprojects { + repositories { + ... + mavenCentral() + ... + } +} +``` + +App module `build.gradle`: + +```text +implementation('org.prebid:prebid-mobile-sdk-next-gen-event-handlers:x.x.x') +``` + +### Initialize the Google Next-Gen Mobile Ads SDK + +Initialize the Next-Gen SDK early in your app lifecycle (e.g., in `Application.onCreate()`): + +```kotlin +val backgroundScope = CoroutineScope(Dispatchers.IO) +backgroundScope.launch { + MobileAds.initialize( + context, + InitializationConfig.Builder("YOUR_APP_ID").build() + ) { + // Initialization complete + } +} +``` + +## AdUnit-Specific Instructions + +This section covers integration details for different ad formats. In each scenario, you'll be asked for a `configId` - this is a key worked out with your Prebid Server provider. It's used at runtime to pull in the bidders and parameters specific to this adunit. Depending on your Prebid Server partner, it may be a UUID or constructed out of parts like an account number and adunit name. + +### Banners + +#### Display Banners + +To integrate the banner ad you need to implement three easy steps: + +```kotlin +// 1. Create a banner custom event handler for the Next-Gen SDK. +val eventHandler = NextGenBannerEventHandler(requireContext(), NEXT_GEN_AD_UNIT_ID, AdSize(WIDTH, HEIGHT)) + +// 2. Create a bannerView instance and provide the Next-Gen event handler +bannerView = BannerView(requireContext(), configId, eventHandler) +// (Optional) set an event listener +bannerView?.setBannerListener(this) + +// Add bannerView to your viewContainer +viewContainer?.addView(bannerView) + +// 3. Execute the loadAd function. +bannerView?.loadAd() +``` + +{% capture warning_note %} +Pay attention that the `loadAd()` should be called on the main thread. +{% endcapture %} +{% include /alerts/alert_warning.html content=warning_note %} + +##### Step 1: Create Event Handler +{:.no_toc} + +Prebid SDK's Next-Gen event handlers are special containers that wrap Next-Gen Ad Views and help to manage collaboration between the Next-Gen SDK and Prebid views. + +**Important:** you should create and use a unique event handler for each ad view. + +To create the event handler you should provide a Next-Gen Ad Unit Id and one or more `AdSize` instances for this ad unit. + +##### Step 2: Create Ad View +{:.no_toc} + +**BannerView** - is the view that will display a particular ad. It should be added to the UI. To create it you should provide: + +- **configId** - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **eventHandler** - the instance of the Next-Gen banner event handler + +Also, you should add the instance of `BannerView` to the UI. + +And assign the listeners for processing ad events. + +##### Step 3: Load the Ad +{:.no_toc} + +Call the `loadAd()` method to make a bid request. + +#### Non-Instream Video +{:.no_toc} + +For **Non-Instream Video** you also need to specify the video placement type of the expected ad: + +```kotlin +bannerView.videoPlacementType = PlacementType.IN_BANNER // or any other available type +``` + +#### Migrating banners from a Bidding-Only integration + +Next-Gen SDK setup: + +1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. +2. Create new Next-Gen SDK ad unit. +3. Setup new [GAM Order](/adops/mobile-rendering-gam-line-item-setup.html) for rendering approach. + +Integration: + +1. Replace the `AdView` with `BannerView` in the UI. +2. Implement the interface `BannerViewListener`. +3. Remove both `AdView` and `BannerAdRequest`. +4. Remove the original `BannerAdUnit`. +5. Follow the instructions to integrate [Banner API](#banners). + +### Interstitials + +To integrate an interstitial ad follow these steps: + +```kotlin +// 1. Create an interstitial custom event handler for the Next-Gen SDK. +val eventHandler = NextGenInterstitialEventHandler(requireContext(), nextGenAdUnitId) + +// 2. Create an interstitialAdUnit instance and provide the Next-Gen event handler +interstitialAdUnit = InterstitialAdUnit(requireContext(), configId, eventHandler) +// (Optional) for multiformat, specify the ad unit formats +// interstitialAdUnit = InterstitialAdUnit(requireContext(), configId, EnumSet.of(AdUnitFormat.BANNER, AdUnitFormat.VIDEO), eventHandler) + +// (Optional) set an event listener +interstitialAdUnit?.setInterstitialAdUnitListener(this) + +// 3. Execute the loadAd function. +interstitialAdUnit?.loadAd() + +//.... + +// 4. After the ad is loaded you can execute the `show` function to trigger ad display +interstitialAdUnit?.show() +``` + +{% capture warning_note %} +Pay attention that the `loadAd()` should be called on the main thread. +{% endcapture %} +{% include /alerts/alert_warning.html content=warning_note %} + +In order to make a `multiformat bid request`, set the respective values into the `adUnitFormats` parameter: + +```kotlin +interstitialAdUnit = InterstitialAdUnit( + requireContext(), + configId, + EnumSet.of(AdUnitFormat.BANNER, AdUnitFormat.VIDEO), + eventHandler) +``` + +#### Step 1: Create Event Handler +{:.no_toc} + +Next-Gen's event handlers are special containers that wrap the Next-Gen Ad Views and help to manage collaboration between the Next-Gen SDK and Prebid views. + +**Important:** you should create and use a unique event handler for each ad view. + +To create an event handler you should provide a Next-Gen Ad Unit ID. + +#### Step 2: Create Interstitial Ad Unit +{:.no_toc} + +**InterstitialAdUnit** - is an object that will load and display a particular ad. To create it you should provide: + +- **configId** - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **minSizePercentage** - specifies the minimum width and height percent an ad may occupy of a device’s screen. +- **eventHandler** - the instance of the Next-Gen interstitial event handler + +Also, you can assign the listeners for processing ad events. + +> **NOTE:** minSizePercentage - plays an important role in a bidding process for display ads. If the provided space is too small demand partners won't respond with bids. + +#### Step 3: Load the Ad +{:.no_toc} + +Call the `loadAd()` method to make a bid request. The ad unit will load an ad and will wait for explicit instructions to display the Interstitial Ad. + +#### Step 4: Show the Ad when it is ready +{:.no_toc} + +The most convenient way to determine if the interstitial ad is ready for displaying is to listen to the listener method: + +```kotlin +override fun onAdLoaded(interstitialAdUnit: InterstitialAdUnit) { + //Ad is ready for display + interstitialAdUnit.show() +} +``` + +#### Migrating interstitials from a Bidding-Only integration + +Next-Gen SDK setup: + +1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. +2. Create a new Next-Gen SDK ad unit. +3. Setup a new [GAM Order](/adops/mobile-rendering-gam-line-item-setup.html) for rendering approach. + +Integration: + +1. Replace the `InterstitialAd` with `InterstitialAdUnit`. +2. Implement the interface for `InterstitialAdUnitListener`. +3. Remove both `InterstitialAd` and `AdRequest`. +4. Follow the instructions to integrate [Interstitial API](#interstitials). + +### Rewarded + +{% include mobile/rewarded-server-side-configuration.md %} + +#### Integration Example + +Displaying the **Rewarded Ad** is the same as displaying an Interstitial Ad, but it adds the ability to handle a reward. To display a Rewarded Ad follow these steps: + +```kotlin +// 1. Create a rewarded custom event handler for the Next-Gen SDK. +val eventHandler = NextGenRewardedEventHandler(requireActivity(), nextGenAdUnitId) + +// 2. Create a rewardedAdUnit instance and provide the Next-Gen event handler +rewardedAdUnit = RewardedAdUnit(requireContext(), configId, eventHandler) + +// You can also set an event listener, this step is optional. +rewardedAdUnit?.setRewardedAdUnitListener(this) + +// 3. Execute the loadAd function. +rewardedAdUnit?.loadAd() + +//... + +// 4. After the ad is loaded you can execute the `show` function to display the ad. +rewardedAdUnit?.show() +``` + +{% capture warning_note %} +Pay attention that the `loadAd()` should be called on the main thread. +{% endcapture %} +{% include /alerts/alert_warning.html content=warning_note %} + +##### Step 1: Create Event Handler +{:.no_toc} + +Next-Gen's event handlers are special containers that wrap the Next-Gen Ad Views and help to manage collaboration between the Next-Gen SDK and Prebid views. + +**Important:** you should create and use a unique event handler for each ad view. + +To create an event handler you should provide a Next-Gen Ad Unit ID. + +##### Step 2: Create Rewarded Ad Unit +{:.no_toc} + +**RewardedAdUnit** - is an object that will load and display the particular ad. To create it you should provide: + +- **configId** - is an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **eventHandler** - is the instance of the Next-Gen rewarded event handler + +You can also assign the listener for processing ad events. + +##### Step 3: Load the Ad +{:.no_toc} + +Call the `loadAd()` method to make a bid request. The ad unit will load an ad and will wait for explicit instructions to display the Rewarded Ad. + +##### Step 4: Display the Ad when it is ready +{:.no_toc} + +The most convenient way to determine if the ad is ready for displaying is to listen for the listener method: + +```kotlin +override fun onAdLoaded(rewardedAdUnit: RewardedAdUnit) { + //Ad is ready for display + rewardedAdUnit.show() +} +``` + +##### Step 5: Handle a reward +{:.no_toc} + +Handle earning the reward in the appropriate method. Important: a reward can be null. + +```kotlin +override fun onUserEarnedReward(rewardedAdUnit: RewardedAdUnit?, reward: Reward?) { + if (reward != null) { + val rewardType = reward.type + val rewardCount = reward.count + val rewardExt = reward.ext + // Process the reward + } +} +``` + +#### Migrating rewarded video from a Bidding-Only integration +{:.no_toc} + +Next-Gen SDK setup: + +1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. +2. Create a new Next-Gen SDK ad unit. +3. Setup a new [GAM Order](/adops/mobile-rendering-gam-line-item-setup.html) for rendering approach. + +Integration: + +1. Replace the `RewardedAd` with `RewardedAdUnit`. +2. Implement the interface for `RewardedAdUnitListener`. +3. Remove the original `RewardedVideoAdUnit`. +4. Follow the instructions to integrate [Rewarded API](#rewarded). + +## Additional Ad Unit Configuration + +{% include mobile/rendering-adunit-config-android.md %} + +## Further Reading + +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK Android Integration](/prebid-mobile/pbm-api/android/code-integration-android.html) +- [Prebid SDK Android Global Parameters](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) \ No newline at end of file diff --git a/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.md b/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.md new file mode 100644 index 0000000000..a34e534f77 --- /dev/null +++ b/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.md @@ -0,0 +1,66 @@ +--- +layout: page_v2 +title: Prebid Mobile - Next-Gen SDK Bidding-Only Integration - Android +description: Integration of Prebid SDK Android with Google Next-Gen SDK using the 'Bidding-Only' integration +sidebarType: 2 +--- + +# Prebid SDK Android with the Next-Gen SDK Bidding-Only Integration Method +{:.no_toc} + +- TOC +{:toc} + +{% include mobile/intro-bidding-only.md platform='android' %} + +## AdUnit-Specific instructions + +This section describes the integration details for different ad formats. In each scenario, you'll be asked for a `configId` - this is a key established in conjunction with your Prebid Server provider. It's used at runtime to pull in the bidders and parameters specific to this adunit. Depending on your Prebid Server partner, it may be a UUID or constructed out of parts like an account number and adunit name. + +### [Format: HTML Banner](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-html-banner.html) + +### [Format: Interstitial Banner](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-banner.html) + +### [Format: Non-Instream Video](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-video-outstream.html) + +### [Format: Interstitial Video](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-video.html) + +### [Format: Rewarded Video Ad](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-rewarded-video.html) + +### [Format: Native In-App](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-native-in-app.html) + +### [Format: Native In-Webview](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-native-in-webview.html) + +### [Format: Multiformat (Banner+Video+InApp Native)](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat.html) + +### [Format: Multiformat Interstitial (Banner+Video)](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat-interstitial.html) + +## Additional Ad Unit Configuration + +{% include mobile/adunit-config-android.md %} + +### Impression tracking + +In the Bidding-Only integration scenario, the Prebid SDK is responsible for tracking events for banner ads, like `burl`, `imp`, and `win`. The disadvantage of this approach is that the SDK doesn't have reliable information about the viewability of the WebView. As a result, impression tracking happens at the rendering stage of the ad. Or, if MRAID is supported, once the `viewableChange` event is fired. It leads to big discrepancies since the "1 pixel in view" requirement is not met. + +To activate impression tracking for the banner ad unit - use the `activatePrebidImpressionTracker(adView)` method. The `adView` parameter should be an instance of the Next-Gen SDK `AdView`: + +```kotlin +adUnit.activatePrebidImpressionTracker(adView) +adUnit.fetchDemand(adRequestBuilder) { ... } +``` + +For activation for the interstitial ad unit, you should call `activateInterstitialPrebidImpressionTracker()`: + +```kotlin +adUnit = InterstitialAdUnit(CONFIG_ID, WIDTH, HEIGHT) +adUnit.activateInterstitialPrebidImpressionTracker() +``` + +After the invocation of `activateInterstitialPrebidImpressionTracker()`, the Prebid SDK will start analyzing the View Hierarchy and track the viewability of the ad view. Once the ad view is viewable for the user for at least 1 pixel for 1 second, the SDK will track an impression event for the presented ad. The SDK will stop analyzing the View Hierarchy once the caller object is destroyed. + +## Further Reading + +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK Android Integration](/prebid-mobile/pbm-api/android/code-integration-android.html) +- [Prebid SDK Android Global Parameters](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) diff --git a/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-html-banner.md b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-html-banner.md new file mode 100644 index 0000000000..a07b6d3280 --- /dev/null +++ b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-html-banner.md @@ -0,0 +1,138 @@ +--- +layout: page_v2 +title: Android Next-Gen SDK Bidding-Only Integration - HTML Banner +description: Android Next-Gen SDK Bidding-Only Integration - HTML Banner +sidebarType: 2 +--- + +# Android Next-Gen SDK Bidding-Only Integration - HTML Banner + +Back to [Bidding-Only Integration](/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html#adunit-specific-instructions) + +Starting with Prebid Mobile `2.1.0` you can use `BannerAdUnit` to bid over the banner and/or video demand. The default ad format is `BANNER`. To customize the bidding format, specify the ad formats in the `BannerAdUnit` constructor. + +Integration example: + +```kotlin +private fun createAd() { + // 1. Create BannerAdUnit + adUnit = BannerAdUnit(CONFIG_ID, WIDTH, HEIGHT) + adUnit?.setAutoRefreshInterval(refreshTimeSeconds) + + // 2. Configure banner parameters + val parameters = BannerParameters() + parameters.api = listOf(Signals.Api.MRAID_3, Signals.Api.OMID_1) + adUnit?.bannerParameters = parameters + + // 3. Create Next-Gen SDK AdView + val adView = AdView(this) + val adSize = AdSize(WIDTH, HEIGHT) + adWrapperView.addView(adView) + + // 4. Build the Next-Gen SDK ad request + val adRequestBuilder = BannerAdRequest.Builder(AD_UNIT_ID, adSize) + + // 5. Make a bid request to Prebid Server + adUnit?.fetchDemand(adRequestBuilder) { + + // 6. Load Next-Gen Ad + adView.loadAd(adRequestBuilder.build(), createAdLoadCallback(adView)) + } +} +``` + +Prebid SDK can be thought of an OpenRTB request synthesizer. OpenRTB does not have a notion of adaptive banners, but it has a notion of several banner sizes / formats in one request. So an adaptive banner may be represented as a request containing several banner sizes, e.g. a fixed width that equals the size of the screen and several different heights. The examples here deal with a single ad size, but more can be added via BannerParameters.adSizes array. + +It may be necessary to resize the banner view according to the creative size when multiple ad sizes are supported. This logic is not needed for a single-size banner: + +Next-Gen SDK ad load callback: + +```kotlin +private fun createAdLoadCallback(adView: AdView): AdLoadCallback { + return object : AdLoadCallback() { + override fun onAdLoaded(ad: BannerAd) { + super.onAdLoaded(ad) + + // 7. Resize ad view if needed + AdViewUtils.findPrebidCreativeSize(adView, object : AdViewUtils.PbFindSizeListener { + override fun success(width: Int, height: Int) { + adView.resize(AdSize(width, height)) + } + + override fun failure(error: PbFindSizeError) {} + }) + + ad.adEventCallback = object : BannerAdEventCallback { + override fun onAdClicked() { + super.onAdClicked() + } + override fun onAdImpression() { + super.onAdImpression() + } + } + } + + override fun onAdFailedToLoad(adError: LoadAdError) { + super.onAdFailedToLoad(adError) + Log.e(TAG, "Ad failed to load: $adError") + } + } +} +``` + +Notes: + +1. In case you use a single-size banner (as opposed to multi-size), i.e. 300x250 - you don't need to call `AdViewUtils.findPrebidCreativeSize` because you already know the size of the creative. However you still need to call `adView.resize()` because the creative has a 1x1 size by default and without this call it will be rendered as a pixel. +2. Make sure you properly process all possible cases in the `AdViewUtils.findPrebidCreativeSize` callbacks (both success and failure). Sometimes you might not get the size of the creative (or a failure callback) - it simply means that this is not a Prebid creative. It means that you still need to render the creative, but you most likely don't need to resize it. + +## Step 1: Create a BannerAdUnit +{:.no_toc} + +Initialize the `BannerAdUnit` with properties: + +- `configId` - an ID of the Stored Impression on the Prebid Server +- `width` - the width of the ad unit which will be used in the bid request. +- `height` - the height of the ad unit which will be used in the bid request. + +## Step 2: Configure banner parameters +{:.no_toc} + +{% include mobile/banner-params.md %} + +## Step 3: Create a Next-Gen SDK AdView +{:.no_toc} + +Follow the [Next-Gen SDK documentation](https://developers.google.com/admob/android/next-gen/banner) to integrate a banner ad unit. + +## Step 4: Build the Ad Request +{:.no_toc} + +Create a `BannerAdRequest.Builder` with the Next-Gen SDK Ad Unit ID and the desired `AdSize`. + +## Step 5: Make a bid request +{:.no_toc} + +The `fetchDemand` method makes a bid request to the Prebid Server. You should provide a `BannerAdRequest.Builder` object to this method. Prebid SDK will set the targeting keywords of the winning bid into the provided object. Eventually you should use this object to make an ad request to the Next-Gen SDK. + +## Step 6: Load an Ad +{:.no_toc} + +You should now request the ad from the Next-Gen SDK. If the `BannerAdRequest` contains targeting keywords, the respective Prebid line item will be returned from GAM, and the Next-Gen SDK will render its creative. + +Be sure that you make the ad request with the same `BannerAdRequest.Builder` object that you passed to the `fetchDemand` method. Otherwise, the ad request won't contain the targeting keywords, and Prebid's ad won't ever be displayed. + +## Step 7: Adjust the ad view size +{:.no_toc} + +Once an app receives a signal that an ad is loaded, you should use the method `AdViewUtils.findPrebidCreativeSize` to verify whether it's Prebid's ad and resize the ad slot respectively to the creative's properties. + +Notes: + +1. In case you use a single-size banner (as opposed to multi-size), e.g. 300x250 - you don't need to call `AdViewUtils.findPrebidCreativeSize` because you already know the size of the creative. However you still need to call `adView.resize()` because the creative has a 1x1 size by default and without this call it will be rendered as a pixel. +2. Make sure you properly process all possible cases in the `AdViewUtils.findPrebidCreativeSize` callbacks (both success and failure). Sometimes you might not get the size of the creative (or a failure callback) - it simply means that this is not a Prebid creative. It means that you still need to render the creative, but you most likely don't need to resize it. + +## Further Reading + +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK Android integration](/prebid-mobile/pbm-api/android/code-integration-android.html) +- [Prebid SDK Global Parameters - Android](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) diff --git a/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-banner.md b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-banner.md new file mode 100644 index 0000000000..aec7d2a201 --- /dev/null +++ b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-banner.md @@ -0,0 +1,88 @@ +--- +layout: page_v2 +title: Android Next-Gen SDK Bidding-Only Integration - Interstitial Banner +description: Android Next-Gen SDK Bidding-Only Integration - Interstitial Banner +sidebarType: 2 +--- + +# Android Next-Gen SDK Bidding-Only Integration - Interstitial Banner + +Back to [Bidding-Only Integration](/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html#adunit-specific-instructions) + +Starting with Prebid Mobile `2.1.0` you can use `InterstitialAdUnit` to bid over the banner and/or video demand. The default ad format is `BANNER`. To customize the bidding format, specify the ad formats in the `InterstitialAdUnit` constructor. + +Integration example: + +```kotlin +private fun createAd() { + // 1. Create InterstitialAdUnit + // minWidthPercent=80, minHeightPercent=60 + adUnit = InterstitialAdUnit(CONFIG_ID, 80, 60) + + // 2. Build the Next-Gen SDK ad request + val request = AdRequest.Builder(AD_UNIT_ID) + adUnit?.fetchDemand(request) { + + // 3. Load a Next-Gen interstitial ad + InterstitialAd.load( + request.build(), + createListener() + ) + } +} +``` + +You also need to implement `AdLoadCallback` in order to track the ad readiness: + +```kotlin +private fun createListener(): AdLoadCallback { + return object : AdLoadCallback() { + override fun onAdLoaded(ad: InterstitialAd) { + super.onAdLoaded(ad) + + // 4. Present the interstitial ad + ad.show(this@Activity) + } + + override fun onAdFailedToLoad(adError: LoadAdError) { + super.onAdFailedToLoad(adError) + Log.e(TAG, "Ad failed to load: $adError") + } + } +} +``` + +## Step 1: Create an InterstitialAdUnit +{:.no_toc} + +Initialize the Interstitial Ad Unit with properties: + +- `configId` - an ID of Stored Impression on the Prebid Server +- `minWidthPerc`: Optional parameter to specify the minimum width percent an ad may occupy of a device's screen. Support in SDK version 1.2+ +- `minHeightPrec`: Optional parameter to specify the minimum height percent an ad may occupy of a device's screen. Support in SDK version 1.2+ + +{: .alert.alert-info :} +Here's how min size percentages work. If the adunit size is 1x1, Prebid Server uses the screen width/height and the minWidthPerc/minHeightPerc to generate a list of ad sizes from a [predefined list](https://github.com/prebid/prebid-server/blob/master/config/interstitial.go). It selects the first 10 sizes that fall within the max size and minimum percentage size. All the interstitial parameters will still be passed to the bidders, allowing them to use their own size matching algorithms if they prefer. If you'd prefer to just define the size list, that's ok too - just set the sizes and don't define minWidthPerc/minHeightPerc. + +## Step 2: Make a bid request +{:.no_toc} + +The `fetchDemand` method makes a bid request to the Prebid Server. You should provide an `AdRequest.Builder` object to this method so Prebid SDK sets the targeting keywords of the winning bid for future ad requests. + +## Step 3: Load a Next-Gen interstitial ad +{:.no_toc} + +You should now request the ad from the Next-Gen SDK. If the `AdRequest` contains targeting keywords, the respective Prebid line item will be returned from GAM, and the Next-Gen SDK will render its creative. + +Be sure that you make the ad request with the same `AdRequest.Builder` object that you passed to the `fetchDemand` method. Otherwise, the ad request won't contain targeting keywords, and Prebid's ad won't ever be displayed. + +## Step 4: Present the interstitial ad +{:.no_toc} + +Follow the [Next-Gen SDK guide](https://developers.google.com/ad-manager/mobile-ads-sdk/android/interstitial#display_the_ad) to display an interstitial ad right after receiving it or later in natural pauses in the flow of an app. + +## Further Reading + +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK Android integration](/prebid-mobile/pbm-api/android/code-integration-android.html) +- [Prebid SDK Global Parameters - Android](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) diff --git a/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-video.md b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-video.md new file mode 100644 index 0000000000..f74a8c8612 --- /dev/null +++ b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-video.md @@ -0,0 +1,116 @@ +--- +layout: page_v2 +title: Android Next-Gen SDK Bidding-Only Integration - Interstitial Video +description: Android Next-Gen SDK Bidding-Only Integration - Interstitial Video +sidebarType: 2 +--- + +# Android Next-Gen SDK Bidding-Only Integration - Interstitial Video + +Back to [Bidding-Only Integration](/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html#adunit-specific-instructions) + +Starting with Prebid Mobile `2.1.0` you can use `InterstitialAdUnit` to bid for the banner and/or video demand. The default ad format is `BANNER`. To customize the bidding format, specify the ad formats in the `InterstitialAdUnit` constructor. + +Integration Example: + +```kotlin +private fun createAd() { + + // 1. Create InterstitialAdUnit with video format + adUnit = InterstitialAdUnit(CONFIG_ID, EnumSet.of(AdUnitFormat.VIDEO)) + + // 2. Configure video ad unit + adUnit?.videoParameters = configureVideoParameters() + + // 3. Make a bid request to Prebid Server + val requestBuilder = AdRequest.Builder(AD_UNIT_ID) + adUnit?.fetchDemand(requestBuilder) { + + // 4. Load a Next-Gen ad + InterstitialAd.load( + requestBuilder.build(), + createAdListener() + ) + } +} +``` + +Configuration function: + +```kotlin +private fun configureVideoParameters(): VideoParameters { + return VideoParameters(listOf("video/x-flv", "video/mp4")).apply { + placement = Signals.Placement.Interstitial + + api = listOf( + Signals.Api.VPAID_1, + Signals.Api.VPAID_2 + ) + + maxBitrate = 1500 + minBitrate = 300 + maxDuration = 30 + minDuration = 5 + playbackMethod = listOf(Signals.PlaybackMethod.AutoPlaySoundOn) + protocols = listOf( + Signals.Protocols.VAST_2_0 + ) + } +} +``` + +Next-Gen SDK ad listener: + +```kotlin +private fun createAdListener(): AdLoadCallback { + return object : AdLoadCallback() { + override fun onAdLoaded(ad: InterstitialAd) { + super.onAdLoaded(ad) + + // 5. Display an interstitial ad + ad.show(this@Activity) + } + + override fun onAdFailedToLoad(adError: LoadAdError) { + super.onAdFailedToLoad(adError) + Log.e(TAG, "Ad failed to load: $adError") + } + } +} +``` + +## Step 1: Create an Ad Unit +{:.no_toc} + +Initialize the `InterstitialAdUnit` with the following properties: + +- `configId` - an ID of Stored Impression on the Prebid Server +- `adUnitFormats` - `AdUnitFormat.VIDEO` for a video ad + +## Step 2: Configure video parameters +{:.no_toc} + +{% include mobile/video-params.md %} + +## Step 3: Make a bid request +{:.no_toc} + +The `fetchDemand` method makes a bid request to the Prebid Server. You should provide an `AdRequest.Builder` object to this method so Prebid SDK sets the targeting keywords of the winning bid for future ad requests. + +## Step 4: Load a Next-Gen interstitial ad +{:.no_toc} + +Now you should request the ad from the Next-Gen SDK. If the `AdRequest` contains targeting keywords, the respective Prebid line item will be returned from GAM, and the Next-Gen SDK will render its creative. + +Be sure that you make the ad request with the same `AdRequest.Builder` object that you passed to the `fetchDemand` method. Otherwise, the ad request won't contain targeting keywords, and Prebid's ad won't ever be displayed. + +## Step 5: Present the interstitial ad +{:.no_toc} + +Follow the [Next-Gen SDK guide](https://developers.google.com/admob/android/next-gen/interstitial#show_the_ad) to display an interstitial ad right after receiving it or later in natural pauses in the flow of an app. + +## Further Reading + +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK Android integration](/prebid-mobile/pbm-api/android/code-integration-android.html) +- [Prebid SDK Global Parameters - Android](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) diff --git a/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat-interstitial.md b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat-interstitial.md new file mode 100644 index 0000000000..56018e26a0 --- /dev/null +++ b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat-interstitial.md @@ -0,0 +1,81 @@ +--- +layout: page_v2 +title: Android Next-Gen SDK Bidding-Only Integration - Multiformat Interstitial Banner+Video +description: Android Next-Gen SDK Bidding-Only Integration - Multiformat Interstitial Banner+Video +sidebarType: 2 +--- + +# Android Next-Gen SDK Bidding-Only Integration - Multiformat Interstitial Banner+Video + +Back to [Bidding-Only Integration](/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html#adunit-specific-instructions) + +Integration example: + +```kotlin +// 1. Create InterstitialAdUnit +adUnit = InterstitialAdUnit(configId, EnumSet.of(AdUnitFormat.BANNER, AdUnitFormat.VIDEO)) +adUnit?.setMinSizePercentage(80, 60) +adUnit?.adUnitConfig.adSize = new AdSize(1, 1); +adUnit?.videoParameters = VideoParameters(listOf("video/mp4")) + +// 2. Make a bid request to Prebid Server +val requestBuilder = AdRequest.Builder(AD_UNIT_ID) +adUnit?.fetchDemand(requestBuilder) { + + // 3. Load a Next-Gen interstitial ad + InterstitialAd.load( + requestBuilder.build(), + createListener() + ) +} +``` + +## Step 1: Create an Ad Unit +{:.no_toc} + +Initialize the `InterstitialAdUnit` with the following properties: + +- `configId` - an ID of Stored Impression on the Prebid Server +- `adUnitFormats` - ad unit formats for the current ad unit. + +{: .alert.alert-info :} +Here's how min size percentages work. If the adunit size is 1x1, Prebid Server takes the screen width/height and the minWidthPerc/minHeightPerc as a size range, generating a list of ad sizes from a [predefined list](https://github.com/prebid/prebid-server/blob/master/config/interstitial.go). It selects the first 10 sizes that fall within the max size and minimum percentage size. All the interstitial parameters will still be passed to the bidders, allowing them to use their own size matching algorithms if they prefer. If you'd prefer to just define the size list, that's ok too - just set the sizes and don't define minWidthPerc/minHeightPerc. + +## Step 2: Set ad formats +{:.no_toc} + +For multiformat ad unit, you must set both banner and video ad formats. + +## Step 3: Configure parameters +{:.no_toc} + +### Banner parameters + +{% include mobile/banner-params.md %} + +### Video parameters + +{% include mobile/video-params.md %} + +## Step 4: Make a bid request +{:.no_toc} + +The `fetchDemand` method makes a bid request to the Prebid Server. You should provide an `AdRequest.Builder` object to this method so Prebid SDK sets the targeting keywords of the winning bid for future ad requests. + +## Step 5: Load a Next-Gen interstitial ad +{:.no_toc} + +You should now request the ad from the Next-Gen SDK. If the `AdRequest` contains targeting keywords, the respective Prebid line item will be returned from GAM, and the Next-Gen SDK will render its creative. + +Be sure that you make the ad request with the same `AdRequest.Builder` object that you passed to the `fetchDemand` method. Otherwise the ad request won't contain targeting keywords and Prebid's ad won't ever be displayed. + +## Step 6: Present the interstitial ad +{:.no_toc} + +Follow the [Next-Gen SDK guide](https://developers.google.com/admob/android/next-gen/interstitial#show_the_ad) to display an interstitial ad right after receiving it or later in natural pauses in the flow of an app. + +## Further Reading + +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK Android integration](/prebid-mobile/pbm-api/android/code-integration-android.html) +- [Prebid SDK Global Parameters - Android](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) diff --git a/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat.md b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat.md new file mode 100644 index 0000000000..26793b3003 --- /dev/null +++ b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat.md @@ -0,0 +1,267 @@ +--- +layout: page_v2 +title: Android Next-Gen SDK Bidding-Only Integration - Multiformat Banner+Video+InAppNative +description: Android Next-Gen SDK Bidding-Only Integration - Multiformat Banner+Video+InAppNative +sidebarType: 2 +--- + +# Android Next-Gen SDK Bidding-Only Integration - Multiformat Banner+Video+InAppNative + +Back to [Bidding-Only Integration](/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html#adunit-specific-instructions) + +Starting with version `2.1.5` Prebid SDK supports the fully multiformat ad unit. It allows to run bid requests with any combination of `banner`, `video`, and `native` formats. + +The following code demonstrates the integration of multiformat ad unit. + +```kotlin +private fun createAd() { + // random() only for test cases, in production use only one config id + val configId = listOf(CONFIG_ID_BANNER, CONFIG_ID_VIDEO, CONFIG_ID_NATIVE).random() + + // Step 1: Create a PrebidAdUnit + prebidAdUnit = PrebidAdUnit(configId) + + // Step 2: Create PrebidRequest + val prebidRequest = PrebidRequest() + + // Step 3: Setup the parameters + prebidRequest.setBannerParameters(createBannerParameters()) + prebidRequest.setVideoParameters(createVideoParameters()) + prebidRequest.setNativeParameters(createNativeParameters()) + + // Step 4: Make a bid request + val requestBuilder = NativeAdRequest.Builder( + AD_UNIT_ID, + listOf(NativeAd.NativeAdType.NATIVE, NativeAd.NativeAdType.CUSTOM_NATIVE, NativeAd.NativeAdType.BANNER) + ).setCustomFormatIds(listOf(CUSTOM_FORMAT_ID)) + .setAdSizes(listOf(AdSize.BANNER, AdSize.MEDIUM_RECTANGLE)) + prebidAdUnit?.fetchDemand(requestBuilder, prebidRequest) { + + // Step 5: Load an Ad + loadAd(requestBuilder.build()) + } +} + +private fun createBannerParameters(): BannerParameters { + val parameters = BannerParameters() + parameters.api = listOf(Signals.Api.MRAID_3, Signals.Api.OMID_1) + + return parameters +} + +private fun createVideoParameters(): VideoParameters { + return VideoParameters(listOf("video/mp4")) +} + +private fun createNativeParameters(): NativeParameters { + val assets = mutableListOf() + + val title = NativeTitleAsset() + title.setLength(90) + title.isRequired = true + assets.add(title) + + val icon = NativeImageAsset(20, 20, 20, 20) + icon.imageType = NativeImageAsset.IMAGE_TYPE.ICON + icon.isRequired = true + assets.add(icon) + + val image = NativeImageAsset(200, 200, 200, 250) + image.imageType = NativeImageAsset.IMAGE_TYPE.MAIN + image.isRequired = true + assets.add(image) + + val data = NativeDataAsset() + data.len = 90 + data.dataType = NativeDataAsset.DATA_TYPE.SPONSORED + data.isRequired = true + assets.add(data) + + val body = NativeDataAsset() + body.isRequired = true + body.dataType = NativeDataAsset.DATA_TYPE.DESC + assets.add(body) + + val cta = NativeDataAsset() + cta.isRequired = true + cta.dataType = NativeDataAsset.DATA_TYPE.CTATEXT + assets.add(cta) + + val nativeParameters = NativeParameters(assets) + nativeParameters.addEventTracker( + NativeEventTracker( + NativeEventTracker.EVENT_TYPE.IMPRESSION, + arrayListOf(NativeEventTracker.EVENT_TRACKING_METHOD.IMAGE) + ) + ) + nativeParameters.setContextType(NativeAdUnit.CONTEXT_TYPE.SOCIAL_CENTRIC) + nativeParameters.setPlacementType(NativeAdUnit.PLACEMENTTYPE.CONTENT_FEED) + nativeParameters.setContextSubType(NativeAdUnit.CONTEXTSUBTYPE.GENERAL_SOCIAL) + + return nativeParameters +} +``` + +Load the ad and process the multiformat response using `NativeAdLoader`: + +```kotlin +private fun loadAd(request: NativeAdRequest) { + val adCallback = object : NativeAdLoaderCallback { + override fun onBannerAdLoaded(bannerAd: BannerAd) { + super.onBannerAdLoaded(bannerAd) + showBannerAd(bannerAd) + } + + override fun onNativeAdLoaded(nativeAd: NativeAd) { + super.onNativeAdLoaded(nativeAd) + showNativeAd(nativeAd, adWrapperView) + } + + override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) { + super.onCustomNativeAdLoaded(customNativeAd) + showPrebidNativeAd(customNativeAd) + } + + override fun onAdFailedToLoad(adError: LoadAdError) { + super.onAdFailedToLoad(adError) + Log.e(TAG, "Ad failed: $adError") + } + } + NativeAdLoader.load(request, adCallback) +} +``` + +The methods managing the Prebid and Next-Gen SDK ads: + +```kotlin +private fun showBannerAd(bannerAd: BannerAd) { + val adView = AdView(this) + adView.registerBannerAd(bannerAd, this) + adWrapperView.addView(adView) + AdViewUtils.findPrebidCreativeSize(adView, object : AdViewUtils.PbFindSizeListener { + override fun success(width: Int, height: Int) { + adView.resize(AdSize(width, height)) + } + + override fun failure(error: PbFindSizeError) {} + }) +} + +private fun showNativeAd(ad: NativeAd, wrapper: ViewGroup) { + val nativeContainer: NativeAdView = + View.inflate(wrapper.context, R.layout.layout_native, null) as NativeAdView + + val icon = nativeContainer.findViewById(R.id.imgIcon) + val iconUrl = ad.icon?.uri?.toString() + if (iconUrl != null) { + ImageUtils.download(iconUrl, icon) + } + + val title = nativeContainer.findViewById(R.id.tvTitle) + title.text = ad.headline + + val image = nativeContainer.findViewById(R.id.imgImage) + val imageUrl = ad.image?.uri?.toString() + if (imageUrl != null) { + ImageUtils.download(imageUrl, image) + } + + val description = nativeContainer.findViewById(R.id.tvDesc) + description.text = ad.body + + val cta = nativeContainer.findViewById