| Module | +Description | +EID Source | +
|---|---|---|
| {{page.title}} | +{{page.description}} | +{{page.eidsource}} | +
| ID System Name | +Prebid.js Attr: bidRequest.userId | +EID Source | +Example | +
|---|---|---|---|
| {{page.title}} | +{{page.bidRequestUserId}} | +{{page.eidsource}} | +{{page.example}} | +
+{: .table .table-bordered .table-striped }
+
| Param | Scope | Type | Description | Example |
| --- | --- | --- | --- | --- |
| name | Required | String | Module identification: `"novatiq"` | `"novatiq"` |
@@ -53,8 +58,6 @@ pbjs.setConfig({
| params.urlParams.useStandardUuid | Optional | Boolean | Use a standard UUID format, or the Novatiq UUID format | `false` |
| params.urlParams.useSspId | Optional | Boolean | Send the sspid (sourceid) along with the sync request
Makes the params.sourceid optional if set | `false` | | params.urlParams.useSspHost | Optional | Boolean | Send the ssphost along with the sync request | `false` | -{: .table .table-bordered .table-striped } -
## Novatiq Hyper ID with Prebid SharedID Support
@@ -62,8 +65,9 @@ You can make use of the Prebid.js SharedId module as follows.
Enable by adding the Novatiq and SharedId submodule to your Prebid.js package with:
-{: .alert.alert-info :}
+```bash
gulp build --modules=novatiqIdSystem,userId
+```
Module activation and configuration:
diff --git a/dev-docs/modules/userid-submodules/onekey.md b/dev-docs/modules/userid-submodules/onekey.md
index 9b4d937868..f371228764 100644
--- a/dev-docs/modules/userid-submodules/onekey.md
+++ b/dev-docs/modules/userid-submodules/onekey.md
@@ -19,8 +19,9 @@ Background information:
It can be added to you Prebid.js package with:
-{: .alert.alert-info :}
+```bash
gulp build –modules=userId,oneKeyIdSystem
+```
⚠️ This module works with a RTD module. Both must be configured. See the [OneKey RTD Module](/dev-docs/modules/oneKeyRtdProvider.html).
@@ -32,6 +33,7 @@ Go to [onekey.community](https://onekey.community/) for more details.
## OneKey Configuration
{: .table .table-bordered .table-striped }
+
| Param under userSync.userIds[] | Scope | Type | Description | Example |
| --- | --- | --- | --- | --- |
| name | Required | String | The name of this module | `"oneKeyData"` |
diff --git a/dev-docs/modules/userid-submodules/pair.md b/dev-docs/modules/userid-submodules/pair.md
index db98f896af..883c19d65b 100644
--- a/dev-docs/modules/userid-submodules/pair.md
+++ b/dev-docs/modules/userid-submodules/pair.md
@@ -11,12 +11,14 @@ reliance on third-party cookies. PAIR can help advertisers and publishers mainta
Add it to your Prebid.js package with:
-{: .alert.alert-info :}
+```bash
gulp build --modules=pairIdSystem
+```
## PAIR ID Configuration
{: .table .table-bordered .table-striped }
+
| Param under userSync.userIds[] | Scope | Type | Description | Example |
| --- | --- | --- | --- | --- |
| name | Required | String | The name of PAIR ID user ID module. | `"pairId"` |
diff --git a/dev-docs/modules/userid-submodules/parrable.md b/dev-docs/modules/userid-submodules/parrable.md
index d8aa3be3ea..99bdf612ec 100644
--- a/dev-docs/modules/userid-submodules/parrable.md
+++ b/dev-docs/modules/userid-submodules/parrable.md
@@ -4,6 +4,9 @@ title: Parrable ID
description: Parrable ID User ID sub-module
pbjs_version_notes: removed in 9.0
useridmodule: parrableIdSystem
+bidRequestUserId: parrableId
+eidsource: parrable.com
+example: '{"eid":"01.15946..."}'
---
@@ -11,8 +14,9 @@ The Parrable ID is a Full Device Identifier that can be used to identify a devic
Add it to your Prebid.js package with:
-{: .alert.alert-info :}
+```bash
gulp build --modules=parrableIdSystem
+```
## Parrable ID Registration
@@ -25,6 +29,7 @@ The Parrable privacy policy as at [www.parrable.com/privacy-policy/](https://www
In addition to the parameters documented above in the Basic Configuration section the following Parrable specific configuration is required:
{: .table .table-bordered .table-striped }
+
| Param under userSync.userIds[] | Scope | Type | Description | Example |
| --- | --- | --- | --- | --- |
| params | Required | Object | Details for the Parrable ID. | |
diff --git a/dev-docs/modules/userid-submodules/publisherlink.md b/dev-docs/modules/userid-submodules/publisherlink.md
index 2f6f44e965..6cbace8f08 100644
--- a/dev-docs/modules/userid-submodules/publisherlink.md
+++ b/dev-docs/modules/userid-submodules/publisherlink.md
@@ -3,6 +3,9 @@ layout: userid
title: Publisher Link
description: Publisher Link User ID sub-module
useridmodule: publinkIdSystem
+bidRequestUserId: publinkId
+eidsource: epsilon.com
+example:
---
@@ -24,13 +27,14 @@ The Publisher Link opt-out is included [here](https://www.epsilon.com/privacy/dm
In addition to the parameters documented above in the Basic Configuration section the following Publisher Link specific configuration is available:
{: .table .table-bordered .table-striped }
+
| Param under userSync.userIds[] | Scope | Type | Description | Example |
| --- | --- | --- | --- | --- |
| name | Required | String | The name of this module. | `'publinkId'` |
| params | Required | Object | Customized parameters. | |
| params.e | Required | String | Hashed email address of the user. Supports MD5 and SHA256. | `'7D320454942620664D96EF78ED4E3A2A'` |
| params.site_id | Required | String | Site ID provided by Epsilon. | `'123456'` |
-| params.api_key | Required | String | API key provided by Epsilon. | `'00000000-0000-0000-0000-00000000000'`
+| params.api_key | Required | String | API key provided by Epsilon. | `'00000000-0000-0000-0000-00000000000'` |
## Publisher Link Examples
diff --git a/dev-docs/modules/userid-submodules/pubprovided.md b/dev-docs/modules/userid-submodules/pubprovided.md
index ba15abfe25..e533bd8c15 100644
--- a/dev-docs/modules/userid-submodules/pubprovided.md
+++ b/dev-docs/modules/userid-submodules/pubprovided.md
@@ -3,6 +3,9 @@ layout: userid
title: PubProvided ID
description: PubProvided ID User ID sub-module
useridmodule: pubProvidedIdSystem
+bidRequestUserId: pubProvidedId
+eidsource: publisher domain
+example: '"1111"'
---
@@ -57,37 +60,37 @@ The PubProvided ID module allows publishers to set and pass a first-party user i
});
```
-If multiple parties are writing to this object in an undetermined order, a setup that feels quite awkward, they should each do something of this nature:
-
-```javascript
-pbjs.mergeConfig({
- userSync: {
- userIds: (() => {
- const uidCfgs = pbjs.getConfig('userSync.userIds') || [];
- let ppid = uidCfgs.find(cfg => cfg.name === 'pubProvidedId');
- if (!ppid) {
- ppid = {name: 'pubProvidedId', params: {eids: []}};
- uidCfgs.push(ppid);
- }
- ppid.params.eids.push({
- source: "example.com",
- uids: [{
- id: "example",
- atype: 1,
- ext: {
- stype: "ppuid"
- }
-
- }]
- })
- return uidCfgs;
- })()
- }
-})
-pbjs.refreshUserIds({submoduleNames: ['pubProvidedId']})
-```
+ If multiple parties are writing to this object in an undetermined order, a setup that feels quite awkward, they should each do something of this nature:
+
+ ```javascript
+ pbjs.mergeConfig({
+ userSync: {
+ userIds: (() => {
+ const uidCfgs = pbjs.getConfig('userSync.userIds') || [];
+ let ppid = uidCfgs.find(cfg => cfg.name === 'pubProvidedId');
+ if (!ppid) {
+ ppid = {name: 'pubProvidedId', params: {eids: []}};
+ uidCfgs.push(ppid);
+ }
+ ppid.params.eids.push({
+ source: "example.com",
+ uids: [{
+ id: "example",
+ atype: 1,
+ ext: {
+ stype: "ppuid"
+ }
-In each case, bid adapters will receive the eid values after consent is validated. The above examples, if calling `setConfig` instead of `mergeConfig`, will overwrite existing known IDs. If there is any possibility other id submodules have already been initiated or multiple scripts on the page are setting these fields, be sure to prefer `mergeConfig`.
+ }]
+ })
+ return uidCfgs;
+ })()
+ }
+ })
+ pbjs.refreshUserIds({submoduleNames: ['pubProvidedId']})
+ ```
+
+ In each case, bid adapters will receive the eid values after consent is validated. The above examples, if calling `setConfig` instead of `mergeConfig`, will overwrite existing known IDs. If there is any possibility other id submodules have already been initiated or multiple scripts on the page are setting these fields, be sure to prefer `mergeConfig`.
2. This design allows for the setting of any number of uuids in the eids object. Publishers may work with multiple ID providers and nest their own ID within the same eids object. The opportunity to link a 1st party uuid and a 3rd party generated UUID presents publishers with a unique ability to address their users in a way demand sources will understand.
@@ -105,12 +108,14 @@ This module is distinct from the Google Ad Manager PPID; which we enable setting
Add it to your Prebid.js package with:
-{: .alert.alert-info :}
+```bash
gulp build --modules=pubProvidedIdSystem
+```
## PubProvided Configuration
{: .table .table-bordered .table-striped }
+
| Params under usersync.userIds[]| Scope | Type | Description | Example |
| --- | --- | --- | --- | --- |
| name | Required | String | ID value for the ID module | `"PubProvided"` |
diff --git a/dev-docs/modules/userid-submodules/quantcast.md b/dev-docs/modules/userid-submodules/quantcast.md
index 14ded4e370..0b4b145dff 100644
--- a/dev-docs/modules/userid-submodules/quantcast.md
+++ b/dev-docs/modules/userid-submodules/quantcast.md
@@ -3,14 +3,18 @@ layout: userid
title: Quantcast ID
description: Quantcast ID User ID sub-module
useridmodule: quantcastIdSystem
+bidRequestUserId: quantcastId
+eidsource: quantcast.com
+example: '"1111"'
---
The Prebid Quantcast ID module stores a Quantcast ID in a first party cookie. The ID is then made available in the bid request. The ID from the cookie added in the bidstream allows Quantcast to more accurately bid on publisher inventories without third party cookies, which can result in better monetization across publisher sites from Quantcast. And, it’s free to use! For easier integration, you can work with one of our SSP partners, like PubMatic, who can facilitate the legal process as well as the software integration for you.
Add it to your Prebid.js package with:
-{: .alert.alert-info :}
+```bash
gulp build --modules=userId,quantcastIdSystem
+```
Quantcast’s privacy policies for the services rendered can be found at
Makes the params.sourceid optional if set | `false` | | params.urlParams.useSspHost | Optional | Boolean | Send the ssphost along with the sync request | `false` | -{: .table .table-bordered .table-striped } -
+{: .table .table-bordered .table-striped }
+
| Param under userSync.userIds[] | Scope | Type | Description | Example |
| --- | --- | --- | --- | --- |
| storage | Optional | Object | Defines where and for how long the results of the call to get a user ID will be stored. | |
| storage.type | Optional | String | Defines where the resolved user ID will be stored (either 'cookie' or 'html5' local storage). | `'cookie'` |
| storage.name | Optional | String | The name of the cookie or html5 local storage where the resolved user ID will be stored. | `'connectId'` |
| storage.expires | Optional | Integer | How long (in days) the user ID information will be stored. | `15` |
-{: .table .table-bordered .table-striped }
-
diff --git a/dev-docs/modules/userid-submodules/yandex.md b/dev-docs/modules/userid-submodules/yandex.md
index 1b0f8bbbbc..7ff4e9ce0a 100644
--- a/dev-docs/modules/userid-submodules/yandex.md
+++ b/dev-docs/modules/userid-submodules/yandex.md
@@ -3,6 +3,9 @@ layout: userid
title: Yandex ID
description: Yandex User ID sub-module
useridmodule: yandexIdSystem
+bidRequestUserId: yandexId
+eidsource: yandex.com
+example: '"1111"'
---
Yandex ID module is designed to improve the personalization of ads for publishers' users. This documentation provides information about the Yandex User ID module, and instructions to install it.
@@ -11,8 +14,9 @@ Yandex ID module is designed to improve the personalization of ads for publisher
Add the module to your Prebid.js package:
-{: .alert.alert-info :}
+```bash
gulp build --modules=yandexIdSystem
+```
## Step 2. Enable Yandex ID
diff --git a/dev-docs/modules/wurflRtdProvider.md b/dev-docs/modules/wurflRtdProvider.md
index 9ecd4cae12..a146b3efdb 100644
--- a/dev-docs/modules/wurflRtdProvider.md
+++ b/dev-docs/modules/wurflRtdProvider.md
@@ -22,7 +22,7 @@ This module loads a dynamically generated JavaScript from prebid.wurflcloud.com
## Description
-The WURFL RTD module enriches the Prebid.js bid request's OpenRTB 2.0 device data with [WURFL device data](https://www.scientiamobile.com/wurfl-js-business-edition-at-the-intersection-of-javascript-and-enterprise/). The module populates the `device.ext.wurfl` with WURFL device capabilities, ensuring that all bidder adapters have access to enriched device data. At a minimum, three WURFL capabilities are made available to all adapters: `is_mobile`, `complete_device_name` and `form_factor`.
+The WURFL RTD module enriches the Prebid.js bid request's OpenRTB 2.0 device data with [WURFL device data](https://www.scientiamobile.com/wurfl-js-business-edition-at-the-intersection-of-javascript-and-enterprise/). The module populates the `device` and `device.ext.wurfl` with WURFL device capabilities, ensuring that all bidder adapters have access to enriched device data. At a minimum, three WURFL capabilities are made available to all adapters: `is_mobile`, `complete_device_name` and `form_factor`.
SSPs and other demand partners subscribed to this service with ScientiaMobile will also receive an expanded set of device properties, including more detailed detection for iOS devices (e.g., specific iPhone and iPad model information). For a comprehensive list of available device capabilities, please refer to the [WURFL device capabilities](https://www.scientiamobile.com/capabilities/?products%5B%5D=wurfl-js) documentation.
@@ -42,8 +42,8 @@ The following scenarios are possible:
| | SSP Adapter | SSP Server Side End-Point |
| :------------------------ | :------------ | :--------------------------------------------------------------- |
| SSP adapter is already passing the ORTB2 device to the server (auction endpoint). | No changes required. | Update backend logic to utilize the device data. |
-| SSP adapter is not currently passing the data to server. | Update adapter to read `device.ext.wurfl` data and pass it to the endpoint. | Update backend logic to utilize the device data. |
-| SSP doesn't have a Bidder Adapter. | Implement PreBid.js adapter and read `device.ext.wurfl` data and pass it to the endpoint. | Update end-point to read and utilize the data. |
+| SSP adapter is not currently passing the data to server. | Update adapter to read `device` and/or `device.ext.wurfl` data and pass it to the endpoint. | Update backend logic to utilize the device data. |
+| SSP doesn't have a Bidder Adapter. | Implement PreBid.js adapter and read `device` and/or `device.ext.wurfl` data and pass it to the endpoint. | Update end-point to read and utilize the data. |
## Usage
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
|
| [**Richmedia Filter**](/prebid-server/pbs-modules/richmedia.html) | Can filter MRAID creatives from the bid stream. | validation | | |
| [**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 | | |
+| [**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 | | |
| [**Request Correction**](/prebid-server/pbs-modules/request-correction.html) | Apply optional corrections to bid requests. | general | | |
| [**Response Correction**](/prebid-server/pbs-modules/response-correction.html) | Apply optional corrections to bid responses. | general | | |
@@ -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)