Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

PBS flexible bidadjustments #5718

Merged
merged 6 commits into from
Nov 20, 2024
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 114 additions & 0 deletions prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md
Original file line number Diff line number Diff line change
Expand Up @@ -404,6 +404,15 @@ Bid adapters do not need to read this data from ext.prebid. PBS will merge the a

##### Bid Adjustments

There are two ways PBS can be instructed to adjust bids:

1. The original `bidadjustmentfactors` approach is simpler and allows for percentage-based adjustments based on bidder and mediatype.
2. The more powerful `bidadjustments` feature allows for percentage, absolute, and static adjustments based on bidder, mediatype and deal IDs.

If both `bidadjustments` and `bidadjustmentfactors` are specified, the bidadjustments (newer approach) takes precedence.

###### Original Bid Adjustment Factors

Bidders are encouraged to make Net bids. However, there's no way for Prebid to enforce this.
If you find that some bidders use Gross bids, publishers can adjust for it with `request.ext.prebid.bidadjustmentfactors`:

Expand Down Expand Up @@ -450,6 +459,111 @@ It's also possible to define different bid adjustment factors by mediatype, whic

Note that video-outstream is defined to be imp[].video requests where imp[].video.placement is greater than 1.

###### Flexible Bid Adjustments

A more powerful approach to adjusting bid values can be specifed on the request or in account config. Here's the general format:

```json5
{
"ext": {
"prebid": {
"bidadjustments": {
"mediatype": {
MEDIATYPE: {
BIDDER: {
DEAL: [ {"adjtype": ADJTYPE, "value": ADJVALUE} ]
bretg marked this conversation as resolved.
Show resolved Hide resolved
}
}
}
}
}
}
}
```

Where:

- MEDIATYPE can be 'banner', 'video-instream', 'video-oustream', 'native', 'audio', or a wildcard (*)
- BIDDER can be a biddercode or a wildcard (*)
- DEAL can be a dealID or a wildcard (*)
- ADJTYPE can be 'multiplier', 'cpm' or 'static'
- ADJVALUE is a float value. See the table below for more details.

Note that the specific adjustments are after the deal level and are an array of adjustments. Most commonly there will be only one entry in the array, but allowing it to have multiple entries can meet some advanced adjustment use cases. The next couple of sections provide detail on the input values.

**MediaType**

{: .table .table-bordered .table-striped }
| MediaType | Definition | Notes |
| --- | --- | --- |
| banner | The response type is format=banner | |
| video-instream | The response type is format=video the request imp.video.placement=1 or imp.video.plcmt=1 | |
| video-outstream | The response type is format=video the request imp.video.placement>1 or imp.video.plcmt>1 | |
| native | The response type is format=native | |
| audio | The response type is format=audio | |
| * | The remaining mediatypes | The wildcard is always used as a default value. i.e. if adjustments are defined for an explicit mediatype, that will take precedence. |

**Adjustment Types and Values**

{: .table .table-bordered .table-striped }
| Adjustment Type | Definition | Values | Notes |
| --- | --- | --- | --- |
| multiplier | multiply the bid price by the value | float between 0 and MAXINT | currency doesn't matter in this scenario |
| cpm | subtract the value from the bid price after adjusting for currency | float between 0 and MAXINT | currency must be specified |
| static | ignore the actual bid value and override it with the specified value and currency | float between 0 and MAXINT | currency must be specified |

**Notes**

- Any validation failure will skip the whole bid adjustment operation
- The system will attempt to merge request-level and account-level bid adjustments. If this fails it will try to use only the account bid adjustments.
- If there's a validation error, a debug message will be added and a sample will be logged to the PBS log file.

**Example**

Here's an example showing a couple of use cases:

```json5
{
"ext": {
"prebid": {
"bidadjustments": {
"mediatype": {
"banner": {
// decrement banner bids from bidderA by 10%
"bidderA": {
"*" : [ {"adjtype": "multiplier", "value": 0.9} ]
},
"*": { // wildcard bidder only matches if there isn't a more direct match
// bids on deal 111111 are always exactly $3.00
"111111": [{
"adjtype": "static", "value": 3.00, "currency": "USD"
}],
// otherwise, always decrement banner bids by $0.10
"*": [{
"adjtype": "cpm", "value": 0.1, "currency": "USD"
}]
}
},
"video-instream": {
// for video bids, take 80% of the bid value and add $0.18.
"*": { // all bidders
"*": [{ // all deals
"adjtype": "multiplier", "value": 0.80
}, {
"adjtype": "cpm", "value": 0.18
bretg marked this conversation as resolved.
Show resolved Hide resolved
}]
}
}
}
}
}
}
}
```

{: .alert.alert-info :}
Note that these bidadjustments can also be specified in the PBS account config in `auction.bidadjustments`

##### Targeting

Targeting refers to strings that are sent to the adserver to
Expand Down