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

// 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

(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

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.

// 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.

// 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

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:

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)

[EN] Adagio Prebid.js installation guide for publishers