Add Adserver Targeting based on bid response info & custom placement data

onBeforeAdRequest & placement tag fields

Overview

This article outlines a method by which a publisher can add adserver targeting to their adserver call based on the results of an auction & the presence of custom placement data (Placement Tag Fields). 

This example involves the use of the 'onBeforeAdRequest' callback. A callback function invoked after the Prebid auction is done and immediately before the ad request is initiated. 

Using the onBeforeAdRequest exposes the auction.usedUnitDatas object from which we can garner both bid response information & placement data information. We can use both of these to decide if there should be extra targeting information set in the adserver call.

This is a particularly useful method when the publisher wishes to setup certain creative / ad slot / rendering rules based on the outcome of the auction. 

Code

relevantDigital.addAuctionCallbacks({
    onBeforeAdRequest: ({ auction }) => {  //retrieve auction object after bids back & before GAM call
        auction.usedUnitDatas.forEach((usedUnit) => {
            const { adUnit, slot } = usedUnit;  //take the pbjs 'adUnit' object, RY adunit info & the gpt 'slot' functions
            const bidOf = usedUnit.getHighestBid()?.bidder;  //retrieve bidder info for highest bid
            const placementData = adUnit.data.custom;  //check if adunit has custom data
                if(placementData && ["bidder1", "bidder2", "bidder3"].includes(bidOf)) {  //check the winning bidder and placement data
                    slot.setTargeting("customTgt","true");  //setTargeting to the GAM slot
                }
            });
        }
});

Walk-through

Opposed to demonstrating the usecase in relevantDigital.loadPrebid(), the code is using relevantDigital.addAuctionCallbacks instead. The addAuctionCallbacks function is useful for implementing callback functions in scenarios where it may not be possible to edit relevantDigital.loadPrebid(). 

onBeforeAdRequest is a function invoked after the auction and before the ad request is initiated. It yields an auction object that contains a 'usedUnitDatas' array of objects that have participated in the auction. For each of these 'usedUnits' we would then like to retrieve the 'adUnit' & 'slot' objects.

The 'adUnit' object exposes all the information on the placement setup via the Yield interface, including that passed via a placement tag field, your custom data. 

The 'slot' object provides access to all the google publisher tag functions.

From each 'usedUnit' we can use the getHighestBid function to retrieve information on the highest bid, from which we can retrieve the bidder name. 

Similarly we can retrieve any custom placement data from the adUnit.data object. 

If there is custom placement data & the highest bidder is either one of 'bidder1', 'bidder2' or 'bidder3' then the gpt setTargeting function is used on the 'slot' to pass extra targeting.