PBS feature update (prebid#3869)

AuDigent · Aug 31, 2023 · 96eed86 · 96eed86
1 parent 44b9b18
commit 96eed86
Show file tree

Hide file tree

Showing 4 changed files with 61 additions and 26 deletions.
diff --git a/prebid-server/endpoints/openrtb2/pbs-endpoint-amp.md b/prebid-server/endpoints/openrtb2/pbs-endpoint-amp.md
@@ -93,7 +93,7 @@ An example Stored Request is given below:
 Note that other ext.prebid extensions can be specified in the stored request such as:
 - [ext.prebid.currency](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#currency-support)
 - [ext.prebid.aliases](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#bidder-aliases)
-- [ext.prebid.multibid](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#multibid-pbs-java-only)
+- [ext.prebid.multibid](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#multibid)
 - etc.
 
 #### First Party Data

diff --git a/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md b/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md
@@ -757,7 +757,10 @@ ext.prebid.data.eidpermissions is an array of objects that can contain these att
 | source | Yes | Which user.ext.eids.source is receiving the permissions | "sharedid.org" | string |
 | bidders | Yes | Which bidders are allowed to receive the named eid source | ["bidderA", "bidderC"] | array of strings |
 
-##### Rewarded Video (PBS-Java only)
+##### Rewarded Video
+
+{: .alert.alert-info :}
+PBS-Java only
 
 Rewarded video is a way to incentivize users to watch ads by giving them 'points' for viewing an ad. A Prebid Server
 client can declare a given adunit as eligible for rewards by declaring `imp.ext.prebid.is_rewarded_inventory:1`.
@@ -768,7 +771,7 @@ The OpenRTB `test` flag has a special meaning that bidders may react to: they ma
 
 You can turn on the extra Prebid Server debug log without the formal `test` behavior by instead setting `ext.prebid.debug: true`.
 
-##### Stored Responses (PBS-Java only)
+##### Stored Responses
 
 While testing SDK and video integrations, it's important, but often difficult, to get consistent responses back from bidders that cover a range of scenarios like different CPM values, deals, etc. Prebid Server supports a debugging workflow in two ways:
 
@@ -1028,7 +1031,10 @@ Prebid Server enforces data permissioning. So before passing values to the bidde
 
 Each adapter must be coded to read the values from the ortb and pass it to their endpoints appropriately.
 
-##### Custom Targeting (PBS-Java only)
+##### Custom Targeting
+
+{: .alert.alert-info :}
+PBS-Java only
 
 An OpenRTB extension, whether in the the original request or the [stored-request](/prebid-server/features/pbs-storedreqs.html), can customize the ad server targeting generated by PBS.
 
@@ -1088,7 +1094,10 @@ In order to pull AMP parameters out into targeting, Prebid Server places AMP que
 }
 ```
 
-##### MultiBid (PBS-Java only)
+##### MultiBid
+
+{: .alert.alert-info :}
+PBS-Java only
 
 Allows a single bidder to bid more than once into an auction and have extra bids passed
 back to the client.
@@ -1170,7 +1179,10 @@ Here's an example response:
 }
 ```
 
-##### Echo StoredRequest Video Attributes (PBS-Java only)
+##### Echo StoredRequest Video Attributes
+
+{: .alert.alert-info :}
+PBS-Java only
 
 Several video specific fields can be set in the Stored Request that
 the device player would not have context to at time of render.
@@ -1228,7 +1240,22 @@ which causes PBS-core to place the video-related attributes on the response.
 }
 ```
 
-##### PG Deals Extensions (PBS-Java only)
+##### Request Passthrough
+
+{: .alert.alert-info :}
+PBS-Java only
+
+In support of the Prebid SDK, PBS supports a simple passthrough mechanism:
+
+If the bidrequest contains ext.prebid.passthrough
+simply copy that object to the bidresponse ext.prebid.passthrough with no validation other than it being valid JSON.
+
+The initial use is for the SDK to define render-time parameters, but this mechanism may find use in other applications.
+
+##### PG Deals Extensions
+
+{: .alert.alert-info :}
+PBS-Java only
 
 In support of [Programmatic Guaranteed](/prebid-server/features/pg/pbs-pg-idx.html),
 there are two extensions at the bidder level to control behavior:
@@ -1363,7 +1390,10 @@ This contains the request after the resolution of stored requests and implicit i
 }
 ```
 
-##### Original Bid CPM (PBS-Java only)
+##### Original Bid CPM
+
+{: .alert.alert-info :}
+PBS-Java only
 
 `response.seatbid[].bid[].ext.origbidcpm` and `response.seatbid[].bid[].ext.origbidcur` will contain the original bid price/currency from the bidder.
 The value in seatbid[].bid[].price may be converted for currency and adjusted with a [bid adjustment factor](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#bid-adjustments).
@@ -1436,35 +1466,37 @@ The Prebid SDK version comes from:
 | req | imp[].ext.prebid. bidder.BIDDER | bidder parameters | object | imp[].ext. prebid.bidder. biddera: { placement: 123 } | They see the object as imp[].ext.bidder |
 | req | imp[].ext.BIDDER | DEPRECATED place to put bidder parameters | object | imp[].ext. prebid.bidder. biddera: { placement: 123 } | They see the object as imp[].ext.bidder |
 | req | imp[].ext.prebid. storedrequest.id | look up the defined stored request and merge the DB contents with this imp | object | see [stored requests](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#stored-requests) | no |
-| req | imp[].ext.prebid. storedauctionresponse | PBS-Core skips the auction and uses the response in the DB instead | object | see [stored responses](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#stored-responses-pbs-java-only) | no |
-| req | imp[].ext.prebid. is_rewarded_inventory | passed through to bid adapters | integer | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#rewarded-video-pbs-java-only) | yes |
+| req | imp[].ext.prebid. storedauctionresponse | PBS-Core skips the auction and uses the response in the DB instead | object | see [stored responses](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#stored-responses) | no |
+| req | imp[].ext.prebid. storedbidresponse | PBS-Core calls the adapter with the response in the DB instead of actually running the auction. | object | see [stored responses](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#stored-responses) | no |
+| req | imp[].ext.prebid. is_rewarded_inventory | passed through to bid adapters | integer | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#rewarded-video) | yes |
 | req | imp[].ext.data.ATTR | Publisher-specific adunit-level first party data | any | "pmp_elig": true | yes |
 | req | app.ext.source | defined by Prebid SDK | string | "prebid-mobile" | yes |
 | req | app.ext.version | defined by Prebid SDK | string | "1.6" | yes |
 | req | ext.prebid.bidadjustmentfactors | Adjust the CPM value of bidrequests | object | See [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#bid-adjustments) | no |
 | req | ext.prebid.bidderparams | Publishers can specify any adapter-specific cross-impression attributes. | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#global-bid-adapter-parameters) | no |
 | req | ext.prebid.targeting | defines the key-value pairs that PBS-core places in seatbid.bid.ext.prebid.targeting | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) | no |
-| req | ext.prebid.adservertargeting | advanced targeting value rules | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#custom-targeting-pbs-java-only) | no |
+| req | ext.prebid.adservertargeting | advanced targeting value rules | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#custom-targeting) | no |
 | req | ext.prebid.integration | host-dependent integration type passed through to events and analytics | string | "managed" | yes |
 | req | ext.prebid.channel | Generally "pbjs", "amp", or "app". Passed through to events and analytics | object | {name: "pbjs", version: "4.39"} | yes |
 | req | ext.prebid.aliases | defines alternate names for bidders | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#bidder-aliases) | no |
 | req | ext.prebid.aliasgvlids | defines the global vendor list IDs for aliases | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#bidder-aliases) | no |
 | req | ext.prebid.debug | provides debug output in response | boolean | true | yes |
 | req | ext.prebid.cache | defines whether to put bid results in Prebid Cache | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#cache-bids) | no |
 | req | ext.prebid.schains | bidder-specific supply chains | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#supply-chain-support) | no |
-| req | ext.prebid.data.bidders | bidders in scope for bidder-specific first party data | array of strings | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#first-party-data-support-pbs-java-only) | no |
-| req | ext.prebid.bidderconfig | bidder-specific first party data | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#first-party-data-support-pbs-java-only) | no |
+| req | ext.prebid.data.bidders | bidders in scope for bidder-specific first party data | array of strings | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#first-party-data-support) | no |
+| req | ext.prebid.bidderconfig | bidder-specific first party data | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#first-party-data-support) | no |
 | req | ext.prebid.currency.rates | publisher-defined currency conversions | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#currency-support) | yes |
 | req | ext.prebid.currency.usepbsrates | if true, currency.rates is used as a backup if dynamic rates aren't found. If false, dynamic rates are not used. | object | true | yes |
 | req | ext.prebid.no-sale | turns off CCPA processing for the named bidder(s) | array of strings | ["bidderA"] | no |
 | req | ext.prebid.interstitial | PBS-core will adjust the sizes on a request for interstitials | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#interstitial-support) | yes |
 | req | ext.prebid.auctiontimestamp | timestamp for use in correlating PBJS and PBS events | long int | 123456789 | yes |
-| req | ext.prebid.options. echovideoattrs | causes PBS-core to [echo video attributes](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#echo-storedrequest-video-attributes-pbs-java-only) on seatbid[].bid[].ext.prebid.storedrequestattributes so the player has access to them | boolean | true | yes |
-| req | ext.prebid.multibid | allows bidders to respond with more than one bid | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#multibid-pbs-java-only) | yes, but only their value |
-| req | user.ext.prebid.buyeruids | An alternate to [/cookie_sync](/prebid-server/endpoints/pbs-endpoint-cookieSync.html), the request can supply bidder ID values | object | See [doc](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#buyer-uid) | no |
+| req | ext.prebid.options. echovideoattrs | causes PBS-core to [echo video attributes](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#echo-storedrequest-video-attributes) on seatbid[].bid[].ext.prebid.storedrequestattributes so the player has access to them | boolean | true | yes |
+| req | ext.prebid.multibid | allows bidders to respond with more than one bid | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#multibid) | yes, but only their value |
+| req | user.ext.prebid.buyeruids | An alternate to [/cookie_sync](/prebid-server/endpoints/pbs-endpoint-cookieSync.html), the request can supply bidder ID values | object | See [doc](#buyer-uid) | no |
 | req | ext.prebid. data.eidpermissions | Allows publishers to define which bidders are allowed to see which extended IDs. | object | See [doc](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#eid-permissions) | no |
-| req | imp[].ext.prebid. bidder.BIDDER.dealsonly | PG: suppress bid responses that arent deals | boolean | See [doc](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#pg-deals-extensions-pbs-java-only) | yes |
-| req | imp[].ext.prebid. bidder.BIDDER.pgdealsonly | PG: don't even call the adapter if there aren't line items ready to deliver | boolean | See [doc](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#pg-deals-extensions-pbs-java-only) | yes |
+| req | ext.prebid. passthrough | Allows an application to pass a value through to the response. | object | See [doc](#request-passthrough) | no |
+| req | imp[].ext.prebid. bidder.BIDDER.dealsonly | PG: suppress bid responses that arent deals | boolean | See [doc](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#pg-deals-extensions) | yes |
+| req | imp[].ext.prebid. bidder.BIDDER.pgdealsonly | PG: don't even call the adapter if there aren't line items ready to deliver | boolean | See [doc](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#pg-deals-extensions) | yes |
 | resp | seatbid[].bid[].ext. prebid.targeting | ad server targeting values. Related to req ext.prebid.targeting. | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#ad-server-targeting) | n/a |
 | resp | seatbid[].bid[].ext.prebid. type | "banner", "video", "native" | string | "banner" | n/a |
 | resp | seatbid[].bid[].ext.prebid. cache.bids/vastXml.url | URL location of the cached object | string | See [docs](#cache-bids). | n/a |
@@ -1473,13 +1505,14 @@ The Prebid SDK version comes from:
 | resp | seatbid[].bid[].ext.prebid. events.imp | URL for registering an impression event for this bid | string | URL | n/a |
 | resp | seatbid[].bid[].ext.prebid. bidid | defines a Prebid-generated id for this bid in case the bidder's ID isn't unique | string | UUID | n/a |
 | resp | seatbid[].bid[].ext.prebid. meta.ATTR | bidder-supplied metadata | object | see [docs](/prebid-server/developers/add-new-bidder-go.html) | n/a |
-| resp | seatbid[].bid[].ext.prebid. storedrequestattributes | results of the ext.prebid.options.echovideoattrs option above. | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#echo-storedrequest-video-attributes-pbs-java-only) | n/a |
-| resp | response.seatbid[].bid[].ext. origbidcpm | a copy of the unadjusted bid price | float | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#original-bid-cpm-pbs-java-only) | n/a |
-| resp | response.seatbid[].bid[].ext. origbidcur | a copy of the original bid currency | string | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#original-bid-cpm-pbs-java-only) | n/a |
+| resp | seatbid[].bid[].ext.prebid. storedrequestattributes | results of the ext.prebid.options.echovideoattrs option above. | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#echo-storedrequest-video-attributes) | n/a |
+| resp | response.seatbid[].bid[].ext. origbidcpm | a copy of the unadjusted bid price | float | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#original-bid-cpm) | n/a |
+| resp | response.seatbid[].bid[].ext. origbidcur | a copy of the original bid currency | string | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#original-bid-cpm) | n/a |
 | resp | ext.responsetimemillis.BIDDER | debug mode: how long the named bidder took to respond with a bid | integer | 100 | n/a |
 | resp | ext.debug.httpcalls.BIDDER | debug mode: the HTTP request/response from the named bidder | object | | n/a |
 | resp | ext.errors.BIDDER | debug mode: errors from the named bidder | object | | n/a |
 | resp | ext.debug | debug mode: useful output | object | see [docs](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#debug-output)| n/a |
+| resp | ext.prebid.passthrough | copied from request ext.prebid.passthrough | object | see [docs](#request-passthrough)| n/a |
 
 ### Further Reading