New function markWinningBidAsUsed for marking video bids

[Caspervw]

Type of change

• Feature

Description of change

In accordance with the discussion in #2282 I’ve created a new function that’s capable of marking a winning bid as used. This addresses the issue where a video-advertisement can be played multiple times on the same page. By proactively calling pbjs.markWinningBidAsUsed the winning video-bid can be marked as consumed. We currently use it in production and call it straight after the buildVideoUrl function. It resolved most of our discrepancy issues video header bidding partners.

Documentation update: prebid/prebid.github.io#861

[mkendall07]

@Caspervw
Can you make this accept an object instead of a string?
I'm thinking we would also want to match against a bidId as well as a adUnitCode.
example:

{
  adUnitCode : <code>,
  bidId : <id>
}

[Caspervw]

Sure thing

[Caspervw]

@mkendall07 I made the change, however I wonder if it became better. If you look at the snippet we now explicitly need to know which bid we’re going to mark. This improves the robustness, however (as far as I know) there is no exposed version of targeting.getWinningBids(adUnitCode);, so which bid did prebid start and what do we need to mark?

Do you think pbjs.getHighestCpmBids() is the best approach for that? What do you recon needs to go on the ...?

pbjs.requestBids({
    bidsBackHandler: function(bids) {
        // The video advertisement you want to show
        const bid = ...

        var videoUrl = pbjs.adServers.dfp.buildVideoUrl({
            adUnit: videoAdUnit,
            bid: bid
            params: {
                iu: '/19968336/prebid_cache_video_adunit'
            }
        });

        // Mark the bid, used in buildVideoUrl, as used
        pbjs.markWinningBidAsUsed({
            adUnitCode: videoAdUnit.code
            adId: bid.adId
        });

        invokeVideoPlayer(videoUrl);
    }
});

[mkendall07]

@Caspervw
Thanks. I actually mean those as to be only one required.
ie - find the highest bid on the AdUnit:

 pbjs.markWinningBidAsUsed({
            adUnitCode: videoAdUnit.code
        });

or find exact bid:

 pbjs.markWinningBidAsUsed({
            adId: bid.adId
        });

if both are specified, then both must match.

[Caspervw]

@mkendall07 Pushed the requested changes.

[mkendall07]

LGTM. Thanks for updating!

[snapwich]

LGTM