Guide d'intégration Vungle OpenRTB 2.3

Il s'agit de la version 2.1.0 (août 2017) du Guide d'intégration Vungle OpenRTB 2.3. Cet article spécifie les détails pour l'intégration avec Vungle Exchange en utilisant OpenRTB 2.3.

Contenu

1. Requête et réponse

1.1 Entité

Toutes les entités présentées dans cette partie constituent un sous-ensemble de la spécification OpenRTB 2.3.1 ; s'il manque des champs ou des exigences, veuillez vous référer aux exigences par défaut de la spécification même.

1.2 Extension

Afin de mieux servir une annonce, Vungle Exchange fournit des informations au-delà du protocole OpenRTB standard. Ces extensions ne chevauchent pas, mais plutôt complètent, l'implémentation OpenRTB existante. Les extensions sont sectionnées en objets individuels, car cela a plus de sens.

Tous les champs d'extension sont encapsulés dans un objet JSON par un champ d'extension de premier niveau nommé 'vungle' sous l'objet OpenRTB 'ext'. Pour simplifier, la documentation des parties suivantes de ce document omet le champ 'vungle'. Voici un exemple d'objet JSON OpenRTB contenant des extensions Vungle :

{
...
"ext": {
"vungle": {
// Champs d'extension individuels des différents lignes ci-dessous.
}
}
}

Par exemple, un objet de demande d'enchères de niveau supérieur peut ressembler à ceci :

{
"id": "572c3535ab0af400011a721a",
"imp": [{<impression object>}],
"app": {<application object>},
"device": {<device object>},
"user": {<user object>},
"at": 2,
"tmax": 2000,
"cur": ["USD"],
"bcat": ["IAB7-3"],
"badv": ["google.com"],
"ext": {
"vungle": {
"badvid": ["2f00ca35ab0abe4df11da700c"]
}
}
}

1.3 Gestion des versions

Au fil du temps, certains champs deviennent obsolètes. Afin d'assurer une compatibilité maximale, Vungle Exchange prend en compte tous les champs « obsolètes » spécifiés dans la spécification Vungle OpenRTB la plus récente. Tous ces champs « obsolètes » sont programmés pour être supprimés à la prochaine mise à jour de la spécification, et Vungle Exchange est alors libéré de la responsabilité de maintenir les champs obsolètes.

Tous les champs supprimés figurent dans la spécification avec une étiquette « supprimé », signifiant que le champ n'est plus pris en charge. Nous utilisons l'étiquette « supprimée » pour appliquer une sémantique de spécification : chaque champ, une fois défini, demeure unique dans la portée pour laquelle il a été défini pour la durée de vie de la spécification. Cela signifie que si le champ 'id' devient obsolète et est ensuite supprimé dans une spécification particulière, il ne sera jamais ressuscité dans une révision future avec une signification différente.

1.3.1 Versions de la sémantique

La gestion des versions de la spécification suivra également les directives Semver 2.0.0, à savoir :

  • Une mise à jour importante de la version peut interrompre la compatibilité ascendante ; par exemple, un champ « obsolète » dans la version X est « supprimé » dans la version X + 1.
  • Une mise à jour mineure de la version ne doit pas interrompre la compatibilité ascendante ; les exemples incluent un champ utilisé marqué comme « obsolète », ou un champ obligatoire marqué comme non requis et obsolète.
  • Une mise à jour en version patch ne doit pas interrompre la compatibilité ascendante ; par exemple, la correction d'une erreur de frappe dans la description des spécifications.

1. Requête

2.1 Champs requis et champs facultatifs

Remarques à propos de la colonne Requis dans les sections suivantes :

  • Oui : l'utilisation en aval d'un tel champ doit toujours attendre une valeur bien formatée et non vide basée sur le type spécifié.
  • Non : l'utilisation en aval ne devrait pas s'attendre à l'existence d'un tel champ, ni à la validité de la valeur. La validation du consommateur sur la valeur est nécessaire, mais inutile pour le type.
  • Défaut : tous les champs non mentionnés dans OpenRTB 2.3.1 sont par défaut non requis.

2.2 Négociation du protocole

Vungle Exchange prend en charge la communication à travers HTTP/2 via la négociation de protocole ; sinon, la valeur par défaut est HTTP/1.1.

2.3 En-têtes de requête

Chaque demande d'enchère a les en-têtes HTTP personnalisés suivants, conformément aux spécifications du protocole OpenRTB :

X-OpenRTB-Version: 2.3

En plus des en-têtes HTTP personnalisés, Vungle Exchange associe également les en-têtes standard suivants :

Content-Type: application/json; charset=utf-8
Accept: application/json 

Enfin, Vungle Exchange attache un en-tête personnalisé pour indiquer la révision des spécifications Vungle OpenRTB :

X-Vungle-OpenRTB-Version: 2

2.4 Objet BidRequest

Champ Type Requis Description
id string oui

ID de demande d'enchère généré par Vungle Exchange ; par exemple, '570b0eb14e67c98f761a0ca0'.

imp

object array

oui Voir l'objet Impression.
app object oui Voir l'objet Application.
device object oui Voir l'objet Device.
at integer oui

Type des enchères ; par exemple, '2' pour les enchères au deuxième prix. Vungle Exchange ne gère que les enchères de deuxième prix, et cette valeur est donc toujours '2'.

tmax integer oui

Durée maximale en millisecondes de soumission d'une réponse à une enchère ; elle vaut toujours '250'.

cur string array non

Liste des devises autorisées pour l'enchère au format ISO-4217-alpha ; par exemple ["USD", "CNY", "EUR"]. Actuellement nous acceptons uniquement « USD ».

bcat string array non Consulter la section 5.1 de OpenRTB 2.3.1.
regs object non Consulter la section 3.2.16 de OpenRTB 2.3.1.
test integer non

Indique si l'enchère est en mode test (1) ou en mode live (0) ; les enchères en mode test ne sont pas fiables.

2.4.1 Objet Impression

Champ Type Requis Description
id string oui ID de l'impression généré par Vungle Exchange ; par exemple, '3a06eb14e67c98f761add01'.
displaymanager string oui Gestionnaire d'affichage côté offre ; Vungle utilise ce champ pour spécifier la technologie SDK utilisée, car nous distinguons les plates-formes mobiles SDK ; par exemple, « Vungle » pour iOS, « VungleDroid » pour Android, et « VungleWindows » pour Windows. Ceci est suivi de la version SDK dans le champ suivant.
displaymanagerserver string oui Version du gestionnaire d'affichage côté offre ; Vungle utilise ceci pour spécifier la version du SDK ; par exemple, '3.3.1'.
bidfloor float oui Prix minimal d'enchère pour une enchère éligible ; par exemple '8.72'.
bidfloorcur string oui Devises autorisées pour l'impression au format ISO-4217-alpha ; par exemple 'USD'.
video object non Voir l'objet Video.
tagid string non ID de référence de l'emplacement correspondant à l'impression spécifiée ; par exemple 'placement_name_1af44fda'.
instl integer non Indique si l'impression représente un interstitiel ou plein écran (1) ou pas (0). Actuellement, Vungle Exchange supporte uniquement les interstitiels/plein écran (1).
secure integer non Indicateur signalant si l'impression nécessite des ressources et des balises de création d'URL HTTPS sécurisées, 0 = non sécurisé et 1 = sécurisé.
ext object non Vungle requiert toujours les ressources et balises sécurisées (1).

2.4.2 Objet Video

Champ Type Requis Description
mimes string array oui Types MIME pris en charge pour le contenu. Vungle Exchange supporte uniquement ["video/mp4"].
h integer oui Hauteur de la vidéo.
w integer oui Largeur de la vidéo.
minduration integer non Durée minimale de lecture de la vidéo en seconde.
maxduration integer non Durée maximale de lecture de la vidéo en seconde.
delivery integer array non Liste des modes de diffusion de vidéo pris en charge : (progressif ou continu) Consulter la section 5.13 de OpenRTB 2.3.1.
minbitrate integer non Débit binaire minimal en kb/s. Actuellement, Vungle Exchange accepte uniquement 250.
maxbitrate integer non Débit binaire maximal en kb/s, par exemple 500.
protocols integer array non Consulter la section 5.8 de OpenRTB 2.3.1 pour des exemple [2, 5].
boxingallowed integer non Indique s'il est possible de modifier le mode d'affichage (1) ou pas (0). La valeur est toujours égale à '1'.
playbackmethod integer array non Consulter la section 5.9 de OpenRTB 2.3.1.
startdelay integer non Consulter la section 5.10 de OpenRTB 2.3.1. La valeur est toujours égale à '0'.

2.4.3 Objet Application

Champ Type Requis Description
id string oui ID spécifique à Exchange. Pour Vungle, il s'agit de l'ID de l'application ; par exemple, '3709293'.
Cet ID peut n'avoir aucune signification pour le DSP, mais ce dernier peut l'utiliser pour comparer et concilier les conflits de rapports.
bundle string oui L'ID du marché unique, c'est un identifiant de l'application spécifique à la plate-forme et destiné à être unique à l'application et indépendant de Vungle Exchange.
- Sur Android, il doit s'agir d'un paquet ou d'un nom de package (par exemple, 'com.supercell.hayday').
- Sur iOS, il s'agit d'un ID numérique.
publisher object oui Voir l'objet Publisher.
name string non Nom de l'application, par exemple 'Hay Day'.
storeurl string non URL du magasin de l'application, par exemple 'https://itunes.apple.com/us/app/hay-day/id506627515?mt=8#'.
cat string array non Consulter la section 5.1 de OpenRTB 2.3.1.
privacypolicy integer non Indique si l'application est dotée d'une politique de confidentialité (1) ou pas (0). Vungle Exchange accepte uniquement la valeur '1' pour ce champs.
paid integer non Indique si l'application est payante (1) ou pas (0).
keywords string non Liste de balises de l'application de l'éditeur, séparées par des virgules.
ext object non DESCRIPTION

2.4.4 Extension de Application

Champ Type Requis Description
altid string non Une ID secondaire spécifique à Vungle Exchange identifiant de manière unique l'application de l'éditeur ; par exemple, '3a06eb14e67c98f761add01'.
sdk object non Voir l'objet SDK Extension.
wtags string array non Liste blanche des balises de l'application de l'éditeur.
btags string array non Liste noire des balises de l'application de l'éditeur.
bundleid string non Identifiant du paquet ou nom du package de l'application.
tags string array non Obsolète ; utiliser les mots-clés.

2.4.5 Extension de SDK

Champ Type Requis Description
name string oui Une chaîne identifiant une famille SDK de l'agent SDK installée sur l'application hôte. Par exemple, « VungleDroid », « Vungle » ou « VungleWindows ».
ver string oui Chaîne de caractères décrivant la version de l'agent SDK installé sur l'application hôte.
plugin string non Nom du plugin SDK avec lequel l'agent SDK est construit ; par exemple 'native', 'unity'.
pluginver string non Version du plugin SDK avec lequel l'agent SDK est construit ; par exemple '1.0'.

2.4.6 Objet Publisher

Champ Type Requis Description
id string oui ID de l'éditeur généré par Vungle Exchange, par exemple '570ffeb14e67998f761a791c'.
name string non Noms de l'éditeur ; par exemple 'Supercell Oy'.
cat string array non Consulter la section 5.1 de OpenRTB 2.3.1.

2.4.7 Objet Device

Champ Type Requis Description
ua string oui Chaîne décrivant l'agent utilisateur du navigateur de l'appareil ; par exemple, 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1'.
ip string oui Non requis lorsque le champ ipv6 est présent. Il s'agit de l'adresse IP de l'impression ; par exemple '212.14.27.104'.
ipv6 string oui Non requis lorsque le champ ip est présent. Il s'agit de l'adresse IPv6 de l'impression ; par exemple '3ffe:1900:4545:3:200:f8ff:fe21:67cf'.
h integer oui Hauteur d'écran de l'appareil en pixels.
w integer oui Largeur d'écran de l'appareil en pixels.
connectiontype string oui Consulter la section 5.18 de OpenRTB 2.3.1.
ifa string oui ID autorisé pour l'utilisation des annonceurs, en texte clair ; par exemple 'e4fe9bdecaa047b6908dffba3fa184f2'.
geo object non Voir l'objet Geo.
make string non Marque de l'appareil.
model string non Modèle de l'appareil.
os string non Système d'exploitation de l'appareil ; par exemple 'iOS', 'Android'. Valeur de l'énumération :
- 'iOS'
- 'Android'
- 'Windows'
osv string non Version du système d'exploitation l'appareil ; par exemple '9.1', '8.0'.
dnt integer non Indique si l'appareil spécifie « Do Not Track (Ne pas suivre) » (1) ou pas (0).
lmt integer non Indique si l'appareil spécifie « Limited Ad Tracking (Suivi d'annonce limité) » (1) ou pas (0).
devicetype string non Consulter la section 5.17 de OpenRTB 2.3.1.
language string non Langue de l'appareil au format ISO-639-1-alpha-2 ; par exemple 'en'.
carrier string non Transporteur ou fournisseur de service internet, par exemple 'VERIZON'.
ext object non Voir l'objet Device Extension.

2.4.8 Extension de Device

Champ Type Requis Description
tz string non Paramètres de fuseau horaire de l'appareil formatés en tant que nom de zone dans la base de données de fuseau horaire IANA ; par exemple, 'America/Los_Angeles'.
vungleua string non Obsolète : utiliser Application.ext.vungle.sdk
sdcard integer non Indique si le stockage sur carte SD est disponible pour les appareils Android (1) ou non (0).
volume float non Valeur comprise entre 0 et 1 indiquant le pourcentage de volume de l'appareil.
muted integer non 0 = false 1 = true ; énumération nécessaire.
idfv string non

ID fournisseur sur les appareil iOS. Il s'agit d'une chaîne alphanumérique identifiant de façon unique un appareil au fournisseur de l'application ; par exemple, '00000000-0001-4d3a-8f98-233623cd8d12'.

Le même appareil peut contenir différentes valeurs IDFV selon que l'application impliquée dans la demande d'enchère appartient à un fournisseur différent.

marketplace string non

Le marché de l'application installé sur le périphérique. Les valeurs possibles sont :

  • 'google'
  • 'apple'
  • 'amazon'
is_sideload_enabled integer non Indicateur booléen signalant si l'appareil permet l'installation d'applications à partir de sources « inconnues ». Si '1' (true), les applications provenant de marchés inconnus sont autorisées. Si '0' (false), elles ne le sont pas.

2.4.9 Objet Geo

Champ Type Requis Description
country string oui Code pays au format ISO-3166-1-alpha-3 ; par exemple 'USA'.
lat float non Latitude de l'appareil ; par exemple '[-90, 90]'.
long float non Longitude de l'appareil ; par exemple '[-180, 180]'.
type integer non Consulter la section 5.16 de OpenRTB 2.3.1.
region string non Code de la région au format ISO-3166-2 ; code d'État à deux lettres pour les États-Unis ; par exemple 'CA'.
city string non Nom de la ville au format libre.
zip string non Code postal.
utcoffset integer non Heure locale sous-forme de nombre en plus ou en moins par rapport au Temps universel coordonné.

2.4.10 Objet Regs

Champ Type Requis Description
coppa integer non Indicateur permettant de savoir si la requête est soumise au règlement COPPA établi par la FTC des États-Unis, où 0 = non et 1 = oui.
ext object non Espace réservé pour les extensions à OpenRTB spécifiques à Vungle Exchange.

2.4.11 Objet PMP

Champ Type Requis Description
private_auction integer non Indicateur d'éligibilité des enchères aux sièges mentionnés dans l'objet « Direct Deals », où 0 = toutes les offres sont acceptées, 1 = les enchères sont limitées aux offres spécifiées et à leurs termes.
deal object array non Tableau d'objets « Deal » (Section 3.2.18) transmettant les transactions spécifiques applicables à cette impression.
ext object non Espace réservé pour les extensions à OpenRTB spécifiques à Vungle Exchange.

3. Réponse

3.1 Champs requis et champs facultatifs

Remarques à propos de la colonne Requis de la sections Réponse :

  • Oui : Vungle Exchange suppose qu'un champ requis doit toujours être formaté selon les spécifications, non vide et ayant le type spécifié ; les valeurs non valides peuvent entraîner la non éligibilité aux enchères.
  • Recommandé : Vungle Exchange utilise le champ pour aider au processus d'enchère si la valeur du champ est formatée suivant les spécifications ; un champ manquant ou invalide n'a pas d'impact négatif sur l'éligibilité aux enchères.
  • Non : Vungle Exchange n'exige pas que les champs existent.
  • Défaut : tous les champs non mentionnés dans OpenRTB 2.3.1 ont cette valeur par défaut à 'No'. En outre, tous les champs doivent correspondre au type spécifié, sans quoi ils peuvent affecter négativement l'éligibilité aux enchères.

3.2 En-têtes de réponse

Les en-têtes de réponse doivent contenir l'en-tête « Content-Type » avec l'une des valeurs acceptées des en-têtes de requête ci-dessus. Par exemple,

Content-Type: application/json 

3.3 Code d'état de la réponse

Toutes les réponses doivent avoir le code 200 ou 204. Tout autre code de réponse HTTP peut affecter négativement l'éligibilité du DSP aux enchères.

3.4 Indication de la raison de l'absence de soumission

Les DSP sont invités à faire savoir les raisons de la non soumission, lorsqu'ils décident de ne pas soumissionner. Cette information peut aider Vungle Exchange à détecter et à résoudre les potentiels problèmes d'intégration. L'indication de la non soumission doit être conforme à la spécification de la section 7.4 de l'OpenRTB 2.3.1. Une indication de non soumission bien formulée avec la raison de non-soumission devrait ressembler à ceci :


{"id": "1234567890", "seatbid": [], "nbr": 2}

3.5 Objet BidResponse

Champ Type Requis Description
id string oui ID de demande d'enchère généré par Vungle Exchange ; par exemple, '570ffeb14e67998f761a791c'. Sa valeur doit être identique à celle de l'ID dans l'objet BidRequest.
bidid string non Un ID de réponse unique généré par le système d'enchères afin d'aider à la journalisation et au suivi.
cur string non Devise de l'enchère utilisant les codes alpha ISO-4217. Actuellement, Vungle Exchange supporte uniquement la devise USD et traite toute valeur comme USD.
seatbid object array oui Tableau d'objets seatbid ; au moins 1 requis si l'enchère doit être définie.
nbr integer non Une raison de non soumission, selon le contenu de la section 5.19 de la spécification OpenRTB 2.3.1.
ext object non  

3.5.1 Objet SeatBid

Champ Type Requis Description
seat string non ID de la participation de l'enchérisseur au nom de qui l'enchère est définie. Consulter les spécifications OpenRTB 2.3.1.
bid object array oui Voir l'objet Bid. Il doit y avoir au moins une enchère.


3.5.2 Objet Bid

Champ Type Requis Description
id string oui ID de l'enchère généré par chaque DSP.
impid string oui ID de l'impression relative à l'impression de la demande d'enchère qui est l'objet de la soumission. Doit être identique à l'ID de l'objet Impression dans la demande d'enchère.
price float oui Prix de l'enchère en unité de CPM ; par exemple '10.30'.
nurl string non URL de notification de gain invoquée par Vungle Exchange en cas d'enchère gagnante.
adm string oui Balises de l'annonce à diffuser en cas d'enchère gagnante. Voir la section Spécifications relatives au balisage de l'annonce.
cid string recommandé ID de campagne procuré par le DSP.
crid string recommandé ID de création procuré par le DSP.
adomain string array recommandé Domaines de l'annonceur pour le contrôle des liste de blocage ; par exemple ["supercell.com"].
bundle string recommandé L'ID du marché unique, c'est un identifiant de l'application spécifique à la plate-forme et destiné à être unique à l'application et indépendant de Vungle Exchange.
- Sur Android, il doit s'agir d'un paquet ou d'un nom de package (par exemple, 'com.supercell.hayday').
- Sur iOS, il s'agit d'un ID numérique.
h integer recommandé Hauteur de la création.
w integer recommandé Largeur de la création.
cat string array non Catégories de contenus de l'IAB ; consulter la section 5.1 de OpenRTB 2.3.1.
iurl string non URL de notification de perte.
dealid string non Référence à l'id de l'offre depuis l'objet BidRequest si cette enchère concerne un accord direct sur le marché privé.
adid string non ID d'une annonce préchargée pour diffusion en cas d'enchère gagnante.
ext object non  

4. Exemples

4.1 Exemple de demande


{
    "id": "58ed309efa8936087efd1349",
    "imp": [{
        "id": "58ed309efa8936087efd134a",
        "video": {
            "mimes": ["video/mp4"],
            "minduration": 5,
            "maxduration": 30,
            "protocols": [2, 5],
            "w": 1080,
            "h": 1920,
            "startdelay": 0,
            "linearity": 1,
            "minbitrate": 250,
            "maxbitrate": 2500,
            "boxingallowed": 1,
            "playbackmethod": [1, 2, 3, 4],
            "delivery": [1, 2],
            "pos": 7
        },
        "displaymanager": "Vungle",
        "displaymanagerver": "3.3.5",
        "instl": 1,
        "bidfloor": 15,
        "bidfloorcur": "USD"
    }],
    "app": {
        "id": "56b8e577819502560b000033",
        "name": "test-pub-app-name",
        "bundle": "1045826890",
        "storeurl": "https://itunes.apple.com/us/app/id1234567?mt=8",
        "cat": [
            "IAB1"
        ],
        "privacypolicy": 1,
        "publisher": {
            "id": "test-pub-app-id",
            "name": "test-pub-app-name",
            "cat": [
                "IAB1"
            ]
        },
        "ext": {
            "vungle": {
                "altid": "5fff577819502560b000033",
                "btags": ["real money gambling", "social casino"],
                "wtags": ["targeted tag", "social"]
            }
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_4 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12H141",
        "geo": {
            "lat": 47.46,
            "lon": -122.16,
            "type": 1,
            "country": "USA",
            "region": "WA",
            "city": "San Francisco",
            "zip": "94103"
        },
        "dnt": 0,
        "lmt": 0,
        "ip": "192.168.1.1",
        "devicetype": 1,
        "make": "Samsung",
        "model": "SM-J200G",
        "connectiontype": 2,
        "os": "iOS",
        "osv": "8.0",
        "w": 1080,
        "h": 1920,
        "js": 1,
        "language": "en",
        "ifa": "test-ifa",
        "ext": {
            "vungle": {
                "isSdCardAvailable": 1,
                "vungleua": "VungleDroid/3.3.5",
                "tz": "Europe/Kaliningrad",
                "sdcard": 1,
                "volume": 0.13333334,
                "muted": 1
            }
        }
    },
    "bcat": ["IAB7-3", "IAB7-5", "IAB7-28", "IAB7-29", "IAB7-30", "IAB7-39", "IAB7-41", "IAB7-42"],
    "at": 2,
    "cur": ["USD"],
    "tmax": 250
}

4.2 Exemple de réponse


{
  "id": "58ed309efa8936087efd1349",
  "bidid": "5508",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "7735",
      "bid": [
        {
          "id": "5508",
          "impid": "58ed309efa8936087efd134a",
          "price": 50,
          "nurl": "http://bidder.com/won?price=${AUCTION_PRICE}",
          "adm": "http://bidder.com/vast?id=${AUCTION_ID}",
          "cid": "554d550b418461cc3700014d",
          "crid": "57767c29a63510e75f000073"
        }
      ]
    }
  ]
}

5. Spécifications relatives au balisage de l'annonce

Vungle Exchange prend principalement en charge trois types de balisages : VAST, MRAID et le balisage d'annonces propres à Vungle. Bien que chacun d'eux ait ses propres spécifications de haut niveau, tous doivent également se conformer aux exigences supplémentaires ci-dessous pour être considérés comme des balisages valides en termes de performance.

5.1 VAST

La balise suivante doit apparaître dans les 100 premiers octets du champ 'adm' ou dans la charge de la réponse 'nurl' :

<VAST version="2.0">

5.2 Substitution de macro

Vungle Exchange prend en charge une substitution de macro pour le prix d'enchère au niveau du champ nurl de l'objet Bid dans la réponse à l'enchère. Par exemple :


"nurl": "http://bidder.com/won?price=${AUCTION_PRICE}"
Vous avez d’autres questions ? Envoyer une demande

Commentaires