Added docs for #2562

[ptomasroos]

prebid/Prebid.js#2562 @mkendall07

[bretg]

Sorry - while I get the general request for flexibility here, don't fully follow how this would be utilized. Please provide an example use case in this doc.

[ptomasroos]

Do you mean something like this https://github.com/prebid/Prebid.js/pull/2562/files#diff-f8e049a1b6d4f9aa96fca41d2f7aa11dR159 or a new example file ?

[bretg]

I mean a short example illustrating it's use. Not the implementation. Doesn't have to be a separate file.

[bretg]

@ptomasroos -- anything else you can provide as to the use of this feature?

[ptomasroos]

Yeah of course. We use it infinite scrolling when we don’t know what the div will be named at the point of when a auction is finished. Since someone might have scrolled in the list. Then we use that to map to what’s visible in the viewport @bretg

[bretg]

Ok @ptomasroos - I took a stab at reverse engineering what's happening here enough to come up with an example that made more sense to me than "return slot => { return adUnitCode => { return slot.getSlotElementId() === 'myFavoriteDivId'; } };" Sorry, I'm slow on this -- functional programming is not my forte.

We use it infinite scrolling when we don’t know what the div will be named at the point of when a auction is finished. Since someone might have scrolled in the list. Then we use that to map to what’s visible in the viewport

Is the function below a realistic use case?

// returns a filter function that matches the current slot to the adUnitCode, but only when that
// slot is in view according to the divInView() function
function pickInViewDiv(slot) {
   return function(adUnitCode) {
        return adUnitCode === slot.getAdUnitPath() &&
                    divInView(slot.getSlotElementId()); }
};

// force the matching of the AdUnit targeting to a slot having the right name, but also being in view
setTargetingForGPTAsync(adUnit, pickInViewDiv);

[ptomasroos]

Sorry for forgetting this! Will reply today

[ptomasroos]

This is more a realistic description @bretg

Does it make sense?

// returns a filter function that matches either with the slot or the adUnitCode
// this filter function is being invoked after the auction has completed
// this means that it can be used in order to place this within viewport instead of a static div naming 
// which regular classic setup allows (by default the its looking for a div id named same as the adUnitCode)

// slot is in view according to the divInView() function
function pickInViewDiv(slot) {
   return function(adUnitCode) {
        return adUnitCode === slot.getAdUnitPath() &&
                    divInView(slot.getSlotElementId()); }
};

// make sure we render the results from the auction in a div that is visible in the viewport (example infinite scrolling, instead of rendering a ad in the top of the list that will never be visible (made up example))

setTargetingForGPTAsync(adUnit, pickInViewDiv);

[ptomasroos]

The reason why this exists is to allow greater flexibility in order to decide when the auction has finished in which div id "placeholder" the ad results should render into.

Since a auction may have a init time of xxx ms and then also run for xxxx ms. This closes the gap in some design decisions in order to avoid having to set the timeout of auctions so short to make sure they get good viewability. Instead the logic can find a good placement for the auction result depending on where the user is at and how much time the auction took to complete.

[bretg]

thanks - makes sense now. Added some words describing the use case.