[EN] Adagio Prebid.js installation guide for publishers
The purpose of this document is to provide you all the instructions necessary for installing the Adagio Prebid.js modules on your website.
The adagioBidAdapter module in Prebid.js versions 3.14.0, 3.15.0 3.16.0 is showing bugs.
Please do not use these versions.
The adagioBidAdapter module must have access to the top window level.
Ads.txt
At integration kickoff Adagio will provide the ads.txt lines that you will need to add.
Attention measurement and ad server events
The attention measurement of each placement has to be collected during the entire user’s visit.
In order to be synced with the reports provided by your ad server, we listen to the events it produces and start our measurer on the one best fit the moment an ad is rendered on the page.
Officially supported ad servers | Event name used to start measurer |
Google Ad Manager (via Google Publisher Tag) | slotRenderEnded |
Smart AdServer | load |
Appnexus (via Xandr) | adLoaded |
Ad servers who are not officially supported
The following information explains the generic process to interface a proprietary ad server with Adagio.
You’ll still need to get in touch with your Adagio Support contact support@adagio.io in order to validate the setup.
For ad servers who are not officially supported, it is up to the proprietary ad server owner (or the publisher) to provide the signal to start a measurer for a placement when the creative is rendered.
Adagio requires the following information:
a flag which determinates if the ad-server response is empty (no creative to render)
the id attribute of the HTML element in which the creative is rendered. This should match the parameter adUnitElementId in Adagio’s bidder configuration.
the id of the ad server creative
the size of the creative served
To start a measurer, call the Prebid.js adagioBidAdapter function: window.top.ADAGIO.queue.push(queueOptions) (see definitions below).
Example with basic javascript CustomEvent api
First dispatch the right event in your own code source
1
2
3
4
5
6
7
8
9
10
11
// proprietary ad server js script
…
document.dispatchEvent(new CustomEvent('myRenderEvent', {
detail: {
isEmpty: false,
elementId: 'adunit-id-xxx',
creativeId: 'crea-1111',
creativeSize: [300,250]
}
}));
…
Then register a listener to this event and call the window.top.ADAGIO.queue.push() function to pass data to Adagio
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
(function() {
try {
// Actually Adagio must have access to top level window.
if (window.top.location.href) {
window.top.ADAGIO = window.top.ADAGIO || {};
window.top.ADAGIO.queue = window.top.ADAGIO.queue || [];
window.document.addEventListener('myRenderEvent', function(evt) {
window.top.ADAGIO.queue.push({
action: 'adagio-my-adserver-events', // Adagio whitelisted action
data: {
eventName: 'renderEvent',
args: evt.detail
},
ts: Date.now()
});
});
}
} catch (error) {
return false;
}
})();
Definitions
ADAGIO.queue.push
Type: (options: queueOptions) => void
queueOptions
The AdagioQueue accepts only a few whitelisted actions. The queueOptions object provides the params that are related.
queueOptions.action
Type: string
The Adagio action name to trigger. This name has to be whitelisted by Adagio.
queueOptions.data
Type: object
A generic object to pass any data. Each action has a specific data object which fits the needs of the action.
queueOptions.ts
Type: number
The timestamp on which the push() function is called. It should always be Date.now().
Custom Event detail
The custom event dispatched by the ad server owner (or publisher) must implement the following properties.
detail.isEmpty
Type: boolean
The ad server sent an empty response (no creative to render)
detail.elementId
Type: string
The id attribute of the HTML element in which the creative is rendered. This id should match the parameter adUnitElementId in Adagio’s bidder configuration.
detail.creativeId
Type: string
The id of the ad server creative
detail.creativeSize
Type: string|array
The size of the served creative. Must match the format width x height or [width, height] where both width and height are numbers.
E.g. 300x250, [300,250]
Prebid.js Adagio adapters
The Adagio integration is based on 2 Prebid.js modules:
bidder adapter
analytics adapter
1
gulp build --modules=adagioBidAdapter,adagioAnalyticsAdapter,…
Bid adapter (mandatory)
The Adagio bid adapter requires a configuration of multiple parameters.
These parameters enable a fine granularity in our analytics and efficiency of our predictions. Without them, our predictions will be less accurate, and you will not be able to filter/triage our analytics data around those parameters.
We highly recommend that you carefully set up the parameters the best you can. The Adagio team is there to help if you need any advice or assistance.
Nom | Scope | Description | Exemple | Type |
---|---|---|---|---|
organizationId | required | Unique identifier of the account. Provided by Adagio. | '1010' | string |
site | required | Name of the website that will display the ad. Provided by adagio | 'mysite-com' | string |
adUnitElementId | required | Id of the adUnit’s HTML element in the DOM. | 'gpt-ban-atf' | string |
useAdUnitCodeAsAdUnitElementId | optional | available since Prebid.js@4.19 - force the value of the adUnit code to set the value of theadUnitElementId param | true | boolean |
environment | required | Environment(device) on which the page is displayed | 'desktop' | string |
placement | required | Refers to the position of the adUnit in the page. | 'ban_atf' | string |
useAdUnitCodeAsPlacement | optional | available since Prebid.js@4.19 - orce the value of the adUnit code to set the value of placement | true | boolean |
pagetype | recommended | Describes the type of content present on the page (ex: article, home, hub, etc..) | 'article' | string |
category | recommended | Category of the content present on the page | 'sport' | string |
subcategory | optional | Subcategory of content present on the page. - max length : 30 | 'handball' | string |
postBid | optional | Use only in a PostBid context. | true | boolean |
video | optional | OpenRTB 2.5 video options object. | {skip: 1, playbackmethod: [6]} | object |
Additional information about params
These parameters will be parsed and treated as such by our SSP:
Characters above the max length will be trimmed
Characters will be converted to lower case
Accents will be removed(é => e)
placement and environment should be generic and shared across each site you handle.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// BAD:
// site 01
{
"placement": "my-site-01-banner-top",
"environment": "ipad"
}
// site 02
{
"placement": "my-site-02-banner-900x80",
"environment": "tablet"
}
--
// GOOD:
// site 01, site 02
{
"placement": "banner-top",
"environment": "tablet"
}
placement represents a slot position on the page and must be unique.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// BAD:
{
"adUnitElementId": 'div-01',
"placement": "banner",
},
{
"adUnitElementId": 'div-02',
"placement": "banner",
}
// GOOD:
{
"adUnitElementId": 'div-01',
"placement": "banner-top",
},
{
"adUnitElementId": 'div-02',
"placement": "banner-bottom",
}
category and subcategory, we do not have a predefined list of values, it is related to each site.
These params are often set with values found in a data layer global variable.
On a typically news website, the category value could be : "world", "sport", "politics", etc
The subcategory param could be tricky to find and is used to qualify the category, ex.: for a "sport" category, it could be "football", "tennis", etc.
In case of doubt, or if the granularity is too high, we prefer you to leave this param empty.
Video outstream, use of the Adagio player (available since Prebid.js - 4.19)
In the context of outstream video advertising, if a renderer has already been configured (for example the ANOutstreamVideo.js render), you must add the backupOnly: true parameter so that the Adagio player is used when Adagio wins a bid.
The Adagio player implements different algorithms to maximize completion in open auction, and guarantee visibility and attention to deals.
Without this well configured parameter (and therefore without the Adagio player), Adagio will be able to deliver videos in open auction but with a reduced completion rate and will not be able to deliver deals. Outstream revenues will therefore be strongly impacted. In addition, the video analytics allowed by the Adagio player will not be available in the manager.
Adagio Bid adapter configuration example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
var adUnits = [{
code: 'div-gpt-ad-1542984663788-0',
mediaTypes: {
banner: {
sizes: [[300, 250]]
},
video: {
context: 'outstream',
playerSize: [[400, 300]],
// Other OpenRTB 2.5 video options…
renderer: {
backupOnly: true, // Use the bidder's renderer first. Use this render as backup.
url: 'https://acdn.adnxs.com/video/outstream/ANOutstreamVideo.js',
render: function (bid) {
bid.renderer.push(() => {
ANOutstreamVideo.renderAd({
targetId: bid.adUnitCode,
adResponse: {
content: bid.ad,
}
});
})
}
}
}
},
bids: [
{
bidder: 'adagio',
params: {
organizationId: '1002',
site: 'ADAGIO',
placement: 'pave_top',
adUnitElementId: 'div-gpt-ad-1542984663788-0',
pagetype: 'topic',
environment: 'desktop',
postBid: true|false // optional, use it in postBid context only
video: {
// Other OpenRTB 2.5 video options
// If needed you can use the params below instead `placement` and `AdUnitElementId`.
// Available since Prebid.js@4.19
useAdUnitCodeAsPlacement: true|false // optional
useAdUnitCodeAsAdUnitElementId: true|false // optional
},
},
}
]
}];
];
Targeting keys
You can configure the adagio targeting keys for your ad server:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
pbjs.bidderSettings = {
adagio: {
alwaysUseBid: true,
adserverTargeting: [{
key: "site",
val: function(bidResponse) {
return bidResponse.site;
}
},
{
key: "environment",
val: function(bidResponse) {
return bidResponse.environment;
}
},
{
key: "placement",
val: function(bidResponse) {
return bidResponse.placement;
}
},
{
key: "pagetype",
val: function(bidResponse) {
return bidResponse.pagetype;
}
},
{
key: "category",
val: function(bidResponse) {
return bidResponse.category;
}
},
{
key: "subcategory",
val: function(bidResponse) {
return bidResponse.subcategory;
}
}
]
}
}
Analytics adapter (optional)
The adagioAnalyticsAdapter module is activated like any Prebid.js analytics module.
1
2
3
pbjs.enableAnalytics([{
provider: 'adagio'
}]);
Post-Bid integration
You can use the Adagio bid adapter in a Prebid.js integration in Post-Bid, with a few requirements:
The placement has to be loaded inside a friendly iframe: our script needs to have access to window.top
The postBid parameter in Adagio’s bidder configuration needs to be true
The adserver events need to be attached to the iframe window from which there are generated (please refer to above section Attention measurements and adserver events)