Major API Updates for Refreshing Ad Units

In the new API, we've made the below changes to better support the refresh functionality. Note that this new API has introduced a few breaking changes:

Breaking Changes

Change 1: A command queue

Now all pbjs commands should be wrapped by pbjs.que.push. This ensures pbjs commands are in scope and are executed in the right order. Example:

pbjs.que.push(function() {
   pbjs.setTargetingForGPTAsync();
});

Change 2: Add ad units

Instead of directly pushing objects into the pbjs.adUnits array (as in the previous versions), the new API requires the function pbjs.addAdUnits(adUnits). Example:

var adUnits = [{
        code: '/9968336/header-bid-tag-0',
        sizes: [[300, 250], [300, 600]],
        bids: [{
            bidder: 'appnexus',
            params: { placementId: 'TO ADD' }
        }]
}];
pbjs.addAdUnits(adUnits);

Change 3: Request bids

Previously, prebid.js automatically sends out bid requests as soon as the library loads. This isn't needed for many sites. The new API requires the page to explicit call pbjs.requestBids to send out bid requests. Example:

pbjs.requestBids({
    bidsBackHandler: function(bidResponses) { }
});

Change 4: Bids back callback

The callback when requested bids are returned are now in pbjs.requestBids (as in the above example). No more pbjs.registerBidCallbackHandler()

Deprecated Functions

1. Function getAdserverTargetingParamsForAdUnit(adUnitCode)

It's now split into getAdserverTargeting() and getAdserverTargetingForAdUnitCode([adunitCode])
Find out docs here

2. Function requestBidsForAdUnit(adUnitCode)

It's now requestBids()

3. Function registerBidCallbackHandler()

It's now a callback within the requestBids()

New Features

1. Request selected array of bids

pbjs.requestBids({
    adUnitCodes: ['/99336/slot-0'],
    bidsBackHandler: function() {
        pbjs.setTargetingForGPTAsync(['/99336/slot-0']);
        googletag.pubads().refresh([slotObj]); 
    }
});

See docs for pbjs.requestBids()
http://prebid.org/publisher-api.html#function-reference

2. New callback functionality (more events will be added)

A new callback when all bids are back for individual ad units:

pbjs.addCallback('adUnitBidsBack', function(adUnitCode){
       console.log('ad unit bids back for : ' + adUnitCode);
});