diff --git a/.markdownlint.json b/.markdownlint.json index ef360a2bf6..2db5196efd 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -6,5 +6,6 @@ "MD024": false, "MD025": false, "MD033": false, - "MD036": false + "MD036": false, + "MD058": false } 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/_includes/mobile/intro-nextgen-bidding-only.md b/_includes/mobile/intro-nextgen-bidding-only.md new file mode 100644 index 0000000000..6d1476f440 --- /dev/null +++ b/_includes/mobile/intro-nextgen-bidding-only.md @@ -0,0 +1,115 @@ +## Overview + +This how-to guide covers the original approach for integrating the Prebid SDK into your app with the Google Next-Gen Mobile Ads SDK. It utilizes: + +- **Prebid SDK** and **Prebid server** to handle the bidding and auction process. +- **GAM** and the **Google Next-Gen Mobile Ads SDK** manage the ad inventory and select the winning ad to display. +- **Prebid Universal Creative** renders display ads when a Prebid bid wins. +- **Next-Gen SDK** renders banner and non-instream ads when a Prebid bid wins. + +If you do not have the Next-Gen Mobile Ads SDK in the app, refer to the [Google Integration Documentation](https://developers.google.com/admob/{{include.platform}}/next-gen/quick-start). + +### Alternative Approaches + +Another way to integrate Next-Gen SDK into your app is with the [Prebid-Rendered Integration](/prebid-mobile/modules/rendering/{{include.platform}}-sdk-integration-nextgen.html). + +Tradeoffs between these integration approaches: + +{: .table .table-bordered .table-striped } +| Aspect | Bidding-Only Integration | Prebid-Rendered Integration | +| --- |:---:|:---:| +| App code has direct access to bids | check | | +| Support for MRAID 3.0 | | check | +| Support for SKAdnetwork | | check | +| Loads data from Prebid Cache | check | | +| Triggers billing and Notice URLs | check | | +| Supports Third Party Rendering libraries | | check | + +**Notes:** + +- On one hand, using Prebid Cache reduces the amount of data that must be sent to the mobile device -- the body of the creative does not need to be transmitted for bids. On the other hand, though, when a bid wins in the ad server, the body of the creative must be retrieved from the cache. +- It is possible to mix-and-match implementations within an app. e.g. you could implement instream video with the Bidding-Only approach and other adunits with Prebid-Rendered. + +### Prerequisites + +The Next-Gen SDK Bidding-Only Integration method assumes that you have the following components: + +- **Google Ad Manager Account** - A GAM account allows you to manage and serve ads within your mobile app. Within this account you'll need to configure your inventory and create orders for serving ads within your app. This involves defining ad units (spaces within your app where ads will be displayed) and setting up orders and line items to deliver ads to those units. See [Prebid's AdOps Guide](/adops/before-you-start.html) for more information. +- **Google Next-Gen Mobile Ads SDK** - This refers to the software development kit provided by Google. You need to ensure that you have the latest version of the Next-Gen Mobile Ads SDK supported by Prebid SDK. This SDK integration is necessary to communicate with the ad server and display ads in your app. +- **Prebid SDK** - You will need the latest version of the Prebid Mobile SDK for either [Android](/prebid-mobile/pbm-api/android/code-integration-android.html) or [iOS](/prebid-mobile/pbm-api/ios/code-integration-ios.html). +- **Prebid Universal Creative** - This needs to be hosted on a CDN and loaded from the creative in GAM as detailed in the [AdOps GAM creative reference](/adops/gam-creative-banner-sbs.html#prebid-universal-creative). +- **Prebid Server** - You will need a cluster of servers running [Prebid Server](/prebid-server/use-cases/pbs-sdk.html). You can set up your own Prebid Server or work with a [Prebid Server managed service](https://prebid.org/managed-services/). Prebid Server provides you with the following: + - Configuration storage - rather than hardcoding all the details of your current business arrangements in the app, Prebid Server stores which bidders you're currently working with, their inventory details, and other settings that can be changed without updating your app. + - Server-side auction - the server will make the connections to multiple auction bidding partners so the app doesn't have to. + - Creative caching - Prebid Cache stores the creatives until the app needs to render them, reducing the auction response bandwidth. + - Privacy regulation tools - the server can help your legal team meet different regulatory needs in different jurisdictions by configuring various protocols and anonyimization activities. + +## How it Works + +Here's how the ad bidding-auction-rendering process works in this integration scenario. + +![Next-Gen Bidding Only Integration Details](/assets/images/prebid-mobile/mobile-details-gam-bidding-only.png) + +1. Prebid SDK calls Prebid Server which supplies one or more bids. +1. PBSDK adds targeting values to Next-Gen SDK. +1. Next-Gen SDK calls GAM, which makes the ad decision. +1. If a 3rd party HTML creative is chosen (banner or interstitial): + 1. Next-Gen SDK writes the HTML to a webview, loading the Prebid Universal Creative (PUC). + 1. The PUC loads the winning creative from Prebid Cache. + 1. The PUC writes this creative into an iframe and hits all the tracking strings: Prebid win URL, billing url (burl), and notice url (nurl). + 1. If MRAID is available, it is used to consider the view state before hitting the burl. +1. If a video VastUrl creative is chosen: + 1. The Next-Gen SDK uses the platform video player which loads the VAST from Prebid Cache. + 1. It then starts playing the VAST, hitting the embedded Impression tags when appropriate. +1. If an In-App Native format is chosen: + 1. Next-Gen SDK delegates the rendering of native to the App and PBSDK when a special signal is specified. + 1. The app code gets the native assets from PBSDK. The app is coded to render the ad. + 1. PBSDK fires the eventtrackers when appropriate. + 1. The PBS win event is fired. +1. The Next-Gen SDK handles Open Measurement SDK interactions. + +## Major Integration Steps + +Assuming your app already has AdUnits integrated with the Next-Gen Mobile Ads SDK, the technical implementation of Prebid mobile into your app will involve these major steps: + +1. [Initialize the Prebid SDK](/prebid-mobile/pbm-api/{{include.platform}}/code-integration-{{include.platform}}.html) - create a connection to your Prebid Server. +2. [Set Global Parameters](/prebid-mobile/pbm-api/{{include.platform}}/pbm-targeting-{{include.platform}}.html) - let bidders know important data about the page, privacy consent, and other settings. +3. Work with your Prebid Server team to create the adunit configIds that will be used in the app. +4. Set up GAM orders, line items, and creatives. See [AdOps guidance](#ad-operations-guidance) +5. Link Prebid AdUnit code to your Next-Gen SDK AdUnits - for any adunits that your business team wants to connect to Prebid with the configIds generated in Step 3. See the [adunit-specific instructions](#adunit-specific-instructions) below. + +## Ad Operations Guidance + +The Ad Operations team will need to create line items in GAM. The creatives used depend on which media formats your adunits utilize. + +{: .table .table-bordered .table-striped } +| AdUnit Format | Line Item Targeting | Creative Type | Prebid Cache? | Ad Ops Details | +| --- | --- | --- | --- | --- | +| HTML banner, interstitial banner | hb_pb
hb_format=banner | 3rd party HTML that loads the [PUC](/overview/prebid-universal-creative.html) | yes | [link](/adops/gam-creative-banner-sbs.html) | +| Video (instream, non-instream, interstitial) | hb_pb
hb_format=video
inventoryType in (instream, mobile app) | VastUrl pointing to Prebid Cache | yes | [link](/adops/setting-up-prebid-video-in-dfp.html) | +| Rewarded Video | hb_pb
hb_format=video
inventoryType in (instream, mobile app)
rewarded adunits | VastUrl pointing to Prebid Cache | yes | [link](/adops/setting-up-prebid-video-in-dfp.html) | +| In-app native | hb_pb
hb_format=native | GAM native | no | [link](/adops/gam-native.html#create-a-new-native-creative) | +| In-Webview native | hb_pb
hb_format=native | 3rd party HTML that loads the native-trk script. | yes | [link](/adops/gam-native.html) | + +Notes: + +- You may need up to 4 sets of line items to support Prebid Mobile depending on adunit types. If you also run Prebid.js or AMP, please see [line item considerations](/adops/line-item-creation.html) for more information. +- Discuss the Prebid Cache column with the Prebid Server team. They can set up the "top-level stored request" for your account to cache or not cache requests as needed. + +### Rendering and Tracking + +This information may be useful when comparing data across various reporting systems: + +{: .table .table-bordered .table-striped } +| Scenario | PUC | VastUrl Creative | GAM Native Creative | +| --- | --- | --- | --- | +| Rendering Method | PUC in iframe | Next-Gen SDK player | App code with data from PBSDK | +| Fires Prebid win event | always | never | always | +| Fires Prebid imp event | never | VAST impression tag | never | +| Fires OpenRTB burl | when in view | n/a | never (1) | +| Fires OpenRTB nurl | always | n/a | always | +| Fires OpenMeasurement events | Next-Gen SDK | n/a | PB SDK | + +Notes: + +1. OpenRTB burl and nurl will be utilized in a future release. diff --git a/_includes/mobile/intro-nextgen-prebid-rendered.md b/_includes/mobile/intro-nextgen-prebid-rendered.md new file mode 100644 index 0000000000..e6e51190d7 --- /dev/null +++ b/_includes/mobile/intro-nextgen-prebid-rendered.md @@ -0,0 +1,125 @@ +## Overview + +This how-to guide covers the 'Prebid-Rendered' approach for integrating the Prebid SDK into your app with the Google Next-Gen Mobile Ads SDK. It utilizes: + +- **Prebid SDK** and **Prebid server** to handle the bidding and auction process. +- **GAM** and the **Google Next-Gen Mobile Ads SDK** manage the ad inventory and select the winning ad to display. +- **Prebid SDK** renders display ads when a Prebid bid wins. +- **Next-Gen SDK** renders ads when a Prebid bid wins. + +If you do not have the Next-Gen Mobile Ads SDK in the app yet, refer to the [Google Integration Documentation](https://developers.google.com/admob/{{include.platform}}/next-gen/quick-start). + +### Alternative Approaches + +Another way to integrate Next-Gen SDK into your app is with the [Next-Gen SDK Bidding-Only integration](/prebid-mobile/pbm-api/{{include.platform}}/{{include.platform}}-sdk-integration-nextgen-original-api.html). + +Tradeoffs between these integration approaches: + +{: .table .table-bordered .table-striped } +| Aspect | Bidding-Only Integration | Prebid-Rendered Integration | +| --- |:---:|:---:| +| App code has direct access to bids | check | | +| Support for MRAID 3.0 | | check | +| Support for SKAdnetwork | | check | +| Loads data from Prebid Cache | check | | +| Triggers billing and Notice URLs | check | | +| Supports Third Party Rendering libraries | | check | + +**Notes:** + +- On one hand, using Prebid Cache reduces the amount of data that must be sent to the mobile device -- the body of the creative does not need to be transmitted for bids. On the other hand, though, when a bid wins in the ad server, the body of the creative must be retrieved from the cache. +- It is possible to mix-and-match implementations within an app. e.g. you could implement instream video with the Bidding-Only approach and other adunits with Prebid-Rendered. + +### Prerequisites + +The Next-Gen SDK Prebid-Rendered Integration method assumes that you have the following components: + +- **Google Ad Manager Account** - A GAM account allows you to manage and serve ads within your mobile app. Within this account you'll need to configure your inventory and create orders for serving ads within your app. This involves defining ad units (spaces within your app where ads will be displayed) and setting up orders and line items to deliver ads to those units. See [Prebid's AdOps Guide](/adops/before-you-start.html) for more information. +- **Google Next-Gen Mobile Ads SDK** - This refers to the software development kit provided by Google. You need to ensure that you have the latest version of the Next-Gen Mobile Ads SDK supported by Prebid SDK. This SDK integration is necessary to communicate with the ad server and display ads in your app. +- **Prebid SDK** - You will need the latest version of the Prebid Mobile SDK for either [Android](/prebid-mobile/pbm-api/android/code-integration-android.html) or [iOS](/prebid-mobile/pbm-api/ios/code-integration-ios.html). +- **Prebid Server** - You will need a cluster of servers running [Prebid Server](/prebid-server/use-cases/pbs-sdk.html). You can set up your own Prebid Server or work with a [Prebid Server managed service](https://prebid.org/managed-services/). Prebid Server provides you with the following: + - Configuration storage - rather than hardcoding all the details of your current business arrangements in the app, Prebid Server stores which bidders you're currently working with, their inventory details, and other settings that can be changed without updating your app. + - Server-side auction - the server will make the connections to multiple auction bidding partners so the app doesn't have to. + - Privacy regulation tools - the server can help your legal team meet different regulatory needs in different jurisdictions by configuring various protocols and anonyimization activities. + +## How it Works + +Here's how the ad bidding-auction-rendering process works in this integration scenario. + +![Next-Gen Prebid-Rendered Integration Details](/assets/images/prebid-mobile/mobile-details-gam-prebid-rendered.png) + +1. Prebid SDK calls Prebid Server which supplies one or more bids. +1. PBSDK adds targeting values to Next-Gen SDK. +1. Next-Gen SDK calls GAM, which makes the ad decision. +1. If a 3rd party HTML creative is chosen (banner, native, interstitial, non-instream video): + 1. Next-Gen SDK writes HTML to a webview, loading google_mobile_app_ads.js. + 1. This script triggers a "PrebidAppEvent". + 1. Which in turn triggers PBSDK to handle the rendering of the creative: + 1. PBSDK fires the Prebid Server win event. + 1. If a 3rd party rendering SDK is in use, PBSDK calls it for rendering. + 1. Otherwise, it writes the creative into an iframe into an internal WebView, replaceing the Next-Gen SDK's WebView. + 1. Injects mraid.js into the webview to listen for events from MRAID: change size, etc. + 1. Sends data to the creative (e.g. 'viewable') which may trigger impression tracking within the creative. + 1. Starting from v3.0.0, the SDK hits the billing and notice urls (burl and nurl). +1. If a video VastUrl creative is chosen (rewarded video only): + 1. The Next-Gen SDK uses the platform video player which loads the special VAST file from the Prebid CDN. + 1. Prebid SDK watches VAST events for "PrebidAppEvent". When it sees this, it takes over the rendering: + 1. PBSDK fires the PBS win event. Starting from v3.0.0, the SDK also hits the billing and notice urls (burl and nurl). + 1. If the response indicates a 3rd party rendering SDK, PBSDK will call it. + 1. Otherwise: + 1. PDBSK renders with the platform-standard VAST player. + 1. It uses the VAST from the bid response, not from Prebid Cache. + 1. The player fires any Impression tags in the VAST. + 1. PBSDK handles MRAID events. + 1. The app is called to handle the reward. +1. If an In-App Native format is chosen: + 1. The Next-Gen SDK delegates the rendering of native to the App and PBSDK when a special signal is specified. + 1. The app code gets the native assets from PBSDK. The app is coded to render the ad. + 1. PBSDK fires the eventtrackers when appropriate. + 1. The PBS win event is fired. Starting from v3.0.0, the SDK also hits the billing and notice urls (burl and nurl). +1. Open Measurement events are handled directly by the Prebid SDK. + 1. If a 3rd party rendering SDK is used to render, then it will handle Open Measurement. + +## Major Integration Steps + +Assuming your app already has AdUnits integrated with the Next-Gen Mobile Ads SDK, the technical implementation of Prebid mobile into your app will involve these major steps: + +1. [Initialize the Prebid SDK](/prebid-mobile/pbm-api/{{include.platform}}/code-integration-{{include.platform}}.html) - create a connection to your Prebid Server. +2. [Set Global Parameters](/prebid-mobile/pbm-api/{{include.platform}}/pbm-targeting-{{include.platform}}.html) - let bidders know important data about the page, privacy consent, and other settings. +3. Work with your Prebid Server team to create the adunit configIds that will be used in the app. +4. Set up GAM orders, line items, and creatives. See [AdOps guidance](#ad-operations-guidance) +5. Link Prebid AdUnit code to your Next-Gen SDK AdUnits - for any adunits that your business team wants to connect to Prebid with the configIds generated in Step 3. See the [adunit-specific instructions](#adunit-specific-instructions) below. + +## Ad Operations Guidance + +The AdOps team will need to create line items in GAM. The creatives used depend on which media formats your adunits utilize: + +{: .table .table-bordered .table-striped } +| AdUnit Format | Line Item Targeting | Creative Type | Prebid Cache? | Ad Ops Details | +| --- | --- | --- | --- | --- | +| HTML banner, interstitial banner or video, non-instream video | hb_pb
hb_format=banner | 3rd party HTML that loads google_mobile_app_ads.js | no | [link](/adops/mobile-rendering-gam-line-item-setup.html#third-party-html) | +| Rewarded Video | hb_pb
hb_format=video
inventoryType in (instream, mobile app)
rewarded adunits | VastUrl pointing to prebid-mobile-rewarded-vast.xml | no | [link](/adops/mobile-rendering-gam-line-item-setup.html#rewarded-video) | +| In-app native | hb_pb
hb_format=native | GAM native | no | [link](/adops/gam-native.html#create-a-new-native-creative) | + +Notes: + +- You may need up to 4 sets of line items to support Prebid Mobile depending on adunit types. If you also run Prebid.js or AMP, please see [line item considerations](/adops/line-item-creation.html) for more information. +- Discuss the Prebid Cache column with the Prebid Server team. They can set up the "top-level stored request" for your account to cache or not cache requests as needed. + +### Rendering and Tracking + +This information may be useful when comparing data across various reporting systems: + +{: .table .table-bordered .table-striped } +| Scenario | 3pHTML Creative | VastUrl Creative | GAM Native Creative | +| --- | --- | --- | --- | +| Rendering Method | js in iframe fires an event | Next-Gen SDK player | App code with data from PBSDK | +| Fires Prebid win event | always | never | always | +| Fires Prebid imp event | always | VAST impression tag | never | +| Fires OpenRTB burl | always (1) | n/a | never | +| Fires OpenRTB nurl | always (1) | n/a | never | +| Fires OpenMeasurement events | PBSDK | n/a | PBSDK | + +Notes: + +1. OpenRTB `burl` and `nurl` are utilized in a PrebidMobile SDK v3.0.0. 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..c39732f5c2 --- /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-nextgen-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) 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..bde7a768e4 --- /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-nextgen-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