Prebid Server support for Parakeet

[bretg]

We're looking to build test support for the Parakeet privacy protocol into Prebid Server.

There's more detail here, but here's the main points:

1. The web page hits a Parakeet Server
2. The Parakeet Server anonymizes the request and sends it to Prebid Server
3. Prebid Server needs to pick a winner

It's not entirely clear how this interaction will be integrated, but here are a couple of possible scenarios:

A) AdUnit with no ad server. The page calls client-side PBJS adapters, sets the highest bid as a floor, then calls Parakeet. If PBS can beat the floor, Parakeet will return the PBS ad for render, otherwise it won't.
B) Secret bid. One of the key design aspects of Parakeet is to hide information that could be used to build a user profile. Bids are info too. So If there's an ad server, Parakeet would not, in the long term, return a bid value or bidder or even creative. Just "yeah, I got something". It's not clear exactly how this would work in a Prebid.js context. Maybe a 0-value bid? Maybe it's used as essentially post-bid?

Anyhow, for the purposes of an initial integration test, I'm going to assume scenario A because I can wrap my head around it.

Parakeet ORTB2 Transformations

1. site.ext.parakeet:1 will flag incoming requests as coming from Parakeet. PBS should also accept app.ext.parakeet:1.
2. imp[].tagid should be viewed as an impression-level stored-request-id
3. The rest of the request fields (site, device, etc) form the basis of the PBS request
4. The following Prebid-specific extensions should be added to the top-level request:
   1. ext.prebid.targeting.includewinners: true
   2. ext.prebid.cache.bid: {}
   3. ext.prebid.channel: {name: "parakeet"}
5. Parakeet expects the response to be a single bid, not an array of bids
6. Parakeet expects PBS to enforce any supplied imp.bidfloor

Proposed Prebid Server implementation

I propose a new 'Parakeet' module that has processing at two stages:

• Raw Auction Request
• Auction Response

Raw Auction Request Stage

1. If the incoming request contains site.ext.parakeet:1 or app.ext.parakeet:1, trigger the following behavior
2. For each imp, look for tagid. If not present, skip it. If present, replace it with ext.prebid.storedrequest.id=value-of-tagid. This will cause the later stages to load and merge a stored-impression id containing the bidders.
3. Add the ext.prebid global values as noted above. It would be nice if these values were configurable because they may evolve as we understand this interface better. e.g. we may be want to add ext.prebid.targeting.preferdeals.

Error handling:

• If the request is flagged as Parakeet any impression fails to contain tagid, reject the request with a 400 and an error message when in debug mode: "Parakeet impressions must contain tagid"
• If an impression contains imp.bidfloor but not imp.bidfloorcur, reject the request with a 400 and an error message when in debug mode: "Parakeet impressions that specify bidfloor must also specify bidfloorcur".
• If a specified tagid/stored-request-id doesn't exist, PBS should fail the request as normal

Auction Response

1. If the original bid request contains site.ext.parakeet:1 or app.ext.parakeet:1, trigger the following behavior
2. For each imp, if imp.bidfloor is supplied, enforce that every bid price meets the floor
   1. Currency conversions must be done on the supplied imp.bidfloor/bidfloorcur before rejecting bids.
   2. If a bid is rejected in debug mode, emit a warning about discarding the bidder's bid.
3. Choose the highest seatbid.bid and remove all others.
   1. Note that if ext.prebid.targeting.preferdeals is present, the highest value bid that specifies a dealid should be kept even if it's not the overall highest bid.
   2. If in debug mode, add a warning "Choosing the highest value (deal) bid for Parakeet"
4. If there are no valid responses after processing the bids, PBS should still return with 200 with the standard empty seatbid array and, in debug mode, any warning messages.