Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
Prebid 1.0 Publisher API changes

Status: Ready for review

Goals

  • 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

Deprecations:

  • All $$PREBID_GLOBAL$$._* varaibles should be depracated as part of 1.0.
  • $$PREBID_GLOBAL$$.addCallback in favor of onEvent API - no reason to have 2 API's for eventing. see also setConfig below for more deprecations.

Publisher API changes

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

setConfig - new API

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.

Example usage

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" : {...}
});

Size Mapping Enhancment

Implement the change suggested by Bret here (https://github.com/prebid/Prebid.js/issues/1007#issuecomment-285714415) with few adjustments.

  • Replace device with labels 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 appropriate label(s) based on the minWidth and device screen width and then filter the adUnit.bids based on the labels 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 selected label. So the adUnit.sizes is a subset of the sizes defined from the resulting intersection of label sizes and adUnit.sizes.

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 Obj

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
}

Items removed from Prebid 1.0 scope:

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

pageOptions Obj - new

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"
      }
    }
  ]
}

bretg commented May 10, 2017

Good start Matt.

PageConfig Obj - can we support a "global" block that is applied to all bids? Possible use cases are things like DigiTrust IDs or viewability signals.

"templates" type support via a unit|fetches param.
Sorry, not understanding this template approach. Comment says "support N number of prefetches on this unit". How are those prefetches triggered? Where can regex's come into play?

In case others have the question - prebid/Prebid.js#1082 helps explain the 'renderer' concept.

On the auctionRequest object - each adapter will receive only the bids for it, right? So the 'bidder' attribute is just FYI.

To make sure I understand the IDs correctly:

  • auctionRequest.auctionId is unique per call to pbjs.requestBids(). It's the same across all bids and bidders.
  • auctionRequest.bids.id is unique to the auctionId+Bid, but is the same across bidders.
  • bidderRequestId - who sets this?
Owner

mkendall07 commented May 12, 2017

Updated the spec:
auctionRequest.auctionId - is unique per call to pbjs.requestBids(). It's the same across all bids and bidders.
auctionRequest.bids.id - is unique to the auctionId, bid, and bidders.
auctionRequest.bids.bidRequestId - unique id to this AdUnit - same across all bidders ( can be used for bid deduping)

bretg commented May 12, 2017

Notes from yesterday's meeting:

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 simply auction?

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.

Few comments/ questions here:

Instead of sizeConfig.type, can we call it sizeConfig.id or sizeConfig.sizeConfigId? To me, calling it type implies a generic classification, whereas sizeMappings are really just arbitrary groupings of valid sizes.

What is the expected behavior if an adUnit is defined with both slotCode and divId?

What are the implications of adUnit.slotCode/ adUnit.divId supporting regex pattern matching? What do we do if the defined pattern matches multiple ad slots on page?

bretg commented Jun 7, 2017

Good progress. I'd suggest sizeConfig.tags instead of sizeConfig.type. I see why you want to generalize from from device. Would also like to see "tags" at the AdUnit level, not just the bids level... this would simplify the administration of AdUnits.

I’ve put together a doc outlining in more detail where I’m hoping we can head with this. The main drivers are a configuration tool and AdUnit scaleability for larger accounts

Will set up some time to discuss.

What is the expected behavior if an adUnit is defined with both slotCode and divId?

Good question. I've identified three roles:

  • unique ID: Rubicon currently puts the divId in the code because it's more unique than slotCode. In the future, I'd suggest that if AdUnit.code isn't specified, we generate an ID for it that would just be used internally
  • slot matching: first check slotCode, then check divId, then give up
  • debugging - both can be useful, so log statements could include them

bretg commented Jun 13, 2017

Summary of changes @mjacobsonny and I have discussed:

  • use 'tags' instead of 'types'
  • allow tags at the AdUnit level
  • use 'slotName' instead of 'slotCode' to reduce confusion with code, which we'll still support
  • update pbjs.addAdUnit() and requestBids() to support tags
  • Optionally provide a way to link slots to AdUnits before the auction
    -- this is a good way to pick which AdUnits are in the auction
    -- allows the sizes to be copied from the slots, simplifying AdUnit creation and maintenance
  • AdUnit templates vs keeping multiple AdUnit lists (master list, auction list). Either way, we're looking to upgrade AdUnit functionality
    -- apply an AdUnit to more than one slot
    -- copy sizes
  • we're not sure if AdUnit.code is needed internally as a unique ID, but agree it should be kept for backwards compatibility

harpere commented Jul 14, 2017

How do we access a config set with setConfig()? is there a getConfig()?

snapwich commented Sep 6, 2017

in the Size Mapping Enhancement rules you mention "adUnits" a few times where I think you mean "bidder", or whatever we call the objects that are in adUnit.bids[]. Other than that, LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment