[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

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
- max length : 50

'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
- max length : 30
- max distinct values : 10

'desktop'

string

placement

required

Refers to the position of the adUnit in the page.
Must not refer to a type of device.
- max length : 30
- max distinct values : 10

'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..)
- max length : 30
- max distinct values : 50

'article'

string

category

recommended

Category of the content present on the page
- max length : 30
- max distinct values : 50

'sport'

string

subcategory

optional

Subcategory of content present on the page.

- max length : 30
- max distinct values : 50

'handball'

string

postBid

optional

Use only in a PostBid context.

true

boolean

video

optional

OpenRTB 2.5 video options object.
All options will override ones defined in mediaTypes.video

{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)