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.

Sign up for GitHub

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

Jump to bottom

PBJS: Document adUnit.bids[].ortb2Imp and module #4376

Merged
merged 1 commit into from
Feb 23, 2023
Merged

PBJS: Document adUnit.bids[].ortb2Imp and module #4376

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
73 changes: 70 additions & 3 deletions dev-docs/adunit-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ See the table below for the list of properties on the ad unit. For example ad u
| `mediaTypes` | Optional | Object | Defines one or more media types that can serve into the ad unit. For a list of properties, see [`adUnit.mediaTypes`](#adUnit.mediaTypes) below. |
| `labelAny` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
| `labelAll` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
| `ortb2Imp` | Optional | Object | ortb2Imp is used to signal OpenRTB Imp objects at the adUnit grain. Similar to the global ortb2 field used for [global first party data configuration](/dev-docs/publisher-api-reference/setConfig.html#setConfig-fpd), but specific to this adunit. The ortb2Imp object currently supports [first party data](#adUnit-fpd-example) including the [Prebid Ad Slot](/features/pbAdSlot.html) and the [interstitial](#adUnit-interstitial-example) signal. |
| `ortb2Imp` | Optional | Object | ortb2Imp is used to signal OpenRTB Imp objects at the adUnit grain. Similar to the global ortb2 field used for [global first party data configuration](/dev-docs/publisher-api-reference/setConfig.html#setConfig-fpd), but specific to this adunit.|
| `ttlBuffer` | Optional | Number | TTL buffer override for this adUnit. See [setConfig({ttlBuffer})](/dev-docs/publisher-api-reference/setConfig.html#setConfig-ttlBuffer) |
| `renderer` | Optional | Object | Custom renderer, typically used for [outstream video](/dev-docs/show-outstream-video-ads.html) |
| `video` | Optional | Object | Used to link an Ad Unit to the [Video Module][videoModule]. For allowed params see the [adUnit.video reference](#adUnit-video). |
Expand All @@ -47,15 +47,17 @@ See the table below for the list of properties on the ad unit. For example ad u

See the table below for the list of properties in the `bids` array of the ad unit. For example ad units, see the [Examples](#adUnit-examples) below.

Note that `bids` is optional only for [Prebid Server stored impressions](/dev-docs/modules/prebidServer.html#stored-imp), and required in all other cases.
Note that `bids` is optional only for [Prebid Server stored impressions](#stored-imp), and required in all other cases.

{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------------------|
| `bidder` | Required | String | Unique code identifying the bidder. For bidder codes, see the [bidder param reference]({{site.baseurl}}/dev-docs/bidders.html). |
| `bidder` | Optional | String | Unique code identifying the bidder. For bidder codes, see the [bidder param reference]({{site.baseurl}}/dev-docs/bidders.html). |
| `module` | Optional | String | Module code - for requesting bids from modules that are not bid adapters. See [Prebid Server stored impressions](#stored-imp). |
| `params` | Required | Object | Bid request parameters for a given bidder. For allowed params, see the [bidder param reference]({{site.baseurl}}/dev-docs/bidders.html). |
| `labelAny` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
| `labelAll` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
| `ortb2Imp` | Optional | Object | OpenRTB first-party data specific to this bidder. This is merged with, and takes precedence over, `adUnit.ortb2Imp`.|
| `renderer` | Optional | Object | Custom renderer. Takes precedence over `adUnit.renderer`, but applies only to this bidder. |

<a name="adUnit.mediaTypes" />
Expand Down Expand Up @@ -605,6 +607,71 @@ pbjs.addAdUnits({

For more information on Interstitial ads, reference the [Interstitial feature page](/features/InterstitialAds.html).

<a id="stored-imp" />

### Prebid Server stored impressions

When using [PBS stored impressions](/dev-docs/modules/prebidServer.html#stored-imp), `bids` is not required:

```javascript
pbjs.addAdUnits({
code: "test-div",
ortb2Imp: {
ext: {
prebid: {
storedrequest: {
id: 'stored-request-id'
}
}
}
}
})
```

To use stored impressions together with client-side bidders - or stored impressions from other instances of Prebid Server - use `bids[].module`:

```javascript
pbjs.addAdUnits({
code: "test-div",
bids: [
{
module: "pbsBidAdapter",
params: {
configName: "server-1"
},
ortb2Imp: {
ext: {
prebid: {
storedrequest: {
id: 'stored-request-server-1'
}
}
}
}
},
{
module: "pbsBidAdapter",
params: {
configName: "server-2"
},
ortb2Imp: {
ext: {
prebid: {
storedrequest: {
id: 'stored-request-server-2'
}
}
}
}
},
{
bidder: 'client-bidder',
// ...
}
]
});
```

## Related Topics

+ [Publisher API Reference](/dev-docs/publisher-api-reference)
Expand Down
3 changes: 3 additions & 0 deletions dev-docs/modules/prebidServer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,12 +45,14 @@ The same bidder cannot be set in both configs. For example:
pbjs.setConfig({
s2sConfig: [
{
name: "pbs-appnexus",
accountId: '12345',
bidders: ['appnexus','pubmatic'],
defaultVendor: 'appnexus',
timeout: 300,
},
{
name: "pbs-rubicon",
accountId: '678910',
bidders: ['rubicon'],
defaultVendor: 'rubicon',
Expand All @@ -65,6 +67,7 @@ There are many configuration options for s2sConfig:
| Attribute | Scope | Type | Description |
|------------+---------+---------+---------------------------------------------------------------|
| `accountId` | Required | String | Your Prebid Server account ID. This is obtained from whoever's hosting your Prebid Server. |
| `name` | Optional | String | A handle for this configuration, used to reference a specific server (when multiple are present) from [ad unit configuration](/dev-docs/adunit-reference.html#stored-imp) |
| `bidders` | Optional | Array of Strings | Which bidders auctions should take place on the server side |
| `allowUnknownBidderCodes` | Optional | Boolean | Allow Prebid Server to bid on behalf of bidders that are not explicitly listed in the adUnit. See important [note](#allowUnknownBidderCodes) below. Defaults to `false`. |
| `defaultVendor` | Optional | String | Automatically includes all following options in the config with vendor's default values. Individual properties can be overridden by including them in the config along with this setting. See the Additional Notes below for more information. |
Expand Down