diff --git a/faq/prebid-server-faq.md b/faq/prebid-server-faq.md
index 897921131b..8ae4ce15de 100644
--- a/faq/prebid-server-faq.md
+++ b/faq/prebid-server-faq.md
@@ -168,3 +168,37 @@ Another way is to [register for our host company mailing list](/prebid-server/ho
Prebid Server is not a full-fledged SSP. Any DSP bid adapters should keep this in mind when it comes to assuming SSP functionality like resolving OpenRTB macros. We debated building this functionality into PBS, but realized it would take precious milliseconds away from the overall header bidding auction to scan kilobytes of bidder creatives for the 9 different OpenRTB macros. Since so few bidders require this functionality, it makes sense to have those adapters do it themselves.
If an adapter doesn't resolve its own macros, AUCTION_PRICE will eventually get resolved by the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative), but by then the bid price will be in the ad server currency and quantized by the price granularity. This will likely cause reporting discrepancies.
+
+## Does Prebid Server support region-specific endpoints for bidders?
+
+Yes. This is handled by the PBS host company in their datacenter config.
+Bidders that want to make use of region-specific endpoints will need to work
+with each PBS host company:
+
+- determine which regions the host company supports
+- map the regions to the bidder's endpoints
+- the host company overrides the bidder's default auction endpoint when they deploy the configuration for each region.
+
+We recognize that it's inconvenient for bidders to be required to have this
+conversation with each host company, but there's really not a better way
+in an open source project. Any number of companies may choose to host
+PBS and we cannot constrain them into a defined set of regions.
+
+## Can bidder endpoints differ by publisher?
+
+You may not use an endpoint domain as a bidder parameter. Prebid Server is not
+an open proxy. If absolutely necessary, you may specify a portion of the
+domain as a parameter to support geo regions or account specific servers.
+However, this is discouraged and may degrade the performance of your adapter
+since the server needs to maintain more outgoing connections. Host companies
+may choose to disable your adapter if it uses a dynamically configured domain.
+
+e.g. this config is not allowed because the entire domain name is a variable:
+
+```
+endpoint: "https://{host}/path"
+```
+but this would be ok:
+```
+endpoint: "https://{host}.example.com/path"
+```
diff --git a/features/InterstitialAds.md b/features/InterstitialAds.md
index 3eda2187fa..e034212528 100644
--- a/features/InterstitialAds.md
+++ b/features/InterstitialAds.md
@@ -54,7 +54,7 @@ pbjs.addAdUnits({
}
},
ortb2Imp: {
- intl:1
+ instl:1
},
...
});
diff --git a/features/firstPartyData.md b/features/firstPartyData.md
index cceb41322d..1d8f94ca29 100644
--- a/features/firstPartyData.md
+++ b/features/firstPartyData.md
@@ -63,7 +63,7 @@ pbjs.setConfig({
userrating: "4",
data: [{
name: "www.dataprovider1.com",
- ext: { "segtax": 1 },
+ ext: { segtax: 4 },
segment: [
{ id: "687" },
{ id: "123" }
@@ -177,6 +177,54 @@ pbjs.setBidderConfig({ // different bidders can receive different data
});
{% endhighlight %}
+### Supplying App Content Data
+
+Occasionally, an app which embeds a webview might run Prebid.js. In this case, the app object is often specified for OpenRTB, and the site object would be invalid. When this happens, one should specify app.content.data in place of site.content.data.
+
+{% highlight js %}
+pbjs.setConfig({
+ ortb2: {
+ app: {
+ name: "myappname",
+ keywords: "power tools, drills",
+ content: {
+ data: [
+ {
+ name: "www.dataprovider1.com",
+ ext: {
+ segtax: 6
+ },
+ segment: [
+ {
+ id: "687"
+ },
+ {
+ id: "123"
+ }
+ ]
+ },
+ {
+ name: "www.dataprovider1.com",
+ ext: {
+ segtax: 7
+ },
+ segment: [
+ {
+ id: "456"
+ },
+ {
+ id: "789"
+ }
+ ]
+ }
+ ]
+ }
+ }
+ }
+)
+
+{% endhighlight %}
+
## Segments and Taxonomy
The [IAB](https://iab.com) offers standard content and audience taxonomies for categorizing sites and users. Prebid supports defining these values as first party data in `site.content.data` or `user.data` as shown in the examples above.
diff --git a/guide.md b/guide.md
index f397c5a8d5..434d04a776 100644
--- a/guide.md
+++ b/guide.md
@@ -9,14 +9,32 @@ sidebarType: 0
# Prebid Website Maintenance Guide
-v 1.1
-Sept 7, 2019
+v 1.2
+Sept 24, 2021
***
+## Reviewing Pull Requests and Issues
+
+Being a reviewer means you're in weekly rotation where you keep an eye on pull requests (PRs) and issues opened in this repo.
+
+### PR Review Guidelines
+
+1. Make sure no inappropriate changes are made. This covers obvious things like bad language and content, but we also don't allow overt marketing language on the site. Phrases like "we're the best BLAH" or "number one FOOZIT" need to be toned down.
+2. Make sure competitors aren't messing with each other's docs. This can be hard to tell because we don't know which github handles belong to which companies, but in general, if a destructive or suspicious change is being made to a doc, check on the Prebid Slack channel to confirm that the affected company approves the change.
+3. Make sure the change doesn't break formatting. It's not always necessary to preview locally, but for large changes, it's worthwhile verifying visually because markdown can be cranky.
+4. Help the author with basic readability - if you as a reviewer don't understand a sentence, probably others will have trouble too. Push back and ask questions about what they're really trying to say.
+5. We don't generally merge a docs PR until the related code is released. Prebid.js releases happen on Weds or Thurs, and people really like to have their docs PRs merged shortly after the code is released. For Prebid Server, it's ok to merge the docs after the code is merged.
+6. Fix broken or out-of-date things you run across. At least flag it in the team slack channel so we can fix it someday.
+7. Bid Adapter Guidelines
+ 1. Check the front-matter: required fields are title and either pbjs or pbs.
+ 2. Every adapter needs a parameters table that contains exactly 5 columns in this order: Name, Scope, Description, Example, Type.
+ 3. Discourage full-page HTML examples. Better to have just the bidder-specific logic and a pointer to a standard Prebid.js example.
+ 4. All headers must be level 3, 4, or 5.
+
## Core Technologies
-The Prebid website is developed using [Jekyll](https://jekyllrb.com/), a static site generator which uses the following technology to create and style HTML pages.
+The Prebid website is developed using [GitHub pages](https://pages.github.com/) and [Jekyll](https://jekyllrb.com/), a static site generator which uses the following technology to create and style HTML pages. See the [main README file](https://github.com/prebid/prebid.github.io/blob/master/README.md) for instructions on how to set this up.
**Markdown**: The majority of the content is written in Markdown language. Jekyll transform this into raw HTML.
@@ -34,11 +52,18 @@ Learn more about [Liquid](https://help.shopify.com/en/themes/liquid/basics)
**CSS**: The site builds on the base Bootstrap template with custom CSS stored in the style.css file.
-***
+### Environment
+
+- prebid.org is built with Wordpress. We call it "the marketing site". We generally use a contracting company to make major updates there so it's pretty. But if you know Wordpress, we may give you permissions to do minor updates there.
+- docs.prebid.org is the Github pages site. We call it "the docs site".
+- dev.prebid.org is served through Netlify from the 'dev' branch of the repo. It's often out of date and only used for major projects or for sharing major docs for external review.
+- stage.prebid.org is also served through Netlify, but from the 'staging' branch. You should assume it's out of date.
+
+On the rare occasions where we need to use the 'dev' or 'stage' sites, we just check with each other to make sure it's not already being used for something.
## Site Config
-The _config.yml file (note underscore prefix) sets the base configuration for the site. Refer to [Jekyll](https://jekyllrb.com/docs/configuration/) documentation on which properties can be set in the _congig.yml file.
+The _config.yml file (note underscore prefix) sets the base configuration for the site. Refer to [Jekyll](https://jekyllrb.com/docs/configuration/) documentation on which properties can be set in the _config.yml file.
***
@@ -236,18 +261,14 @@ The attributes in the Jekyll 'front matter' drive various behaviors and dynamic
| ----- | ------ | ------ | ------ |
| layout | yes | bidder | Links this file to the bidder.html layout |
| title | yes | company name | For display |
+| pbjs | sorta | true or false | defines whether this is a Prebid.js bidder |
+| pbs | sorta | true or false | defines whether this is a Prebid Server bidder |
| description | no | - | Not used |
-| hide | no | - | Not used |
| biddercode | yes | preferred bidder code | Used as the default ad server targeting suffix and the default download filename |
| aliasCode | no | download filename | Overrides the filename used to build the PBJS package on the download page |
| prevBiddercode | no | secondary bidder code | Adds a note about an alternate code that may have been used. |
-| bidder_supports_deals | no | true or false, whether the adapter supports deals | For display. Defaults to 'true'. |
-| s2s_only | no | true or false, whether the adapter is server-to-server only | Adds a note to the display. Defaults to 'false'. |
-| gdpr_supported | no | true or false, whether the adapter supports GDPR | For display. Defaults to 'false'. |
-| coppa_supported | no | true or false, whether the adapter supports COPPA | For display. Defaults to 'false'. |
-| media_types | no | comma-separated list of: banner, video, native | For display. |
-| userIds | no | comma-separated list of supported user id modules | For display. |
-| prebid_member | no | true or false, whether this company is a prebid.org member | For display. |
+| pbjs_version_notes | no | string | Displays on the download page |
+| ANYTHING ELSE | no | string | There are many pieces of metadata (e.g. GDPR support, user IDs supported) that bid adapters can disclose. They're displayed on the bidder's parameter page. |
The bidderCode, aliasCode, and prevBiddercode parameters bear some description.
Some adapters have a longer bidderCode and a shorter bidderCode -- their adapter supports both (with the `alias` feature) but
diff --git a/prebid-server/developers/add-new-bidder-go.md b/prebid-server/developers/add-new-bidder-go.md
index b710431d91..83e4e47a06 100644
--- a/prebid-server/developers/add-new-bidder-go.md
+++ b/prebid-server/developers/add-new-bidder-go.md
@@ -13,7 +13,7 @@ Thank you for contributing a bid adapter to the open source Prebid Server projec
This document guides you through the process of developing a new bid adapter for your bidding server. We encourage you to look at [existing bid adapters](https://github.com/prebid/prebid-server/tree/master/adapters) for working examples and practical guidance. You can also ask us questions by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new).
{: .alert.alert-info :}
-**NOTE:** There are two implementations of Prebid Server, [PBS-Go](https://github.com/prebid/prebid-server) and [PBS-Java](https://github.com/prebid/prebid-server-java). We recommend you build new adapters for PBS-Go and allow us to port it to PBS-Java within a couple of months. If you'd like to build both yourself, please also follow these [instructions for building an adapter in PBS-Java](/prebid-server/developers/add-new-bidder-java.html).
+There are two implementations of Prebid Server, [PBS-Go](https://github.com/prebid/prebid-server) and [PBS-Java](https://github.com/prebid/prebid-server-java). We recommend you build new adapters for PBS-Go and allow us to port it to PBS-Java within a couple of months. If you'd like to build both yourself, please also follow these [instructions for building an adapter in PBS-Java](/prebid-server/developers/add-new-bidder-java.html).
* TOC
@@ -31,7 +31,7 @@ An OpenRTB 2.5 Bid Request contains one or more Impressions, each representing a
You will need to choose a unique name for your bid adapter. Names should be written in lower case and may not contain special characters or emoji. If you already have a Prebid.js bid adapter, we encourage you to use the same name with the same bidder parameters. You may not name your adapter `all`, `context`, `data`, `general`, `prebid`, or `skadn` as those have special meaning in various contexts. Existing bid adapter names are [maintained here](https://github.com/prebid/prebid-server/blob/master/openrtb_ext/bidders.go#L37).
-We ask that the first 6 letters of the name you choose be unique among the existing bid adapters. This consideration helps with generating targeting keys for use by some ad exchanges, such as Google Ad Manager. There's no need to manually check, as this constraint is enforced by the [`TestBidderUniquenessGatekeeping`](https://github.com/prebid/prebid-server/blob/master/openrtb_ext/bidders_test.go#L61) test.
+We ask that the first 6 letters of the name you choose be unique among the existing bid adapters. This consideration helps with generating targeting keys for use by some ad exchanges, such as Google Ad Manager. There's no need to manually check, as this constraint is enforced by the [`TestBidderUniquenessGatekeeping`](https://github.com/prebid/prebid-server/blob/master/openrtb_ext/bidders_validate_test.go#L45) test.
Throughout the rest of this document, substitute `{bidder}` with the name you've chosen.
@@ -48,9 +48,9 @@ We are proud to run the Prebid Server project as a transparent and trustworthy h
- Adapters must annotate the bid response with the proper media type, ideally based on the response from the bidding server.
{: .alert.alert-warning :}
-Failure to follow the rules will lead to delays in approving your adapter for inclusion in Prebid Server. If you'd like to discuss an exception to a rule, please make your request by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new).
+Failure to follow the rules will lead to delays in approving your adapter. If you'd like to discuss an exception to a rule, please make your request by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new).
-### Ongoing Support and Maintenance
+### Support and Maintenance
You are expected to provide support and maintenance for the code you contribute to Prebid Server as part of your bid adapter. We ask that you proactively update your adapter when your bidding server introduces new features or breaking changes.
@@ -60,18 +60,18 @@ Please be attentive in reading and responding to emails and [GitHub issues](http
## Create Your Adapter
-Prebid Server bid adapters consist of several components: bidder info, bidder parameters, adapter code, user sync code, registration with the core framework, and default configuration values. This chapter will guide you though each component.
+Prebid Server bid adapters consist of several components: bidder info, bidder parameters, adapter code, registration with the core framework, and default configuration values. This document will guide you though each component.
-Please refer to [existing bid adapters](https://github.com/prebid/prebid-server/tree/master/adapters) for working examples and practical guidance, but understand that our adapter interfaces and coding style evolve over time. Please refer to the examples in this document over differences you may find in an existing bid adapter.
+Please refer to [existing bid adapters](https://github.com/prebid/prebid-server/tree/master/adapters) for working examples and practical guidance, but understand that our adapter interfaces and coding style evolve over time. The examples in this document have precedence over differences you may find in an existing bid adapter.
Our project is written in the [Go programming language](https://golang.org/). We understand not everyone has prior experience writing Go code. Please try your best and we'll respectfully steer you in the right direction during the review process.
{: .alert.alert-info :}
-Please do not ignore errors from method calls made in your bid adapter code. Even if it's seemingly impossible for an error to occur, such as from `json.Marshal`, it's still possible under the high throughput multi-threaded nature of Prebid Server.
+**Please do not ignore errors from method calls made in your bid adapter code.** Even if it's seemingly impossible for an error to occur, such as from `json.Marshal`, it's still possible under the high throughput multi-threaded nature of Prebid Server.
### Bidder Info
-Let's begin with your adapter's bidder information YAML file. This file is required and contains your maintainer email address, your [GDPR Global Vendor List (GVL) id](https://iabeurope.eu/vendor-list-tcf-v2-0/), specifies the ad formats your adapter will accept, and allows you to opt-out of video impression tracking.
+Let's begin with your adapter's bidder information YAML file. This file is required and contains your bid adapter's maintainer email address, [GDPR Global Vendor List (GVL) ID](https://iabeurope.eu/vendor-list-tcf-v2-0/), supported ad formats, user sync endpoints, and allows you to opt-out of video impression tracking.
Create a file with the path `static/bidder-info/{bidder}.yaml` and begin with the following template:
@@ -93,6 +93,10 @@ capabilities:
- video
- audio
- native
+userSync:
+ redirect:
+ url: https://foo.com/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%}
+ userMacro: $UID
```
Modify this template for your bid adapter:
@@ -100,6 +104,7 @@ Modify this template for your bid adapter:
- Change the `gvlVendorID` from the sample value of `42` to the id of your bidding server as registered with the [GDPR Global Vendor List (GVL)](https://iabeurope.eu/vendor-list-tcf-v2-0/), or remove this line entirely if your bidding server is not registered with IAB Europe.
- Change the `modifyingVastXmlAllowed` value to `false` if you'd like to opt-out of [video impression tracking](https://github.com/prebid/prebid-server/issues/1015), or remove this line entirely if your adapter doesn't support VAST video ads.
- Remove the `capabilities` (app/site) and `mediaTypes` (banner/video/audio/native) combinations which your adapter does not support.
+- Follow the [User Sync Configuration](#user-sync-configuration) documentation below to configure the endpoints for your bid adapter, or remove the `userSync` section if not supported.
Example: Website with banner ads only.
@@ -112,6 +117,10 @@ capabilities:
site:
mediaTypes:
- banner
+userSync:
+ redirect:
+ url: https://foo.com/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%}
+ userMacro: $UID
```
@@ -125,6 +134,10 @@ capabilities:
site:
mediaTypes:
- banner
+userSync:
+ redirect:
+ url: https://foo.com/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%}
+ userMacro: $UID
```
@@ -145,22 +158,72 @@ capabilities:
mediaTypes:
- banner
- video
+userSync:
+ redirect:
+ url: https://foo.com/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%}
+ userMacro: $UID
```
+#### User Sync Configuration
+
+Prebid Server offers a federated [user sync](https://docs.prebid.org/prebid-server/developers/pbs-cookie-sync.html) process to store user ids from multiple bidders in a single cookie under the host's domain. You may add support for your bid adapter by configuring iframe and/or redirect endpoints.
+
+The Bidder Info template above demonstrates configuration of a `redirect` user sync. The `url` points to an endpoint on your bidding server which will honor the privacy policies, replace the `userMacro` in the redirect url with the user's tracking id, and respond with an HTTP 302 redirect to that url. You may also specify an `iframe` endpoint which will return an HTML document to be rendered in an `iframe` on the user's device and use JavaScript to perform the redirect. You may omit the `{%raw%}{{.GDPR}}{%endraw%}`, `{%raw%}{{.GDPRConsent}}{%endraw%}`, and/or `{%raw%}{{.USPrivacy}}{%endraw%}` macros if they are not applicable to your legal situation.
+
+If both `iframe` and `redirect` endpoints are provided, you must specify a `default` field with a value of either `iframe` or `redirect`, based on your preference.
+
+```yaml
+userSync:
+ default: iframe
+ iframe:
+ url: https://foo.com/iframe/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%}
+ userMacro: $UID
+ redirect:
+ url: https://foo.com/redirect/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%}
+ userMacro: $UID
+```
+
+If your bid adapter supports user sync and doesn't have a good default, you may optionally specify a `supports` array with the items `iframe` and/or `redirect` to inform Prebid Server hosts. Hosts will receive a warning on startup if a bid adapter supports user sync and isn't configured. Expect hosts to contact you at the maintainer email address in this file for instructions.
+
+```yaml
+userSync:
+ # foo supports user syncing, but requires configuration by the host. contact this
+ # bidder directly at the email address in this file to ask about enabling user sync.
+ supports:
+ - iframe
+ - redirect
+```
+
+Each user sync is assigned a case-sensitive `key`, defaulting to your bidder name. You may use a different `key` value, but we discourage doing so except for when multiple bidders share the same bidding server. You might encounter this use case for built-in aliases or for multiple bidders implementing different protocols for the same bidding server. Only one bid adapter may specify endpoints when using a shared key, or Prebid Server will fail to startup due to the ambiguity.
+
+```yaml
+foo.yaml
+--------
+userSync:
+ redirect:
+ url: https://foo.com/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%}
+ userMacro: $UID
+
+bar.yaml
+--------
+userSync:
+ key: foo
+```
+
### Bidder Parameters
-Your bid adapter might require extra information from the publisher to form a request to your bidding server. The bidder parameters JSON Schema codifies this information to allow Prebid Server to verify requests and to provide an API for third party configuration systems.
+Your bid adapter might require extra information from the publisher to form a request to your bidding server. The bidder parameters JSON Schema codifies this information to allow Prebid Server to verify requests and to provide an API for configuration systems.
Publishers will provide extra information using an OpenRTB 2.5 Bid Request Extension, preferably at `request.imp[].ext.prebid.bidder.{bidder}` but also supported at `request.imp[].ext.{bidder}`. Prebid Server will validate the publisher information based on your schema and relocate the data to `request.imp[].ext.bidder`, regardless of your bidder name or the publisher's chosen location.
-We request that you do not duplicate information that is already present in the [OpenRTB 2.5 Bid Request specification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf#page=13) or is already part of an established Prebid convention. For example, your bidder parameters should not include first party data, bid floors, schain, video parameters, referrer information, or privacy consent including COPPA, CCPA, and GDPR TCF. For video parameters in particular, you must prefer the OpenRTB 2.5 Bid Request standard of `request.imp[].video`.
+We request you do not duplicate information already present in the [OpenRTB 2.5 Bid Request specification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf#page=13) or already part of an established Prebid convention. For example, your bidder parameters should not include first party data, bid floors, schain, video parameters, referrer information, or privacy consent including COPPA, CCPA, and GDPR TCF. For video parameters in particular, you must prefer the OpenRTB 2.5 Bid Request standard of `request.imp[].video`.
{: .alert.alert-warning :}
-**ENDPOINT NOTE:** You may not use an endpoint domain as a bidder parameter. Prebid Server is not an open proxy. If absolutely necessary, you may specify a portion of the domain as a parameter to support geo regions or account specific servers. However, this is discouraged and may degrade the performance of your adapter since the server needs to maintain more outgoing connections. Host companies may choose to disable your adapter if it uses a dynamically configured domain.
+You may not use an endpoint domain as a bidder parameter. Prebid Server is not an open proxy. If absolutely necessary, you may specify a portion of the domain as a parameter to support geo regions or account specific servers. However, this is discouraged and may degrade the performance of your adapter since the server needs to maintain more outgoing connections. Host companies may choose to disable your adapter if it uses a dynamically configured domain.
-Create a file with the path `static/bidder-params/{bidder}.json` using [JSON Schema](https://spacetelescope.github.io/understanding-json-schema/) to define your bidder parameters. Prebid Server requires this file for every adapter, even if yours doesn't require bidder parameters (see the 'no parameters' example at the end of this section).
+Create a file with the path `static/bidder-params/{bidder}.json` and use [JSON Schema](https://spacetelescope.github.io/understanding-json-schema/) to define your bidder parameters. Prebid Server requires this file for every adapter, even if yours doesn't require bidder parameters (see the 'no parameters' example at the end of this section).
Let's start with this example which defines one required `placementId` string parameter:
@@ -183,7 +246,9 @@ Let's start with this example which defines one required `placementId` string pa
```
We encourage you to utilize the full features of [JSON Schema](https://spacetelescope.github.io/understanding-json-schema/) to narrowly define your bidder parameter data types. If you copy and paste these examples, please remember to change the `title` and `description` to refer to your bidder name instead of our fictional Foo example.
-When choosing your parameter names, please consider aligning with the OpenRTB 2.5 standard by using lower case letters without camel casing or special characters.
+When choosing your parameter names, please consider aligning with the OpenRTB 2.5 standard by using lower case letters without camel casing or special characters.
+
+Properties in [JSON Schema](https://spacetelescope.github.io/understanding-json-schema/) are case sensitive. If you choose to specify multiple properties differing only by case for compatibility, we ask that you include the word 'preferred' in one of the descriptions to give a hint to third party configuration systems.
In addition to the examples listed below, please refer to [existing bidder parameter files](https://github.com/prebid/prebid-server/tree/master/static/bidder-params) for guidance.
@@ -234,7 +299,7 @@ In addition to the examples listed below, please refer to [existing bidder param
"title": "Foo Adapter Params",
"description": "A schema which validates params accepted by the Foo adapter",
"type": "object",
-
+
"properties": {
"token": {
"type": "string",
@@ -280,18 +345,47 @@ In addition to the examples listed below, please refer to [existing bidder param
}
```
+
+
+ Example: Multiple properties differing only by case.
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "title": "Foo Adapter Params",
+ "description": "A schema which validates params accepted by the Foo adapter",
+ "type": "object",
+
+ "properties": {
+ "partnerid": {
+ "type": "string",
+ "description": "Partner ID, preferred."
+ },
+ "partnerID": {
+ "secret": "string",
+ "description": "Partner ID"
+ }
+ },
+
+ "oneOf": [
+ { "required": ["partnerid"] },
+ { "required": ["partnerID"] }
+ ]
+}
+```
+
### Bidder Parameters Code
{: .alert.alert-info :}
-You can skip this step if your adapter has no bidder parameters.
+You can skip this section if your adapter has no bidder parameters.
-If you've defined bidder parameters for your adapter, you also need to represent your bidder parameters in code. The core framework uses the JSON Schema file for validation, but your adapter code needs a data structure to support JSON unmarshalling / deserialization. These data structures are organized in a shared path using a standard naming convention, which also serves as documentation of all adapter parameters.
+If you defined bidder parameters for your adapter, you also need to represent your bidder parameters in code. The core framework uses the JSON Schema file for validation, but your adapter code needs a data structure to support JSON unmarshalling / deserialization. These data structures are organized in a shared path using a standard naming convention, which also serves as documentation of all adapter parameters.
Create a file with the path `openrtb_ext/imp_{bidder}.go` containing an exported (must start with an upper case letter) data structure named `ImpExt{Bidder}`. All required and optional bidder parameters from the JSON Schema should be represented as fields.
-For example, this is what the bidder parameter code looks like for the example we used in the previous section:
+For example, this is what the bidder parameter code looks like for the Foo example we used in the previous section:
```go
package openrtb_ext
@@ -301,7 +395,7 @@ type ImpExtFoo struct {
}
```
-Please follow [Go's standard naming convention](https://golang.org/doc/effective_go.html) for the field names (particularly for acronyms) and use `` `json:...` `` attributes to specify the JSON name, matching exactly what you defined in the bidder parameters JSON Schema. Please keep in mind that JSON is case sensitive.
+Please follow [Go's standard naming convention](https://golang.org/doc/effective_go.html) for the field names (particularly for acronyms) and use `` `json:...` `` attributes to specify the JSON name, matching exactly what you defined in the bidder parameters JSON Schema.
### Adapter Code
@@ -326,7 +420,7 @@ import (
"fmt"
"net/http"
- "github.com/mxmCherry/openrtb"
+ "github.com/mxmCherry/openrtb/v15/openrtb2"
"github.com/prebid/prebid-server/adapters"
"github.com/prebid/prebid-server/config"
"github.com/prebid/prebid-server/errortypes"
@@ -345,7 +439,7 @@ func Builder(bidderName openrtb_ext.BidderName, config config.Adapter) (adapters
return bidder, nil
}
-func (a *adapter) MakeRequests(request *openrtb.BidRequest, requestInfo *adapters.ExtraRequestInfo) ([]*adapters.RequestData, []error) {
+func (a *adapter) MakeRequests(request *openrtb2.BidRequest, requestInfo *adapters.ExtraRequestInfo) ([]*adapters.RequestData, []error) {
requestJSON, err := json.Marshal(request)
if err != nil {
return nil, []error{err}
@@ -356,15 +450,15 @@ func (a *adapter) MakeRequests(request *openrtb.BidRequest, requestInfo *adapter
Uri: a.endpoint,
Body: requestJSON,
}
-
+
return []*adapters.RequestData{requestData}, nil
}
-func (a *adapter) MakeBids(request *openrtb.BidRequest, requestData *adapters.RequestData, responseData *adapters.ResponseData) (*adapters.BidderResponse, []error) {
+func (a *adapter) MakeBids(request *openrtb2.BidRequest, requestData *adapters.RequestData, responseData *adapters.ResponseData) (*adapters.BidderResponse, []error) {
if responseData.StatusCode == http.StatusNoContent {
return nil, nil
}
-
+
if responseData.StatusCode == http.StatusBadRequest {
err := &errortypes.BadInput{
Message: "Unexpected status code: 400. Bad request from publisher. Run with request.debug = 1 for more info.",
@@ -379,18 +473,17 @@ func (a *adapter) MakeBids(request *openrtb.BidRequest, requestData *adapters.Re
return nil, []error{err}
}
- var response openrtb.BidResponse
+ var response openrtb2.BidResponse
if err := json.Unmarshal(responseData.Body, &response); err != nil {
return nil, []error{err}
}
-
+
bidResponse := adapters.NewBidderResponseWithBidsCapacity(len(request.Imp))
bidResponse.Currency = response.Cur
for _, seatBid := range response.SeatBid {
- for _, bid := range seatBid.Bid {
- bid := bid // pin https://github.com/kyoh86/scopelint#whats-this
+ for i, bid := range seatBid.Bid {
b := &adapters.TypedBid{
- Bid: &bid,
+ Bid: &seatBid.Bid[i],
BidType: getMediaTypeForBid(bid),
}
bidResponse.Bids = append(bidResponse.Bids, b)
@@ -409,16 +502,16 @@ The first argument, `bidderName`, is the name of the bidder being built. This ma
The second argument, `config`, is all the configuration values set for your adapter. However, not all of this information is intended for use by the `Builder` method. The only two fields relevant here are `config.Endpoint` and `config.ExtraAdapterInfo`:
- `config.Endpoint` is the base url of your bidding server and may be interpreted as either a literal address or as a templated macro to support dynamic domains or dynamic paths.
-- `config.ExtraAdapterInfo` may be used for any other values your adapter may need, such as an application token or publisher allow/deny list. You may interpret this string however you like, although JSON is a common choice.
+- `config.ExtraAdapterInfo` is an optional setting may be used for any other values your adapter may need, such as an application token or publisher allow/deny list. You may interpret this string however you like, although JSON is a common choice.
-The `Builder` method is expected to return an error if either the `config.Endpoint` or the `config.ExtraAdapterInfo` values are invalid or cannot be parsed. Errors will be surfaced to the host during application startup as a fatal error.
+The `Builder` method is expected to return an error if either the `config.Endpoint` or the `config.ExtraAdapterInfo` values are invalid or cannot be parsed. Errors will be surfaced to the host during application startup as a fatal error.
Example: Builder using endpoint macros.
```go
type adapter struct {
- endpointTemplate template.Template
+ endpointTemplate *template.Template
}
// Builder builds a new instance of the Foo adapter for the given bidder with the given config.
@@ -427,9 +520,9 @@ func Builder(bidderName openrtb_ext.BidderName, config config.Adapter) (adapters
if err != nil {
return nil, fmt.Errorf("unable to parse endpoint url template: %v", err)
}
-
+
bidder := &adapter{
- endpointTemplate: *template,
+ endpointTemplate: template,
}
return bidder, nil
}
@@ -450,7 +543,7 @@ func Builder(bidderName openrtb_ext.BidderName, config config.Adapter) (adapters
if err != nil {
return nil, err
}
-
+
bidder := &adapter{
endpoint: config.Endpoint,
token: info.token,
@@ -484,9 +577,9 @@ func buildDefaultExtraInfo() extraInfo {
The `MakeRequests` method is responsible for returning none, one, or many HTTP requests to be sent to your bidding server. Bid adapters are forbidden from directly initiating any form of network communication and must entirely rely upon the core framework. This allows the core framework to optimize outgoing connections using a managed pool and record networking metrics. The return type `adapters.RequestData` allows your adapter to specify the HTTP method, url, body, and headers.
-This method is called once by the core framework for bid requests which have at least one valid Impression for your adapter. Impressions not configured for your adapter will be removed and are not accessible.
+This method is called once by the core framework for bid requests which have at least one valid Impression for your adapter. Impressions not configured for your adapter are not accessible.
-The first argument, `request`, is the OpenRTB 2.5 Bid Request object. Extension information is stored as `json.RawMessage` byte arrays and must be unmarshalled and/or marshalled to be read and/or mutated. It is *critical* to understand that the `request` object contains pointers to shared memory. If your adapter needs to alter any data referenced by a pointer then you *must* first make a shallow copy. The only exception is for `request.Imp` and its elements, as these are already shallow copies. The exact same instance of the `request` object is also passed to the `MakeBids` method, so please be careful when mutating. It's safe to assume that `request.Imp[]` always contains at least one element and that the `request.Imp[].ext.bidder` was successfully validated by your bidder parameter JSON Schema.
+The first argument, `request`, is the OpenRTB 2.5 Bid Request object. Extension information is stored as `json.RawMessage` byte arrays and must be unmarshalled and/or marshalled to be read and/or mutated. It is *critical* to understand that the `request` object contains pointers to shared memory. If your adapter needs to alter any data referenced by a pointer then you *must* first make a shallow copy. The only exception is for `request.Imp` and its elements, as these are already shallow copies. The exact same instance of the `request` object is also passed to the `MakeBids` method, so please be careful when mutating. It's safe to assume that `request.Imp[]` always contains at least one element and that the `request.Imp[].ext.bidder` was successfully validated per your bidder parameter JSON Schema.
Example: Mutating banner shared memory (make a copy).
@@ -506,36 +599,35 @@ if request.Imp[i].W == nil && request.Imp[i].H == nil && len(request.Imp[i].Form
The second argument, `requestInfo`, is for extra information and helper methods provided by the core framework. This includes:
-- `requestInfo.PbsEntryPoint` to access the entry point of the bid request, commonly used to determine if the request is for AMP or for a Long Form Video Ad Pod.
-- `requestInfo.GlobalPrivacyControlHeader` to read the value of the Sec-GPC Global Privacy Control (GPC) header of the bid request.
+- `requestInfo.PbsEntryPoint` to access the entry point of the bid request, commonly used to determine if the request is for AMP or for a [Long Form Video Ad Pod](/dev-docs/modules/adpod.html).
+- `requestInfo.GlobalPrivacyControlHeader` to read the value of the `Sec-GPC` Global Privacy Control (GPC) header of the bid request.
- `requestInfo.ConvertCurrency` a method to perform currency conversions.
-The `MakeRequests` method is expected to return a slice (similar to a C# `List` or a Java `ArrayList`) of `adapters.RequestData` objects representing the HTTP calls to be sent to your bidding server and a slice of type `error` for any issues encountered creating them. If there are no HTTP calls or if there are no errors, please return `nil` for both return values. Neither slices may contain `nil` elements.
+The `MakeRequests` method is expected to return a slice (similar to a C# `List` or a Java `ArrayList`) of `adapters.RequestData` objects representing the HTTP calls to be sent to your bidding server and a slice of type `error` for any issues encountered creating them. If there are no HTTP calls or if there are no errors, please return `nil` for both return values. Please do not add `nil` items in the slices.
{: .alert.alert-info :}
HTTP calls to your bidding server will automatically prefer GZIP compression. You should not specify it yourself using headers. You don't have to worry about decompressing the response in `MakeBids` either, as that will be taken care of automatically.
-An Impression may define multiple sizes and/or multiple ad formats. If your bidding server limits requests to a single ad placement, size, or format, then your adapter will need to split the Impression into multiple calls and merge the responses.
+##### Impression Splitting
-
- Example: Impression splitting.
+An Impression may define multiple sizes and/or multiple ad formats. If your bidding server limits requests to a single ad placement, size, or format, then your adapter will need to split the Impression into multiple calls and merge the responses.
```go
-func (a *adapter) MakeRequests(request *openrtb.BidRequest, requestInfo *adapters.ExtraRequestInfo) (*adapters.RequestData, []error) {
+func (a *adapter) MakeRequests(request *openrtb2.BidRequest, requestInfo *adapters.ExtraRequestInfo) (*adapters.RequestData, []error) {
var requests []*adapters.RequestData
var errors []error
-
+
requestCopy := *request
for _, imp := range request.Imp {
- requestCopy.Imp = []openrtb.Imp{imp}
+ requestCopy.Imp = []openrtb2.Imp{imp}
requestJSON, err := json.Marshal(request)
if err != nil {
errors = append(errors, err)
continue
}
-
+
requestData := &adapters.RequestData{
Method: "POST",
Uri: a.endpoint,
@@ -546,10 +638,12 @@ func (a *adapter) MakeRequests(request *openrtb.BidRequest, requestInfo *adapter
return requests, errors
}
```
-
-
-If your bidding server supports multiple currencies, please be sure to pass through the `request.cur` field. If your bidding server only bids in a single currency, such as USD or EUR, that's fine. Prebid Server will convert your bid to the request currency if you include it in the bid response, otherwise we assume USD and conversion will not occur.
+##### Currency
+
+If your bidding server supports multiple currencies, please pass through the `request.cur` field. If your bidding server only bids in a single currency, such as USD or EUR, that's fine. Prebid Server will convert your bid to the request currency if you include it in the bid response, otherwise we assume USD and conversion will not occur.
+
+Please ensure you forward the bid floor (`request.imp[].bidfloor`) and bid floor currency (`request.imp[].bidfloorcur`) values to your bidding server for enforcement. You can use of the `requestInfo.ConvertCurrency` helper method for currency conversions if your endpoint only supports floors in a specific currency.
Please ensure you forward the bid floor (`request.imp[].bidfloor`) and bid floor currency (`request.imp[].bidfloorcur`) values to your bidding server for enforcement. You have access to the currency conversion helper method `ConvertCurrency` in case your endpoint only supports floors in a single currency.
@@ -558,9 +652,8 @@ Please ensure you forward the bid floor (`request.imp[].bidfloor`) and bid floor
```go
func (a *adapter) MakeRequests(request *openrtb2.BidRequest, requestInfo *adapters.ExtraRequestInfo) (*adapters.RequestData, []error) {
-
- for _, imp := range request.Imp {
+ for _, imp := range request.Imp {
// Check if imp comes with bid floor amount defined in a foreign currency
if imp.BidFloor > 0 && imp.BidFloorCur != "" && strings.ToUpper(imp.BidFloorCur) != "USD" {
@@ -571,8 +664,7 @@ func (a *adapter) MakeRequests(request *openrtb2.BidRequest, requestInfo *adapte
}
// Update after conversion. All imp elements inside request.Imp are shallow copies
- // therefore, their non-pointer values are not shared memory and are safe to modify
- // without risking a data race condition
+ // therefore, their non-pointer values are not shared memory and are safe to modify.
imp.BidFloorCur = "USD"
imp.BidFloor = convertedValue
}
@@ -588,13 +680,15 @@ func (a *adapter) MakeRequests(request *openrtb2.BidRequest, requestInfo *adapte
Uri: a.endpoint,
Body: requestJSON,
}
-
+
return []*adapters.RequestData{requestData}, nil
}
```
+##### Common Data
+
There are a several values of a bid that publishers expect to be populated. Some are defined by the OpenRTB 2.5 specification and some are defined by Prebid conventions.
{: .table .table-bordered .table-striped }
@@ -607,7 +701,7 @@ There are a several values of a bid that publishers expect to be populated. Some
| [Request-Defined currency conversion rates](https://docs.prebid.org/prebid-server/features/pbs-currency.html) | Prebid | `request.ext.prebid.currency` Example: Setting metadata.
```go
-func (a *adapter) MakeBids(request *openrtb.BidRequest, requestData *adapters.RequestData, responseData *adapters.ResponseData) (*adapters.BidderResponse, []error) {
+func (a *adapter) MakeBids(request *openrtb2.BidRequest, requestData *adapters.RequestData, responseData *adapters.ResponseData) (*adapters.BidderResponse, []error) {
...
for _, seatBid := range response.SeatBid {
- for _, bid := range seatBid.Bid {
- bid := bid // pin https://github.com/kyoh86/scopelint#whats-this
+ for i, bid := range seatBid.Bid {
b := &adapters.TypedBid{
- Bid: &bid,
+ Bid: &seatBid.Bid[i],
BidType: getMediaTypeForBid(bid),
- }
-
- if meta, err := buildMeta(b); err != nil {
- errs = append(errs, metaErr)
- } else {
- b.Bid.Ext = meta
- bidResponse.Bids = append(bidResponse.Bids, b)
+ BidMeta: getBidMeta(bid),
}
}
...
}
-func buildMeta(bid *adapters.TypedBid) (json.RawMessage, error) {
- metaExt := openrtb_ext.ExtBidPrebid {
- Meta: &openrtb_ext.ExtBidPrebidMeta {
- NetworkID: 1,
- NetworkName: "Some Network Name",
- AgencyID: 2,
- AgencyName: "Some Agency Name",
- AdvertiserID: 3,
- AdvertiserName: "Some Advertiser Name",
- DChain: json.RawMessage(`{Some Demand Chain JSON}`),
- BrandID: 4,
- BrandName: "Some Brand Name",
- PrimaryCategoryID: "IAB-1",
- SecondaryCategoryIDs: []string{"IAB-2", "IAB-3"},
- MediaType: b.BidType,
- }
+func getBidMeta(bid *adapters.TypedBid) *openrtb_ext.ExtBidPrebidMeta {
+ // Not all fields are required. This example includes all fields for
+ // demonstration purposes.
+ return &openrtb_ext.ExtBidPrebidMeta {
+ NetworkID: 1,
+ NetworkName: "Some Network Name",
+ AgencyID: 2,
+ AgencyName: "Some Agency Name",
+ AdvertiserID: 3,
+ AdvertiserName: "Some Advertiser Name",
+ AdvertiserDomains: []string{"Some Domain"},
+ DemandSource: "Some Demand Source",
+ DChain: json.RawMessage(`{Some Demand Chain JSON}`),
+ BrandID: 4,
+ BrandName: "Some Brand Name",
+ PrimaryCategoryID: "IAB-1",
+ SecondaryCategoryIDs: []string{"IAB-2", "IAB-3"},
+ MediaType: "banner",
}
- return json.Marshal(meta)
}
```
-### Create A User Syncer (Optional)
-
-Prebid Server offers a federated [user sync solution](https://docs.prebid.org/prebid-server/developers/pbs-cookie-sync.html) to store user ids in a single cookie under the host's domain. You may add support with a relatively small amount of code if your bidding server supports this protocol.
-
-Create a file with the path `adatpers/{bidder}/usersync.go` using the following template:
-
-```go
-package {bidder}
-
-import (
- "text/template"
-
- "github.com/prebid/prebid-server/adapters"
- "github.com/prebid/prebid-server/usersync"
-)
-
-func NewSyncer(template *template.Template) usersync.Usersyncer {
- return adapters.NewSyncer("{bidder}", template, adapters.SyncTypeRedirect)
-}
-```
-
-The heavy lifting is handled by the `adapters.NewSyncer` method. You just need to provide a few arguments:
-
-{: .table .table-bordered .table-striped }
-| Argument | Description
-| - | -
-| `familyName` | Name used for storing your user sync id within the federated cookie. Please keep this the same as your bidder name.
-| `urlTemplate` | Pass through the `template` argument.
-| `syncType` | Type of user sync supported by your bidding server. The valid options are `SyncTypeRedirect` and `SyncTypeIframe`.
-
### Register With The Core
-Prebid Server does not use reflection or any other automagic technology to recognize your new bid adapter. You must manually register it with the core framework.
+Prebid Server does not use reflection or any other automated technology to recognize your new bid adapter. You must manually register it with the core framework.
{: .alert.alert-info :}
You will need to add an `import` statement for your bid adapter package in these files. Modern code editors such as Visual Studio Code and JetBrain's GoLand will automatically do that for you.
@@ -791,7 +854,7 @@ const (
func CoreBidderNames() []BidderName {
return []BidderName{
...
- Bidder{Bidder},
+ Bidder{Bidder},
...
}
}
@@ -809,20 +872,9 @@ func newAdapterBuilders() map[openrtb_ext.BidderName]adapters.Builder {
}
```
-If you have a user syncer, edit the file `usersync/usersyncers/syncer.go` to include it in the syncer map.
-
-```go
-func NewSyncerMap(cfg *config.Configuration) map[openrtb_ext.BidderName]usersync.Usersyncer {
- syncers := make(map[openrtb_ext.BidderName]usersync.Usersyncer, len(cfg.Adapters))
- ...
- insertIntoMap(cfg, syncers, openrtb_ext.Bidder{Bidder}, {bidder}.NewSyncer)
- ...
-}
-```
-
### Set Adapter Defaults
-Lastly, you need to provide default settings for your bid adapter. You can decide if you'd like your bid adapter to be enabled out of the box, and if so, you'll need to provide a default endpoint and default extra adapter info if applicable. If your bid adapter requires host specific information to function properly, such as a security token or host account, then it's best to leave the adapter disabled.
+You need to provide default settings for your bid adapter. You can decide if you'd like your bid adapter to be enabled out of the box, and if so, you'll need to provide a default endpoint and default extra adapter info (if applicable). If your bid adapter requires host specific information to function properly, such as a security token or host account, then it's best to leave the adapter disabled.
{: .alert.alert-warning :}
**HOST SPECIFIC INFO:** The default endpoint must not be specific to any particular host, such as Xandr/AppNexus. We may ask you about suspicious looking ids during the review process. Please reach out to individual hosts if you need to set specialized configuration.
@@ -835,7 +887,7 @@ Edit the file `config/config.go` to register your default endpoint within the `S
func SetupViper(v *viper.Viper, filename string) {
...
v.SetDefault("adapters.{bidder}.endpoint", "https://your.url/any/path")
- v.SetDefault("adapters.{bidder}.extra_info", `{"your": "extra info"}`)
+ v.SetDefault("adapters.{bidder}.extra_info", `{"your": "extra info"}`)
...
}
```
@@ -852,76 +904,9 @@ func SetupViper(v *viper.Viper, filename string) {
}
```
-### Set User Syncer Defaults
-
-If you implemented a user syncer, you'll need to provide a default endpoint. Edit the file `config/config.go` to alphabetically register your user syncer in the `setDerivedDefaults` method:
-
-```go
-func (cfg *Configuration) setDerivedDefaults() {
- ...
- setDefaultUsersync(cfg.Adapters, openrtb_ext.Bidder{Bidder}, "https://your.url/sync?r="+url.QueryEscape(externalURL)+"%2Fsetuid%3Fbidder%3D{bidder}%26gdpr%3D{%raw%}{{.GDPR}}%26gdpr_consent%3D{{.GDPRConsent}}{%endraw%}%26uid%3D%5BUUID%5D")
- ...
-}
-```
-
-If you don't have a good default, please add a comment instead.
-
-```go
-func (cfg *Configuration) setDerivedDefaults() {
- ...
- // openrtb_ext.Bidder{Bidder} doesn't have a good default.
- ...
-}
-```
-
-
-Yes, you're right. That url value is quite complicated. You can find further details in our [user sync documentation](https://docs.prebid.org/prebid-server/developers/pbs-cookie-sync.html).
-
-The user sync endpoint is composed of two main parts, the url of your user syncer and a redirect back to Prebid Server. The url of your user syncer is responsible for reading the user id from the client's cookie and redirecting to Prebid Server with a user id macro resolved.
-
-The url of your user syncer can make use of the following privacy policy macros which will be resolved by Prebid Server before sending the url to your server:
-- `{%raw%}{{.USPrivacy}}{%endraw%}`: Client's CCPA consent string.
-- `{%raw%}{{.GDPR}}{%endraw%}`: Client's GDPR TCF enforcement flag.
-- `{%raw%}{{.GDPRConsent}}{%endraw%}`: Client's GDPR TCF consent string.
-
-
- Example: Bidding server url with no macros.
-
-```go
-"https://your.url/sync?r="
-```
-
-
-
- Example: Bidding server url with CCPA privacy consent.
-
-```go
-"https://your.url/sync?usp={%raw%}{{.USPrivacy}}{%endraw%}&r="
-```
-
-
-
-The redirect url for Prebid Server must follow this format:
-```
-{host}/setuid?bidder={bidder}&gdpr={%raw%}{{.GDPR}}&gdpr_consent={{.GDPRConsent}}{%endraw%}&uid=[UUID]
-```
-
-{: .table .table-bordered .table-striped }
-| Token | Description
-| - | -
-| `{host}` | Placeholder for the Prebid Server host url. In code, you would substitute it with `url.QueryEscape(externalURL)`.
-| `{bidder}` | Placeholder for the name of your bid adapter.
-| `[UUID]` | Macro defined by your user sync server which will be replaced with the user's id.
-
-The final value of the redirect url is encoded for safe use within a query string:
-
-```
-{host}%2Fsetuid%3Fbidder%3D{bidder}%26gdpr%3D{%raw%}{{.GDPR}}%26gdpr_consent%3D{{.GDPRConsent}}{%endraw%}%26uid%3D%5BUUID%5D
-```
-
## Test Your Adapter
-This chapter will guide you through the creation of automated unit tests to cover your bid adapter code, bidder parameters JSON Schema, and user sync code. We use GitHub Action Workflows to ensure the code you submit passes validation. You can run the same validation locally with this command:
+This section will guide you through the creation of automated unit tests to cover your bid adapter code and bidder parameters JSON Schema. We use GitHub Action Workflows to ensure the code you submit passes validation. You can run the same validation locally with this command:
```bash
./validate.sh --nofmt --cov --race 10
@@ -940,7 +925,7 @@ package {bidder}
import (
"testing"
-
+
"github.com/prebid/prebid-server/adapters/adapterstest"
"github.com/prebid/prebid-server/config"
"github.com/prebid/prebid-server/openrtb_ext"
@@ -949,11 +934,11 @@ import (
func TestJsonSamples(t *testing.T) {
bidder, buildErr := Builder(openrtb_ext.Bidder{Bidder}, config.Adapter{
Endpoint: "http://whatever.url"})
-
+
if buildErr != nil {
t.Fatalf("Builder returned unexpected error %v", buildErr)
}
-
+
adapterstest.RunJSONBidderTest(t, "{bidder}test", bidder)
}
```
@@ -1008,7 +993,7 @@ The format of a JSON test is as follows:
The `mockBidRequest`, `httpCalls`, and `expectedBidResponses` fields are required. The `expectedMakeRequestsErrors` and `expectedMakeBidsErrors` may be omitted if there are no expected errors. We provide a `literal` and `regex` mode for testing error values. We often use the `regex` mode to handle error messages produced by the core Go framework which changed between recent releases.
-To make everyone's life easier, please use a JSON 'prettifier' to apply standard formatting to your test files. We recommend the use of Visual Studio Code's [Beautify](https://marketplace.visualstudio.com/items?itemName=HookyQR.beautify) extension.
+Please use a JSON 'prettifier' to apply standard formatting to your test files. We recommend the use of Visual Studio Code's [Beautify](https://marketplace.visualstudio.com/items?itemName=HookyQR.beautify) extension.
### Builder Tests
@@ -1020,7 +1005,7 @@ If your adapter supports template parsing, we recommend adding this failure test
func TestEndpointTemplateMalformed(t *testing.T) {
_, buildErr := Builder(openrtb_ext.Bidder{Bidder}, config.Adapter{
Endpoint: "{%raw%}{{Malformed}}{%endraw%}"})
-
+
assert.Error(t, buildErr)
}
```
@@ -1033,7 +1018,7 @@ func TestBadConfig(t *testing.T) {
Endpoint: `http://it.doesnt.matter/bid`,
ExtraAdapterInfo: `{foo:42}`,
})
-
+
assert.Error(t, buildErr)
}
@@ -1042,9 +1027,9 @@ func TestEmptyConfig(t *testing.T) {
Endpoint: `http://it.doesnt.matter/bid`,
ExtraAdapterInfo: ``,
})
-
+
bidder{Bidder} := bidder.(*adapter)
-
+
assert.NoError(t, buildErr)
assert.Empty(t, bidder{Bidder}.extraInfo.SomeInfo)
}
@@ -1060,7 +1045,7 @@ package {bidder}
import (
"encoding/json"
"testing"
-
+
"github.com/prebid/prebid-server/openrtb_ext"
)
@@ -1069,7 +1054,7 @@ func TestValidParams(t *testing.T) {
if err != nil {
t.Fatalf("Failed to fetch the json schema. %v", err)
}
-
+
for _, p := range validParams {
if err := validator.Validate(openrtb_ext.Bidder{Bidder}, json.RawMessage(p)); err != nil {
t.Errorf("Schema rejected valid params: %s", p)
@@ -1082,7 +1067,7 @@ func TestInvalidParams(t *testing.T) {
if err != nil {
t.Fatalf("Failed to fetch the json schema. %v", err)
}
-
+
for _, p := range invalidParams {
if err := validator.Validate(openrtb_ext.Bidder{Bidder}, json.RawMessage(p)); err == nil {
t.Errorf("Schema allowed invalid params: %s", p)
@@ -1101,66 +1086,11 @@ var invalidParams = []string{
```
Please include tests for required fields, optional fields, conditional fields such as `oneOf`, regex filters, and data type mismatches. For example, if the field is defined as a string please include one invalid case for the wrong data type such as an integer in this example.
-You don't have to go crazy with combinatorials. We're looking for just enough test cases to build confidence.
-
-### User Syncer Tests
-
-{: .alert.alert-info :}
-Please skip to the end of this section if your adapter doesn't define a user syncer.
-
-We ask that you include a user syncer test to verify the basic mechanics of macro substitution. The `syncURL` should be the same value used in the `setDefaultUsersync` call with the `url.QueryEscape(externalURL)` code replaced with a simple hardcoded value such as `"host"`. Please keep the privacy policy values simple, as we're only testing substitution.
-
-Create a file with the path `adapters/{bidder}/usersync_test.go` using the following template:
-
-```go
-package {bidder}
-
-import (
- "testing"
- "text/template"
-
- "github.com/prebid/prebid-server/privacy"
- "github.com/prebid/prebid-server/privacy/ccpa"
- "github.com/prebid/prebid-server/privacy/gdpr"
- "github.com/stretchr/testify/assert"
-)
-
-func TestSyncer(t *testing.T) {
- syncURL := "
"
- syncURLTemplate := template.Must(
- template.New("sync-template").Parse(syncURL),
- )
-
- syncer := NewSyncer(syncURLTemplate)
- syncInfo, err := syncer.GetUsersyncInfo(privacy.Policies{
- GDPR: gdpr.Policy{
- Signal: "A",
- Consent: "B",
- },
- CCPA: ccpa.Policy{
- Consent: "C",
- },
- })
-
- assert.NoError(t, err)
- assert.Equal(t, "", syncInfo.URL)
- assert.Equal(t, "redirect", syncInfo.Type)
-}
-```
-
-If you *DON'T* have a user syncer, edit the file `usersync/usersyncers/syncer_test.go` to exclude your bid adapter from user sync tests:
-
-```go
-adaptersWithoutSyncers := map[openrtb_ext.BidderName]bool{
- ...
- openrtb_ext.Bidder{Bidder}: true,
- ...
-}
-```
+There is no need to provide a combinatorial for every edge case possibility. We're looking for just enough test cases to build confidence.
### Manual End To End Tests
-We'll verify your adapter works correctly on a technical level during the code review, but you'll need to perform separate end-to-end testing:
+We'll verify your adapter works correctly on a technical level during the code review, but you'll need to perform manual end-to-end testing:
1. Build the project and start your server:
```bash
@@ -1204,13 +1134,15 @@ We'll verify your adapter works correctly on a technical level during the code r
}'
```
-If your bid adapters defines a user syncer, please perform end-to-end testing of the user sync process:
+### User Sync Testing
+
+If your bid adapter defines one or more user sync endpoints, you'll need to perform manual end-to-end testing of each endpoint using the following process:
-1. [Save a User ID](https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-setuid.html) using the `familyName` of your user syncer. This is likely the same as your bidder name.
+1. [Save a User ID](https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-setuid.html) using the `key` of your user sync endpoint. This should default to your bidder name and is case sensitive.
1. Run a test auction (see the curl example above) and verify in the debug response that the outgoing `request.ext.debug.httpcalls` calls includes the User ID you saved in step 1.
-It may be a bit tricky to track down the root cause of user sync errors. If you get stuck, please [submit a GitHub issue](https://github.com/prebid/prebid-server/issues/new) and we'll provide guidance.
+If you are having issues finding the root cause of user sync errors, please [submit a GitHub issue](https://github.com/prebid/prebid-server/issues/new) and we'll provide guidance.
## User Documentation
@@ -1234,7 +1166,9 @@ dchain_supported: true/false
userId:
media_types: banner, video, audio, native
safeframes_ok: true/false
-bidder_supports_deals: true/false
+deals_supported: true/false
+floors_supported: true/false
+fpd_supported: true/false
pbjs: true/false
pbs: true/false
pbs_app_supported: true/false
@@ -1264,7 +1198,9 @@ Notes on the metadata fields:
- If you support adding a demand chain on the bid response, add `dchain_supported: true`. Default is false.
- If your bidder doesn't work well with safeframed creatives, add `safeframes_ok: false`. This will alert publishers to not use safeframed creatives when creating the ad server entries for your bidder. No default.
- If your bidder supports mobile apps, set `pbs_app_supported: true`. No default value.
-- If your bidder supports deals, set `bidder_supports_deals: true`. No default value.
+- If your bidder supports deals, set `deals_supported: true`. No default value.
+- If your bidder supports floors, set `floors_supported: true`. No default value.
+- If your bidder supports first party data, set `fpd_supported: true`. No default value.
- If you're a member of Prebid.org, add `prebid_member: true`. Default is false.
@@ -1281,13 +1217,6 @@ Notes on the metadata fields:
- `adapters/{bidder}/{bidder}_test.go`
- `adapters/{bidder}/{bidder}test/exemplary/*.json`
- `adapters/{bidder}/{bidder}test/supplemental/*.json`
- - `adapters/{bidder}/{bidder}test/params/race/{mediaType}.json`
-- User Syncer - If You Have One
- - `adapters/{bidder}/usersync.go`
- - `adapters/{bidder}/usersync_test.go`
- - `usersync/usersyncers/syncer.go`
-- User Syncer - If You Don't
- - `usersync/usersyncers/syncer_test.go`
- Register With The Core
- `openrtb_ext/bidders.go`
- `exchange/adapter_builders.go`
@@ -1296,7 +1225,7 @@ Notes on the metadata fields:
## Contribute
-Whew! You're almost done. Thank you for taking the time to develop a Prebid Server bid adapter. When you're ready, [contribute](https://github.com/prebid/prebid-server/blob/master/docs/developers/contributing.md) your new bid adapter by opening a PR to the [PBS-Go GitHub repository](https://github.com/prebid/prebid-server) with the name "New Adapter: {Bidder}".
+Thank you for taking the time to develop a Prebid Server bid adapter. When you're ready, [contribute](https://github.com/prebid/prebid-server/blob/master/docs/developers/contributing.md) your new bid adapter by opening a PR to the [PBS-Go GitHub repository](https://github.com/prebid/prebid-server) with the name "New Adapter: {Bidder}".
{: .alert.alert-warning :}
You don't need to ask permission or open a GitHub issue before submitting an adapter.
diff --git a/prebid-server/developers/add-new-bidder-java.md b/prebid-server/developers/add-new-bidder-java.md
index a40bebcad0..61471a929d 100644
--- a/prebid-server/developers/add-new-bidder-java.md
+++ b/prebid-server/developers/add-new-bidder-java.md
@@ -104,7 +104,6 @@ adapters:
Modify this template for your bid adapter:
- Change the maintainer email address to a group distribution list on your ad server's domain. A distribution list is preferred over an individual mailbox to allow for robustness, as roles and team members naturally change.
- Change the `modifying-vast-xml-allowed` value to `false` if you'd like to opt out of video impression tracking. It defaults to `true`.
-- Change the `pbs-enforces-gdpr` to `false` if you'd like to disable gdpr enforcement. Defaults to `true`.
- Change the `pbs-enforces-ccpa` to `false` if you'd like to disable ccpa enforcement. Defaults to `true`.
- Change the `vendor-id` value to id of your bidding server as registered with the [GDPR Global Vendor List (GVL)](https://iabeurope.eu/vendor-list-tcf-v2-0/). Leave this as `0` if you are not registered with IAB Europe.
- Remove the `capabilities` (app/site) and `mediaTypes` (banner/video/audio/native) combinations which your adapter does not support.
@@ -129,13 +128,15 @@ Default configuration:
```yaml
adapter-defaults:
enabled: false
- pbs-enforces-gdpr: true
pbs-enforces-ccpa: true
- deprecated-names:
- aliases: {}
modifying-vast-xml-allowed: true
```
+There are also some default properties which can't be overridden in adapter-defaults, but rather in particular adapter's config:
+- `aliases`: Defaults to empty
+- `deprecated-names`: Defaults to empty
+- `extra-info`: Defaults to empty
+
### Create bidder alias
If you want to add bidder that is an alias of existing bidder, you need just to update configuration of parent bidder:
@@ -143,7 +144,7 @@ Example of adding bidder alias:
```yaml
adapters:
yourBidderCode:
- endpoint: http://possible.endpoint
+ ...
aliases:
yourBidderAlias:
endpoint: http://possible.alias/endpoint
@@ -155,26 +156,6 @@ adapters:
- video
usersync:
cookie-family-name: yourBidderCode
- meta-info:
- maintainer-email: maintainer@email.com
- app-media-types:
- - banner
- - video
- - audio
- - native
- site-media-types:
- - banner
- - video
- - audio
- - native
- supported-vendors:
- vendor-id: your_vendor_id
- usersync:
- url: your_bid_adapter_usersync_url
- redirect-url: /setuid?bidder=yourBidderCode&gdpr={%raw%}{{gdpr}}{%endraw%}&gdpr_consent={%raw%}{{gdpr_consent}}{%endraw%}&us_privacy={%raw%}{{us_privacy}}{%endraw%}
- cookie-family-name: yourBidderCode
- type: redirect
- support-cors: false
```
Aliases are configured by adding child configuration object at `adapters.yourBidderCode.aliases.yourBidderAlias`
@@ -814,7 +795,6 @@ Go to `test-application.properties` file and add folowing properties
```yaml
adapters.{bidder}.enabled=true
adapters.{bidder}.endpoint=http://localhost:8090/{bidder}-exchange
-adapters.{bidder}.pbs-enforces-gdpr=true
adapters.{bidder}.usersync.url=//{bidder}-usersync
```
@@ -1188,7 +1168,9 @@ dchain_supported: true/false
userId:
media_types: banner, video, audio, native
safeframes_ok: true/false
-bidder_supports_deals: true/false
+deals_supported: true/false
+floors_supported: true/false
+fpd_supported: true/false
pbjs: true/false
pbs: true/false
pbs_app_supported: true/false
@@ -1218,7 +1200,9 @@ Notes on the metadata fields:
- If you support adding a demand chain on the bid response, add `dchain_supported: true`. Default is false.
- If your bidder doesn't work well with safeframed creatives, add `safeframes_ok: false`. This will alert publishers to not use safeframed creatives when creating the ad server entries for your bidder. No default.
- If your bidder supports mobile apps, set `pbs_app_supported`: true. No default value.
-- If your bidder supports deals, set `bidder_supports_deals: true`. No default value.
+- If your bidder supports deals, set `deals_supported: true`. No default value.
+- If your bidder supports floors, set `floors_supported: true`. No default value.
+- If your bidder supports first party data, set `fpd_supported: true`. No default value.
- If you're a member of Prebid.org, add `prebid_member: true`. Default is false.
diff --git a/prebid-server/developers/pbs-cookie-sync.md b/prebid-server/developers/pbs-cookie-sync.md
index 5469f89994..dc739375db 100644
--- a/prebid-server/developers/pbs-cookie-sync.md
+++ b/prebid-server/developers/pbs-cookie-sync.md
@@ -50,9 +50,9 @@ POST https://prebid-server.example.com/cookie_sync
3) When it receives the response, Prebid.js loops through each element of `bidder_status[]`, dropping a pixel for each `bidder_status[].usersync.url`.
-4) The bidder-specific endpoints read the users's cookie for the bidder's domain and respond with a redirect back to Prebid Server's [`/setuid` endpoint](/prebid-server/endpoints/pbs-endpoint-setuid.html)
+4) The bidder-specific endpoints read the users' cookie for the bidder's domain and respond with a redirect back to Prebid Server's [`/setuid` endpoint](/prebid-server/endpoints/pbs-endpoint-setuid.html)
-5) When the browser receives this redirect, it contacts Prebid Server, which will once again check the privacy settings and will update the `uids` cookie if allowed.
+5) When the browser receives this redirect, it contacts Prebid Server, which will once again check the privacy settings and if allowed, update the `uids` cookie.
### Setting the uids cookie from AMP
@@ -60,7 +60,8 @@ Cookie sync for AMP works in a way quite similar to Prebid.js.
1) The Prebid Server hosting company places a modified version of the `load-cookie` script onto a CDN. This script is part of the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative/blob/master/src/cookieSync.js) repo.
-Note that the only two values currently valid for 'endpoint' are 'appnexus' and 'rubicon' -- other host companies should update their copy to include their endpoint.
+{: .alert.alert-warning :}
+The only two values currently valid for 'endpoint' are 'appnexus' and 'rubicon' -- other host companies should update their copy to include their endpoint.
See [the AMP implementation guide](/dev-docs/show-prebid-ads-on-amp-pages.html#user-sync) for more information.
@@ -76,21 +77,19 @@ See [the AMP implementation guide](/dev-docs/show-prebid-ads-on-amp-pages.html#u
```
-Note: if the publisher has an AMP Consent Management Platform, they should use `load-cookie-with-consent.html`.
+{: .alert.alert-info :}
+If the publisher has an AMP Consent Management Platform, they should use `load-cookie-with-consent.html`.
3) At runtime, the `load-cookie` script just calls the Prebid Server /cookie_sync endpoint. The rest works the same as described for Prebid.js above.
## Bidder Instructions for Building a Sync Endpoint
-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:
+Building a sync endpoint is optional -- there is no benefit from ID syncing for mobile-only bidders. 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.
@@ -99,20 +98,24 @@ Bidders must implement an endpoint under their domain which accepts an encoded U
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 as coded into PBS-Go:
+Here's an example that shows the privacy macros as configured in 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%3DYOURMACRO
+userSync:
+ redirect:
+ url: https://some-bidder-domain.com/usersync-url?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%}
+ userMacro: YOURMACRO
```
+
PBS-Java uses slightly different macros in the bidder config:
```
- 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
+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={%raw%}{{gdpr}}{%endraw%}&gdpr_consent={%raw%}{{gdpr_consent}}{%endraw%}&us_privacy={%raw%}{{us_privacy}}{%endraw%}&uid=YOURMACRO
```
-In either case, the {%raw%}{{}}{%endraw%} macros are resolved by PBS.
+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.
+{: .alert.alert-warning :}
+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.
Here's how this all comes together:
diff --git a/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md b/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md
index 079e38ee65..007d721f2b 100644
--- a/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md
+++ b/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md
@@ -211,10 +211,10 @@ It's also possible to define different bid adjustment factors by mediatype, whic
"prebid": {
"bidadjustmentfactors": {
"bidderA": 0.9,
- "bidderB": 0.8
+ "bidderB": 0.8,
"mediatypes": {
"banner": {
- "bidderA": 0.8,
+ "bidderA": 0.8
},
"video-outstream": {
"bidderC": 0.9
@@ -222,7 +222,7 @@ It's also possible to define different bid adjustment factors by mediatype, whic
"video": {
"bidderB": 0.85
}
- }
+ }
}
}
}
@@ -268,7 +268,8 @@ to set these params on the response at `response.seatbid[i].bid[j].ext.prebid.ta
"precision": 2,
"ranges": [{
"max": 20.00,
- "increment": 0.10 // This is equivalent to the deprecated "pricegranularity": "medium"
+ "increment": 0.10 // This is equivalent to the deprecated
+ // "pricegranularity": "medium"
}]
},
"includewinners": true, // Optional param defaulting to false
@@ -423,9 +424,9 @@ This prevents breaking API changes as new Bidders are added to the project.
For example, if the Request defines an alias like this:
```
- "aliases": {
- "appnexus": "rubicon"
- }
+"aliases": {
+ "appnexus": "rubicon"
+}
```
then any `imp.ext.appnexus` params will actually go to the **rubicon** adapter.
@@ -438,13 +439,16 @@ For environments that have turned on [GDPR enforcement](/prebid-server/features/
To do this, just set `ext.prebid.aliasgvlids` alongside ext.prebid.aliases:
```
-"ext":
+"ext": {
"prebid": {
- "aliases": { "newAlias": "originalBidderCode" },
- "aliasgvlids": { "newAlias": 11111 }
+ "aliases": {
+ "newAlias": "originalBidderCode"
+ },
+ "aliasgvlids": {
+ "newAlias": 11111
}
}
-});
+}
```
##### Stored Requests
@@ -526,12 +530,10 @@ Example:
{
"imp": [{
...
- "banner": {
- ...
- }
+ "banner": { ... },
"instl": 1,
...
- }]
+ }],
"device": {
...
"h": 640,
@@ -556,20 +558,20 @@ PBS with interstitial support will come preconfigured with a list of common ad s
To set the desired 'ad server currency', use the standard OpenRTB `cur` attribute. Note that Prebid Server only looks at the first currency in the array.
```
- "cur": ["USD"]
+"cur": ["USD"]
```
If you want or need to define currency conversion rates (e.g. for currencies that your Prebid Server doesn't support),
-define ext.prebid.currency.rates. (Currently supported in PBS-Java only)
+define ext.prebid.currency.rates.
```
"ext": {
"prebid": {
- "currency": {
- "rates": {
- "USD": { "UAH": 24.47, "ETB": 32.04 }
- }
- }
+ "currency": {
+ "rates": {
+ "USD": { "UAH": 24.47, "ETB": 32.04 }
+ }
+ }
}
}
```
@@ -585,9 +587,9 @@ Basic supply chains are passed to Prebid Server on `source.ext.schain` and passe
Bidder-specific schains:
```
-ext.prebid.schains: [
- { bidders: ["bidderA"], schain: { SCHAIN OBJECT 1}},
- { bidders: ["*"], schain: { SCHAIN OBJECT 2}}
+"ext.prebid.schains": [
+ { "bidders": ["bidderA"], "schain": { SCHAIN OBJECT 1}},
+ { "bidders": ["*"], "schain": { SCHAIN OBJECT 2}}
]
```
In this scenario, Prebid Server sends the first schain object to `bidderA` and the second schain object to everyone else.
@@ -600,24 +602,23 @@ Prebid Server adapters can support the [Prebid.js User ID modules](/dev-docs/mod
```
{
- "user": {
- "ext": {
- "eids": [{
- "source": "adserver.org",
- "uids": [{
- "id": "111111111111",
- "ext": {
- "rtiPartner": "TDID"
- }
- }]
- },
- {
- "source": "pubcid.org",
- "id":"11111111"
- }
- ]
- }
+ "user": {
+ "ext": {
+ "eids": [{
+ "source": "adserver.org",
+ "uids": [{
+ "id": "111111111111",
+ "ext": {
+ "rtiPartner": "TDID"
+ }
+ }]
+ },
+ {
+ "source": "pubcid.org",
+ "id":"11111111"
+ }]
}
+ }
}
```
@@ -627,17 +628,17 @@ Publishers can constrain which bidders receive which user.ext.eids entries. See
```
{
- ext: {
- prebid: {
- data: {
- eidpermissions: [ // prebid server will use this to filter user.ext.eids
- {"source": "sharedid.org", "bidders": ["*"]}, // * is the default
- {"source": "neustar.biz", "bidders": ["bidderB"]},
- {"source": "id5-sync.com", "bidders": ["bidderA","bidderC"]}
- ]
- }
- }
+ "ext": {
+ "prebid": {
+ "data": {
+ "eidpermissions": [ // prebid server will use this to filter user.ext.eids
+ {"source": "sharedid.org", "bidders": ["*"]}, // * is the default
+ {"source": "neustar.biz", "bidders": ["bidderB"]},
+ {"source": "id5-sync.com", "bidders": ["bidderA","bidderC"]}
+ ]
+ }
}
+ }
}
```
@@ -678,24 +679,34 @@ When a storedauctionresponse ID is specified:
This request:
```
{
- "test":1,
- "tmax":500,
+ "test": 1,
+ "tmax": 500,
"id": "test-auction-id",
"app": { ... },
"ext": {
- "prebid": {
- "targeting": {},
- "cache": { "bids": {} }
- }
+ "prebid": {
+ "targeting": {},
+ "cache": {
+ "bids": {}
+ }
+ }
},
"imp": [
{
"id": "a",
- "ext": { "prebid": { "storedauctionresponse": { "id": "1111111111" } } }
+ "ext": {
+ "prebid": {
+ "storedauctionresponse": { "id": "1111111111" }
+ }
+ }
},
{
"id": "b",
- "ext": { "prebid": { "storedauctionresponse": { "id": "22222222222" } } }
+ "ext": {
+ "prebid": {
+ "storedauctionresponse": { "id": "22222222222" }
+ }
+ }
}
]
}
@@ -704,16 +715,16 @@ This request:
Will result in this response, assuming that the ids exist in the appropriate DB table read by Prebid Server:
```
{
- "id": "test-auction-id",
- "seatbid": [
- {
- // BidderA bids from storedauctionresponse=1111111111
- // BidderA bids from storedauctionresponse=22222222
- },
- {
- // BidderB bids from storedauctionresponse=1111111111
- // BidderB bids from storedauctionresponse=22222222
- }
+ "id": "test-auction-id",
+ "seatbid": [
+ {
+ // BidderA bids from storedauctionresponse=1111111111
+ // BidderA bids from storedauctionresponse=22222222
+ },
+ {
+ // BidderB bids from storedauctionresponse=1111111111
+ // BidderB bids from storedauctionresponse=22222222
+ }
]
}
```
@@ -724,37 +735,37 @@ In contrast to what's outlined above, this approach lets some real auctions take
```
{
- "test":1,
- "tmax":500,
+ "test": 1,
+ "tmax": 500,
"id": "test-auction-id",
"app": { ... },
"ext": {
- "prebid": {
- "targeting": {},
- "cache": { "bids": {} }
- }
+ "prebid": {
+ "targeting": {},
+ "cache": { "bids": {} }
+ }
},
"imp": [
{
"id": "a",
"ext": {
- "prebid": {
- "storedbidresponse": [
- { "bidder": "BidderA", "id": "333333" },
- { "bidder": "BidderB", "id": "444444" },
- ]
- }
+ "prebid": {
+ "storedbidresponse": [
+ { "bidder": "BidderA", "id": "333333" },
+ { "bidder": "BidderB", "id": "444444" },
+ ]
+ }
}
},
{
"id": "b",
"ext": {
- "prebid": {
- "storedbidresponse": [
- { "bidder": "BidderA", "id": "5555555" },
- { "bidder": "BidderB", "id": "6666666" },
- ]
- }
+ "prebid": {
+ "storedbidresponse": [
+ { "bidder": "BidderA", "id": "5555555" },
+ { "bidder": "BidderB", "id": "6666666" },
+ ]
+ }
}
}
]
@@ -764,18 +775,18 @@ Could result in this response:
```
{
- "id": "test-auction-id",
- "seatbid": [
- {
- "bid": [
- // contents of storedbidresponse=3333333 as parsed by bidderA adapter
- // contents of storedbidresponse=5555555 as parsed by bidderA adapter
- ]
- },
- {
- // contents of storedbidresponse=4444444 as parsed by bidderB adapter
- // contents of storedbidresponse=6666666 as parsed by bidderB adapter
- }
+ "id": "test-auction-id",
+ "seatbid": [
+ {
+ "bid": [
+ // contents of storedbidresponse=3333333 as parsed by bidderA adapter
+ // contents of storedbidresponse=5555555 as parsed by bidderA adapter
+ ]
+ },
+ {
+ // contents of storedbidresponse=4444444 as parsed by bidderB adapter
+ // contents of storedbidresponse=6666666 as parsed by bidderB adapter
+ }
]
}
```
@@ -793,49 +804,52 @@ It specifies where in the OpenRTB request non-standard attributes should be pass
```
{
+ "ext": {
+ "prebid": {
+ "data": { "bidders": [ "rubicon", "appnexus" ] } // these are the bidders allowed to see protected data
+ }
+ },
+ "site": {
+ "keywords": "",
+ "search": "",
"ext": {
- "prebid": {
- "data": { "bidders": [ "rubicon", "appnexus" ] } // these are the bidders allowed to see protected data
- }
- },
- "site": {
- "keywords": "",
- "search": "",
- "ext": {
- data: { GLOBAL SITE DATA } // only seen by bidders named in ext.prebid.data.bidders[]
- }
- },
- "user": {
- "keywords": "",
- "gender": "",
- "yob": 1999,
- "geo": {},
- "ext": {
- data: { GLOBAL USER DATA } // only seen by bidders named in ext.prebid.data.bidders[]
+ "data": { GLOBAL SITE DATA } // only seen by bidders named in ext.prebid.data.bidders[]
+ }
+ },
+ "user": {
+ "keywords": "",
+ "gender": "",
+ "yob": 1999,
+ "geo": {},
+ "ext": {
+ "data": { GLOBAL USER DATA } // only seen by bidders named in ext.prebid.data.bidders[]
+ }
+ },
+ "imp": [
+ {
+ ...
+ "ext": {
+ "data": {
+ ADUNIT SPECFIC CONTEXT DATA // can be seen by all bidders
}
- },
- "imp": [
- ...
- "ext": {
- "data": {
- ADUNIT SPECFIC CONTEXT DATA // can be seen by all bidders
- }
- }
- ]
+ }
+ }
+ ]
+}
```
Bidder-specific data can be defined with ext.prebid.bidderconfig:
```
-ext: {
- prebid: {
- bidderconfig:
- bidders: ["bidderA", "bidderB"],
- config: [
- ortb2: {
- site: { ... },
- user: { ... }
- }
- ]
+"ext": {
+ "prebid": {
+ "bidderconfig": {
+ "bidders": ["bidderA", "bidderB"]
+ },
+ "config": {
+ "ortb2": {
+ "site": { ... },
+ "user": { ... }
+ }
}
}
}
@@ -858,20 +872,21 @@ An OpenRTB extension, whether in the the original request or the [stored-request
The OpenRTB field is `ext.prebid.adservertargeting`. Here's an example:
```
- ext.prebid.adservertargeting: [{
- "key": "hb_amp_ow", // the targeting key
- "source": "bidrequest", // pull the value from the path specified in the bid request object
- "value": "ext.prebid.amp.data.ow" // path to value in the bidrequest
- },{
- "key": "hb_static_thing",
- "source": "static", // just use the 'value' provided
- "value": "my-static-value"
- },{
- "key": "{{BIDDER}}_custom1", // {{BIDDER}} is a macro to be resolved
- "source": "bidresponse", // pull the value from the path specified in the bid response object
- "value": "seatbid.bid.ext.custom1"
- }
- }]
+"ext.prebid.adservertargeting": [
+ {
+ "key": "hb_amp_ow", // the targeting key
+ "source": "bidrequest", // pull the value from the path specified in the bid request object
+ "value": "ext.prebid.amp.data.ow" // path to value in the bidrequest
+ },{
+ "key": "hb_static_thing",
+ "source": "static", // just use the 'value' provided
+ "value": "my-static-value"
+ },{
+ "key": "{% raw %}{{BIDDER}}{% endraw %}_custom1", // {% raw %}{{BIDDER}}{% endraw %} is a macro to be resolved
+ "source": "bidresponse", // pull the value from the path specified in the bid response object
+ "value": "seatbid.bid.ext.custom1"
+ }
+]
```
`ext.prebid.adservertargeting` is an array objects. Each object has the following format:
@@ -884,30 +899,30 @@ The OpenRTB field is `ext.prebid.adservertargeting`. Here's an example:
In order to pull AMP parameters out into targeting, Prebid Server places AMP query string parameters in ext.prebid.amp.data. e.g.
```
- "ext": {
- "prebid": {
- "amp": {
- "data": {
- "adc": "GA1.2.662776284.1602172186",
- "curl": "https://example.com/index.html",
- "debug": "1",
- "pvid": "", // page view ID
- "ms": "", // multi-size
- "ow": "", // override-width
- "oh": "", // override-height
- "w": "300",
- "h": "50",
- "gdpr_consent": "",
- "purl": "https://example.com/index.html",
- "slot": "/11111/amp_test",
- "timeout": "1000",
- "targeting": "{\"site\":{\"attr\":\"val\"}}",
- "tag_id": "amp-AMP_Test-300x250",
- "account": "22222"
- }
- }
- }
+"ext": {
+ "prebid": {
+ "amp": {
+ "data": {
+ "adc": "GA1.2.662776284.1602172186",
+ "curl": "https://example.com/index.html",
+ "debug": "1",
+ "pvid": "", // page view ID
+ "ms": "", // multi-size
+ "ow": "", // override-width
+ "oh": "", // override-height
+ "w": "300",
+ "h": "50",
+ "gdpr_consent": "",
+ "purl": "https://example.com/index.html",
+ "slot": "/11111/amp_test",
+ "timeout": "1000",
+ "targeting": "{\"site\":{\"attr\":\"val\"}}",
+ "tag_id": "amp-AMP_Test-300x250",
+ "account": "22222"
+ }
}
+ }
+}
```
##### EID Permissions (PBS-Go only)
@@ -917,17 +932,17 @@ in user.ext.eids is allowed to be passed to which bid adapter. For example:
```
{
- ext: {
- prebid: {
- data: {
- eidpermissions: [ // prebid server will use this to filter user.ext.eids
- {"source": "sharedid.org", "bidders": ["*"]}, // * is the default
- {"source": "neustar.biz", "bidders": ["bidderB"]},
- {"source": "id5-sync.com", "bidders": ["bidderA","bidderC"]}
- ]
- }
- }
+ "ext": {
+ "prebid": {
+ "data": {
+ "eidpermissions": [ // prebid server will use this to filter user.ext.eids
+ {"source": "sharedid.org", "bidders": ["*"]}, // * is the default
+ {"source": "neustar.biz", "bidders": ["bidderB"]},
+ {"source": "id5-sync.com", "bidders": ["bidderA","bidderC"]}
+ ]
+ }
}
+ }
}
```
@@ -942,19 +957,19 @@ The Prebid extension to the OpenRTB protocol is `ext.prebid.multibid`. For examp
```
{
- ext: {
- prebid: {
- multibid: [{
- bidder: "bidderA",
- maxbids: 2,
- targetbiddercodeprefix: "bidA"
- },{
- bidder: "bidderB",
- maxbids: 3,
- targetbiddercodeprefix: "bidB"
- },{
- bidders: ["bidderC", "bidderD"]
- maxbids: 2
+ "ext": {
+ "prebid": {
+ "multibid": [{
+ "bidder": "bidderA",
+ "maxbids": 2,
+ "targetbiddercodeprefix": "bidA"
+ }, {
+ "bidder": "bidderB",
+ "maxbids": 3,
+ "targetbiddercodeprefix": "bidB"
+ }, {
+ "bidders": ["bidderC", "bidderD"],
+ "maxbids": 2
}]
}
}
@@ -980,36 +995,36 @@ Prebid Server core does the following when it sees `ext.prebid.multibid`:
Here's an example response:
```
{
-seatbid: [{
- seat: "bidderA",
- bid: [{
- id: "bid1",
- impid: "imp1",
- price: 1.04,
- ext: {
- prebid: {
- targeting: {
- hb_pb_bidderA: 1.00
- },
- targetbiddercode: "bidderA"
+ "seatbid": [{
+ "seat": "bidderA",
+ "bid": [{
+ "id": "bid1",
+ "impid": "imp1",
+ "price": 1.04,
+ "ext": {
+ "prebid": {
+ "targeting": {
+ "hb_pb_bidderA": 1.00
+ },
+ "targetbiddercode": "bidderA"
}
- }
- ...
- },{
- id: "bid2",
- impid: "imp1", // same imp as above
- price:0.8,
- ext: {
- prebid: {
- targeting: {
- hb_pb_bidA2: 0.50
- },
- targetbiddercode: "bidA2"
+ }
+ ...
+ }, {
+ "id": "bid2",
+ "impid": "imp1", // same imp as above
+ "price": 0.8,
+ "ext": {
+ "prebid": {
+ "targeting": {
+ "hb_pb_bidA2": 0.50
+ },
+ "targetbiddercode": "bidA2"
}
- }
- ...
+ }
+ ...
+ }]
}]
-}]
}
```
@@ -1022,24 +1037,25 @@ which causes PBS-core to place the video-related attributes on the response.
```
{
- ...
-
- "imp": [
- {
- "id": "123456789",
- "video": { ... },
- "ext": {
- "prebid": {
- "storedrequest": { "id": "xxx" },
- "options": {
- "echovideoattrs": true
- }
- }
- },
- ...
+ ...
+ "imp": [{
+ "id": "123456789",
+ "video": {
+ ...
+ },
+ "ext": {
+ "prebid": {
+ "storedrequest": {
+ "id": "xxx"
+ },
+ "options": {
+ "echovideoattrs": true
}
- ]
+ }
+ },
...
+ }]
+ ...
}
```
1. Prebid Server receives this request and expands the `storedrequest` value, merging it with the imp object.
@@ -1047,31 +1063,26 @@ which causes PBS-core to place the video-related attributes on the response.
```
{
- "seatbid": [{
- "bid": [{
- ...
- "ext": {
- "prebid": {
- "storedrequestattributes":{
- "maxduration": 60,
- "mimes": [
- "video/mp4"
- ],
- "minduration": 15,
- "protocols": [
- 1,
- 2
- ],
- "skipafter": 0,
- "skipmin": 0,
- "startdelay": 0,
- "playbackmethod": [1]
- }
- }
- }
- }]
- }],
-...
+ "seatbid": [{
+ "bid": [{
+ ...
+ "ext": {
+ "prebid": {
+ "storedrequestattributes": {
+ "maxduration": 60,
+ "mimes": ["video/mp4"],
+ "minduration": 15,
+ "protocols": [1, 2],
+ "skipafter": 0,
+ "skipmin": 0,
+ "startdelay": 0,
+ "playbackmethod": [1]
+ }
+ }
+ }
+ }]
+ }],
+ ...
}
```
@@ -1133,31 +1144,31 @@ Prebid Server will generate ad server targeting variables as defined by request
```
{
-seatbid: [{
- seat: "bidderA",
- bid: [{
- id: "bid1",
- impid: "imp1",
- price: 1.04,
- ext: {
- prebid: {
- targeting: {
- hb_pb: 1.00, // values without prefixes on the winning bids only
- hb_pb_bidderA: 1.00, // only if includebidderkeys is true
- hb_bidder: "bidderA",
- hb_size: "300x250",
- hb_size_bidderA: "300x250",
- hb_format: "video" // only if includeformat is specified
- hb_deal: "123" // only if bid response contains a deal
- }
+ "seatbid": [{
+ "seat": "bidderA",
+ "bid": [{
+ "id": "bid1",
+ "impid": "imp1",
+ "price": 1.04,
+ "ext": {
+ "prebid": {
+ "targeting": {
+ "hb_pb": 1.00, // values without prefixes on the winning bids only
+ "hb_pb_bidderA": 1.00, // only if includebidderkeys is true
+ "hb_bidder": "bidderA",
+ "hb_size": "300x250",
+ "hb_size_bidderA": "300x250",
+ "hb_format": "video", // only if includeformat is specified
+ "hb_deal": "123" // only if bid response contains a deal
+ }
}
- }
- ...
+ }
+ ...
+ }]
}]
-}]
+}
```
-
##### Debug Output
`response.ext.debug.httpcalls.{bidder}` will be populated only if `test:1` or `ext.prebid.debug:true`.
@@ -1170,20 +1181,16 @@ 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).
```
- "ext": {
- "debug": {
- "httpcalls": {
- "bidderA": [
- ...
- ]
- },
- "resolvedrequest": {
- ...
- },
- "responsetimemillis": {
- ...
- }
- ...
+"ext": {
+ "debug": {
+ "httpcalls": {
+ "bidderA": [ ... ]
+ },
+ "resolvedrequest": { ... },
+ "responsetimemillis": { ... }
+ ...
+ }
+}
```
##### Original Bid CPM (PBS-Java only)
@@ -1244,9 +1251,9 @@ The PBJS version comes from ext.prebid.channel: `{name: "pbjs", version: "4.39"}
The Prebid SDK version comes from:
```
-app.ext.prebid: {
- source: "prebid-mobile"
- version: "1.2.3"
+"app.ext.prebid": {
+ "source": "prebid-mobile"
+ "version": "1.2.3"
}
```
@@ -1281,6 +1288,7 @@ app.ext.prebid: {
| 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 | ext.prebid.buyeruid | 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 |
| 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.url | URL location of the bid or VAST | string | URL | n/a |
diff --git a/prebid-server/endpoints/pbs-endpoint-admin.md b/prebid-server/endpoints/pbs-endpoint-admin.md
index 15f77672ab..bca308651e 100644
--- a/prebid-server/endpoints/pbs-endpoint-admin.md
+++ b/prebid-server/endpoints/pbs-endpoint-admin.md
@@ -138,6 +138,7 @@ Query Params
- statusCode - specifies that only interactions resulting in this response status code should be logged; valid values: >=200 and <=500
- account - specifies that only interactions involving this account should be logged
- limit - number of interactions to log; there is an upper threshold for this value set in configuration
+- bidder - name of the bidder whose adapter request will be logged
## /logging/changelevel
diff --git a/prebid-server/endpoints/pbs-endpoint-event.md b/prebid-server/endpoints/pbs-endpoint-event.md
index 0c354142a3..28a4f38b05 100644
--- a/prebid-server/endpoints/pbs-endpoint-event.md
+++ b/prebid-server/endpoints/pbs-endpoint-event.md
@@ -7,7 +7,7 @@ title: Prebid Server | Endpoints | Events
# Prebid Server | Endpoints | Events (Java-only)
-PBS-Java supports events as described in these GitHub issues:
+Prebid Server supports events as described in these GitHub issues:
- [Prebid Server Event Notification proposal](https://github.com/prebid/prebid-server/issues/800)
- [Prebid Server Event Updates](https://github.com/prebid/prebid-server/issues/1202)
diff --git a/prebid-server/endpoints/pbs-endpoint-overview.md b/prebid-server/endpoints/pbs-endpoint-overview.md
index 502dcfe7b1..e6f0e6c739 100644
--- a/prebid-server/endpoints/pbs-endpoint-overview.md
+++ b/prebid-server/endpoints/pbs-endpoint-overview.md
@@ -22,8 +22,8 @@ The API endpoints recognized by Prebid Server:
| [GET /getuids](/prebid-server/endpoints/pbs-endpoint-getuids.html) | Parses the `uids` cookie and returns JSON. |
| [GET /status](/prebid-server/endpoints/pbs-endpoint-status.html) | A health check. |
| [GET /info](/prebid-server/endpoints/info/pbs-endpoint-info.html) | Returns various information about how the server is configured. |
-| [GET /event](/prebid-server/endpoints/pbs-endpoint-event.html) | (PBS-Java only) Alerts Prebid Server to process an event. |
-| [POST /vtrack](/prebid-server/endpoints/pbs-endpoint-event.html) | (PBS-Java only) Cache VAST XML after inserting tracking string. |
+| [GET /event](/prebid-server/endpoints/pbs-endpoint-event.html) | Alerts Prebid Server to process an event. |
+| [POST /vtrack](/prebid-server/endpoints/pbs-endpoint-event.html) | Cache VAST XML after inserting tracking string. |
| [/currency/rates](/prebid-server/endpoints/pbs-endpoint-admin.html) | (Admin port only) Retrieves the server's current currency conversion rates. |
## Prebid Cache
diff --git a/prebid-server/endpoints/pbs-endpoint-setuid.md b/prebid-server/endpoints/pbs-endpoint-setuid.md
index ea379418ac..eb47472dd5 100644
--- a/prebid-server/endpoints/pbs-endpoint-setuid.md
+++ b/prebid-server/endpoints/pbs-endpoint-setuid.md
@@ -16,7 +16,7 @@ This endpoint saves a UserID for a Bidder in the Cookie. Saved IDs will be recog
### Query Params
-- `bidder`: The FamilyName of the Usersyncer (`../../usersync/usersync.go`) which is being synced.
+- `bidder`: The key of the bidder which is being synced. This may not always match the bidder name,.
- `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).
@@ -38,16 +38,8 @@ If in doubt, contact the company hosting Prebid Server and ask if they're GDPR-r
### 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 451 - PBS does not have permission to set a cookie due to GDPR or another 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
diff --git a/prebid-server/features/pbs-currency.md b/prebid-server/features/pbs-currency.md
index 3fe503fe98..347abf63e6 100644
--- a/prebid-server/features/pbs-currency.md
+++ b/prebid-server/features/pbs-currency.md
@@ -84,13 +84,13 @@ Rates can be passed in on the request:
```
"ext": {
- "prebid": {
- "currency": {
- "rates": {
- "USD": { "UAH": 24.47, "ETB": 32.04, "EUR": 0.92, ... }
- },
- "usepbsrates": false // defaults to true
- }
+ "prebid": {
+ "currency": {
+ "rates": {
+ "USD": { "UAH": 24.47, "ETB": 32.04, "EUR": 0.92, ... }
+ },
+ "usepbsrates": false // defaults to true
+ }
}
}
```
@@ -104,3 +104,9 @@ Note that the `usepbsrates` flag allows you to define which rates to use when PB
A dedicated endpoint on the Admin port will allow you to see what's happening within the currency converter.
See [currency rates endpoint](/prebid-server/endpoints/pbs-endpoint-admin.html) for more details.
+
+## Price Granularity
+
+When converting to a currency where the typical nominal CPMs are much different than USD such as JPY or INR, use a custom price granularity that reflects the typical range of CPMs in that currency.
+
+The predefined price granularities such as `medium` or `dense` will not be correctly scaled and thus almost every bid will end in the top bucket. Unlike Prebid.js, Prebid Server does not support `granularityMultiplier` to scale granularities so a custom price granularity needs to be used.
\ No newline at end of file
diff --git a/prebid-server/features/pbs-default-request.md b/prebid-server/features/pbs-default-request.md
index 3badc95482..d11b01a092 100644
--- a/prebid-server/features/pbs-default-request.md
+++ b/prebid-server/features/pbs-default-request.md
@@ -21,7 +21,7 @@ default_request:
alias_info: false
```
-The `file.name` option is the path/filename of a JSON file containing default request JSON. See the [stored request doc](/prebid-server/features/pbs-storedreqs.html) and the [openrtb2/auction endpoint doc](/prebid-server/endpoints/openrtb2/auction.html) for details about the syntax.
+The `file.name` option is the path/filename of a JSON file containing default request JSON. See the [stored request doc](/prebid-server/features/pbs-storedreqs.html) and the [openrtb2/auction endpoint doc](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html) for details about the syntax.
PBS-Java has a slightly different configuration in application.yaml:
```
diff --git a/prebid-server/features/pbs-feature-idx.md b/prebid-server/features/pbs-feature-idx.md
index 8165c65688..6a11cfb541 100644
--- a/prebid-server/features/pbs-feature-idx.md
+++ b/prebid-server/features/pbs-feature-idx.md
@@ -11,8 +11,8 @@ title: Prebid Server | Features
| Feature Set | Feature | Description | PBS-Go | PBS-Java |
|-------------+---------+-------------+--------+----------|
| [Currency](/prebid-server/features/pbs-currency.html) | Core | Loads currency conversions from an outside source, allows non-supported currencies to come in on the OpenRTB2 request, converts bid currencies to the request's prefered currency. |
+ 
|