Define how server-side adapters should pass fledge auction config

[bretg]

Related to prebid/Prebid.js#9080

We need to define how server-side adapters should pass fledge auction config.

We're working out the PBS-PBJS protocol in the other issue. This one is for tracking how adapters specify the value.

[bretg]

Here's the format of the wire protocol as discussed in prebid/Prebid.js#9080

{
  ext: {
    fledge: {
      auctionconfigs: [{
          impid: "123",
          bidder: "bidderA",
          config: { ... }
     },{
          impid: "123",
          bidder: "bidderB",
          config: { ... }
     }]
  }
}

So I think PBS-core will have the following responsibilities:

1. Pick up the fledge auctionconfig from wherever bid adapters are placing it
2. Make sure that bidders aren't submitting fledge auctionconfig for other bidders. (subject to the "multiple biddercode" rules)
3. Make sure that fledge auctionconfig is associated with a valid imp object

No need to validate the body of the fledge auctionconfig

I'm too fuzzy on the bid adapter interface to suggest the path-forward here. Need @SyntaxNode and @Net-burst to weigh in on this aspect.

[bretg]

We discussed fledge in the PBJS committee. The JSON format is approved, but might change in the future if the IAB comes up with a different format.

The preference is that "bidder" is the biddercode that's in imp.ext.prebid.bidders... i.e. 'pubm_ss' rather than 'pubmatic'. Not clear to me this is available to bid adapters.

If the bid adapter is aware of how it was invoked, then it should use that code. This might differ if the adapter is fronting other bidders, i.e. in "allowUnknownBidderCodes" mode. In that case, it seems that the adapter will need to return the best biddercode it has available.

[laurb9]

The bidder code could (and I would argue, should) be added by the framework. In PBS-Go bidders respond with a structure that has Bids and Currency, we can leverage that to pass the auction config array.

I may have some bandwidth so I can look into implementing this once the prebid.js prebid-server adapter convention is sorted out.

[laurb9]

We should also discuss how the "auction environment" parameter ae should be passed. There are two options:

• imp.ext.ae/imp.ext.auction_environment hoping to be eventually standardized, or
• a prebid extension imp.ext.prebid.ae which is similar to how is_rewarded_inventory is passed, or
• bidder-specific extensions imp.ext.prebid.<bidder>.ae but that could turn out to be unnecessarily verbose in constructing the request as well as code, as it would need to be added to every ext/imp bidder contract.

[SyntaxNode]

Discussed in the Prebid Server Committee.

The bidder should pass the auction config to Prebid Server via the existing bid response data structure (as suggested by @laurb9), which is TypedBid for PBS-Go and BidderBid for PBS-Java. PBS-Core will put it in the right spot.

We still need to work out the multi-bid scenario. How should this be handled in respect to bundling?

[SyntaxNode]

@laurb9 What is the Fledge "auction environment"?

[laurb9]

@SyntaxNode The auction environment is a numeric flag passed in the bid request, indicating that the client would accept a FLEDGE response for that imp. Originally it was spec-ed as a DSP parameter (imp.ext.ae=1) then we adopted the same form for SSP, so we can pass it through.

[bretg]

PBS will pass imp.ext.ae through. Is there any enforcement actions that should be taken -- like if imp.ext.ae:0, then don't accept fledgeauctionconfig?

[laurb9]

I have pushed a proposal for PBS-Go so we can discuss over it.

PBS does pass imp.ext.ae but due to historical usage of imp.ext. for bidder parameters, other parameters like is_rewarded_inventory live in imp.ext.prebid instead. Open to move it back to imp.ext.ae and carve another bidder name exception, makes for less decoding if we want to validate impid.

Regarding bid passing - since the auction config structure shares nothing with a regular Bid, I defined the adapter contract in PBS-Go as BidderResponse.FledgeAuctionConfig, independent of BidderResponse.Bids. From there it is copied to a corresponding field inpbsOrtbSeatBid and collected into the response ext afterwards.

I'll take a look at PBS-Java next.

[bretg]

My take is that adding an exception for imp.ext.ae is easy. Let's do that.

[bretg]

@laurb9 - where did ae come from? Found two docs on this, both defining BidRequest.imp.ext.auction_environment

• https://developers.google.com/authorized-buyers/rtb/fledge-origin-trial
• https://github.com/google/openrtb-doubleclick/blob/master/doubleclick-openrtb/src/main/protobuf/openrtb-adx.proto

[bretg]

We discussed in a meeting today and agreed this is ready-for-dev once we settle the ae request parameter.

Given that the references found so far are for auction_environment, but apparently that's not an official IAB extension. So we have several options:

1. Since there's not IAB-level approval, we should start off with imp.ext.prebid.ae and move it when the community settles
2. Since there's not IAB-level approval, just wait
3. Assume that Google's recommendation is going to stick - just use imp.ext.auction_environment

We also discussed tuning the response to push it down to ext.prebid and add 'adapter':

{
  ext: {
    prebid: {
      fledge: {
        auctionconfigs: [{
          impid: "123",
          bidder: "bidderA",     // adapterB was called with alias bidderA
          adapter: "bidderB",
          config: { ... }
       },{
          impid: "123",
          bidder: "bidderC",
          adapter: "bidderC",
          config: { ... }
       }]
     }
  }
}

PBS-core actions:

1. Pick up the fledge auctionconfig from (typedbid/bidderbid)
2. Make sure that fledge auctionconfig is associated with a valid imp object
3. Generate combined ORTB for all submitted auctionconfig

[laurb9]

The DSPs we worked on early integrations with (DV360 and RTBHouse) used imp.ext.ae so we went with that in Prebid.js and our corresponding backend, since those were the only implementations we were aware of.

FLEDGE is a trial and we can change the field name if it ends up standardized as something else.

The request and response should both agree on whether they're in prebid or not, so if the request comes in imp.ext.auction_environment then the response should be in ext.fledge; conversely, if request is imp.ext.prebid.ae then we have ext.prebid.fledge in response.

[laurb9]

Regarding implementation, I think both PBS-Go and PBS-Java could use a clean and explicit mechanism to pass back response data that is independent of the stream of bids. There is no overlap between the fledge auction config fields and TypedBid or BidderBid,which indicates to me that the auction config should be a different class.

Similar to Prebid.js, PBS-Go has a specialized BidderResponse as the contract with bidder adapters, so it took minimal changes to add the fledge config as I did in my PR.

PBS-Java expects a Result<List<BidderBid>> from bidder adapters, Result is a generic template used for other purposes, so passing the metadata just for the bid responses will have a larger impact on the code here.

[bretg]

The Prebid.js committee resolved to use imp.ext.ae as the input parameter.

The request and response should both agree on whether they're in prebid or not

We also discussed this and decided it's not important for them to both be in prebid or not. For the record, here's the logic:

• imp.ext.ae: there's (supposedly) already some industry weight behind this parameter. It's a single value. Seems likely that the IAB will accept this recommendation.
• ext.prebid.fledge: this is very different. It seems unlikely that the IAB will accept this entire complex structure and we don't want to end up partly conflicting with their final recommendation.

Marking this ready-for-dev.

[dmdabbs]

apparently that's not an official IAB extension

Regarding Imp.ext.ae and IG auction signaling moving forward, see the proposed IG signaling in public comment:

PR: InteractiveAdvertisingBureau/openrtb2.x#86
Public Comment Issue: InteractiveAdvertisingBureau/openrtb2.x#83

[SyntaxNode]

We will open a new issue and implement the new signals as part of OpenRTB 2.6 202312.