diff --git a/assets/images/prebid-server/module-example.png b/assets/images/prebid-server/module-example.png index ea864b1c15..3c3d22e468 100644 Binary files a/assets/images/prebid-server/module-example.png and b/assets/images/prebid-server/module-example.png differ diff --git a/dev-docs/analytics/yandex.md b/dev-docs/analytics/yandex.md index a1d380e372..5626374e5b 100644 --- a/dev-docs/analytics/yandex.md +++ b/dev-docs/analytics/yandex.md @@ -20,7 +20,7 @@ Disclosure: The adapter utilizes the Metrica Tag build based on [github.com/yand 2. **Insert Counter Initialization Code:** - Retrieve the counter initialization code from the Yandex Metrica settings page at `https://metrica.yandex.com/settings?id={counterId}`, where `{counterId}` is your counter ID, and embed it into your website's HTML. + Retrieve the counter initialization code from the Yandex Metrica settings page at [metrica.yandex.com/r/settings](https://metrica.yandex.com/r/settings), and embed it into your website's HTML. 3. **Initialize the Adapter in Prebid.js:** @@ -43,4 +43,4 @@ Disclosure: The adapter utilizes the Metrica Tag build based on [github.com/yand ## Accessing Analytics Data -You can view the collected analytics data in the Yandex Metrica dashboard. Navigate to [metrika.yandex.com/dashboard](https://metrika.yandex.com/dashboard) and look for the Prebid Analytics section to analyze your data. +You can view the collected analytics data in the Yandex Metrica dashboard. Navigate to [metrika.yandex.com/r/stat/prebid_events](https://metrika.yandex.com/r/stat/prebid_events) to analyze your data. diff --git a/dev-docs/bidders/equativ.md b/dev-docs/bidders/equativ.md index ffa7dfb630..4ddca56f68 100644 --- a/dev-docs/bidders/equativ.md +++ b/dev-docs/bidders/equativ.md @@ -35,20 +35,19 @@ The Equativ bidder adapter requires setup and approval from the Equativ service {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |------|-------|-------------|---------|------| -| `networkId` | required | The network identifier you have been provided with. _See **Bid Parameter Usage** notes below for more information_. | `1234` | `integer` | -| `siteId` | required | The placement site ID. _See **Bid Parameter Usage** notes below for more information_. |`1234` | `integer` | -| `pageId` | required | The placement page ID. _See **Bid Parameter Usage** notes below for more information_. | `1234` | `integer` | -| `formatId` | required | The placement format ID. _See **Bid Parameter Usage** notes below for more information_. | `1234` | `integer` | +| `networkId` | required | The network identifier you have been provided with. Normally required, but there are certain conditions under which this may be omitted. _See **Bid Parameter Usage** notes below for more information_. | `1234` | `integer` | +| `siteId` | optional | The placement site ID. _See **Bid Parameter Usage** notes below for more information_. |`1234` | `integer` | +| `pageId` | optional | The placement page ID. _See **Bid Parameter Usage** notes below for more information_. | `1234` | `integer` | +| `formatId` | optional | The placement format ID. _See **Bid Parameter Usage** notes below for more information_. | `1234` | `integer` | #### Bid Parameter Usage Different combinations of parameters are required depending upon which ones you choose to use. -There are three options for passing bidder parameters: +There are two options for passing parameters: -- **Option 1**. Specify `networkId` by itself (_without_ `siteId`, `pageId` and `formatId`), or -- **Option 2**. Specify `siteId` _and_ `pageId` _and_ `formatId` (all together) _without_ `networkId`, or -- **Option 3**. Specify _none_ of the above parameters, and instead use either `ortb2.site.publisher.id`, `ortb2.app.publisher.id` or `ortb2.dooh.publisher.id` +- **Option 1**. Specify `networkId` by itself (_and optionally providing_ `siteId`, `pageId` and `formatId`), or +- **Option 2**. Specify either `ortb2.site.publisher.id`, `ortb2.app.publisher.id` or `ortb2.dooh.publisher.id` See **Sample Banner Setup** for examples of these parameter options. @@ -93,9 +92,9 @@ pbjs.bidderSettings = { #### Sample Banner Setup -As mentioned in the **Bid Parameter Usage** section, when including `'equativ'` as one of your available bidders your adunit setup, there are three general approaches to how you can specify parameters. Below are examples that illustrate them. +As mentioned in the **Bid Parameter Usage** section, when including `'equativ'` as one of your available bidders your adunit setup, there are two approaches to how you can specify parameters. Below are examples that illustrate them. -#### Option 1 -- Using networkId as the only bid param +#### Option 1 -- Using networkId as a parameter ```html ``` -#### Option 2 - Using siteId, pageId and formatId as bid params - -```html - -``` - -#### Option 3 - Using ortb2 for parameter info +#### Option 2 - Using ortb2 for parameter info You can also, as an alternative to using bidder params, specify a value for `publisher.id` that may be nested under an `app`, `site` or `dooh` object. The Equativ adapter will, in turn, look for these property paths under the `ortb2` property of the request: diff --git a/dev-docs/bidders/kuantyx.md b/dev-docs/bidders/kuantyx.md new file mode 100644 index 0000000000..cf13210888 --- /dev/null +++ b/dev-docs/bidders/kuantyx.md @@ -0,0 +1,44 @@ +--- +layout: bidder +title: Kuantyx +description: Kuantyx Bid Adapter +biddercode: kuantyx +tcfeu_supported: false +usp_supported: true +media_types: video, native +safeframes_ok: true +pbjs: true +pbs: true +pbs_app_supported: true +floors_supported: true +schain_supported: true +fpd_supported: true +ortb_blocking_supported: true +multiformat_supported: will-bid-on-one +userIds: all +sidebarType: 1 +aliasCode: aso +--- +### Note + +The Kuantyx adapter requires approval and setup. Please reach out to or visit us at [kuantyx.com](https://kuantyx.com) for more details. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|------------------|-----------------------------|-----------| +| `server` | required | Server endpoint | `https://srv.kuantyx.com` | `String` | +| `zone` | required | Zone ID | `73815` | `Integer` | + +#### Video Caching + +Note that the Kuantyx adapter expects a client-side Prebid Cache to be enabled for video bidding. + +```js +pbjs.setConfig({ + cache: { + url: 'https://prebid.adnxs.com/pbc/v1/cache' + } +}); +``` diff --git a/dev-docs/bidders/smilewanted.md b/dev-docs/bidders/smilewanted.md index 4cedc9c33c..0bac421c76 100644 --- a/dev-docs/bidders/smilewanted.md +++ b/dev-docs/bidders/smilewanted.md @@ -3,7 +3,7 @@ layout: bidder title: Smile Wanted description: SmileWanted Bidder Adapter biddercode: smilewanted -tcfeu_supported: false +tcfeu_supported: true gvl_id: 639 usp_supported: true coppa_supported: true diff --git a/dev-docs/bidders/spinx.md b/dev-docs/bidders/spinx.md index a4a1e80d9f..60ca37b1b3 100644 --- a/dev-docs/bidders/spinx.md +++ b/dev-docs/bidders/spinx.md @@ -32,5 +32,5 @@ The SpinX bidding adapter requires setup and approval before implementation. Ple {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |----------|----------|-----------------------|---------------------------|----------| -| `host` | required | RTB host | `'cpm.arteabee.com'` | `string` | +| `host` | required | RTB host | `'cpm.rtads.bid'` | `string` | | `zoneId` | required | Zone Id | 30164 | `integer` | diff --git a/dev-docs/bidders/ttd.md b/dev-docs/bidders/ttd.md index 7768c16df0..5c29b31048 100644 --- a/dev-docs/bidders/ttd.md +++ b/dev-docs/bidders/ttd.md @@ -92,7 +92,7 @@ var bannerAdUnit = { #### `mediaTypes.video` Parameters The TTD adapter for video requires certain parameters in the AdUnit's -[mediaTypes.video](https://docs.prebid.org/dev-docs/adunit-reference.html#adUnit.mediaTypes.video) definition. Specifically, `maxduration`, `api`, `mimes`, `placement`, and `protocols` are all required for video ad units. `playerSize`, `startdelay`, `playbackmethod`, and `pos` are recommended. `minduration`, `minbitrate`, `maxbitrate`, `skip`, `skipmin`, and `skipafter` are optional. +[mediaTypes.video](https://docs.prebid.org/dev-docs/adunit-reference.html#adUnit.mediaTypes.video) definition. Specifically, `maxduration`, `api`, `mimes`, `plcmt`, and `protocols` are all required for video ad units. `playerSize`, `startdelay`, `playbackmethod`, and `pos` are recommended. `minduration`, `minbitrate`, `maxbitrate`, `skip`, `skipmin`, and `skipafter` are optional. Note: TTD does not currently support `adpod` video contexts. @@ -108,7 +108,7 @@ var videoAdUnit = { playerSize: [640, 480], api: [1, 3], mimes: ['video/mp4'], - placement: 3, + plcmt: 3, protocols: [2, 3, 5, 6], startdelay: -1, playbackmethod: [1], diff --git a/dev-docs/modules/currency.md b/dev-docs/modules/currency.md index be27ef75a7..51358c93d2 100644 --- a/dev-docs/modules/currency.md +++ b/dev-docs/modules/currency.md @@ -30,6 +30,7 @@ currency conversion file while the bids are taking place. Alternately, the conve be provided in the page. 1. At runtime, bids are converted to the ad server currency as needed. 1. Default rates can be provided in case the file cannot be loaded. +1. When `requestBids` is called, the Currency Module will delay the auction up to the supplied amount of time in `currency.auctionDelay` or as soon as the dynamic endpoint returns data, whichever is first. ## Currency Architecture @@ -195,6 +196,8 @@ pbjs.setConfig({ "conversionRateFile": "URL_TO_RATE_FILE", // optionally provide a default rate in case the file can't be read "defaultRates": { "USD": { "GPB": 0.75 }} + // optionally sets the auction defer time if the file has not been loaded yet + "auctionDelay": 1000 } }); ``` diff --git a/dev-docs/publisher-api-reference/setConfig.md b/dev-docs/publisher-api-reference/setConfig.md index fef8e66c1e..43957cffb6 100644 --- a/dev-docs/publisher-api-reference/setConfig.md +++ b/dev-docs/publisher-api-reference/setConfig.md @@ -1175,7 +1175,8 @@ The `auctionOptions` object controls aspects related to auctions. | Field | Scope | Type | Description | |----------+---------+--------+---------------------------------------------------------------------------------------| | `secondaryBidders` | Optional | Array of Strings | Specifies bidders that the Prebid auction will no longer wait for before determining the auction has completed. This may be helpful if you find there are a number of low performing and/or high timeout bidders in your page's rotation. | -| `suppressStaleRender` | Optional | Boolean | When true, prevents `banner` bids from being rendered more than once. It should only be enabled after auto-refreshing is implemented correctly. Default is false. +| `suppressStaleRender` | Optional | Boolean | When true, prevents `banner` bids from being rendered more than once. It should only be enabled after auto-refreshing is implemented correctly. Default is false. | +| `suppressExpiredRender` | Optional | Boolean | When true, prevent bids from being rendered if TTL is reached. Default is false. #### Examples {: .no_toc} @@ -1212,6 +1213,28 @@ PBJS performs following actions when stale rendering is detected. Stale winning bids will continue to be rendered unless `suppressStaleRender` is set to true. Events including `STALE_RENDER` and `BID_WON` are unaffected by this option. +Render only non-expired bids. + +```javascript +pbjs.setConfig({ + 'auctionOptions': { + 'suppressExpiredRender': true + } +}); +``` + +#### More on Expired Rendering +{: .no_toc} + +We are validating the `ttl` property before rendering an ad. If the ad has exceeded its ttl value and the `suppressExpiredRender` property is enabled, the system will suppress the rendering of the expired ad. + +PBJS performs the following actions when expired rendering is detected. + +* Log a warning in the browser console if pbjs_debug=true. +* Emit a `EXPIRED_RENDER` event before `BID_WON` event. + +Expired winning bids will continue to be rendered unless `suppressExpiredRender` is set to true. Events including `STALE_RENDER` and `BID_WON` are unaffected by this option. + ### maxNestedIframes diff --git a/prebid-server/developers/add-a-module-java.md b/prebid-server/developers/add-a-module-java.md index 90aaa31aa7..72b43f3b14 100644 --- a/prebid-server/developers/add-a-module-java.md +++ b/prebid-server/developers/add-a-module-java.md @@ -123,6 +123,7 @@ These are the available hooks that can be implemented in a module: - org.prebid.server.hooks.v1.bidder.RawBidderResponseHook - org.prebid.server.hooks.v1.bidder.AllProcessedBidResponsesHook - org.prebid.server.hooks.v1.auction.AuctionResponseHook +- org.prebid.server.hooks.v1.exitpoint.ExitpointHook In a module it is not necessary to implement all mentioned interfaces but only one (or several) required by your functionality. @@ -131,6 +132,17 @@ Each hook interface internally extends org.prebid.server.hooks.v1.Hook basic int - `code()` - returns module code. - `call(...)` - returns result of hook invocation. +### Difference between AuctionResponseHook and ExitpointHook +In a nutshell, both hooks allow the modification of the OpenRTB Bid Response but in different ways. +The `AuctionResponseHook` provides a last chance to work with the Java objects that modify the auction response. +The `ExitpointHook` allows you to build a completely different response based on the received auction context. i.e. something that's not OpenRTB JSON - something like VAST. These hooks could modify the auction/amp/video response that PBS has built, or it could build another one and modify response headers accordingly. + +Important Notes: + +- The ExitpointHook is a powerful tool that allows rewriting the auction results, so make sure important data won't be lost for the client. +- Since the response body is not modified after calling the ExitpointHook, debug and traces won't be added by PBS-core. The exitpoint hook is responsible for adding its own tracing to the generated output. +- Analytics adapters doesn't have access to the response built by the ExitpointHook, but they receive the up-to-date auction context with the ExitpointHook execution status and analytics tags. + ### Examples 1. To **update** the request in the `RawAuctionRequestHook` you would return: diff --git a/prebid-server/developers/add-a-module.md b/prebid-server/developers/add-a-module.md index 74059d93a3..0edbbd3cb7 100644 --- a/prebid-server/developers/add-a-module.md +++ b/prebid-server/developers/add-a-module.md @@ -70,7 +70,8 @@ Here's a description of the Stages of a PBS request that modules can tap into fo | Bidder Request | The request has been customized for a particular bidder in the auction. Note that the module will be called in parallel for each bidder in the auction. | auction, amp, video | Bidder-specific bcat/badv, Bidder-specific deals | | Raw Bidder Response | Hook functions can get access to the unprocessed bidder response. Note that the module will be called in parallel for each bidder in the auction. | auction, amp, video | Response validations | | All Processed Bid Responses | All bids are back and PBS-core bid validations are done. | auction, amp, video | Creative validation, advanced bid validations. | -| Auction Response | Last step before the response goes back to the client | auction, amp, video | Inject ad server targeting, alternate auction winner logic | +| Auction Response | Last chance to modify the bid auction response | auction, amp, video | Inject ad server targeting, alternate auction winner logic | +| Exitpoint | (PBS-Java 3.16+) Last step before the response goes back to the client. Specify the response headers and body | auction, amp, video | Create a VAST response instead of OpenRTB. | ### 3. Figure Out Which Stages You're Going to Hook Into diff --git a/prebid-server/developers/add-new-bidder-go.md b/prebid-server/developers/add-new-bidder-go.md index 02f3eb8ae0..b18d63acdb 100644 --- a/prebid-server/developers/add-new-bidder-go.md +++ b/prebid-server/developers/add-new-bidder-go.md @@ -8,16 +8,16 @@ title: Prebid Server | Developers | Building a Bid Adapter (Go) # Prebid Server - New Bid Adapter (Go) {: .no_toc} -Thank you for your valuable contribution of a bid adapter to the open source Prebid Server project. Each new adapter expands the monetization possibilities for publishers and provides greater options to maximize their inventory's potential. We truly appreciate your support in making this ecosystem thrive! +- TOC +{:toc } + +Thank you for your contribution of a bid adapter to the open source Prebid Server project. Each new adapter expands the monetization possibilities for publishers and provides greater options to maximize their inventory's potential. We appreciate your support in making this ecosystem thrive! 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 ask us questions by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new). {: .alert.alert-info :} 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 -{:toc } - ## Overview Bid adapters are responsible for translating a 'Prebid-flavored' OpenRTB Bid Request to your bidding server's protocol and mapping your server's response to a Prebid-flavored response. @@ -71,15 +71,15 @@ We are proud to run the Prebid Server project as a transparent and trustworthy h **Please take the time to read the rules in full.** Below is a summary of some of the rules which apply to your Prebid Server bid adapter: -* Adapters must include maintainer information with a group email address for Prebid.org to contact for ongoing support and maintenance. -* Your bidder's endpoint domain name cannot be fully variable. We will accept endpoint domains that include account IDs, but we do not like them, and Prebid Server host companies may disable adapters using this approach if there are technical issues with it. We will not accept hostnames that have a required dynamic element for the purpose of sending traffic to different geographic regions. -* If you have a client-side adapter, all parameters (including biddercodes and aliases) must be consistent between your client- and server-side adapters. This allows publishers to utilize the PBJS [s2sTesting module](/dev-docs/modules/s2sTesting.html). -* Adapters must not modify bids from demand partners, except to either change the bid from gross to net or from one currency to another. -* Adapters must use the functions provided by the core framework for all external communication. Initiation of any form of network connection outside of what is provided by the core framework is strictly prohibited. No exceptions will be made for this rule. -* Adapters must support the creation of multiple concurrent instances. This means adapters may not mutate global or package scoped variables. -* Bidding server endpoints should prefer secure HTTPS to protect user privacy and should allow keep alive connections (preferably with HTTP/2 support) to increase host performance. -* Adapters must annotate the bid response with the proper media type, ideally based on the response from the bidding server. -* Bid adapters must not create their own transaction IDs or overwrite the tids supplied by Prebid. +- Adapters must include maintainer information with a group email address for Prebid.org to contact for ongoing support and maintenance. +- Your bidder's endpoint domain name cannot be fully variable. We will accept endpoint domains that include account IDs, but we do not like them, and Prebid Server host companies may disable adapters using this approach if there are technical issues with it. We will not accept hostnames that have a required dynamic element for the purpose of sending traffic to different geographic regions. +- If you have a client-side adapter, all parameters (including biddercodes and aliases) must be consistent between your client- and server-side adapters. This allows publishers to utilize the PBJS [s2sTesting module](/dev-docs/modules/s2sTesting.html). +- Adapters must not modify bids from demand partners, except to either change the bid from gross to net or from one currency to another. +- Adapters must use the functions provided by the core framework for all external communication. Initiation of any form of network connection outside of what is provided by the core framework is strictly prohibited. No exceptions will be made for this rule. +- Adapters must support the creation of multiple concurrent instances. This means adapters may not mutate global or package scoped variables. +- Bidding server endpoints should prefer secure HTTPS to protect user privacy and should allow keep alive connections (preferably with HTTP/2 support) to increase host performance. +- Adapters must annotate the bid response with the proper media type, ideally based on the response from the bidding server. +- Bid adapters must not create their own transaction IDs or overwrite the tids supplied by Prebid. {: .alert.alert-warning :} 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). @@ -150,20 +150,20 @@ userSync: Modify this template for your bid adapter: -* The endpoint can be static if you only have one data center or use a Global Load Balancer as described in 'Planning Your Adapter' above. -* Remove the `endpointCompression` value if your bidding server does not accept gzip compressed bid requests. Setting this value to `gzip` will save on network bandwidth at the expense of slightly increased cpu and memory usage for the host. -* The `geoscope` parameter is not currently read programmatically. Instead, it's intended to be used by PBS host companies to disable your adapter in geographic regions where you don't do business. However, we may make a module for this someday, so we ask that you follow this syntax for `geoscope`: - * YAML array - * Values can be either a 3-letter country code, "EEA", or "global". (EEA means European Economic Area) - * Values can be negated. e.g. "!EEA" -* 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 `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/tcf-for-vendors/), or remove this line entirely if your bidding server is not registered with IAB Europe. -* Remove the `openrtb.version` parameter if your adapter cannot receive the OpenRTB 2.6 data model. In this case, Prebid Server will downgrade values back to their 2.5 ext locations. New OpenRTB 2.6 fields are still passed to adapters. -* If absolutely necessary, change the `modifyingVastXmlAllowed` value to `false` to opt-out of [video impression tracking](https://github.com/prebid/prebid-server/issues/1015). However, please note that Prebid Server host companies depend on this feature being enabled to track video analytics. This feature has been live for many years with no known problems. -* Remove the `capabilities` (app/site/dooh) and `mediaTypes` (banner/video/audio/native) combinations which your adapter does not support. (Note: 'dooh' is [Digital Out Of Home](/prebid-server/use-cases/pbs-dooh.html)) -* Add an `extra_info` field if you'd like to pass additional values that your adapter may need. See below for an example. -* Add the `disabled` flag and set it to true if you would like to unregister adapter from the core. It's enabled by default. -* 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. +- The endpoint can be static if you only have one data center or use a Global Load Balancer as described in 'Planning Your Adapter' above. +- Remove the `endpointCompression` value if your bidding server does not accept gzip compressed bid requests. Setting this value to `gzip` will save on network bandwidth at the expense of slightly increased cpu and memory usage for the host. +- The `geoscope` parameter is not currently read programmatically. Instead, it's intended to be used by PBS host companies to disable your adapter in geographic regions where you don't do business. However, we may make a module for this someday, so we ask that you follow this syntax for `geoscope`: + - YAML array + - Values can be either a 3-letter country code, "EEA", or "global". (EEA means European Economic Area) + - Values can be negated. e.g. "!EEA" +- 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 `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/tcf-for-vendors/), or remove this line entirely if your bidding server is not registered with IAB Europe. +- Remove the `openrtb.version` parameter if your adapter cannot receive the OpenRTB 2.6 data model. In this case, Prebid Server will downgrade values back to their 2.5 ext locations. New OpenRTB 2.6 fields are still passed to adapters. +- If absolutely necessary, change the `modifyingVastXmlAllowed` value to `false` to opt-out of [video impression tracking](https://github.com/prebid/prebid-server/issues/1015). However, please note that Prebid Server host companies depend on this feature being enabled to track video analytics. This feature has been live for many years with no known problems. +- Remove the `capabilities` (app/site/dooh) and `mediaTypes` (banner/video/audio/native) combinations which your adapter does not support. (Note: 'dooh' is [Digital Out Of Home](/prebid-server/use-cases/pbs-dooh.html)) +- Add an `extra_info` field if you'd like to pass additional values that your adapter may need. See below for an example. +- Add the `disabled` flag and set it to true if you would like to unregister adapter from the core. It's enabled by default. +- 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. #### Additional Bidder Info Examples @@ -355,7 +355,7 @@ Publishers will provide extra information using an OpenRTB 2.x Bid Request Exten We request you do not duplicate information already present in the [OpenRTB 2.x Bid Request specification](https://github.com/InteractiveAdvertisingBureau/openrtb2.x) 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.x Bid Request standard of `request.imp[].video`. {: .alert.alert-warning :} -You may not try so set the full endpoint domain from a publisher-specified 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 try to set the full endpoint domain from a publisher-specified 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` and use [JSON Schema](https://json-schema.org/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). @@ -545,8 +545,8 @@ Each adapter has its own directory (a 'package' in Go parlance) for all code and Create a file with the path `adapters/{bidder}/{bidder}.go`. Your bid adapter code will need to implement and export: -* The `adapters.Builder` method to create a new instance of the adapter based on the host configuration. -* The `adapters.Bidder` interface consisting of the `MakeRequests` method to create outgoing requests to your bidding server and the `MakeBids` method to create bid responses. +- The `adapters.Builder` method to create a new instance of the adapter based on the host configuration. +- The `adapters.Bidder` interface consisting of the `MakeRequests` method to create outgoing requests to your bidding server and the `MakeBids` method to create bid responses. {: .alert.alert-info :} **ACCESS MODIFIERS:** Go has only two kinds of access modifiers, exported and private, which are scoped at the package level. The access modifier is encoded into the name of the type or method. Names starting with an upper case letter are exported whereas names starting with a lower case letter are private. Please only export the three required methods and keep everything else private. @@ -667,8 +667,8 @@ 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 paths. -* `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. +- `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 paths. +- `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 third argument, `server`, is a set of host configs. It can be passed in two different ways. One way is to pass this info in the auction request itself at the path `ext.prebid.server` (i.e. `ext.prebid.server.datacenter`). The second way is to pass this info as a configuration data structure. @@ -770,9 +770,9 @@ 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](/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. +- `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. Please do not add `nil` items in the slices. @@ -1076,8 +1076,8 @@ aliasOf: "appnexus" Notes: -* The alias name must be unique for the first 6 chars as noted above for biddercodes. -* This process will be simplified someday. +- The alias name must be unique for the first 6 chars as noted above for biddercodes. +- This process will be simplified someday. {: .alert.alert-info :} Note on aliases and TCF Global Vendor List IDs: if an alias entry does not have its own GVLID but wishes to claim GDPR support, @@ -1128,8 +1128,8 @@ You should use an obviously fake endpoint for your tests. There's no reason to u Each test case should be written in its own JSON file with a succinct, yet descriptive, name of what's being tested. The files should be located in either: -* `adapters/{bidder}/{bidder}test/exemplary/` for straight forward "happy path" tests. We expect to see tests here for each supported media type. -* `adapters/{bidder}/{bidder}test/supplemental` for tests which produce errors or cover more complicated scenarios. +- `adapters/{bidder}/{bidder}test/exemplary/` for straight forward "happy path" tests. We expect to see tests here for each supported media type. +- `adapters/{bidder}/{bidder}test/supplemental` for tests which produce errors or cover more complicated scenarios. The format of a JSON test is as follows: @@ -1382,41 +1382,41 @@ The Example Bidding adapter requires setup before beginning. Please contact us a Notes on the metadata fields: -* Add `pbs: true`. If you also have a [Prebid.js bid adapter](/dev-docs/bidder-adaptor.html), add `pbjs: true`. Default is false for both. -* If you're on the IAB's Global Vendor List, place your ID in `gvl_id`. No default. -* If you support the IAB's TCF protocol and have a GVL ID, you may add `tcfeu_supported: true`. Default is false. -* If you support the US Privacy consentManagementUsp module, add `usp_supported: true`. Default is false. -* If you support one or more userId modules, add `userId: (list of supported vendors)`. Default is none. -* If you support video, native, or audio mediaTypes add `media_types: video, native, audio`. Note that display is added by default. If you don't support display, add "no-display" as the first entry, e.g. `media_types: no-display, native`. No defaults. -* If you support COPPA, add `coppa_supported: true`. Default is false. -* If you support sections within the IAB's GPP consent string, add `gpp_sids:' and then which sections you support: tcfeu, tcfca, usnat, usstate_all, usp -* If you support the [supply chain](/dev-docs/modules/schain.html) feature, add `schain_supported: true`. Default is false. -* 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 `deals_supported: true`. No default value. -* If your bidder supports floors, set `floors_supported: true`. No default value. -* If you support first party data, you must document what exactly is supported and then you may set `fpd_supported: true`. No default value. -* If you support any OpenRTB blocking parameters, you must document what exactly is supported and then you may set `ortb_blocking_supported` to ‘true’,’partial’, or ‘false’. No default value. In order to set ‘true’, you must support: bcat, badv, battr, and bapp. -* Let publishers know how you support multiformat requests -- those with more than one mediatype (e.g. both banner and video). Here are the options: will-bid-on-any, will-bid-on-one, will-not-bid -* If you're a member of Prebid.org, add `prebid_member: true`. Default is false. +- Add `pbs: true`. If you also have a [Prebid.js bid adapter](/dev-docs/bidder-adaptor.html), add `pbjs: true`. Default is false for both. +- If you're on the IAB's Global Vendor List, place your ID in `gvl_id`. No default. +- If you support the IAB's TCF protocol and have a GVL ID, you may add `tcfeu_supported: true`. Default is false. +- If you support the US Privacy consentManagementUsp module, add `usp_supported: true`. Default is false. +- If you support one or more userId modules, add `userId: (list of supported vendors)`. Default is none. +- If you support video, native, or audio mediaTypes add `media_types: video, native, audio`. Note that display is added by default. If you don't support display, add "no-display" as the first entry, e.g. `media_types: no-display, native`. No defaults. +- If you support COPPA, add `coppa_supported: true`. Default is false. +- If you support sections within the IAB's GPP consent string, add `gpp_sids:' and then which sections you support: tcfeu, tcfca, usnat, usstate_all, usp +- If you support the [supply chain](/dev-docs/modules/schain.html) feature, add `schain_supported: true`. Default is false. +- 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 `deals_supported: true`. No default value. +- If your bidder supports floors, set `floors_supported: true`. No default value. +- If you support first party data, you must document what exactly is supported and then you may set `fpd_supported: true`. No default value. +- If you support any OpenRTB blocking parameters, you must document what exactly is supported and then you may set `ortb_blocking_supported` to ‘true’,’partial’, or ‘false’. No default value. In order to set ‘true’, you must support: bcat, badv, battr, and bapp. +- Let publishers know how you support multiformat requests -- those with more than one mediatype (e.g. both banner and video). Here are the options: will-bid-on-any, will-bid-on-one, will-not-bid +- If you're a member of Prebid.org, add `prebid_member: true`. Default is false. ## File Checklist -* Bidder Info - * `static/bidder-info/{bidder}.yaml` -* Bidder Parameters - * `static/bidder-params/{bidder}.json` - * `openrtb_ext/imp_{bidder}.go` - * `adapters/{bidder}/params_test.go` -* Adapter Code - * `adapters/{bidder}/{bidder}.go` - * `adapters/{bidder}/{bidder}_test.go` - * `adapters/{bidder}/{bidder}test/exemplary/*.json` - * `adapters/{bidder}/{bidder}test/supplemental/*.json` -* Register With The Core - * `openrtb_ext/bidders.go` - * `exchange/adapter_builders.go` +- Bidder Info + - `static/bidder-info/{bidder}.yaml` +- Bidder Parameters + - `static/bidder-params/{bidder}.json` + - `openrtb_ext/imp_{bidder}.go` + - `adapters/{bidder}/params_test.go` +- Adapter Code + - `adapters/{bidder}/{bidder}.go` + - `adapters/{bidder}/{bidder}_test.go` + - `adapters/{bidder}/{bidder}test/exemplary/*.json` + - `adapters/{bidder}/{bidder}test/supplemental/*.json` +- Register With The Core + - `openrtb_ext/bidders.go` + - `exchange/adapter_builders.go` ## Contribute diff --git a/prebid-server/developers/add-new-bidder-java.md b/prebid-server/developers/add-new-bidder-java.md index 18b20e2b0b..f0aa1b5f3c 100644 --- a/prebid-server/developers/add-new-bidder-java.md +++ b/prebid-server/developers/add-new-bidder-java.md @@ -11,7 +11,7 @@ title: Prebid Server | Developers | Adding a New Bidder - TOC {:toc } -Thank you for your valuable contribution of a bid adapter to the open source Prebid Server project. Each new adapter expands the monetization possibilities for publishers and provides greater options to maximize their inventory's potential. We truly appreciate your support in making this ecosystem thrive! +Thank you for your contribution of a bid adapter to the open source Prebid Server project. Each new adapter expands the monetization possibilities for publishers and provides greater options to maximize their inventory's potential. We appreciate your support in making this ecosystem thrive! 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-java/tree/master/src/main/java/org/prebid/server/bidder) for working examples and practical guidance. You can ask us questions by [submitting a GitHub issue](https://github.com/prebid/prebid-server-java/issues/new). @@ -267,7 +267,7 @@ Publishers will provide extra information using an OpenRTB 2.x Bid Request Exten We request that you do not duplicate information that is already present in the [OpenRTB 2.x request](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md) 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.x Bid Request standard of `request.imp[].video`. {: .alert.alert-warning :} -**ENDPOINT NOTE:** You may not try so set the full endpoint domain from a publisher-specified 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 try to set the full endpoint domain from a publisher-specified 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://json-schema.org/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). @@ -428,11 +428,11 @@ Please follow [Java standard naming convention](https://www.oracle.com/java/tech Now it's time to write your bid adapter code. -Each adapter has its own directory (a 'package' in java parlance) for all code and tests associated with translating an OpenRTB 2.x Bid Request to your bidding server's protocol and mapping your server's response to an OpenRTB 2.x Bid Response. The use of separate packages provide each adapter with its own naming scope to avoid conflicts and gives the freedom to organize files as you best see fit (although we make suggestions in this guide). +Each adapter has its own directory (a 'package' in java parlance) for all code and tests associated with translating an OpenRTB 2.x Bid Request to your bidding server's protocol and mapping your server's response to an OpenRTB 2.x Bid Response. The use of separate packages provides each adapter with its own naming scope to avoid conflicts and gives the freedom to organize files as you best see fit (although we make suggestions in this guide). Create a file with the path `org.prebid.server.bidder.{bidder}/{bidder}Bidder.java`. Your bid adapter code will need to implement Bidder interface where `T` is a model which will represent HttpRequest body. -- The `Bidder` interface consisting of the `MakeHttpRequests` method to create outgoing requests to your bidding server and the `MakeBids` method to create bid responses. +- The `Bidder` interface consists of the `MakeHttpRequests` method to create outgoing requests to your bidding server and the `MakeBids` method to create bid responses. Here is a reference implementation for a bidding server which uses the OpenRTB 2.x protocol: diff --git a/prebid-server/pbs-modules/index.md b/prebid-server/pbs-modules/index.md index d0b88cd008..c07d1de507 100644 --- a/prebid-server/pbs-modules/index.md +++ b/prebid-server/pbs-modules/index.md @@ -12,7 +12,7 @@ The core of Prebid Server contains the foundational code needed for header biddi If you're looking for bidder adapter parameters, see [Bidders' Params](/dev-docs/pbs-bidders.html). -* TOC +- TOC {:toc} ## The Modules @@ -33,6 +33,7 @@ The full list of modules: | [**US Custom Logic Privacy**](/prebid-server/features/pbs-uscustomlogic.html) | Similar to the `US Gen Privacy` module, but publishers define their own interpretation of the GPP string. | privacy | | check | | [**Richmedia Filter**](/prebid-server/pbs-modules/richmedia.html) | Can filter MRAID creatives from the bid stream. | validation | | check | | [**51Degrees Device Detection**](/prebid-server/pbs-modules/51degrees-device-detection.html) | Enriches an incoming OpenRTB request with [51Degrees Device Data](https://51degrees.com/documentation/_device_detection__overview.html) | general | check | check | +| [**Greenbids Real Time Data**](/prebid-server/pbs-modules/greenbids-real-time-data.html) | Filters out bidders that are not expected to bid on this request, saving money and carbon. | general | | check | | [**Request Correction**](/prebid-server/pbs-modules/request-correction.html) | Apply optional corrections to bid requests. | general | | check | | [**Response Correction**](/prebid-server/pbs-modules/response-correction.html) | Apply optional corrections to bid responses. | general | | check | @@ -53,10 +54,10 @@ mvn clean package --file extra/pom.xml The execution plan details: -* which modules are used in your server -* what order they're invoked in -* how long modules have to run before timeout -* whether any modules depend on each other +- which modules are used in your server +- what order they're invoked in +- how long modules have to run before timeout +- whether any modules depend on each other If you want the module to run on every request regardless of account, this is a host-level config you should place in `application.yaml`. If the module should @@ -64,9 +65,9 @@ be active only for certain accounts, you'll need to place the plan in the accoun To define a plan, you'll need to know the following module details, which should be available in the module documentation: -* urls: which PBS 'entry points' are relevant. e.g. /openrtb2/auction, /openrtb2/amp -* stages: one or more of the 7 workflow stages where the module should be called: entrypoint, raw-auction-request, processed-auction-request, bidder-request, raw-bidder-response, processed-bidder-response, and/or auction-response. -* hooks: for each stage where a module runs, its documentation will provide the hook function name. +- urls: which PBS 'entry points' are relevant. e.g. /openrtb2/auction, /openrtb2/amp +- stages: one or more of the 7 workflow stages where the module should be called: entrypoint, raw-auction-request, processed-auction-request, bidder-request, raw-bidder-response, processed-bidder-response, and/or auction-response. +- hooks: for each stage where a module runs, its documentation will provide the hook function name. Here's an example application.yaml entry: @@ -131,13 +132,131 @@ hooks: } ``` +{: .alert.alert-info : +Execution plans can be placed in account configuration, but depending on how modules are enabled in your environment, it can be inconvenient to provide instructions to place the highly technical execution plan into the account config. Some organizations have +chosen to keep all execution plans in host-level config, then enabling the `require-config-to-invoke` option as described in the next section. + ### 3. Supply the module with configuration Modules may require configuration at startup or during the request: -* If the module requires config at initialization, its documentation will +- If the module requires config at initialization, its documentation will describe where the config file lives and what format it should take. -* If the module requires runtime config, it should be passed via the account-conig mechanism. +- If the module requires runtime config, it should be passed via the account-config mechanism. + +### 3.1 Module Execution Configuration + +PBS-Java 3.16 introduced new configurations that give the host company flexible control over which modules run for which accounts +while still allowing all execution plans to be defined at the host-level. + +- `hooks.admin.module-execution` is a key-value map, where a key is a module name and a value is a boolean. It defines whether a module's hooks should be executed. +This property can be configured on the host level at initialization as well as via account-config mechanism (a runtime config). +- `settings.modules.require-config-to-invoke` is a host-level boolean property. When set to `true`, it requires a runtime config to exist for a module in order to actually run the execution plan. + +Here's how these work together: + +1. If `hooks.admin.module-execution` is defined at the host-level (application.yaml), it overrides all account config. No account can turn off a module flagged as true, and likewise they can’t turn on a module flagged as false. +1. Essentially, setting false at the host level has the same effect as removing the module’s execution plan. +1. If `hooks.admin.module-execution` is not defined at the host level, then normal precedence rules are in effect: any value in account config overrides what’s in default account config. +1. If nothing is found for the module in the merged `hooks.admin.module-execution` and `require-config-to-invoke` is true, then account-level config is required. + +Example: + +```yaml +# host-level config +settings: + modules: + require-config-to-invoke: true +hooks: + admin: + host-execution-plan: > + {"endpoints":{... define execution plans for module1, module3, and module4 here ...}} + module-execution: + module1: true // don't allow accounts to turn off this module. Also don't worry about requiring config. Always run this one. + module2: false // don't allow accounts to utilize this module at all, even if they define a plan in account config. +``` + +```json +// account-level config +// the end result is that module1, module3, and module5 are run. +// module2 is not run even though a plan is defined in this account config because the host company has forbidden it above +// module4 is not run because there's no config and require-config-to-invoke is true +{ + "hooks": { + "admin": { + "module-execution": { + "module1": false // does nothing, since module1 is always on at the host level + } + }, + "modules": { + "module3": { ... module 3 config ... }, + "module5": { ... module 5 config ... }, + }, + "execution-plan": { + ... define an execution plan for module2 and module5 here ... + } + } +} +``` + +### 3.2 A/B Testing Modules + +Host companies and accounts might want to try enabling a module on a small percentage of traffic before turning it on all the way. + +PBS-Java 3.16 introduced a new A/B testing framework that applies to any module. + +```json5 +{ + "hooks": { + "execution-plan": { + "abtests": [{ + "accounts": [ 123, 456 ], // these are ignored if in account-level config + "module-code": "module1", + "enabled": true, // defaults to false + "percent-active": 5, // defaults to 100 + "log-analytics-tag": true // defaults to true + },{ + ... abtest config for other modules ... + }], + "endpoints": { + "/openrtb2/auction": { + ... + } + } + ] + ] +] +``` + +These are the parameters accepted within the `abtests` object: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Description | Type | Default | +|-----------+-------+-------------+------+---------| +| module-code | required | Which module is being tested. | string | none | +| percent-active | required | What percent of the time the module will run. | integer | none | +| accounts | optional | Defines which accounts this abtest block applies to. This is useful when the execution plan is defined at the host level and is ignored when the plan is at the account level. | array of int | none | +| enabled | optional | Allows the abtest to be disabled without removing it. | boolean | true | +| log-analytics-tag | optional | Directs PBS-core to log an analytics tag for reporting. | boolean | false | + +To get reporting on the test results, analytics adapters will need to read the [analytics tag](/prebid-server/developers/module-atags.html) created by the A/B test, which looks like this: + +```json5 +{ + activities: [{ + name: "core-module-abtests", + status: "success", + results: [{ // one results object for each module in the abtests object + "status": STATUS, // "run" or "skipped" + "values": { + "module": "module1" + } + }] + }, + ... the status of other abtest decisions ... + }] +} +``` ## Installing a PBS Privacy Module @@ -146,6 +265,6 @@ relevant 'Activity' using the `privacyreg` directive as described in the [Activi ## Further Reading -* [Developing a Prebid Server General Module](/prebid-server/developers/add-a-module.html) -* [Developing a Prebid Server Privacy Module](/prebid-server/developers/add-a-privacy-module.html) -* [Prebid Server Features](/prebid-server/features/pbs-feature-idx.html) +- [Developing a Prebid Server General Module](/prebid-server/developers/add-a-module.html) +- [Developing a Prebid Server Privacy Module](/prebid-server/developers/add-a-privacy-module.html) +- [Prebid Server Features](/prebid-server/features/pbs-feature-idx.html)