Proposal - GPT Pre-Auction module

[caitlinwright123]

This is a followup to the pbAdSlot feature covered in #4149

Background

PbAdSlot’s current solution solved the issue of publishers having no consistent inventory identifier passed to each bidder that can be used for reporting and deal targeting, but if there is a predefined value of 'pbadslot', the GAM ad unit is not also passed.

Problems to Solve

This update to PbAdSlot is attempting to solve the following:
Publishers passing PbAdSlot are not necessarily passing GAM ad unit

• The current solution allows publishers to define the field, and in that scenario, GAM ad unit is not passed. This is needed for publishers to compare inventory across other potential integration types.
• Low adoption rates

Proposal

We propose a new 'GPT Pre-Auction" module:

1. accept optional initialization parameters:
   -ability to turn off module (on by default)
   -customGptSlotMatching function
   -customPbAdSlot function
2. if the module is on, use the BEFORE_REQUEST_BIDS hook to define a function that:
3. loops through each adunit in the auction
   -maps the adunit to the GPT slot using the same algorithm as setTargetingForGPTAsync including customGptSlotMatching
   -if GPT slot matching succeeded:
   --set fpd.context.adserver.name to 'gam'
   --copy the resulting GPT slot name to fpd.context.adserver.adSlot
   -if customPbAdSlot function was specified, invoke it, writing the results to fpd.context.pbAdSlot.
   -Else use a default algorithm to determine fpd.context.pbAdSlot:
   --First use the AdUnit's context.pbAdSlot if defined
   --Else, see if the AdUnit.code corresponds to a div and if so, try to retrieve a data element from the div called data-adslotid.
   --Else if the GPT slot matching succeeded, use the GPT slot name
   --Else, just use the AdUnit.code, assuming that that's the ad unit slot

We also need to update the prebidServerBidAdapter to:

• pass fpd.context.adserver.name in the OpenRTB as imp[].ext.context.data.adserver.name
• pass fpd.context.adserver.adSlot in the OpenRTB as imp[].ext.context.data.adserver.adslot
• at some point we may change to pass fpd.context.pbAdSlot in the OpenRTB as imp[].ext.context.data.pbadslot. But this would be a breaking change and PBS will need time to get ready for it.

[patmmccann]

is this related to line 39 here?

https://github.com/prebid/Prebid.js/blob/master/modules/33acrossBidAdapter.js

[bretg]

No - this is an evolution of http://prebid.org/features/pbAdSlot.html

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[bretg]

Ok, we need to hammer out the config for this. Here's a straw:

pbjs.setConfig({
  gptPreAuction: {
    enabled: true,
    customGptSlotMatchingFunction: function(slot) {
       // This should work similarly to the customSlotMatching argument of
       // https://prebid.org/dev-docs/publisher-api-reference.html#module_pbjs.setTargetingForGPTAsync
    },
    customPbAdSlotFunction: function(adunit) {
      // this is the same as described in https://prebid.org/features/pbAdSlot.html
    }
  }
});

Notes:

• There's precedence for putting functions in config. See s2sConfig. syncUrlModifier
• Debating the name of this data: gpt-pre-auction? Or gptPreAuction? Or add another layer like modules.gptPreAuction?

[msm0504]

@bretg I'd prefer to call it gptPreAuction since all of the other config properties are camelcase.

Also, a couple notes on the custom function params:

customGptSlotMatchingFunction should be function(adUnitCode). For targeting, each slot is being matched to an ad unit. Since the input from the hook is the list of ad units, this module will work the other way: loop over the ad units and try to match each to a slot. The function should return a filter function for slot.

Does customPbAdSlotFunction need the entire ad unit? I was planning to have the input to the function be the ad unit code and expect the function to return the pbAdSlot value.

[bretg]

The pseudo-code I had in mind is basically the core of what PBJS does in targeting.setTargetingForGPT. In that context, the customSlotMatching functions have access to both the AdUnit and the proposed GPT slot

1. hook into BEFORE_REQUEST_BIDS with a function
2. that function checks the enabled flag
3. then loops through the ad units are involved in the auction
   3a. Loop through GPT ad slots
   3a1. If there's a customSlotMatching function call it, else call isAdUnitCodeMatchingSlot
   3a2. once we find a match
   3a3a. set fpd.context.adserver.name="gam", fpd.context.adserver.adSlot
   3a3b. if there's a customPbAdSlotFunction, call it, else call the default. Either way, set fpd.context.pbAdSlot
   3a.3c. exit the GPT loop

[robertrmartinez]

Assigning to @msm0504 as I believe he has begun the work

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[bretg]

Added a task to update the pbsBidAdapter so these values can make it server-side as well.