Skip to content

Commit c6e7fdf

Browse files
osazososazos
authored
Adagio: update bidder adapter documentation (#6327)
* Adagio: update bid adapter doc * Adagio: fix metadata fields
1 parent fa0c49b commit c6e7fdf

File tree

1 file changed

+125
-65
lines changed

1 file changed

+125
-65
lines changed

‎dev-docs/bidders/adagio.md‎

Lines changed: 125 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ floors_supported: true
1313
tcfeu_supported: true
1414
dsa_supported: true
1515
usp_supported: true
16-
gpp_supported: true
1716
coppa_supported: true
17+
gpp_sids: tcfeu, tcfca, usnat, usstate_all, usp
1818
schain_supported: true
1919
gvl_id: 617
2020
prebid_member: true
@@ -24,98 +24,158 @@ dchain_supported: false
2424
deals_supported: false
2525
ortb_blocking_supported: false
2626
endpoint_compression: true
27+
privacy_sandbox: 'no'
2728
sidebarType: 1
2829
---
2930

30-
### Note
31+
### Table of contents
32+
33+
* [Table of contents](#table-of-contents)
34+
* [Introduction](#introduction)
35+
* [Bid params](#bid-params)
36+
* [Setting params: AdUnit Level vs First Party Data](#setting-params-adunit-level-vs-first-party-data)
37+
* [Prebid Server](#prebid-server-adapter)
38+
* [Additional informations](#additional-informations)
39+
* [User Sync](#user-sync)
40+
* [Recommended placement param values](#recommended-placement-param-values)
41+
* [Video outstream](#video-outstream)
42+
43+
### Introduction
3144

3245
The Adagio bidder adapter requires setup and approval from the Adagio team. Please reach out to [[email protected]](mailto:[email protected]) for more information.
3346

34-
### Configuration for Prebid.js
47+
We strongly recommend using it alongside the [Adagio RTD Provider](/dev-docs/modules/adagioRtdProvider.md), which leverages viewability and attention predictions to enhance inventory quality and maximize performance.
3548

36-
#### User Sync
49+
We also strongly suggest enabling the gptPreAuction module, which automatically populates the GPID (Global Placement ID) values. The GPID helps improve monetization by providing more accurate identification of each ad placement. For setup details, see the [gptPreAuction module documentation](/dev-docs/modules/gpt-pre-auction.md).
3750

38-
Adagio strongly recommends enabling user syncing through iFrames. This functionality improves DSP user match rates and increases the bid rate and bid price. Make sure to call `pbjs.setConfig()` only once. This configuration is optional in Prebid, but required by Adagio.
51+
### Bid params
3952

40-
```js
41-
// https://docs.prebid.org/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing
42-
pbjs.setConfig({
43-
userSync: {
44-
filterSettings: {
45-
iframe: {
46-
bidders: ['adagio'],
47-
filter: 'include'
48-
}
49-
}
50-
}
51-
});
52-
```
53+
{: .table .table-bordered .table-striped .table-responsive }
5354

54-
#### Bidder Settings
55+
| Name | Scope | Description | Example | Type |
56+
| ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------- |
57+
| `organizationId` | required | Id of the Organization. Handed out by Adagio. | `'1010'` | `string` |
58+
| `site` | required / optional (in-app) | Name of the site. Handed out by Adagio.<br><span style="display:inline-block; margin-top: 0.6em; line-height:1.5; font-size:14px; font-style:italic;">- max length: 50</span> | `'mysite-com'` | `string` |
59+
| `placement` | required | Refers to the placement of an adunit in a page. See [recommended values](#recommended-placement-param-values).<br><span style="display:inline-block; margin-top: 0.6em; line-height:1.5; font-size:14px; font-style:italic;">- max length: 50<br>- max distinctives values: 10</span> | `'banner_top'` | `string` |
60+
| `pagetype` | highly recommended | Describes what kind of content will be present in the page.<br><span style="display:inline-block; margin-top: 0.6em; line-height:1.5; font-size:14px; font-style:italic;">- max length: 30<br>- max distinctives values: 50</span><br><span style="display:inline-block; line-height:1.5; font-size:14px;">Can be set at adUnit level or via FPD ([see below](#setting-params-adunit-level-vs-first-party-data))</span> | `'article'` | `string` |
61+
| `category` | recommended | Category of the content displayed in the page.<br><span style="display:inline-block; margin-top: 0.6em; line-height:1.5; font-size:14px; font-style:italic;">- max length: 30<br>- max distinctives values: 50</span><br><span style="display:inline-block; line-height:1.5; font-size:14px;">Can be set at adUnit level or via FPD ([see below](#setting-params-adunit-level-vs-first-party-data))</span> | `'sport'` | `string` |
62+
63+
#### Setting params: AdUnit Level vs First Party Data
5564

56-
The Adagio bid adapter uses browser local storage. Since Prebid.js 7.x, the access to it must be explicitly set.
65+
You can set `pagetype` and `category` parameters in two ways:
5766

58-
{% include dev-docs/storageAllowed.md %}
67+
**1. At the adUnit level** (individual ad slots):
5968

6069
```js
61-
// https://docs.prebid.org/dev-docs/publisher-api-reference/bidderSettings.html
62-
pbjs.bidderSettings = {
63-
adagio: {
64-
storageAllowed: true
65-
}
70+
{
71+
code: 'div-gpt-ad-1234567890',
72+
mediaTypes: {
73+
banner: {
74+
sizes: [[300, 250]]
75+
}
76+
},
77+
bids: [{
78+
bidder: 'adagio',
79+
params: {
80+
organizationId: '1010',
81+
site: 'mysite-com',
82+
placement: 'banner_top',
83+
pagetype: 'article',
84+
category: 'sport'
85+
}
86+
}]
6687
}
6788
```
6889

69-
#### Bid Params for Prebid.js
70-
71-
**Important**: Adagio needs to collect attention data about the ads displayed on a page and must listen to some specifics ad-server events. Please refer to the [Adagio user guide](https://adagioio.notion.site/Adagio-Account-Setup-Guide-fbcd940649224cdfa10393d2f008792e) for details.
72-
73-
{: .table .table-bordered .table-striped }
90+
**2. Globally via First Party Data** (applies to all adUnits on the page):
7491

75-
| Name | Scope | Description | Example | Type |
76-
| ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------- |
77-
| `organizationId` | required | Id of the Organization. Handed out by Adagio. | `'1010'` | `string` |
78-
| `site` | required | Name of the site. Handed out by Adagio.<br><i>- max length: 50</i> | `'mysite-com'` | `string` |
79-
| `placement`* | required | Refers to the placement of an adunit in a page.<br>Must not contain any information about the type of device.<br><i>- max length: 50</i><br><i>- max distinctives values: 10</i> | `'ban_atf'` | `string` |
80-
| `adUnitElementId` | required | Refers to the adunit html attribute id in a page. | `'gpt-ban-atf'` | `string` |
81-
| `pagetype`* | highly recommended | Describes what kind of content will be present in the page.<br><i>- max length: 30</i><br><i>- max distinctives values: 50</i> | `'article'` | `string` |
82-
| `category`* | recommended | Category of the content displayed in the page.<br><i>- max length: 30</i><br><i>- max distinctives values: 50</i> | `'sport'` | `string` |
83-
| `video` | optional | OpenRTB 2.5 video options object. All options will override ones defined in mediaTypes video.<br>Mandatory: <br>- api <small><i>(your video player must at least support the value 2)</i></small><br> Highly recommended: <br> - playbackmethod <br> Not supported: <br>`protocol`, `companionad`, `companiontype`, `ext` options| `{api: [2], playbackmethod: [6], skip: 1, startdelay: 0}` | `object` |
84-
| `native` | optional | Partial OpenRTB Native 1.2 request object. Supported fields are:<br>- context<br>- plcmttype | `{context: 1, plcmttype: 2}` | `object` |
85-
| `splitKeyword` | optional | Keyword that can later be used in a split rule targeting to trigger the rule (especially for Direct Seats AB testing) | `'splitrule-one'` | `string` |
86-
| `dataLayer` | optional | A set of arbitrary key-value pairs. This can be used to configure mappings. The keys and values must be strings. | `{placement: 'my-placement', siteid: 'my-siteid'}` | `object` |
87-
88-
<i>*These parameters will have their accentuated characters converted to their non-accentuated version:&nbsp;`é`&nbsp;=>&nbsp;`e`</i>
92+
```js
93+
pbjs.setConfig({
94+
ortb2: {
95+
site: {
96+
ext: {
97+
data: {
98+
pagetype: 'article',
99+
category: 'sport'
100+
}
101+
}
102+
}
103+
}
104+
});
105+
```
89106

90-
#### First Party Data
107+
* First Party Data takes precedence over AdUnit-level parameters.
108+
* If the FPD value is an array, the first value will be used.
109+
110+
<a id="prebid-server-adapter"></a>
111+
### Prebid Server
112+
113+
If you are hosting a Prebid Server, you must configure the Adagio Prebid Server adapter by changing the [`static/bidder-info/adagio.yaml` file](https://github.com/prebid/prebid-server/blob/master/static/bidder-info/adagio.yaml) in order to:
114+
115+
1. enable the adapter by deleting the `disabled: true` entry _(or set it to `false`)_
116+
2. replace the endpoints containing the `REGION` by one of the value below:
117+
* **AMER:**
118+
* Auction: `https://mp-las.4dex.io/pbserver`
119+
* Usersync: `https://u-las.4dex.io/pbserver/usync.html`
120+
* **EMEA:**
121+
* Auction: `https://mp-ams.4dex.io/pbserver`
122+
* Usersync: `https://u-ams.4dex.io/pbserver/usync.html`
123+
* **APAC:**
124+
* Auction: `https://mp-tyo.4dex.io/pbserver`
125+
* Usersync: `https://u-tyo.4dex.io/pbserver/usync.html`
126+
127+
**Example for EMEA**
128+
129+
{% raw %}
130+
131+
```yaml
132+
endpoint: "https://mp-ams.4dex.io/pbserver"
133+
userSync:
134+
iframe:
135+
url: "https://u-ams.4dex.io/pbserver/usync.html?gdpr={{.GDPR}}&gdpr_consent={{.GDPRConsent}}&us_privacy={{.USPrivacy}}&gpp={{.GPP}}&&gpp_sid={{.GPPSID}}&r={{.RedirectURL}}"
136+
userMacro: "{UID}"
137+
disabled: false
138+
# …
139+
```
91140

92-
Adagio will use FPD data as fallback for the params below:
141+
{% endraw %}
93142

94-
- pagetype
95-
- category
143+
### Additional informations
96144

97-
If the FPD value is an array, the 1st value of this array will be used.
145+
#### User Sync
98146

99-
#### Video outstream
147+
Enable user sync via iframe to improve DSP user match rates, leading to higher bid rates and bid prices. While this configuration is optional in Prebid, it is required by Adagio. Ensure that `pbjs.setConfig()` is called only once.
100148

101-
The AdagioBidAdapter includes a default video player powered by [Blue Billywig](https://www.bluebillywig.com). This default player is used when no renderer is configured for the adUnit.
149+
```js
150+
// https://docs.prebid.org/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing
151+
pbjs.setConfig({
152+
userSync: {
153+
filterSettings: {
154+
iframe: {
155+
bidders: ['adagio'],
156+
filter: 'include'
157+
}
158+
}
159+
}
160+
});
161+
```
102162

103-
### Configuration for Prebid Server
163+
#### Recommended placement param values
104164

105-
{: .alert.alert-warning :}
106-
Adagio Prebid Server adapter is currently **available for apps**. Website support is coming soon. Activation requires setup and approval before beginning. Please reach out to your account manager or <[email protected]> for more details.
165+
Setting a meaningful value for the `placement` parameter is essential for our adapter to optimize ad delivery and performance, as it defines the specific location and context of your ad unit within the page. To streamline your implementation and ensure consistent naming conventions across your inventory, we provide these standardized values that eliminate guesswork and ensure your ad units are properly categorized for maximum yield.
107166

108-
Adagio supports different regions for the Prebid Server. Please deploy the prebid config in each of your datacenters with the appropriate regional subdomain.
167+
{: .table .table-bordered :}
109168

110-
#### Bid Params for Prebid Server
169+
| Format | recommended values |
170+
| --------------------| --------------------- |
171+
| Banner | `banner_top`,<br>`banner_middle`,<br>`banner_bottom`,<br>`banner_left`,<br>`banner_right`,<br>`banner_sticky_top`,<br>`banner_sticky_bottom` |
172+
| Interstitial | `interstitial_page_load`,<br>`interstitial_exit`,<br>`interstitial_pause` |
173+
| Video | `video_instream`,<br>`video_outstream`,<br>`video_rewarded`,<br>`video_midroll` |
174+
| Native | `native_feed`,<br>`native_article`,<br>`native_recommendation` |
175+
| Special | `sticky_footer`,<br>`sticky_header`,<br>`companion_banner`,<br>`overlay_ad` |
111176

112-
{: .table .table-bordered .table-striped }
177+
#### Video outstream
113178

114-
| Name | Scope | Description | Example | Type |
115-
|-------------------|--------------------|-------------|---------|------|
116-
| `organizationId` | required | Id of the Organization. Handed out by Adagio. | `'1010'` | `string` |
117-
| `placement`* | required | Refers to the placement of an adunit in a page.<br>Must not contain any information about the type of device.<br><i>- max length: 50</i><br><i>- max distinctives values: 10</i> | `'ban_atf'` | `string` |
118-
| `pagetype`* | highly recommended | Describes what kind of content will be present in the page.<br><i>- max length: 30</i><br><i>- max distinctives values: 50</i> | `'article'` | `string` |
119-
| `category`* | recommended | Category of the content displayed in the page.<br><i>- max length: 30</i><br><i>- max distinctives values: 50</i> | `'sport'` | `string` |
179+
The Adagio bidder adapter (Prebid.js only) includes a default video player powered by [Blue Billywig](https://www.bluebillywig.com). This default player is used when no renderer is configured for the adUnit.
120180

121-
<i>*These parameters will have their accentuated characters converted to their non-accentuated version:&nbsp;`é`&nbsp;=>&nbsp;`e`</i>
181+
---

0 commit comments

Comments
 (0)