Add onBidWon handler to bid adapters spec

[Spark-NF]

Type of change

• Feature
• Does this change affect user-facing APIs or examples documented on http://prebid.org?

Description of change

Some bid adapters might want to know when their bid won the auction. Given listening to events is off-limits for bid adapters, they can now add a onBidWon handler to their spec that will be called with their winning bid.

Corresponding PR for documentation: prebid/prebid.github.io#864.

[jsnellbaker]

@Spark-NF Thanks for submitting this PR.

Based on some internal discussion, would it be possible to convert this new field to only handle a pixel URL that would be fired if the bidder won rather than allow a free-form callback method?

It's likely (unless there's some use-case I'm not aware of) that bidders would ultimately just want to fire off this pixel when they won. So having the field setup to handle this call directly rather than setup customized code (that would need to be reviewed each time) would be more conducive.

Please me let me know your thoughts on this. Thanks

[Spark-NF]

@jsnellbaker I see where you're coming from with this. Indeed, firing pixels would be a very common use of this handler, and I see how having a way to simply provide URLs (or a method that returns them after building them) would be useful. However, I don't think bid adapters should be limited to this.

In our case for example, we prefer not to generate an additional network call (to not flood the publisher nor the user), and keep the information that would possibly be passed in the pixel (in this case "our bid won") in the localStorage. Then, in the next call, we would send this information along with our bid request, effectively only ever causing a single XHR. This sometimes causes loss of information (if the user doesn't cause another bid request), but as we only use this information for monitoring purposes (not billing), we find this to be an acceptable compromise, and a win-win for everyone.

[jsnellbaker]

@Spark-NF Thanks for the additional feedback/context, those were some valid points.

LGTM.

[mkendall07]

LGTM. Thanks!