The purpose of this document is to provide you all the instructions necessary for installing the Adagio Prebid.js modules on your website.

1 Ads.txt
2 Attention measurement and ad server events
- 2.1 Ad servers who are not officially supported
  - 2.1.1 Example with basic javascript CustomEvent api
  - 2.1.2 Definitions
3 Prebid.js Adagio adapters
4 Post-Bid integration

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 the`adUnitElementId` 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.

Native, use of renderer Adagio (available since Prebid.js - 4.39)

In the bidder configuration, you can add specific options for the native under the bids []. Params.native key. These options are parameters noted as “recommended” by the OpenRTB Native 1.2 spec. If they are not present, our SSP will send the request without these parameters.

Also in the ad-manager, it will be necessary to specify to use our renderer. This happens in the Native template.

<script>
  var isAdagioBidder = function isAdagioBidder() {
    var bidder = "%%PATTERN:hb_bidder%%";
    return bidder === 'adagio';
  }
  var rendererUrl = (isAdagioBidder())
    ? "https://script.4dex.io/renderers/native/native-render.js"
    : "https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/native-render.js";
  
  document.write('<sc'+'ript type="text/javascript" src="' + rendererUrl + '"></scr'+'ipt>');
</script>

<script>
    var pbNativeTagData = {};
    pbNativeTagData.pubUrl = "%%PATTERN:url%%";
    pbNativeTagData.adId = "%%PATTERN:hb_adid%%";
    // if you're using 'Send All Bids' mode, you should use %%PATTERN:hb_adid_BIDDER%%
    pbNativeTagData.requestAllAssets = true;
    pbNativeTagData.bvw = "%%PATTERN:hb_adagio_bvw%%";
    window.pbNativeTag.renderNativeAd(pbNativeTagData);
</script>

Adagio Bid adapter configuration example

var adUnits = [{
    code: 'div-gpt-ad-1542984663788-0',
    mediaTypes: {
        banner: {
            sizes: [[300, 250]]
        },
        native: {
// Context Type ID | Description
// 1 | Content-centric context such as newsfeed, article, image gallery, video gallery, or similar.
// 2 | Social-centric context such as social network feed, email, chat, or similar.
// 3 | Product context such as product listings, details, recommendations, reviews, or similar.
//
context: 1,

// Placement Type ID | Description
// 1 | In the feed of content - for example as an item inside the organic feed/grid/listing/carousel.
// 2 | In the atomic unit of the content - IE in the article page or single image page
// 3 | Outside the core content - for example in the ads section on the right rail, as a banner-style placement near the content, etc.
// 4 | Recommendation widget, most commonly presented below the article content.
//
plcmttype: 2
},

        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