Ad Server KVP update to dev (#3456)

* Create generic bidder documentation (#3413)

* Fixed typo

* Added Generic bidder docs

* iProm Bid Adapter: update versions included (#3420)

per pr -> prebid/Prebid.js#7700

* add first-party data support to beachfront doc (#3418)

Co-authored-by: John Salis <john@beachfront.com>

* new bidderSettings field - allowZeroCpmBids (#3414)

* add native support (#3409)

* Missena Bid Adapter: update with prebid compliance (#3408)

* Missena Bid Adapter: update with prebid compliance

per pr -> prebid/Prebid.js#7648

* update versioning to include not in 5.x

* Add Intersection RTD Provider docs (#3407)

* upd docs

* Update dev-docs/modules/intersectionRtdProvider.md

Co-authored-by: Andrew <fowler446@users.noreply.github.com>

* Limelight Digital Bid Adapter: Add optional Publisher ID field (#3405)

* smartx Bid Adapter: refactor descriptions and adding "visibilityThreshold" (#3403)

* initial commit

* adjustments

* adjustments

* adjustments

* typo, further adjustments

* removed userIds and schain support

* Added optionals to outstream and made formatting

* Update smartx.md

minor edits for clarification and readability.

* adjusted outstream_options

* remove outstream_function, added pbjs_version_notes

* bugfix outstream options for default outstream renderer configuration

* refactor descriptions and adding "visibilityThreshold"

Co-authored-by: Gino <adtech@smartclip.tv>
Co-authored-by: Jean Stemp <38964447+jeanstemp@users.noreply.github.com>

* VIS.X: update docs (#3402)

Update the VIS.X documentation under the latest adapter changes.

* Adplus bid adapter doc added (#3389)

* Adplus bid adapter doc added

* Quotes added to string arguments

Co-authored-by: TCCDENIZ <cansin.deniz@turkcell.com.tr>

* Created gb_xandr.md docs (#3384)

* Create gb_xandr.md

* renamed the file

* Update dev-docs/bidders/goldbach.md

Co-authored-by: Andrew <fowler446@users.noreply.github.com>

* Lupon Media Bid Adapter: update prebid 5 complianc (#3347)

* Lupon Media Bid Adapter: update prebid 5 complianc

per pr -> prebid/Prebid.js#7458

* update not in 5.x

* Update userId.md (#2788)

* gpid docs (#3421)

* fixed broken link (#3423)

* fixed floors doc issue (#3425)

* added api version note (#3434)

* Interstitials (#2869)

* removed sizes from RP bid params

* added interstitial page and config to adUnit

* interstitial page corrections

* Update InterstitialAds.md

* Update InterstitialAds.md

* modified sidebar link

* changed interstitials file name and reference

* wordsmithing

Co-authored-by: MartianTribe <steve@martiantribe.com>
Co-authored-by: bretg <bgorsline@gmail.com>

* added vendor-specific flag (#3437)

* added KVP reference

* review comments

* adding link to related reading

Co-authored-by: Alex Maltsev <and1sscsgo@gmail.com>
Co-authored-by: Chris Huie <phoenixtechnerd@gmail.com>
Co-authored-by: John Salis <jsalis531@gmail.com>
Co-authored-by: John Salis <john@beachfront.com>
Co-authored-by: jsnellbaker <31102355+jsnellbaker@users.noreply.github.com>
Co-authored-by: AdmixerTech <35560933+AdmixerTech@users.noreply.github.com>
Co-authored-by: Andrew <fowler446@users.noreply.github.com>
Co-authored-by: Ilya Medvedev <medved55rus@gmail.com>
Co-authored-by: Skylinar <53079123+Skylinar@users.noreply.github.com>
Co-authored-by: Gino <adtech@smartclip.tv>
Co-authored-by: Jean Stemp <38964447+jeanstemp@users.noreply.github.com>
Co-authored-by: rrelict <rrelict@users.noreply.github.com>
Co-authored-by: cnsndnz <82813495+cnsndnz@users.noreply.github.com>
Co-authored-by: TCCDENIZ <cansin.deniz@turkcell.com.tr>
Co-authored-by: dveljovicTX <69788339+dveljovicTX@users.noreply.github.com>
Co-authored-by: Patrick McCann <patmmccann@gmail.com>
Co-authored-by: Bryan Szekely <49168870+bszekely1@users.noreply.github.com>
Co-authored-by: MartianTribe <steve@martiantribe.com>

adops/before-you-start.md

@@ -126,5 +126,6 @@ Implementing header bidding requires much more collaboration with your dev team
 ## Related Topics
 
 - [Getting Started with Prebid.js](/overview/getting-started.html): How Prebid.js works at a high level.
+- [Prebid.js and Ad Server Key Values](/features/adServerKvps.html)
 - [What is Prebid?](/overview/intro.html): Overview and history of header bidding and Prebid.js.
 + [Docs by Format](/dev-docs/docs-by-format.html): Engineering and ad ops docs arranged by ad format (video, native, etc.).

features/adServerKvps.md

@@ -23,19 +23,79 @@ Here's the general way PBJS is integrated into the page:
 1. Set auction parameters
 1. Initiate the auction
 1. Gather bid responses to send to the ad server
+1. The ad server makes the final decision about which ad to render
 
 This last step has historically been called "targeting" in Prebid.js, but really what's
 sent to the adserver is a set of Key Value Pairs (KVPs) that serve several purposes:
 - **Ad server line item targeting**. These values are used to pick out which line items match the request. Generally targets depend on the hb_pb attribute, but could also include hb_deal and hb_format.
 - **Display**. Some of these values are needed for rendering the creative properly when the Prebid line item is chosen, including hb_adid, hb_uuid, hb_size, and for AMP/app hb_cache_host.
 - **Reporting**. Some publishers rely on ad server key-values for important business reporting. The keys used for reporting could be any of the above, along with hb_source.
 
+## Decide How The Results Will Be Used
+
+How a publisher should configure Prebid.js to report auction results
+will depend on how the final ad decision will be made. These approaches
+need to be in sync.
+
+There are four main scenarios that follow.
+
+### Ad Server Line Items are Created Per-Bidder
+
+In order to have header bidding compete with direct-sold demand,
+a publisher can set up placeholder line items in their ad server.
+
+Prebid.org recommends setting up separate line items
+for each bidder. Benefits:
+- use ad server reporting to get a view of which bidders are performing well
+- control ad decisions with the ad server
+- video bids have a fallback available
+
+There are more details on this scenario in the [Ad Ops section](/adops/before-you-start.html#one-set-of-line-items-for-each-bidder).
+
+Once implemented in the ad server, setting this up in Prebid.js is
+simple, as it is the default [Send All Bids](#send-all-kvps) mode. However
+to limit the number of values sent to the ad server, some flavor of
+this solution like the [Top Two Bids and Deals](#top-two-bids-and-deals)
+may be of interest. 
+
+{: .alert.alert-info :}
+Note that `enableSendAllBids` mode can send a lot of keys to your
+ad server. Though we recommend this setting, we also recommend that
+publishers monitor the key traffic and [control](#controls) as necessary.
+
+### Only One Set of Ad Server Line Items are Created
+
+However, there are reasons a publisher may not want to create
+separate line items for each bidder:
+- some ad servers have a limit on how many line items can be created
+- it takes work to set up line items
+- the volume of key-value pairs can be a factor
+
+So the other ad-server based solution is to create one set of line
+items that is used by all bidders.
+
+Setting this mode up in Prebid.js is done by setting [enableSendAllBids](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-All-Bids)
+to false. See the [Bare Minimum solution](#the-bare-minimum-for-display-ads) for reference.
+
+### Post-Bid
+
+Sometimes Prebid.js is used as a fallback. This mode is called [PostBid](/overview/what-is-post-bid.html)
+
+In this scenario, the ad server line item is scheduled as a low-priority 'remnant' and the auction takes place when there's nothing else to serve.
+The Prebid.js code is in the ad server creative, which decides the overall winner itself. See the [Post Bid Example](/dev-docs/examples/postbid.html).
+
+### No Ad Server
+
+Finally, a publisher may want a particular ad unit to be programmatic-only, which Prebid.js can support.
+Please see the [No Ad Server Example](https://github.com/prebid/Prebid.js/blob/master/integrationExamples/noadserver/basic_noadserver.html).
+
 ## Obtaining Auction Results
 
 ### Display and Native
 
-In the early versions of Prebid.js, there were a couple of basic functions
-publishers could use to get the 
+In early versions of Prebid.js, there were a couple of basic functions
+publishers could use to get the auction results:
+
 - [pbjs.setTargetingForGPTAsync](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) - matches Google Publisher Toolkit ad slots to Prebid.js AdUnits, obtains the auction results for that adunit, and adds "targeting" values using GPT-provided functions.
 - [pbjs.getAdserverTargeting](/dev-docs/publisher-api-reference/getAdserverTargeting.html) - a more generic interface for obtaining KVPs
 
@@ -57,9 +117,19 @@ Publishers using other ad servers need to integrate on their own
 using the [pbjs.getAdserverTargetingForAdUnitCode](/dev-docs/publisher-api-reference/getAdserverTargetingForAdUnitCode.html) function to build whatever
 needed to pass to the video player.
 
+### Mobile App
+
+The Prebid SDK does not have a direct way to control what key-value pairs will
+be generated by Prebid Server. Instead, the [top-level stored request](/prebid-server/features/pbs-storedreqs.html) stored in Prebid Server defines what should be produced.
+
+That stored request will contain the 'targeting' options needed to
+match the line item setup. See the [Prebid-Server-based
+targeting configuration](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#ad-server-targeting), for more detail. The rest of this document is about Prebid.js.
+
 ## Controls
 
-Over the years, quite a few options have been added to adjust the number of bids and the exact set of KVPs sent to the ad server. This is an overlapping-but-powerful set of controls. There are often
+Over the years, quite a few options have been added to to Prebid.js to adjust the number of bids and the exact set of KVPs sent to the ad server. This is an overlapping-but-powerful set of controls. There are often
+
 multiple ways to implement the same requirements, and there's no "wrong"
 way to do it.