[FR] Guide d'installation Prebid.js pour éditeurs

La présente documentation vise à fournir les instructions d’installation des modules Prebid.js Adagio en vue d’utiliser le SSP Adagio.

 

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.

Ads.txt

Les lignes devant être ajoutées au fichier ads.txt vous seront fournies par un agent Adagio.

Mesures d’attention et événements ad server

La mesure d’attention de chaque emplacement publicitaire sur une page doit être collectée tout au long de la visite de l’utilisateur. Pour être en phase avec les rapports fournies par l’ad server utilisé, nous écoutons les événements émis par ces derniers. Nous supportons actuellement :

  • Google Ad Manager (via Google Publisher Tag)

  • Smart AdServer

Ad servers non supportés

Dans le cas de l’utilisation d’un ad-server non supporté par Adagio, Il revient à l'éditeur de dispatcher les événements à écouter en retour.

Contactez le support technique Adagio, support@adagio.io, afin de mettre en place la solution appropriée.

Basiquement, nous devons connaitre à quel moment l’ad unit est considérée comme affichée.

L'événement émis doit exposer à minima les paramètres suivants :

1 2 3 4 5 6 { isEmpty: Boolean elementId: String creativeId: String creativeSize: String|Array }

Nom

Description

Exemple

Type

Nom

Description

Exemple

Type

isEmpty

Le placement est rempli avec une creative ou pas.

 

boolean

elementId

La valeur de l'attribut id de l'élément HTML dans lequel la creative est ajoutée. Devrait correspondre au paramètre adUnitElementId du bidder adapter Adagio.

 

string

creativeId

L’id de la creative de l’ad-server.

 

string

creativeSize

Taille de la creative affichée en respectant le format largeur x hauteur

300x25
[300,250]

string | array

Prebid.js Adagio adapters

L’intégration d’Adagio repose sur l’ajout de 2 modules Prebid.js :

  • analytics adapter

  • bidder adapter

Analytics adapter

Le module adagioAnalyticsAdapter s’active comme n’importe quel autres modules analytics Prebid.js :

1 2 3 pbjs.enableAnalytics([{  provider: 'adagio' }]);

Bid adapter

Le bidder adapter Adagio demande plusieurs paramètres.

Ces paramètres permettent d'avoir des analytics granulaires, ainsi que des prédictions efficaces. Sans eux, les prédictions seront moins précises et les analytics ne pourront pas être filtrées/triées sur ces paramètres.

Nous vous recommandons d’y apporter une attention toute particulière et la team Adagio est à votre disposition pour vous accompagner si besoin.

Nom

Scope

Description

Exemple

Type

Nom

Scope

Description

Exemple

Type

organizationId

required

Id unique du compte client. Fourni par Adagio.

'1010'

string

site

required

Nom du site sur lequel la publicité sera affichée. Fourni par Adagio.
- longueur max. : 50

'mysite-com'

string

adUnitElementId

required

L’ID de l'élément HTML de l’ad-unit dans le DOM.

'gpt-ban-atf'

string

useAdUnitCodeAsAdUnitElementId

optional

disponible à partir de Prebid.js@4.19 - force l’utilisation de la valeur de l’adUnit code pour définir la valeur du param adUnitElementId

true

boolean

environment

required

Environnement (device) dans lequel la page est affichée.
- longueur max. : 30
- valeurs distinctes max. : 10

'desktop'

string

placement

required

Fait référence au positionnement de l’ad-unit dans la page. Ne doit pas faire référence à un type de device.
- longueur max. : 30
- valeurs distinctes max. : 10

'ban_atf'

string

useAdUnitCodeAsPlacement

optional

disponible à partir de Prebid.js@4.19 - force l’utilisation de la valeur de l'adUnit code comme valeur du placement.

true

boolean

pagetype

recommended

Décrit le template de la page (home, article, …).
- longueur max. : 30
- valeurs distinctes max. : 50

'article'

string

category

recommended

Catégorie du contenu de la page (sport, business, …).
- longueur max. : 30
- valeurs distinctes max. : 50

'sport'

string

subcategory

optional

Sous-catégorie du contenu de la page (football, handball, …).
- longueur max. : 30
- valeurs distinctes max. : 50

'handball'

string

postBid

optional

A utiliser dans un contexte Post-Bid uniquement.

true

boolean

video

optional

Options video de la spec OpenRTB 2.5.
Toutes les options remplaceront celles définies dans mediaTypes.video

{
skip: 1,
protocols: [7,8]
}

object

Informations supplémentaires sur les params

Ces paramètres seront traités et modifiés si besoin par notre SSP :

  • les caractères dépassant la longueur max. autorisée seront supprimés

  • les caractères seront convertis en lower case,

  • les caractères accentués seront convertis en leur version non-accentuée : é => e

placement et environment devraient être génériques et partagés pour l’ensemble des sites que vous gérez.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 // INCORRECT: // site 01 { "placement": "my-site-01-banner-top", "environment": "ipad" } // site 02 { "placement": "my-site-02-banner-900x80", "environment": "tablet" } -- // CORRECT: // site 01, site 02 { "placement": "banner-top", "environment": "tablet" }

placement représente la position d’un slot dans la page et doit être unique.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 // INCORRECT: { "adUnitElementId": 'div-01', "placement": "banner", }, { "adUnitElementId": 'div-02', "placement": "banner", } // CORRECT: { "adUnitElementId": 'div-01', "placement": "banner-top", }, { "adUnitElementId": 'div-02', "placement": "banner-bottom", }

Pour category et subcategory, nous ne disposons pas d’une liste pré-définie de valeurs, les valeurs possibles sont relatives à chaque site.
Ces params peuvent généralement être renseignés avec les valeurs déjà existantes dans une variable globale type datalayer.

Sur un site de news, la valeur du param category pourrait être : "monde", "sport", "politique", etc

Le param subcategory peut être plus complexe à identifier proprement et sert à qualifier la category.
Ex.: pour la catégorie "sport", une valeur appropriée pourrait être "football", "tennis", etc.
Dans le doute, ou si la granularité est trop élevée, nous préférons laisser vide ce param.

Video outstream, utilisation du player Adagio (disponible à partir de Prebid.js - 4.19)

Dans le cadre de publicité video outstream, si un renderer a déjà été configuré (par exemple le render ANOutstreamVideo.js), il faut obligatoirement ajouter le paramètre backupOnly:true afin que le player Adagio soit utilisé quand Adagio remporte une enchère.

Le player Adagio implémente différents algorithmes pour maximiser la complétion en open auction et garantir la visibilité et l’attention pour les deals.
Sans ce paramètre configuré (et donc sans le player Adagio), Adagio pourra diffuser des videos en open auction mais avec un taux de complétion diminué et ne sera pas en mesure de diffuser des deals. Les revenus outstream en seront donc fortement impactés. De plus, les analytics video permises par le player Adagio ne seront pas disponibles dans le manager.

Native, utilisation du renderer Adagio (disponible à partir de Prebid.js - 4.39)

Dans la configuration du bidder, vous pouvez ajouter des options spécifiques pour le native sous la clé bids[].params.native. Ces options sont des paramètres notés comme “recommended” par la spec OpenRTB Native 1.2. S’ils ne sont pas présents, notre SSP enverra la demande sans ces paramètres.

Egalement dans l’ad-manager, il faudra spécifier d’utiliser notre renderer. Cela se passe dans le template Native.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 <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>

Exemple de configuration du bidder adapter Adagio

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 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 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 }, } ] }];

Clés de targeting

Si besoin, vous pouvez configurer les clés de targeting Adagio pour l'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; } } ] } }

Intégration en Post-Bid

L’utilisation du bidder adapteur Adagio dans le cadre d’une intégration Prebid.js en Post-Bid est possible sous certaines conditions :

  • l’emplacement doit être chargé dans une friendly iframe : notre script doit avoir accès à window.top

  • le paramètre postBid du bidder Adagio doit avoir la valeur true.

  • les événements ad-server doivent être attachés sur la window de l’iframe dans laquelle ils sont émis. (voir Mesures d’attention et événements ad-server)