mkendall07/publisher_api_changes.md

## publisher_api_changes.md

      
    Raw
  

              publisher_api_changes.md
            
          
    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 (prebid/Prebid.js#1007 (comment)) 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"
      }
    }
  ]
}