Status: Ready for review
- Make the public API easier / simpler if possible, while preserving the ability for more advanced setups.
- Depracting API's as needed.
- Configration to be expressed JSON
- Expanding functionality of size mapping
- All
$$PREBID_GLOBAL$$._*
varaibles should be depracated as part of 1.0. $$PREBID_GLOBAL$$.addCallback
in favor ofonEvent
API - no reason to have 2 API's for eventing. see alsosetConfig
below for more deprecations.
Summary:
- (Breaking): Add
setConfig
API for reducing public API footprint. - (Breaking): Size Mapping enhancement
- AdUnit:
- (breaking) Formalize
mediaTypes
support - (non-breaking) Params must be valid JSON
- (breaking) Support size mapping filtering
- (breaking) Formalize
Deprecate the following APIs in favor of a generic "options" param object:
$$PREBID_GLOBAL$$.bidderTimeout
$$PREBID_GLOBAL$$.logging
1$$PREBID_GLOBAL$$.publisherDomain
$$PREBID_GLOBAL$$.cookieSyncDelay
$$PREBID_GLOBAL$$.setPriceGranularity
$$PREBID_GLOBAL$$.enableSendAllBids
2$$PREBID_GLOBAL$$.setBidderSequence
$$PREBID_GLOBAL$$.setS2SConfig
Mapping will be straigthfoward with the name of the param being the same except dropping set
where appropriate.
1: Renamed to debug
.
2: $$PREBID_GLOBAL$$.enableSendAllBids
will default to true in 1.0.
Note: input must be JSON (no JS functions allowed).
pbjs.setConfig({
"currency": {
"adServerCurrency": "JPY", // enables currency feature to be enabled -- loads the rate file
"conversionRateFile": "url" // allows the publisher to override the default rate file
},
"debug" : true, // previously `logging`
"s2sConfig : {...},
"priceGranularity": "medium",
"enableSendAllBids": false, // default will be `true` as of 1.0
"bidderSequence": "random",
"bidderTimeout" : 700, // default for all requests.
"publisherDomain" : "abc.com", // used for SafeFrame creative.
"pageOptions" : {...},
"sizeConfig" : {...}
});
Implement the change suggested by Bret here (prebid/Prebid.js#1007 (comment)) with few adjustments.
- Replace
device
withlabels
to make this more extensible in the future. - Include this option in
setConfig
Rules:
- If
sizeConfig
is present- before
requestBids
sends bids requests to adapters, it will evaluate and pick the appropriatelabel(s)
based on theminWidth
and device screen width and then filter theadUnit.bids
based on thelabels
defined (by dropping those adUnits that don't match the label defination). - If a label doesn't exist on an adUnit, it is automtatically included in all requests for bids
- The
adUnit.sizes
selected above will be filtered based on the selectedlabel
. So theadUnit.sizes
is a subset of the sizes defined from the resulting intersection oflabel
sizes andadUnit.sizes
.
- before
Example:
setConfig(
{
"sizeConfig": [{
"minWidth": 1200,
"sizesSupported": [
[970, 90],
[728, 90],
[300, 250]
],
"labels": ["desktop"]
}, {
"minWidth": 768,
"sizesSupported": [
[728, 90]
],
"labels": ["tablet", "phone"]
}, {
"minWidth": 0,
"sizesSupported": [
[300, 250],
[300, 100]
],
"labels": ["phone"]
}]
});
Usage is defined by adUnit definitions:
var adUnits = [{
"code": "ad-slot-1",
// these are all sizes that can be associated with the slot on the page, but adapters will only
// be passed the relevant sizes as filtered by 'sizesSupported' for the form factor
"sizes": [ [ 970,90 ], [ 728,90 ], [ 300,250 ], [ 300,100 ] ],
"bids": [ // the full set of bids, not all of which are relevant on all devices
{
"bidder": "pulsepoint",
"labels": [ "desktop", "tablet" ], // flags this bid as relevant only on these screen sizes
"params": {
"cf": "728X90",
"cp": 123456,
"ct": 123456
}
},
{
"bidder": "pulsepoint",
"labels": [ "desktop", "phone" ],
"params": {
"cf": "300x250",
"cp": 123456,
"ct": 123456
}
},
{
"bidder": "districtmDMX",
// labels not specified, so applies to all sizes / devices / labels.
"params": {
"id": 123456
}
},
{
"bidder": "sovrn",
"labels": [ "desktop", "tablet" ],
"params": {
"tagid": "123456"
}
},
{
"bidder": "sovrn",
"labels": [ "phone" ],
"params": {
"tagid": "111111"
}
}
]
}];
adUnit =
{
"code" : "unique_code_for_placement" //optional/required onf of ['code', 'slotName', 'divId']
"sizes" : [[300,250]], //optional - supports DFP style array of arrays for size.
"mediaTypes": { //optional. Complext type for attributes. Open ending for expansion. Will default to banner if not specified.
video: { context: 'outstream' },
banner: {...options},
native: {...options}
},
labels : ['desktop', 'mobile']
bids : {...} //same as existing defination with additional of `label` attribute
}
The following items were decided to be dropped from 1.0 scope as they can be implemented later and should be non-breaking (just adding functionality).
- (non-breaking): Add a new page level config option - this can simplify setup for applying bidders / params to all adUnits on page
- Allowing
labels
to be passed in requestBids as a filter and potionally provide a way to link slots to AdUnits before the auction. - AdUnit templates
Allows for defining data params that are added globally to every invocation of a given adapter.
Shown here for simplicity but this should go into setConfig
.
pageOptions = {
bids : [{
bidder: "appnexus", //define global value for AppNexus bidder - will be applied to all adUnits
"params" : {
"globalParam" : "globalValue"
}
},
{
bidder: "*", //apply to all bidders - will be applied to all adUnits
"params" : {
"dtId" : "123456"
}
}
]
}
A few notes:
The concurrent bids and prefetch / bid pools use cases are somewhat different so may be helpful to define both. In the first case we want support for multiple calls to requestBids fired in quick succession and in the latter case we want to retain "good" bids that are still within the bids declared ttl.
Can
auctionRequest
be simplyauction
?bidRequestId
currently is unique to a bidder for a given auction, not to an ad unit, and it makes sense to move this to ad unit, just checking to make sure the change is clear.Overall this looks good to me, with the caveat that both Bid and AdUnit types will include additional methods to update their status, determine timeouts, and so forth.
I'd also like to further discuss how to handle cases where an AdUnit is included in two or more concurrent auctions.