PBS feature updates (#2916)

dev-docs/modules/userId.md

@@ -1780,18 +1780,6 @@ Bidders that want to support the User ID module in Prebid Server, need to update
 }
 {% endhighlight %}
 
-### ID Providers
-
-If you're an ID provider that wants to get on this page:
-
-- Fork Prebid.js and write a sub-module similar to one of the *IdSystem modules already in the [modules](https://github.com/prebid/Prebid.js/tree/master/modules) folder.
-- Add your *IdSystem name into the modules/.submodules.json file
-- Follow all the guidelines in the [contribution page](https://github.com/prebid/Prebid.js/blob/master/CONTRIBUTING.md).
-- Submit a Pull Request against the [Prebid.js repository](https://github.com/prebid/Prebid.js).
-- Fork the prebid.org [documentation repository](https://github.com/prebid/prebid.github.io), modify the /dev-docs/modules/userId.md, and submit a documentation Pull Request as well.
-
-<a name="getUserIds"></a>
-
 ### Exporting User IDs
 
 If you need to export the user IDs stored by Prebid User ID module, the `getUserIds()` function will return an object formatted the same as bidRequest.userId.
@@ -1837,6 +1825,18 @@ pbjs.getUserIdsAsEids() // returns userIds in ORTB Eids format. e.g.
 ]
 ```
 
+## ID Providers
+
+If you're an ID provider that wants to get on this page:
+
+- Fork Prebid.js and write a sub-module similar to one of the *IdSystem modules already in the [modules](https://github.com/prebid/Prebid.js/tree/master/modules) folder.
+- Add your *IdSystem name into the modules/.submodules.json file
+- Follow all the guidelines in the [contribution page](https://github.com/prebid/Prebid.js/blob/master/CONTRIBUTING.md).
+- Submit a Pull Request against the [Prebid.js repository](https://github.com/prebid/Prebid.js).
+- Fork the prebid.org [documentation repository](https://github.com/prebid/prebid.github.io), modify the /dev-docs/modules/userId.md, and submit a documentation Pull Request as well.
+
+<a name="getUserIds"></a>
+
 ## Passing UserIds to Google Ad Manager for targeting
 
 User IDs from Prebid User ID module can be passed to GAM for targeting in Google Ad Manager or could be passed ahead to Google Open Bidding using ```userIdTargeting``` module. Note Google deprecated the ability to pass key values, including identifiers, to OB partners and then later began a closed beta to resume it with details non-public (see  https://developers.google.com/authorized-buyers/rtb/request-guide ). More details on the user id module can be found [here](https://github.com/prebid/Prebid.js/blob/master/modules/userIdTargeting.md). In short, you just need to add the optional userIdTargeting sub-module into your `gulp build` command and the additional `userIdTargeting` config becomes available.

prebid-server/developers/pbs-cookie-sync.md

@@ -83,34 +83,46 @@ Note: if the publisher has an AMP Consent Management Platform, they should use `
 
 ## Bidder Instructions for Building a Sync Endpoint
 
-Bidders must implement an endpoint under their domain which accepts an encoded URI for redirects. 
-This URL should be able to accept privacy parameters:
+Building a sync endpoint is optional -- mobile-only bidders don't benefit from
+ID syncing. But for browser-based bidding, ID syncing can help improve buyer bid rate. There are two main options a bidder can choose to support:
+
+- redirect: the client will drop an IMG tag into the page, then call the bidder's URL which needs to redirect to the Prebid Server /setuid endpoint.
+- iframe: the client will drop an IFRAME tag into the page, then call the bidder's URL which responds with HTML and Javascript that calls the Prebid Server /setuid endpoint at some point.
+
+PBS-Java allows bidders to support both options.
+
+Bidders must implement an endpoint under their domain which accepts an encoded URI for redirects. This URL should be able to accept privacy parameters:
 
 - gdpr: if 0, declares this request isn't in GDPR scope. If 1, declares it is in scope. Otherwise indeterminate.
 - gdpr_consent: the TCF1 or TCF2 consent string. This is unpadded base64-URL encoded.
 - us_privacy: the IAB US Privacy string
 
-These values will be passed to your usersync endpoint. For example:
+The specific attributes can differ for your endpoint. For instance, you could choose to receive gdprConsent rather than gdpr_consent.
 
-Here's an example that shows the privacy macros used by PBS-Go:
+Here's an example that shows the privacy macros as coded into PBS-Go:
 ```
-GET some-bidder-domain.com/usersync-url?gdpr={%raw%}{{.GDPR}}&gdpr_consent={{.GDPRConsent}}&us_privacy={{.USPrivacy}}{%endraw%}&redirectUri=prebid-server.example.com%2Fsetuid%3Fbidder%3Dsomebidder%26uid%3D%24UID
+GET some-bidder-domain.com/usersync-url?gdpr={%raw%}{{.GDPR}}&gdpr_consent={{.GDPRConsent}}&us_privacy={{.USPrivacy}}{%endraw%}&redirectUri=prebid-server.example.com%2Fsetuid%3Fbidder%3Dsomebidder%26uid%3DYOURMACRO
 ```
-PBS-Java uses slightly different macros:
+PBS-Java uses slightly different macros in the bidder config:
 ```
-GET some-bidder-domain.com/usersync-url?gdpr={%raw%}{{gdpr}}&gdpr_consent={{gdpr_consent}}&us_privacy={{us_privacy}}{%endraw%}&redirectUri=prebid-server.example.com%2Fsetuid%3Fbidder%3Dsomebidder%26uid%3D%24UID
+    usersync:
+      url: https://some-bidder-domain.com/usersync-url?gdpr={%raw%}{{gdpr}}&gdpr_consent={{gdpr_consent}}&us_privacy={{us_privacy}}{%endraw%}&redirectUri=
+      redirect-url: /setuid?bidder=acuityads&gdpr={{gdpr}}&gdpr_consent={{gdpr_consent}}&us_privacy={{us_privacy}}&uid=YOURMACRO
 ```
-In either case, you can receive the values on whatever query string parameters you'd like -- these are
-the macros you can use to define the values.
+In either case, the {%raw%}{{}}{%endraw%} macros are resolved by PBS.
+
+{: .alert.alert-info :}
+Important: The "YOURMACRO" string here needs to be whatever your sync endpoint will recognize and resolve to the user's ID from your domain. Some examples of macros that bidders use: $UID, ${UID}, $$visitor_cookie$$, ${DI_USER_ID}, etc. Every bidder has their own value here.
 
-This example endpoint would URL-decode the `redirectUri` param to get `prebid-server.example.com/setuid?bidder=somebidder&uid=$UID`.
-It would then replace the `$UID` macro with the user's ID from their cookie. Supposing this user's ID was "132",
-it would then return a redirect to `prebid-server.example.com/setuid?bidder=somebidder&uid=132`.
+Here's how this all comes together:
 
-Prebid Server would then save this ID mapping of `somebidder: 132` under the cookie at `prebid-domain.com`.
+1. Prebid.js calls Prebid Server's cookie_sync endpoint
+2. PBS responds with an array of user sync URLs, which may include your bidder's sync url
+3. Prebid.js drops an img or iframe into the page, causing the browser to connect to the your usersync endpoint.
+4. Your usersync endpoint will return with either a redirect to Prebid Server's /setuid endpoint or iframe HTML that eventually calls Prebid Server's /setuid endpoint.
+5. Prebid Server then saves this ID mapping of `mybidder: 132` under the cookie at `prebid-domain.com`.
 
-When the client then calls `www.prebid-domain.com/openrtb2/auction`, the ID for `somebidder` will be available in the Cookie.
-Prebid Server will then stick this into `request.user.buyeruid` in the OpenRTB request it sends to `somebidder`'s Bidder.
+Then the next time the client then calls `www.prebid-domain.com/openrtb2/auction`, the ID for `mybidder` will be available in the Cookie. Prebid Server will then stick this value into `request.user.buyeruid` in the OpenRTB request it sends to `mybidder`'s bid adapter.
 
 ## Further Reading
 

prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md

@@ -194,8 +194,8 @@ If you find that some bidders use Gross bids, publishers can adjust for it with
   "ext": {
     "prebid": {
       "bidadjustmentfactors": {
-        "appnexus": 0.8,
-        "rubicon": 0.7
+        "bidderA": 0.9,
+        "bidderB": 0.8
       }
     }
   }
@@ -204,6 +204,33 @@ If you find that some bidders use Gross bids, publishers can adjust for it with
 
 This may also be useful for publishers who want to account for different discrepancies with different bidders.
 
+It's also possible to define different bid adjustment factors by mediatype, which can be helpful to adjust discrepancies that differ across mediatypes (PBS-Java only):
+```
+{
+  "ext": {
+    "prebid": {
+      "bidadjustmentfactors": {
+        "bidderA": 0.9,
+        "bidderB": 0.8
+        "mediatypes": {
+          "banner": {
+            "bidderA": 0.8,
+          },
+          "video-outstream": {
+            "bidderC": 0.9
+          },
+          "video": {
+            "bidderB": 0.85
+          }
+       }
+      }
+    }
+  }
+}
+```
+
+Note that video-outstream is defined to be imp[].video requests where imp[].video.placement is greater than 1.
+
 ##### Targeting
 
 Targeting refers to strings which are sent to the adserver to
@@ -1008,6 +1035,10 @@ It is only returned on `test` bids for performance reasons, but may be useful du
 
 This contains the request after the resolution of stored requests and implicit information (e.g. site domain, device user agent).
 
+##### Original Bid CPM (PBS-Java only)
+
+`response.seatbid[].bid[].ext.origbidcpm` will contain the original bid price 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).
 
 ### OpenRTB Ambiguities
 

prebid-server/endpoints/pbs-endpoint-setuid.md

@@ -20,6 +20,10 @@ This endpoint saves a UserID for a Bidder in the Cookie. Saved IDs will be recog
 - `uid`: The ID which the Bidder uses to recognize this user. If undefined, the UID for `bidder` will be deleted.
 - `gdpr`: This should be `1` if GDPR is in effect, `0` if not, and undefined if the caller isn't sure
 - `gdpr_consent`: This is required if `gdpr` is one, and optional (but encouraged) otherwise. If present, it should be an [unpadded base64-URL](https://tools.ietf.org/html/rfc4648#page-7) encoded [Vendor Consent String](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/Consent%20string%20and%20vendor%20list%20formats%20v1.1%20Final.md).
+- `f`: The desired format of the response.
+    - If f=i (format=image), PBS will respond with a blank 1x1 PNG, set the Content-Length to the appropriate number of bytes, and set Content-Type to image/png
+    - If f=b (format=blank), PBS will response with empty HTML with Content-Length 0 and Content-Type to text/html
+
 
 If the `gdpr` and `gdpr_consent` params are included, this endpoint will _not_ write a cookie unless:
 
@@ -31,3 +35,20 @@ If in doubt, contact the company hosting Prebid Server and ask if they're GDPR-r
 ### Sample request
 
 `GET http://prebid.site.com/setuid?bidder=adnxs&uid=12345&gdpr=1&gdpr_consent=BONciguONcjGKADACHENAOLS1rAHDAFAAEAASABQAMwAeACEAFw`
+
+### Return Values
+
+PBS-Go: 
+
+- HTTP 200
+    - Success: blank body with Set-Cookies header
+    - Failure: error message in body
+
+PBS-Java:
+
+- HTTP 400 - The request is in GDPR scope and the consent string is missing or invalid.
+- HTTP 451 - PBS does not have permission to set a cookie due to GDPR or other privacy rule.
+- HTTP 200
+    - Success with image response: if the f=i parameter is specified or if the named bidder prefers redirect cookie_syncs, then PBS responds with a blank 1x1 PNG, set the Content-Length to the appropriate number of bytes, and set Content-Type to image/png
+    - Success with empty response: if the f=b parameter is specified or if the named bidder prefers iframe cookie_syncs, then PBS responds with empty HTML, Content-Length 0 and Content-Type to text/html
+

prebid-server/features/pbs-feature-idx.md

@@ -20,6 +20,8 @@ title: Prebid Server | Features
 | Targeting | [Custom Targeting](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#custom-targeting-pbs-java-only) | Request can specify `ext.prebid.adservertargeting`, which causes PBS to emit custom targeting values. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | [Price Granularity](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) | Core | Request can define quantization rules. Bids are quantized before being added to ad server targeting. | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | Price Granularity | Mediatype pricegranularity | Request can define different quantization rules for different mediatypes. Bids are quantized before being added to ad server targeting. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
+| [Bid Adjustments](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#bid-adjustments) | Core | Allows publishers to adjust bid prices to account for gross/net or consistent discrepancies. | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
+| [Bid Adjustments](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#bid-adjustments) | By mediatype | Allows for different bid adjustments by mediatype banner, video, native. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | [GDPR](/prebid-server/features/pbs-privacy.html) | TCF 1.1 core | Able to: read the TCF1.1 global vendor list, parse incoming TCF1.1 consent strings, and [take appropriate enforcement action](https://docs.google.com/document/d/1g0zAYc_EfqyilKD8N2qQ47uz0hdahY-t8vfb-vxZL5w/edit). | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | GDPR | TCF 1.1 Account Config | Able to turn on and off TCF1 enforcement per account. | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | GDPR | TCF 1.1 Geo-lookup | Can use a geographic lookup service to help determine whether the incoming request is in-scope for GDPR. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
@@ -54,7 +56,8 @@ title: Prebid Server | Features
 | [Interstitials](/prebid-server/features/pbs-interstitials.html) | Core | Support device.ext.prebid.interstitial.minwidthperc and device.ext.prebid.interstitial.minheightperc parameters, [dynamically updating the impression format object](https://github.com/prebid/prebid-server/issues/755) from a configurable list of sizes filtered by these parameters. | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | [Aliases](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#bidder-aliases) | Core | Maps a biddercode on an incoming request to a specific server-side bid adapter named in the request or defined in config. | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | Aliases | [GVL ID support](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#bidder-alias-gvl-ids-pbs-java-only) | Define the IAB GVL ID for an aliased biddercode. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
-| [User ID Sync](/prebid-server/developers/pbs-cookie-sync.html) | Core | Implements the /cookie_sync and /setuid endpoints. | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
+| [User ID Sync](/prebid-server/developers/pbs-cookie-sync.html) | Core | Implements the /cookie_sync and /setuid endpoints. Bidders may choose either redirect or iframe method. | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
+| User ID Sync | Multi-Method | Bidders can supply both pixel redirects as well as iframe syncs. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | User ID Sync | Cooperative sync | Does a pixel sync with more than just the bidders on the page. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | User ID Sync | Account override | Allows accounts to override the cooperative sync feature and bidder limits. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | User ID | [EID Permissions](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#eid-permissions) | The Publisher can define which bidders receive which extended user IDs. | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |