From 38776fb3eeb828d933a225bf3f0dce11428be700 Mon Sep 17 00:00:00 2001 From: bretg Date: Mon, 24 Aug 2020 23:12:13 -0400 Subject: [PATCH] adding example config to GPT pre-auction (#2270) --- dev-docs/modules/gpt-pre-auction.md | 57 +++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 12 deletions(-) diff --git a/dev-docs/modules/gpt-pre-auction.md b/dev-docs/modules/gpt-pre-auction.md index 4e7f20e5e5..9f75d69752 100644 --- a/dev-docs/modules/gpt-pre-auction.md +++ b/dev-docs/modules/gpt-pre-auction.md @@ -5,7 +5,7 @@ title: Module - GPT Pre-Auction description: Adds PB Ad Slot and matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters module_code : gptAPreAuction display_name : GPT Pre-Auction -enable_download : false +enable_download : true sidebarType : 1 --- @@ -17,33 +17,66 @@ sidebarType : 1 ## Overview -When enabled, this module will add PB Ad Slot and matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters. +This module enables targeting and tracking at the ad server adunit level. -* **Prebid Server Adapter** - pass `fpd.context.adserver.name` in the OpenRTB as `imp[].ext.context.data.adserver.name`, and pass `fpd.context.adserver.adSlot` in the OpenRTB as `imp[].ext.context.data.adserver.adslot` +Enabled by default if compiled into your package, this module will add the [Prebid Ad Slot](/features/pbAdSlot.html) and matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters. -## How It Works +* **Prebid.js Adapters** - will be able to utilize these values as: + * AdUnit.fpd.context.adServer.name="gam" + * AdUnit.fpd.context.adServer.adSlot="/1111/home" + * AdUnit.fpd.context.pbAdSlot="/1111/home-left" +* **Prebid Server Adapters** - will see the OpenRTB as: + * imp[].ext.context.data.adserver.name + * imp[].ext.context.data.adserver.adslot + * imp[].ext.context.data.pbadslot + +## Configuration + +{: .alert.alert-info :} +Unlike many other modules, the GPT Pre-Auction Module is on by default if it's compiled +into the Prebid.js package. -Accepts optional initialization parameters: +Optional initialization parameters: -- ability to turn off module (on by default) +- enabled (on by default) - customGptSlotMatching function - customPbAdSlot function -If the module is on, use the BEFORE_REQUEST_BIDS hook to define a function that: +``` +pbjs.setConfig({ + gptPreAuction: { + enabled: true, // enabled by default + customPbAdSlot: function(adUnitCode, adServerAdSlot) { + ... + return "customPbAdSlot"; + }, + customGptSlotMatching: function(gptSlotObj) { + ... + return true; // or false + } + } +}); +``` + +## How It Works + +When this module is on, it uses the BEFORE_REQUEST_BIDS event to insert functionality that: - 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: +If GPT slot matching succeeds: -- set fpd.context.adserver.name to 'gam' -- copy the resulting GPT slot name to fpd.context.adserver.adSlot +- it sets fpd.context.adserver.name to 'gam' +- it copies the resulting GPT slot name to fpd.context.adserver.adSlot -If customPbAdSlot function was specified, invoke it, writing the results to fpd.context.pbAdSlot. If not, use a default algorithm to determine fpd.context.pbAdSlot: +The customPbAdSlot function is called if it was specified, writing the results to fpd.context.pbAdSlot. +If there's no customPbAdSlot, a default algorithm is used 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 -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. +# Further Reading +- [Prebid Ad Slot](/features/pbAdSlot.html)