Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PBS feature updates #2916

Merged
merged 1 commit into from
Apr 28, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions dev-docs/modules/userId.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
42 changes: 27 additions & 15 deletions prebid-server/developers/pbs-cookie-sync.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
35 changes: 33 additions & 2 deletions prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
}
}
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down
21 changes: 21 additions & 0 deletions prebid-server/endpoints/pbs-endpoint-setuid.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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

5 changes: 4 additions & 1 deletion prebid-server/features/pbs-feature-idx.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"> |
Expand Down Expand Up @@ -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"> |
Expand Down