Type of change

• Feature

Description of change

• update PAAPI requestedSize handling as described in PAAPI module: fill out auctionSignals.prebid.ortb2Imp.banner better #11189 (comment)
• introduce a new module, topLevelPaapi, intended for pubs running top level auctions. Example configuration:

  pbjs.setConfig({
    paapi: {
      topLevelSeller: {
         auctionConfig: {
             seller: 'example.seller',
             decisionLogicURL: 'https://example.seller/dl.js',
             // ...
         },
         autorun: true,
         overrideWinner: true
      }
    }
  })
  

• auctionConfig is reflected by getPAAPIConfig().
• introduce a new public api, pbjs.getPAAPIBids(), which accepts the same filters as getPAAPIConfig, and returns a promise to a map from ad unit code to paapi auction result (obtained by calling runAdAuction).
  The auction result is an object with the format {adId, adUnitCode, auctionId, width, height, urn, frameConfig} (where urn and frameConfig are mutually exclusive)
• the adId generated by getPAAPIBids() can be rendered with pbjs.renderAd like "normal" adIds
• autorun, if true (the default), starts runAdAuction ASAP (currently, that's when the Prebid auction ends)
• overrideWinner, if true (default is false), makes it so that PAAPI bids are rendered instead of the contextual winner.For example, calling renderAd() or rendering PUC / other creatives in the normal way would check if there's a a PAAPI bid for the ad slot, and if so render that instead.
• introduce new events paapiRunAuction, paapiBid, paapiNoBid, and paapiError
• update the top level auction integration example to use the above.

Other information

Closes #11189
Closes: #10690