Concurrent Auctions

concurrent_auctions.md

Concurrent Auctions - ready for review

The proposal for concurrent auction support will be for Prebid.js to hide details of concurrency from the end user (publisher). They will still use the same public API's that are in place (i.e. requestBids() etc) but receive the benefit of better performance (not having to have bid requests queued). Concurrency just works (CJW).

When a getTargeting request is made to prebid, prebid will deteremine the best bid that is available at the given time out of the pool of available bids.

Auction Manager // new class to replace bidmanager.js

• Is responsible for storing auction references (each auction object will store N # of bids associated with a particular call of requestBids()) in a internal structure
• Concurrent auctions will be supported via creating new auction instances
• auction instances will be bound to a specific auctionRequest copy that is passed from adaptermanager.js
• auction instances methods will be passed to each bidder adapter to keep reference via closure
  • example: adapter.callBids(auction.auctionRequest, auction.addBidResponse, auction.done );
• Auction Manager will be responsible for closing the auction when it determines that all bids are received (via done callbacks, or alternatively counting bid requests # === bid responses #)
• Limit the number of concurrent auctions (3?)

Auction Mechanics for concurrent bid requests

Having multiple concurrent auctions means the potential for multiple bids to exist for a given placement. The following rules apply to any methods that would need to get a targeting set for a given adUnit.

• Bids will be auctioned at the adUnit level (same as today) where the top CPM bid is picked as the winner across all auction instances that are marked complete auction.status = complete
  • alternatively, it might be desired to auction bids on first in, first out basis FIFO (open for debate).
• Bids will be evaluated against their defined bid.ttl and will not be eligible to win if time since retrieve > ttl (will be marked expired) and can be removed at a later point in time.
• A bid picked for targeting (prebid auction win) will be marked bid.status = 'targetingSet' - which indicates it's not eligible for future auctions, until such status is cleared. This will prevent a winning bid to be set in targeting more than 1 time.
• A bid that wins the final adserver auction (bid passed through to renderAd) will be marked as bid.status = 'rendered' and it's lifecycle is complete. It can be removed at a later point in time.
• A callback method that signifies a given auction is complete can release (how to do this?) and update any targetingSet status bids back to available - assuming they are not expired.

bidder requirements

Each bidder would be responsible for the following:

• Will support a new function signature for callBids(auctionRequest, addBidResponse, done)
  • auctionRequest // auctionRequest obj filtered to their bidder code.
  • addBidResponse // bound function to auctionManager.addBidResponse(). Will store a reference to the current auction
  • done // callback to fire when this bidder is done bidding
• Bidder must store state that it needs to track and know when it's done bidding for a given auctionRequest
• Bidder must continue to pass a bid.id that is from the auctionRequest request so we can match request/response properly
  • If the bidder doesn't pass bid.id, auctionManager will infer it from the combination auction instance + adUnit.code + bidder.code
• Bidder must include a bid.ttl specified in seconds on each bid, or include a method on the adapter getBidTtl