Support multiformat adunits

We have a publisher that wants to create an adunit that supports both banner and outstream video. Prebid.js and Prebid Server call this a 'multiformat' adunit. It's supported in OpenRTB requests by specifying both imp.banner and imp.video in the same imp object.

This is not currently possible with the Prebid SDK

Describe the solution you'd like

Please update the SDK, both iOS and Android, to allow publishers to declare both banner params and video params for the same adunit.

And of course add test cases and documentation on docs.prebid.org for how to form the request and set up the line items for the response side.

[DRAFT] Implementation spec

Summary

This comment captures the requirements and specs for the final solution and the steps to implement it. While you see a DRAFT mark in the header, this comment still needs to be prepared for dev. Feel free to add notes and propositions below.

Description

Prebid SDK API is a set of classes that allows configuring bid requests. They are similar to stored impressions on PBS. They implement some predefined properties and add them to the SDK's portion of the bid request.

For instance, the BannerAdUnit contains the property parameters of BannerParameters types which eventually will be added to the banner object of the bid request. The same is relevant to the VideoAdUnit and VideoParameters. And the same is relevant for Interstitial ad units. Each of ad-format-specific AdUnit has own set of properties.

In order to implement multi-format bid requests, we have to merge pairs of ad units by the ad placement type - banner and interstitial. As a result, some of the current API classes will be deleted. Because such classes like InterstitialAdUnit and VideoInterstitialAdUnit will become useless.

At the same time, the integration of "main" ad units will remain the same. Publishers will get the ability to make multiformat requests by adding respective properties to the ad unit classes. The removed classes should be replaced with new ones with different names but the same API.

The API change requires updating at least a minor semantic version of the SDK. So it will be a 2.1.0 release.

The removal of outdated classes will be implemented in two steps

Depreciation - v2.1.0
Removing from the codebase - v3.0.0

Objectives

Banner (HTML, OUTSREAM VIDEO)

Add property adFormats as an array of AdFormat enum cases. Default value [.banner]
Remane property parameters to bannerParameters
Add property videoParameters
Deprecate class BannerBaseAdUnit.Parameters, use only BannerParameters instead.
Deprecate class VideoBaseAdUnit.Parameters, use only VideoParameters instead.

Interstitial (HTML, VIDEO)
Add property adFormats as an array of AdFormat enum cases. Default value [.banner]
Remane property parameters to bannerParameters
Add property videoParameters
Deprecate class VideoInterstitialAdUnit, use InterstitialAdUnit with .adFormats = [.video] instead

Rewarded (VIDEO)

Keep the RewardedVideoAdUnit without external changes but now it should inherit the new behavior of InterstitialAdUnit with .video ad format type

InStream Video

Deprecate class VideoAdUnit
Introduce class InstreamVideoAdUnit
Use BannerAdUnit with .adFormats = [.video] for the out-stream video.

Demo Apps & Internal Test Apps

Update existing cases to use the new API approach
Introduce new cases for multiformat Banner and Interstitial multiformat ad units

@YuriyVelichkoPI some notes from after the Verve team reviewed the proposal. We are not super familiar with Prebid's development cycles so please ignore any suggestions or comments that might not apply 🙂

The removal of outdated classes will be implemented in two steps

Depreciation - v2.1.0
Removing from the codebase - v2.1.X

This deprecation timeline seems very tight. I’d be more in favor of doing breaking changes in major version jumps like 3.0.0. But if that’s not a common practice on Prebid I’d at least make it a feature version jump. Like 2.2.0 or so. Introducing breaking changes in a patch version is not a good practice.

In the case of these deprecations

Deprecate class BannerBaseAdUnit.Parameters, use only BannerParameters instead.
Deprecate class VideoBaseAdUnit.Parameters, use only VideoParameters instead.

I’d still for the time being introduce some converters in the setters for the parameters that will translate into the new BannerParameters and VideoParameters. This way publishers with the old implementation will still have full support until they can do the update to remove the deprecated API calls.

InStream Video

Deprecate class VideoAdUnit
Introduce class InstreamVideoAdUnit
Use BannerAdUnit with .adFormats = [.video] for the out-stream video.

Will this be used as a wrapper for BannerAdUnit? Won’t it be better just to keep the logic in the banner and not add this extra potential source of errors or confusion for publishers? This depends of course on how Prebid is marketing this format, maybe it’s of business interest to sell it as something different than a banner placement.

Last note here and mentioned from experience. The Prebid SDK should ensure to keep the consistency between the video and banner request via the identifier. This will prevent some issues later in case a bid is received for each format and the SDK will not know how to render the adm since there’s no clear differentiator between video and banner

@eros902002 Thanks for the detailed feedback! It is very helpful and makes sense. Let me address its items:

The removal of outdated classes

I'll update the description and change it to 3.0.0. In several months, the prominent feature "Rendering Delegation" will probably be introduced, and we can edit the major version and remove deprecated classes.

Deprecation of Parameters classes

There is no need for converters here because, technically, they are the same classes. They are struct with identical properties. Both of them exist due to historical reasons for adding rendering functionality. We couldn't remove or deprecate existing ones and, at the same time, couldn't reuse them due to the nesting. To migrate from the deprecated classes, publishers must remove the name of a wrapper class and nothing more. In any case, I got your point and will ensure the transition is smooth.

InstreamVideoAdUnit

Right, the point of a standalone ad unit is that In-Stream integration differs from the domain perspective. It even uses a different Google SDK - IMA, but not Google Ads SDK. So semantically is not a banner integration.

consistency between the video and banner

Sure, in this case, we rely on PBS processing of multiformat ads. SDK adds the ext.prebid.targeting to the request and expects the hb_format keyword in the response.

But, just for note, SDK doesn't utilize the format of winning bid because it doesn't render the bid (in the scope of this task, we are working only on Original API). So the rendering will be provided by GAM setup. On GAM publisher should have a set of line items with banner and video creatives. The hb_format keyword of the winning bid should target these line items respectively. The GMA SDK will render the creative(PUC for banner and VAST tag for video) from the targeted line item, and the creative will download the ad from PBC and display it.

The multiformat ad cases will be added to the Demo and Internal Tests apps.

prebid / prebid-mobile-ios