This module helps support bidders that aren’t full-service SSPs by allowing PBS host companies to configure per-account OpenRTB blocking details. OpenRTB 2.5 defines the following 6 attributes available for some kind of bid exclusion logic:
The module supports all of these blocking scenarios except the last: bseat. Prebid uses the ‘seat’ field in OpenRTB to indicate the biddercode, losing any agency information that might have been passed to the bid adapter.
For each of the supported attributes, there are a range of behaviors that can be configured:
Here’s a summary of the features the module supports:
Scenario | Configure Blocks | Enforce Blocks | Enforce Unknown Values | Deal Overrides |
---|---|---|---|---|
Advertiser Domains | ||||
Advertiser Categories | ||||
Apps | ||||
Banner Types | ||||
Banner Attributes |
This module supports running at two stages:
We recommend defining the execution plan right in the account config so the module is only invoked for specific accounts. See below for an example.
There is no host-company level config for this module except the execution plan may optionally be at the host level.
Here’s a general template for the account config used in PBS-Java:
{
"hooks": {
"modules": {
"ortb2-blocking": { // start of this module's config
"attributes": {
"ATTRIBUTE": { // badv, bcat, bapp, btype, battr
DEFAULT_SETTINGS,
"action-overrides": {
OVERRIDE_SETTING: [{
"conditions": { ... },
// the value below will be the datatype of the SETTING
"override": VALUE
}]
}
}
}
}
},
"execution-plan": {
...
}
}
}
PBS-Go uses underscores instead of dashes, so this is the Go version of the same config:
{
"hooks": {
"modules": {
"prebid": {
"ortb2blocking": { // start of this module's config
"attributes": {
"ATTRIBUTE": { // badv, bcat, bapp, btype, battr
DEFAULT_SETTINGS,
"action_overrides": {
OVERRIDE_SETTING: [{
"conditions": { ... },
// the value below will be the datatype of the SETTING
"override": VALUE
}]
}
}
}
}
}
},
"execution_plan": {
...
}
}
}
The ‘ATTRIBUTE’ above is one of the 5 blockable entities defined in OpenRTB. A ‘SETTING’ is a feature this module supports. The following sections detail each of the 5 blockable entities.
Here’s a detailed example for PBS-Java:
{
"hooks": {
"modules": {
"ortb2-blocking": {
"attributes": {
"badv": {
"enforce-blocks": false, // default is false
"blocked-adomain": [], // these are unconditionally blocked domains
"action-overrides": {
"blocked-adomain": [ // these are conditionally blocked domains
{
"override": [ "example.com" ],
"conditions": {
"bidders": [ "bidderA" ]
}
}
]
}
},
"bcat": {
"enforce-blocks": false, // default is false
"blocked-adv-cat": [], // these are unconditionally blocked categories
"action-overrides": {
"blocked-adv-cat": [ // these are conditionally blocked categories
{
"override": [ "IAB7" ],
"conditions": {
"bidders": [ "bidderA" ]
}
}
]
}
},
"battr": {
"enforce-blocks": false, // default is false
"action-overrides": {
"blocked-banner-attr": [ // these are conditionally blocked categories
{
"override": [1,3,8,9,10,13,14,17],
"conditions": {
"bidders": [
"bidderA"
]
}
}
]
},
"blocked-banner-attr": [] // these are unconditionally blocked categories
}
}
}
},
"execution-plan": {
"endpoints": {
"/openrtb2/amp": {
"stages": {
"bidder-request": {
"groups": [
{
"timeout": 5,
"hook-sequence": [
{
"module-code": "ortb2-blocking",
"hook-impl-code": "ortb2-blocking-bidder-request"
}
]
}
]
}
}
},
"/openrtb2/auction": {
"stages": {
"bidder-request": {
"groups": [
{
"timeout": 5,
"hook-sequence": [
{
"module-code": "ortb2-blocking",
"hook-impl-code": "ortb2-blocking-bidder-request"
}
]
}
]
}
}
}
}
}
}
}
For PBS-Go:
{
"hooks": {
"modules": {
"prebid": {
"ortb2blocking": {
"attributes": {
"badv": {
"enforce_blocks": false,
"blocked_adomain": [],
"action_overrides": {
"blocked_adomain": [
{
"override": [ "example.com" ],
"conditions": {
"bidders": [ "bidderA" ]
}
}
]
}
},
"bcat": {
"enforce_blocks": false,
"blocked_adv_cat": [],
"action_overrides": {
"blocked_adv_cat": [
{
"override": [ "IAB7" ],
"conditions": {
"bidders": [ "bidderA" ]
}
}
]
}
},
"battr": {
"enforce_blocks": false,
"action_overrides": {
"blocked_banner_attr": [
{
"override": [1,3,8,9,10,13,14,17],
"conditions": {
"bidders": [ "bidderA" ]
}
}
]
},
"blocked_banner_attr": []
}
}
}
}
},
"execution_plan": {
"endpoints": {
"/openrtb2/amp": {
"stages": {
"bidder_request": {
"groups": [
{
"timeout": 5,
"hook_sequence": [
{
"module_code": "prebid.ortb2blocking",
"hook_impl_code": "ortb2-blocking-bidder-request"
}
]
}
]
}
}
},
"/openrtb2/auction": {
"stages": {
"bidder_request": {
"groups": [
{
"timeout": 5,
"hook_sequence": [
{
"module_code": "prebid.ortb2blocking",
"hook_impl_code": "ortb2-blocking-bidder-request"
}
]
}
]
}
}
}
}
}
}
}
The module supports flexibile definition of behavior surrounding the 5 blocked attributes. Here are the details.
This attribute is related to the ‘badv’ of the request, and the ‘adomain’ of the response.
Setting | Description | Data Type | Override Conditions Supported |
---|---|---|---|
blocked-adomain | List of adomains not allowed to display on this inventory | array of strings | bidders (array of strings), media-types (array of strings). |
enforce-blocks | Whether to enforce adomains in responses. Default is false. | boolean | bidders (array of strings), media-types (array of strings) |
block-unknown-adomain | Whether to block responses not specifying adomain. Only active if enforce-blocks is true. | boolean | bidders (array of strings), media-types (array of strings) |
allowed-adomain-for-deals | List of adomains allowed for deals in general or a specific dealid. | array of strings | deal-ids (array of strings). This isn’t a true override - values are added to the global. |
Here’s an example account config for PBS-Java with several scenarios:
{
"hooks": {
"modules": {
"ortb2-blocking": { // start of this module's config
"attributes": {
"badv": {
// enforce domain blocks by default
"enforce-blocks": true,
"block-unknown-adomain": true,
// these are the default undesirable domains
"blocked-adomain": [ "a.com", "b.com", "c.com" ],
// but deals can return this one
"allowed-adomain-for-deals": [ "a.com" ],
"action-overrides": {
"blocked-adomain": [{
// c.com allowed on these bidders for video
"conditions": {
"bidders": [ "bidderA", "bidderB" ],
"media-type": [ "video" ]
},
"override": [ "a.com", "b.com" ]
},
{
// more domains blocked for this bidder
"conditions": {
"bidders": [ "bidderc" ]
},
"override": [ "a.com", "b.com", "c.com", "d.com", "e.com" ]
}
],
"block-unknown-adomain": [
{
// don't block unnknown for video bids from this bidder
"conditions": {
"bidders": [ "bidderA" ],
"media-type": [ "video" ]
},
"override": false
}
],
"allowed-adomain-for-deals": [
{
// this deal is for normally blocked domain b.com
"conditions": {
"deal-ids": [ "12345678" ]
},
"override": [ "b.com" ]
}
]
}
}
}
}
}
}
}
For PBS-Go:
{
"hooks": {
"modules": {
"prebid": {
"ortb2blocking": { // start of this module's config
"attributes": {
"badv": {
// enforce domain blocks by default
"enforce_blocks": true,
"block_unknown_adomain": true,
// these are the default undesirable domains
"blocked_adomain": [ "a.com", "b.com", "c.com" ],
// but deals can return this one
"allowed_adomain_for_deals": [ "a.com" ],
"action_overrides": {
"blocked_adomain": [{
// c.com allowed on these bidders for video
"conditions": {
"bidders": [ "bidderA", "bidderB" ],
"media_types": [ "video" ]
},
"override": [ "a.com", "b.com" ]
},
{
// more domains blocked for this bidder
"conditions": {
"bidders": [ "bidderc" ]
},
"override": [ "a.com", "b.com", "c.com", "d.com", "e.com" ]
}
],
"block_unknown_adomain": [
{
// don't block unnknown for video bids from this bidder
"conditions": {
"bidders": [ "bidderA" ],
"media_types": [ "video" ]
},
"override": false
}
],
"allowed_adomain_for_deals": [
{
// this deal is for normally blocked domain b.com
"conditions": {
"deal_ids": [ "12345678" ]
},
"override": [ "b.com" ]
}
]
}
}
}
}
}
}
}
}
This attribute is related to the ‘bcat’ of the request and ‘cat’ of the response.
Setting | Description | Data Type | Override Conditions Supported |
---|---|---|---|
blocked-adv-cat | List of IAB categories not allowed to display on this inventory | array of strings | bidders (array of strings), media-types (array of strings) |
enforce-blocks | Whether to enforce cat in responses. Default is false. | boolean | bidders (array of strings), media-types (array of strings) |
block-unknown-adv-cat | Whether to block responses not specifying cat. Only active if enforce-blocks is true. | boolean | bidders (array of strings), media-types (array of strings) |
allowed-adv-cat-for-deals | List of adomains allowed for deals in general or a specific dealid. | array of strings | deal-ids (array of strings). This isn’t a true override - values are added to the global. |
Here’s an example account config for PBS-Java with several scenarios:
{
"hooks": {
"modules": {
"ortb2-blocking": { // start of this module's config
"attributes": {
"bcat": {
// don't enforce blocks
"enforce-blocks": false,
// block these categories by default
"blocked-adv-cat": [ "IAB-1", "IAB-2" ],
// deals can return this cat
"allowed-adv-cat-for-deals": [ "IAB-1" ],
"action-overrides": {
"blocked-adv-cat": [
{
// block additional categories for video
"conditions": {
"media-types": [ "video" ]
},
"override": [ "IAB-1", "IAB-2", "IAB-3", "IAB-4" ]
}
],
"enforce-blocks": [
{
// enforce bcat blocks for this bidder
"conditions": {
"bidders": [ "bidderA" ]
},
"override": true
}
],
"block-unknown-adv-cat": [
{
// enforce unknown cat for this bidder
"conditions": {
"bidders": [ "bidderA" ]
},
"override": true
}
],
"allowed-adv-cat-for-deals": [
{
// this deal ID allowed to be this category
"conditions": {
"deal-ids": [ "1111111" ]
},
"override": [ "IAB-2" ]
}
]
}
}
}
}
}
}
}
For PBS-Go
{
"hooks": {
"modules": {
"prebid": {
"ortb2blocking": { // start of this module's config
"attributes": {
"bcat": {
// don't enforce blocks
"enforce_blocks": false,
// block these categories by default
"blocked_adv_cat": [ "IAB-1", "IAB-2" ],
// deals can return this cat
"allowed_adv_cat_for_deals": [ "IAB-1" ],
"action_overrides": {
"blocked_adv_cat": [
{
// block additional categories for video
"conditions": {
"media_types": [ "video" ]
},
"override": [ "IAB-1", "IAB-2", "IAB-3", "IAB-4" ]
}
],
"enforce_blocks": [
{
// enforce bcat blocks for this bidder
"conditions": {
"bidders": [ "bidderA" ]
},
"override": true
}
],
"block_unknown_adv_cat": [
{
// enforce unknown cat for this bidder
"conditions": {
"bidders": [ "bidderA" ]
},
"override": true
}
],
"allowed_adv_cat_for_deals": [
{
// this deal ID allowed to be this category
"conditions": {
"deal_ids": [ "1111111" ]
},
"override": [ "IAB-2" ]
}
]
}
}
}
}
}
}
}
}
This attribute is related to the ‘bapp’ of the request and ‘bundle’ of the response.
Setting | Description | Data Type | Override Conditions Supported |
---|---|---|---|
blocked-app | List of bundles not allowed to display on this inventory | array of strings | bidders (array of strings), media-types (array of strings) |
enforce-blocks | Whether to enforce bundles in responses. Default is false. | boolean | bidders (array of strings), media-types (array of strings) |
allowed-bapp-for-deals | List of bundles allowed for deals in general or a specific dealid. | array of strings | deal-ids (array of strings). This isn’t a true override - values are added to the global. |
Here’s an example account config for PBS-Java:
{
"hooks": {
"modules": {
"ortb2-blocking": { // start of this module's config
"attributes": {
"bapp": {
// don't enforce
"enforce-blocks": false,
// these bundles blocked by default
"blocked-app": [ "app1", "app2" ],
"action-overrides": {
"blocked-app": [
{
// this bidder also blocked for an additional app
"conditions": {
"bidders": [ "bidderA" ]
},
"override": [ "app1", "app2", "app3" ]
}
]
}
}
}
}
}
}
}
For PBS-Go
{
"hooks": {
"modules": {
"prebid": {
"ortb2blocking": { // start of this module's config
"attributes": {
"bapp": {
// don't enforce
"enforce_blocks": false,
// these bundles blocked by default
"blocked_app": [ "app1", "app2" ],
"action_overrides": {
"blocked_app": [
{
// this bidder also blocked for an additional app
"conditions": {
"bidders": [ "bidderA" ]
},
"override": [ "app1", "app2", "app3" ]
}
]
}
}
}
}
}
}
}
}
This attribute is related to the ‘btype’ of the request.
Setting | Description | Data Type | Override Conditions Supported |
---|---|---|---|
blocked-banner-type | List of IAB banner types not allowed to display on this inventory | array of int | bidders (array of strings), media-types (array of strings) |
See Table 5.2 in the OpenRTB 2.5 spec for the possible values.
Note: no enforcement is possible because the creative type is not explictly part of the response and Prebid Server does not currently contain logic to parse creatives to derive the type.
Here’s an example account config for PBS-Java:
{
"hooks": {
"modules": {
"ortb2-blocking": { // start of this module's config
"attributes": {
"btype": {
// block these types for all bidders
"blocked-banner-type": [ 3, 4 ],
"action-overrides": {
"blocked-banner-type": [
{
// block an additional type for this bidder
"conditions": {
"bidders": [ "bidderA" ]
},
"override": [ 3, 4, 5 ]
}
]
}
}
}
}
}
}
}
For PBS-Go
{
"hooks": {
"modules": {
"prebid": {
"ortb2blocking": { // start of this module's config
"attributes": {
"btype": {
// block these types for all bidders
"blocked_banner_type": [ 3, 4 ],
"action_overrides": {
"blocked_banner_type": [
{
// block an additional type for this bidder
"conditions": {
"bidders": [ "bidderA" ]
},
"override": [ 3, 4, 5 ]
}
]
}
}
}
}
}
}
}
}
This attribute is related to the ‘battr’ of the request and ‘attr’ of the response.
Setting | Description | Data Type | Override Conditions Supported |
---|---|---|---|
blocked-banner-attr | List of IAB banner attributes not allowed to display on this inventory | array of int | bidders (array of strings), media-types (array of strings) |
enforce-blocks | Whether to enforce attr in responses. Default is false. | boolean | bidders (array of strings), media-types (array of strings) |
allowed-banner-attr-for-deals | List of IAB attributes allowed for deals in general or a specific dealid. | array of strings | deal-ids (array of strings). This isn’t a true override - values are added to the global. |
See Table 5.3 in the OpenRTB 2.5 spec for the possible values.
Here’s an example account config for PBS-Java:
{
"hooks": {
"modules": {
"ortb2-blocking": { // start of this module's config
"attributes": {
"battr": {
// don't enforce
"enforce-blocks": false,
// block these attributes for all bidders
"blocked-banner-attr": [ 1, 8, 9, 10 ],
"action-overrides": {
"enforce-blocks": [
{
// enforce the attr block for this bidder
"conditions": {
"bidders": [ "bidderA" ]
},
"override": true
}
]
}
}
}
}
}
}
}
For PBS-Go
{
"hooks": {
"modules": {
"prebid": {
"ortb2blocking": { // start of this module's config
"attributes": {
"battr": {
// don't enforce
"enforce_blocks": false,
// block these attributes for all bidders
"blocked_banner_attr": [ 1, 8, 9, 10 ],
"action_overrides": {
"enforce_blocks": [
{
// enforce the attr block for this bidder
"conditions": {
"bidders": [ "bidderA" ]
},
"override": true
}
]
}
}
}
}
}
}
}
}
In order to allow the module to be picked up by PBS-Java, a Spring Boot configuration property hooks.ortb2-blocking.enabled
must be set to true
.
Here’s an example of how your PBS configuration YAML should look like:
hooks:
ortb2-blocking:
enabled: true
There’s only one analytics activity defined by this module: “enforce-blocking”.
It’s only applied to attributes where enforce-blocks
is true, which means ‘btype’ never shows up here. ATag values:
values
block:
appliedto
block:
values
blockappliedto
block:
Here’s an example analytics tag that might be produced for use in an analytics adapter:
[{
activities: [{
name: "enforce-blocking",
status: "success",
results: [{
// bidderA was blocked for both badv and bcat for imp=1
status: "success-block",
values: {
"attributes": ["badv", "bcat"],
"adomain": ["bad.com"],
"bcat": ["IAB-7"]
},
appliedto: {
"bidder": "bidderA",
imp: ["1"]
}
},{
// the other 3 bids from bidderA were ok
status: "success-allow",
appliedto: {
"bidder": "bidderA",
"imp": ["2","3","4"]
}
},{
// scenario: bidderB not blocked at all
status: "success-allow",
appliedto: {
"bidder": "bidderB",
"imp": ["1","2","3","4"] }
},{
// scenario: bidderC blocked on battr and bapp for imp=3
status: "success-block",
values: {
"app": "com.test",
"attr": [2]
"attributes": ["bapp", "battr"]
},
appliedto: {
"bidder": "bidderC",
"imp": ["3"]
}
},{
// otherwise bidderC's bids were fine
status: "success-allow",
appliedto: {
"bidder": "bidderC",
"imp": ["1","2","4"]
}
}]
}]
}]