Une fois que votre application a traité la demande d'enchère de Google, elle doit créer et envoyer une réponse. Ce guide explique comment coder votre application pour créer la réponse.
Créer un message BidResponse
Authorized Buyers envoie l'BidRequest
en tant que corps de message d'une requête HTTP POST
. L'en-tête Content-Type
de la réponse envoyée par votre application doit être défini sur application/octet-stream
et le corps du message doit être constitué d'un tampon de protocole sérialisé. Le tampon de protocole est un message BidResponse
tel que défini dans realtime-bidding.proto
. Votre application doit renvoyer un objet BidResponse
analysable en réponse à chaque BidRequest
. Les délais d'inactivité et les réponses qui ne peuvent pas être analysés sont considérés comme des erreurs, et Google ralentit les enchérisseurs dont le taux d'erreur est élevé.
Si vous ne souhaitez pas enchérir sur une impression, vous pouvez définir uniquement le champ processing_time_ms
et laisser tous les autres champs vides. Vous pouvez obtenir realtime-bidding.proto
à partir de la page des données de référence.
ID de la création
BidResponse
spécifie une création via le champ buyer_creative_id
(64 octets maximum). Même les créations similaires doivent avoir des valeurs uniques pour buyer_creative_id
si elles diffèrent par des caractéristiques notables, y compris, mais sans s'y limiter, la taille, l'URL déclarée, les attributs de la création et les types de fournisseurs. En d'autres termes, vous devez attribuer des ID de création différents à deux annonces:
- Aspect ou comportement différents.
- Effectuez le rendu sur différentes images.
- Afficher par des moyens différents (par exemple, l'une se compose d'une image, l'autre d'une annonce Flash).
Lorsque vous concevez votre application, vous devez choisir une manière systématique de générer des identifiants adaptés aux types de créations que vous prévoyez d'envoyer.
Attributs d'annonce
Vous devez déclarer dans BidResponse.Ad.attribute
les attributs de la création qui décrivent de manière exhaustive les caractéristiques et le ciblage de l'annonce. Voici les attributs qui doivent être déclarés (voir la liste complète des attributs acceptés sur le fichier buyer-declarable-creative-attributes.txt):
7 Tagging: IsTagged
L'annonce contient un pixel ou une balise Web servant à créer une liste d'ID de cookie en vue de remarketing ultérieur.8 Remarketing: IsRemarketing
L'annonce cible les consommateurs en fonction de leur ID de cookie ou d'ID d'appareil, la liste de ces ID représentant un ensemble de consommateurs ayant déjà interagi avec un site appartenant à l'acheteur ou représenté par celui-ci.9 UserInterestTargeting: IsUserInterestTargeted
L'annonce cible les consommateurs en fonction de leur ID de cookie ou d'ID d'appareil, la liste de ces ID représentant un ensemble de consommateurs définis par l'acheteur comme appartenant à une même catégorie de centres d'intérêt.30 InstreamVastVideoType: Vpaid
L'annonce doit être compatible avec VPAID pour pouvoir s'afficher.32 MraidType: MRAID
L'annonce nécessite l'API MRAID pour s'afficher.
En outre, les attributs suivants sont acceptés, mais leur déclaration n'est pas obligatoire, car Authorized Buyers les détecte automatiquement et bloque (ou autorise) vos créations en fonction des valeurs détectées plutôt que selon votre déclaration. Consultez l'API Créations pour découvrir comment obtenir des commentaires concernant les propriétés détectées dans vos créations.
34 RichMediaCapabilityType: RichMediaCapabilityFlash
L'annonce nécessite la compatibilité avec Flash pour s'afficher.50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
L'annonce ne nécessite pas de format Flash pour s'afficher.47 RichMediaCapabilityType: RichMediaCapabilitySSL
L'annonce peut s'afficher sur une page SSL. Notez qu'Authorized Buyers traite les créations ayant différentes valeurs déclarées pour cet attribut de manière distincte (elles seront examinées séparément et ont un état d'approbation distinct). Par conséquent, si vous enchérissez avec des versions SSL et non SSL d'une même création, vous devez déclarer cet attribut en conséquence afin que cette distinction soit correctement reflétée dans AdX.
Champs Open Bidding
Les réponses aux enchères envoyées par les enchérisseurs de place de marché et sur le réseau participant à Open Bidding sont semblables à celles des enchérisseurs Authorized Buyers participant aux enchères en temps réel standards. Les clients Open Bidding peuvent spécifier un petit nombre de champs supplémentaires, et quelques champs existants peuvent avoir des utilisations alternatives. Voici quelques exemples:
OpenRTB | Authorized Buyers | Détails |
---|---|---|
BidResponse.imp[].pmp.deals[].id |
BidResponse.ad[].adslot[].exchange_deal_id |
ID d'accord de l'espace de noms de la place de marché associé à cette enchère et transmis aux éditeurs. |
BidResponse.seatbid[].bid[].ext.exchange_deal_type |
BidResponse.ad[].adslot[].exchange_deal_type |
Type d'accord signalé aux éditeurs, qui a une incidence sur la façon dont il est traité lors des enchères. |
BidResponse.seatbid[].bid[].ext.third_party_buyer_token |
BidResponse.ad[].adslot[].third_party_buyer_token |
Jeton utilisé pour identifier les informations des acheteurs tiers finaux si la place de marché en tant qu'enchérisseur Open Bidding est un intermédiaire. Ces informations sont obtenues auprès de l'acheteur tiers et doivent être transmises à Google en l'état dans la réponse à l'enchère. |
Recommandations
- Activez les connexions HTTPS persistantes (également appelées "keep-alive" ou "réutilisation de la connexion") sur vos serveurs. Définissez le délai avant expiration sur 10 secondes au minimum. Des valeurs plus élevées sont utiles dans de nombreux cas. Google vérifie cette information lors des premiers tests de latence de votre application, car Authorized Buyers envoie des requêtes à un taux élevé et doit éviter la latence liée à l'établissement d'une connexion TCP distincte pour chaque requête.
Incluez l'URL de suivi des impressions facultative pour suivre le moment où l'impression s'affiche plutôt que lorsque l'enchérisseur gagne. En raison de l'écart entre les victoires et les rendus, cela permet d'obtenir des statistiques de suivi plus précises.
- Veillez à ce que le code de votre enchérisseur ne dépende pas de champs obsolètes, car cela pourrait entraîner l'échec de vos enchères et générer des erreurs.
- Incluez
BidResponse.Ad.width
etBidResponse.Ad.height
dans votreBidResponse
. L'élémentBidResponse
d'une demande incluant plusieurs tailles d'annonces doit inclure les valeurswidth
etheight
, sans quoi il sera retiré de l'enchère. - Limitez la taille de votre réponse à moins de 8 Ko. Les réponses très volumineuses peuvent augmenter la latence du réseau et entraîner des délais avant expiration.
- Suivez les consignes relatives aux enchères sur l'inventaire iOS nécessitant une attribution SKAdNetwork.
Exemple de réponse à l'enchère
Les exemples suivants représentent des exemples lisibles par l'humain des requêtes Protobuf et JSON.
JSON OpenRTB
Protobuf OpenRTB
Important:Les messages Protobuf présentés dans les exemples sont représentés ici sous forme de texte lisible. Cependant, ce n'est pas ainsi que les messages sont envoyés sur le réseau. Lorsque vous utilisez le format de protocole Google ou OpenRTB, seuls les messages BidResponse sérialisés sont acceptés.
Vous pouvez créer et sérialiser un message BidResponse
à l'aide du code C++ suivant:
BidResponse bid_response; // fill in bid response with bid information string post_response; if (bid_response.SerializeToString(&post_response)) { // respond to the POST with post_response as the content } else { // return an error to the POST }
Spécifier une création
Votre réponse à l'enchère spécifie la création à diffuser si votre enchère l'emporte. Votre enchère doit inclure l'un des formats d'annonces compatibles (AMP, vidéo, natif). Dans cet exemple, nous spécifions la création à l'aide du champ html_snippet
.
Vous pouvez également spécifier votre création à l'aide de l'un des champs suivants, en fonction du format de l'annonce:
- Annonce affichée par le SDK
BidResponse.Ad.sdk_rendered_ad
- AMP
BidResponse.Ad.amp_ad_url
- Vidéo
BidResponse.Ad.video_url
ouBidResponse.Ad.video_vast_xml
- Natif
BidResponse.Ad.native_ad
Spécifiez une annonce hébergée sur vos propres serveurs à l'aide d'un extrait de code HTML dans le champ html_snippet
du fichier BidResponse
. L'extrait est inclus dans un iFrame inséré dans la page Web, ce qui entraîne la récupération et l'affichage de l'annonce lors du chargement de la page. Vous devez créer l'extrait de code HTML de sorte que l'annonce (bannière ou interstitiel) s'affiche correctement dans un iFrame, et à une taille appropriée pour l'espace publicitaire sur lequel vous enchérissez.
En outre, la taille d'annonce déclarée dans la réponse à l'enchère doit correspondre exactement à l'une des combinaisons de tailles présentes dans la demande d'enchère lorsque:
- Une annonce est une bannière standard (pas de vidéo, native ou interstitielle).
- L'enchérisseur a déclaré la taille dans sa réponse à l'enchère. La déclaration de taille est requise lorsque la requête comporte plusieurs tailles.
- Une exception est faite pour les annonces interstitielles. Pour les interstitiels, la largeur doit être d'au moins 50% de la largeur de l'écran et sa hauteur au moins 40% de sa hauteur.
Le champ html_snippet
est compatible avec tout code HTML valide qui s'affiche correctement. Toutefois, gardez à l'esprit les restrictions concernant la spécification du champ buyer_creative_id
dans la section Créer un message BidResponse. Vous pouvez par exemple insérer des informations supplémentaires dans les arguments des URL extraites de vos serveurs lors de l'affichage de l'annonce. Cela vous permet de transmettre des données arbitraires concernant l'impression à vos propres serveurs.
La plupart des règles concernant les extraits de code HTML renvoyés dans les réponses aux enchères sont les mêmes que pour les annonces tierces. Pour en savoir plus, consultez le Règlement du programme Authorized Buyers, les Conditions requises pour la diffusion d'annonces par des tiers et la section Déclarer des URL de destination dans les annonces.
Spécifier des macros
L'extrait de code HTML qui définit une création peut inclure une ou plusieurs constructions spéciales appelées macros. Au moment de la diffusion de l'annonce, les valeurs sont remplacées par les macros. Par exemple, votre application d'enchères cliente peut utiliser la macro WINNING_PRICE
pour déterminer le montant qu'elle a payé pour l'annonce si elle remporte l'enchère. Pour analyser cette macro, vous devez mettre en œuvre une application qui déchiffre les confirmations de prix. Pour en savoir plus, consultez la page Déchiffrement des confirmations de prix.
Spécifiez une macro dans un extrait de code HTML au format %%MACRO%%
, où MACRO
est l'une des macros acceptées répertoriées dans le tableau ci-dessous.
Google exige que vous utilisiez la macro CLICK_URL_UNESC
ou CLICK_URL_ESC
dans la création de l'annonce diffusée par un tiers. Google utilise les macros CLICK_URL
pour suivre les clics.
Pour utiliser une macro, incluez-la dans l'annonce afin que l'URL soit récupérée lorsqu'un utilisateur clique dessus. La valeur renvoyée par la récupération est une redirection vers une autre URL que vous ajoutez à CLICK_URL
.
Macro | Description |
---|---|
ADVERTISING_IDENTIFIER |
Permet aux acheteurs de recevoir l'IDFA d'iOS ou l'identifiant publicitaire d'Android lors du rendu des impressions. Pour en savoir plus, consultez Déchiffrer les identifiants d'annonceur. |
CACHEBUSTER |
Représentation, sous forme de chaîne, d'un entier aléatoire non signé de quatre octets. |
CLICK_URL_UNESC |
URL de suivi des clics sans échappement pour l'annonce. Dans l'extrait, une version avec caractères d'échappement de l'URL de suivi des clics tierce doit suivre directement la macro. Par exemple, si l'URL de suivi des clics tierce est <a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> Au moment de la diffusion de l'annonce, il est étendu comme suit: <a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> L'URL enregistre d'abord le clic auprès de Google, puis est redirigée vers l'URL cliquable tierce. |
CLICK_URL_ESC |
URL de suivi des clics avec échappement pour l'annonce. Utilisez cette méthode à la place de Par exemple, le code suivant peut être utilisé dans un extrait de code HTML: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a> Au moment de la diffusion de l'annonce, il est étendu comme suit: <a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a> Le clic sera alors enregistré auprès de Vous pouvez ajouter une URL avec deux échappements après |
CLICK_URL_ESC_ESC |
URL de l'annonce avec deux échappements. Utilisez cette méthode à la place de Par exemple, le code suivant peut être utilisé dans un extrait de code HTML: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a> Au moment de la diffusion de l'annonce, il est étendu comme suit: <a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a> |
SCHEME |
Développée au format http: si la demande d'enchère ne nécessite pas SSL ou au format https: si la demande d'enchère l'exige. |
SITE |
Domaine avec séquence d'échappement dans l'URL de contenu ou ID anonyme pour l'inventaire anonyme. |
SITE_URL |
Obsolète. Remplacé par la macro SITE qui offre des fonctionnalités identiques. |
TZ_OFFSET |
Décalage de fuseau horaire. |
VERIFICATION |
Les différentes valeurs pour la production et le moment où la création est analysée dans le pipeline de validation Le format est le suivant: %%?VERIFICATION:true-val:false-val%% . Toutes les valeurs, à l'exception des macros, peuvent être utilisées pour true-val et false-val , y compris les chaînes vides. Pour Open Bidding, nous recommandons aux places de marché d'utiliser cette macro. Une fois cette opération effectuée, les plates-formes côté demande n'ont pas besoin d'apporter de modifications.Par exemple, si une création doit inclure %%?VERIFICATION:-1:5000%% , le texte de remplacement sera 5000 lors de la diffusion et -1 dans le pipeline de validation. Cela permet de distinguer ces deux ensembles de pings. |
WINNING_PRICE |
Coût de l'impression encodée (c'est-à-dire le CPI plutôt que le CPM) en micro-unités de la devise du compte. Par exemple, un CPM gagnant de 5 USD équivaut à 5 000 000 micro-unités de CPM, soit 5 000 micro-unités de CPI. Dans ce cas,la valeur décodée de WINNING_PRICE serait 5 000.
Le prix gagnant est indiqué en CPI.
|
WINNING_PRICE_ESC |
WINNING_PRICE avec séquence d'échappement dans l'URL. |
L'échappement des URL dans les macros utilise le schéma suivant:
- Le caractère espace est remplacé par un signe plus (
+
). - Les caractères alphanumériques (0-9, a-z, A-Z) et les caractères de l'ensemble !()*,-./:_~ restent inchangés.
- Tous les autres caractères sont remplacés par
%XX
, oùXX
est le nombre hexadécimal représentant le caractère.
Restrictions des éditeurs
Les éditeurs utilisent le BidRequest
pour transmettre des restrictions sur les annonces qu'ils acceptent. Vous devez appliquer les restrictions indiquées dans les champs suivants:
allowed_vendor_type
excluded_attribute
excluded_sensitive_category
L'un indique les fonctionnalités autorisées de l'annonce, et l'autre les fonctionnalités non autorisées. Ne jamais renvoyer une annonce avec une fonctionnalité non autorisée. Pour les fonctionnalités autorisées telles que le type de fournisseur, ne renvoyez une annonce que si son type figure dans la liste allowed_vendor_type
du BidRequest
. Pour en savoir plus, consultez les commentaires sur ces champs dans la définition du tampon de protocole BidRequest
.
Si un extrait de code HTML est renvoyé dans BidResponse
, vous devez définir avec précision les champs attribute
, category
et click_through_url
dans BidResponse
.
Si une annonce comporte plusieurs valeurs applicables pour ces champs, vous devez inclure chaque valeur. Pour en savoir plus, consultez les commentaires associés à ces champs dans la définition du tampon de protocole BidResponse
.
Les réponses pour lesquelles ces champs ne sont pas définis sont supprimées.
Les valeurs possibles de l'attribut BidRequest.excluded_attribute
sont les suivantes (voir publisher-excludable-creative-attributes.txt):
7 Tagging: IsTagged
Les annonces ne sont pas autorisées si elles contiennent un pixel ou une balise Web servant à créer une liste d'ID de cookie en vue d'un remarketing ultérieur.8 CookieTargeting: IsCookieTargeted
Les annonces ne sont pas autorisées si elles ciblent les consommateurs en fonction de leur ID de cookie, la liste de ces ID représentant un ensemble de consommateurs ayant déjà interagi avec un site appartenant à l'acheteur ou représenté par celui-ci.9 UserInterestTargeting: IsUserInterestTargeted
Les annonces ne sont pas autorisées si elles ciblent des consommateurs en fonction de leur ID de cookie, où la liste de ces ID représente un ensemble de consommateurs définis par l'acheteur comme appartenant à une même catégorie de centres d'intérêt.21 CreativeType: Html
Les annonces ne peuvent pas utiliser le champhtml_snippet
nisnippet_template
dansBidResponse.Ad
.22 CreativeType: VastVideo
Les annonces ne peuvent pas utiliser le champvideo_url
dansBidResponse.Ad
.30 InstreamVastVideoType: Vpaid
Les annonces ne doivent pas nécessiter la compatibilité avec VPAID pour s'afficher.32 MraidType: MRAID
Les annonces ne sont pas autorisées à exiger l'API MRAID pour s'afficher.34 RichMediaCapabilityType: RichMediaCapabilityFlash
Les annonces ne doivent pas nécessiter la compatibilité avec Flash pour s'afficher.39 RichMediaCapabilityType: RichMediaCapabilityHTML5
Les annonces ne doivent pas avoir besoin de fonctionnalités HTML5 pour s'afficher.48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
Les annonces ne sont pas autorisées à envoyer des demandes non-SSL.
Par conséquent, si le champ excluded_attribute
contient la valeur 7, vous ne devez pas renvoyer d'annonce qui utilise un pixel ou une balise Web pour créer une liste. Notez que si une annonce effectue cette opération, elle doit définir la valeur 7 dans le champ d'attribut de BidResponse
.
De même, si le champ excluded_attribute
contient la valeur 48, vous ne devez renvoyer que les annonces pouvant s'afficher sur une page SSL (et déclarez donc l'attribut 47 RichMediaCapabilityType: RichMediaCapabilitySSL).
De plus, le champ excluded_sensitive_category
de BidRequest
utilise les codes du fichier ad-sensitive-categories.txt
disponible sur la page des données de référence. Voici des descriptions étendues de certains de ces codes:
3 Politics
Cette catégorie inclut les annonces politiques ou sociales controversées. Elle n'inclut pas les annonces pour des organismes de presse qui ne manifestent généralement pas de point de vue partisan.4 Dating
Cette catégorie inclut les services de rencontre et les communautés de rencontres en ligne.5 Religion
Cette catégorie inclut les annonces à caractère religieux, ainsi que les annonces prônant ou attaquant la religion ; elle ne concerne ni l'astrologie, ni la spiritualité non confessionnelle.7 Video Games (Casual & Online)
Cette catégorie inclut les jeux vidéo, les jeux en ligne et les jeux téléchargeables ; elle ne concerne pas les consoles de jeu vidéo.8 Ringtones & Downloadables
Modules complémentaires pour mobiles, tels que sonneries et autres accessoires téléchargeables (économiseurs d'écran et fonds d'écran pour PC, thèmes de profil et images pour réseaux sociaux, par exemple).10 Get Rich Quick
Méthodes susceptibles de générer rapidement des revenus.18 Weight Loss
Cette catégorie inclut les annonces concernant la perte de poids, les régimes, ainsi que les produits et programmes associés. Elle n'inclut pas les annonces relatives à l'alimentation équilibrée ou à la forme physique en général.19 Cosmetic Procedures & Body Modification
Cette catégorie concerne les liftings, les liposuccions, les opérations au laser, l'épilation, les implants capillaires, les tatouages et les modifications corporelles.23 Drugs & Supplements:
Cette catégorie inclut les détaillants de produits pharmaceutiques, de vitamines, de compléments alimentaires et autres produits associés ; elle n'inclut pas les ressources fournissant des informations sur les médicaments.24 Sexual & Reproductive Health
Cette catégorie inclut les annonces liées à la sexualité et aux problèmes de fertilité. Elle n'inclut pas les annonces relatives aux grossesses normales.35 Social Casino Games
Cette catégorie inclut les simulations de jeux d'argent et de hasard (y compris, mais sans s'y limiter, le poker, les machines à sous, le bingo, les loteries, les paris sportifs, le paris sur les courses, ainsi que d'autres jeux de cartes et de casino) ne proposant aucune récompense de valeur (telle que de l'argent ou des prix).36 Significant Skin Exposure
Images d'annonces dans lesquelles une partie du corps humain (du sternum jusqu'à la mi-cuisse) n'est pas habillée, le corps en sous-vêtements, en maillot de bain, en lingerie ou d'autres vêtements transparents, ou des vêtements non vestimentaires (serviette ou drap de lit, par exemple).37 Sensationalism
Annonces dont l'objectif est d'inciter les utilisateurs à cliquer dessus en attisant leur curiosité, souvent par le biais d'un message d'accroche contenant un langage ou des images hyperboliques. Cette catégorie inclut les annonces qui sont axées sur des sujets à sensations (tels que l'arrestation, le décès ou le divorce de célébrités) ou qui ont pour but de choquer.
Open Measurement
Open Measurement vous permet de spécifier des fournisseurs tiers qui fournissent des services de mesure et de vérification indépendants pour les annonces diffusées dans les environnements d'applications mobiles.Les formats d'annonces actuellement compatibles incluent les annonces vidéo, les bannières et les annonces interstitielles. Pour en savoir plus sur l'utilisation d'Open Measurement dans une réponse à l'enchère contenant ces formats, consultez l'article du centre d'aide sur le SDK Open Measurement.
Exemples de réponses aux enchères
Les sections suivantes présentent des exemples de réponses aux enchères pour différents types d'annonces.