Module fledgeForGpt: Document AuctionConfig fields

[maxime-dupuis]

Other than the addition of the bidId field, the AuctionConfig object should adhere to the requirements set forth in FLEDGE. The details of creating an AuctionConfig object are beyond the scope of this document.

FledgeForGpt module being the API between bidder adapters and GPT, I think this documentation would be improved by explicitly documenting the supported AuctionConfig fields:

• Field name
• Definition
• Type and accepted values

Currently it's unclear to me

• if fledgeForGpt supports
  • only the fields from the GPT reference (which seems suggested by this Prebid.js code using Googletag's Slot.setConfig
  • or all fields documented in turtledove/Fledge.md ("the AuctionConfig object should adhere to the requirements set forth in FLEDGE")
• and if the names are case sensitive (Url VS URL)

Here's a diff of the fields between the 2 documentations:

[laurb9]

The fledgeForGpt module and Prebid.js treat the auctionConfig as a blob received from adapters, to be passed to the GPT slot. It does not concern itself with any other fields than seller needed in setSlot. GPT itself moves these blobs into componentAuctions the same way. GPT published spec lags behind but their actual implementation does not.

The authority onAuctionConfig seems to be what navigator.runAdAuction supports, and the best place to look is the FLEDGE doc with more details in the WICG spec.

To me, the differences noted above show a good reason why incorporating the AuctionConfig specification in the fledgeForGpt documentation in any way other than by reference is likely to result in yet another lagging spec to foster confusion. Maybe at this time it's more beneficial to have many pointers to one authoritative spec than many copies with varying degrees of fidelity to it.

[maxime-dupuis]

Thanks for confirming that the GTP spec lags, we'll follow the FLEDGE/WICG spec :)

I agree to not duplicate yet another doc and risk it getting outdated

If Prebid can guarantee the module will always be in sync with the FLEDGE doc, we can work with that

[patmmccann]

fwiw the right hand part of the chart is not valid for the component seller, as there are no sub-components

[bretg]

@maxime-dupuis - there's a new version of this page at #5135 - please take a look at the preview if you have a few mins to see if it addresses your concerns.

[maxime-dupuis]

@maxime-dupuis - there's a new version of this page at #5135 - please take a look at the preview if you have a few mins to see if it addresses your concerns.

@bretg I do like the new structure and how you separated the PAAPI vs PAAPI for GPT doc

But to answer your question, as a bid adapter maintainer, it neither improves nor worsen my understanding about the shape of the AuctionConfig object.

the AuctionConfig object should adhere to the requirements set forth in PAAPI is pretty vague and doesn't link to the appropriate documentation.

Even if it did, the PAAPI doc is just a big confusing wall of text. (I don't expect Prebid to fix that, that one is on Google)

[bretg]

the shape of the AuctionConfig object

So what exactly do you mean by this @maxime-dupuis ?

If you're looking for "which fields should I specify in my auctionconfig", that's not for Prebid to decide or document.

If you're looking for "does Prebid care what fields are in the auction config", the answer is clearly no -- Prebid does not validate anything in this opaque object.

If you're looking for "does Prebid add anything to auctionconfig", I believe the answer is yes, Prebid.js adds a "bidfloor" to the auctionconfig since I see deepSetValue(cfg, 'auctionSignals.prebid.bidfloor', bidfloor); but not sure the docs are clear on this point... @dgirardi ?

[maxime-dupuis]

what exactly do you mean by this

"which fields should I specify in my auctionconfig"

that's not for Prebid to decide or document

I understand and agree. I propose that Prebid should link to the external documentation

[bretg]

Cool, but link to where? The PR already has several links to https://github.com/WICG/turtledove/blob/main/FLEDGE.md -- are you suggesting that since it's such a large doc, that linking to https://github.com/WICG/turtledove/blob/main/FLEDGE.md#21-initiating-an-on-device-auction might be useful? With what text -- something like "Prebid can't tell you what fields to include in auctionconfig, but you can start by looking in this section of the PAAPI documentation."

[maxime-dupuis]

Right on! That would be great

[bretg]

Ok, updated the PR with this note. Thanks.