Closed bretg closed 1 year ago
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.
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
v2.1.0
v3.0.0
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.
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
RewardedVideoAdUnit
without external changes but now it should inherit the new behavior of InterstitialAdUnit with .video
ad format type VideoAdUnit
InstreamVideoAdUnit
BannerAdUnit
with .adFormats = [.video]
for the out-stream video.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
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
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
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.
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.