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
Pour envoyer une enchère, votre application d'enchères doit répondre à une demande d'enchère avec un BidResponse contenant un Bid au format que vous avez configuré. Si vous utilisez le format JSON, votre réponse doit définir l'en-tête Content-Type sur application/json; charset=utf-8 et inclure le BidResponse JSON dans le corps. Si vous utilisez le format Protobuf, votre application doit définir l'en-tête Content-Type sur application/octet-stream et inclure le BidResponse sérialisé dans le corps.
Pour créer et sérialiser un BidResponse au format Protobuf, vous devez générer et utiliser des bibliothèques Protobuf basées sur openrtb.proto et openrtb-adx.proto, qui implémentent respectivement les champs BidResponse OpenRTB standards et les extensions Google dans Protobuf. Vous les trouverez dans Protos et données de référence.
Si vous ne souhaitez pas enchérir sur une impression, vous devez renvoyer une réponse HTTP 204 vide. Votre application doit renvoyer une réponse à chaque BidRequest. Les délais d'expiration et les réponses qui ne peuvent pas être analysées sont considérés comme des erreurs, et Google limite les enchérisseurs présentant des taux d'erreur élevés.
ID de la création
Votre BidResponse spécifie une création via le champ BidResponse.seatbid.bid.crid (limite de 128 octets). Même les créations similaires doivent avoir des valeurs uniques pour ce champ 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 création et les types de fournisseurs. En d'autres termes, vous devez attribuer des ID de création différents à deux annonces qui :
- avoir une apparence ou un comportement différents.
- Effectuer le rendu sur différentes images
- Elles sont affichées de différentes manières (par exemple, une annonce se compose d'une image, tandis que l'autre est une vidéo).
Lorsque vous concevez votre application, vous devez choisir une méthode systématique de génération d'identifiants qui soit adaptée aux types de créations que vous prévoyez d'envoyer.
Attributs d'annonce
Google recommande de déclarer des attributs de création pour décrire les caractéristiques de votre annonce et son ciblage en utilisant une combinaison de BidResponse.seatbid.bid.apis et de BidResponse.seatbid.bid.attr, ou l'extension BidResponse.seatbid.bid.ext.attribute. La section suivante décrit comment déclarer des attributs :
VPAIDDéfinissezBidResponse.seatbid.bid.apissurVPAID_1ouVPAID_2. Pour le format JSON, vous pouvez définir respectivement1ou2.MRAIDDéfinissezBidResponse.seatbid.bid.apissurMRAID_1ou3pour le format JSON.SIZELESSDéfinissezBidResponse.seatbid.bid.attrsurRESPONSIVEou18pour le format JSON.PLAYABLEPour ce faire, définissezBidResponse.seatbid.bid.attrsurUSER_INTERACTIVEou13pour le format JSON.
Consultez la ressource Creatives pour savoir comment obtenir des commentaires sur les propriétés détectées de vos créations.
Champs Open Bidding
Les réponses aux enchères envoyées par les enchérisseurs des places de marché et des réseaux participant à Open Bidding sont semblables à celles des 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 certains champs existants peuvent avoir d'autres utilisations. En voici quelques exemples :
| Champ | Détails |
|---|---|
BidResponse.imp.pmp.deals.id |
ID de l'accord de l'espace de noms de la place de marché associé à cette enchère et signalé aux éditeurs. |
BidResponse.seatbid.bid.ext.exchange_deal_type |
Type d'accord signalé aux éditeurs, qui affecte la façon dont l'accord est traité lors des enchères. |
BidResponse.seatbid.bid.ext.third_party_buyer_token |
Jeton utilisé pour identifier les informations sur l'acheteur tiers final si la place de marché en tant qu'enchérisseur Open Bidding est un intermédiaire. Il est obtenu auprès de l'acheteur tiers et doit être transmis à Google sans modification dans la réponse à l'enchère. |
Recommandations
- Activez les connexions HTTPS persistantes (également appelées "keep-alive" ou "réutilisation de connexion") sur vos serveurs. Définissez le délai avant expiration sur 10 secondes au minimum. Des valeurs plus élevées sont bénéfiques dans de nombreux cas. Google vérifie cela lors des tests de latence initiaux de votre application, car Authorized Buyers envoie des requêtes à un débit élevé et doit éviter la surcharge de 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 est affichée plutôt que celui où l'enchérisseur remporte l'enchère. En raison de la différence entre les enchères remportées et les affichages, cela permet d'obtenir des statistiques de suivi plus précises.
- Assurez-vous que votre code d'enchérisseur ne dépend pas de champs obsolètes, ce qui peut entraîner l'échec de vos enchères avec des erreurs.
- Incluez
BidResponse.seatbid.bid.wetBidResponse.seatbid.bid.hdans votreBidResponse. UneBidResponseà une demande incluant plusieurs tailles d'annonces doit inclure ces champs, sinon elle sera exclue des enchères. - 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 concernant les enchères sur l'inventaire iOS qui nécessitent l'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.
OpenRTB Protobuf
OpenRTB JSON
Important : Les messages Protobuf représentés dans les exemples sont présentés ici sous forme de texte lisible par l'humain. Cependant, ce n'est pas ainsi que les messages sont envoyés sur le réseau. Lorsque vous utilisez le format OpenRTB Protobuf, 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'annonce 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 d'annonce :
- Annonce affichée par le SDK
BidResponse.seatbid.bid.ext.sdk_rendered_ad
- AMP
BidResponse.seatbid.bid.amp_ad_url
- Vidéo
BidResponse.seatbid.bid.adm
- Natif
BidResponse.seatbid.bid.adm_native
Spécifiez une annonce hébergée sur votre ou vos propres serveurs à l'aide d'un extrait HTML dans le champ BidResponse.seatbid.bid.adm. L'extrait est inclus dans un iFrame inséré dans la page Web, ce qui permet de récupérer et d'afficher l'annonce lorsque la page est chargée. Vous devez créer l'extrait 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.
De plus, la taille d'annonce déclarée dans la réponse à l'enchère doit correspondre exactement à l'une des combinaisons de tailles de la demande d'enchère lorsque :
- L'annonce est une bannière standard (pas une vidéo, une annonce native ni un interstitiel).
- L'enchérisseur a déclaré la taille dans la réponse à l'enchère. La déclaration de la taille est obligatoire chaque fois que plusieurs tailles sont présentes dans la demande.
- 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 la hauteur d'au moins 40% de la hauteur de l'écran.
Vous pouvez spécifier une création d'extrait HTML à l'aide de n'importe quel code HTML valide qui s'affiche correctement, mais tenez compte des restrictions concernant la spécification du champ crid dans la section Créer un message BidResponse.
Vous pouvez par exemple ajouter des informations supplémentaires dans les arguments des URL récupérées à partir de vos serveurs lors de l'affichage de l'annonce. Cela vous permet de renvoyer des données arbitraires sur l'impression à vos propres serveurs.
La plupart des règles concernant les extraits HTML renvoyés dans les réponses aux enchères sont identiques à celles des 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 Déclarer les URL de destination dans les annonces.
Utiliser des URL de destination cohérentes
L'URL de destination que vous spécifiez dans le champ BidResponse.seatbid.bid.ext.clickurl doit être identique à l'URL de la page de destination spécifiée dans votre création. Voici des exemples de créations dans des formats compatibles qui sont cohérents avec le champ clickurl défini sur https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1 :
HTML
<div id="my-app-install-ad"
style="font-family: sans-serif; border: 1px solid #ddd; padding: 10px;
display: flex; align-items: center; width: 100%; height: 100%;
box-sizing: border-box; cursor: pointer;"
onclick="window.open('https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1', '_blank')">
<img src="https://example.com/path/to/app_icon.png" alt="App Icon"
style="width: 60px; height: 60px; margin-right: 10px;
border-radius: 8px;">
<div style="flex-grow: 1;">
<h4 style="margin: 0 0 5px 0; font-size: 16px; color: #1a73e8;">
My Awesome App
</h4>
<p style="margin: 0 0 10px 0; font-size: 14px; color: #5f6368;">
The best app for doing awesome things! Download now and get started!
</p>
<span style="background-color: #1a73e8; color: white; padding: 8px 12px;
text-align: center; text-decoration: none;
display: inline-block; border-radius: 4px; font-size: 14px;
font-weight: bold;">Install</span>
</div>
</div>XML VAST
<VAST version="3.0"> <Ad id="creative_id_789"> <InLine> <AdSystem>MyBidderSystem</AdSystem> <AdTitle>My Awesome App Install Video</AdTitle> <Description>Install My Awesome App now!</Description> <Error> <![CDATA[https://tracking.example.com/vast_error?errorcode=[ERRORCODE]]]> </Error> <Impression> <![CDATA[https://tracking.example.com/vast_impression]]> </Impression> <Creatives> <!-- Main Video Creative --> <Creative> <Linear> <Duration>00:00:15</Duration> <TrackingEvents> <Tracking event="start"> <![CDATA[https://tracking.example.com/vast_event?label=start]]> </Tracking> <Tracking event="firstQuartile"> <![CDATA[https://tracking.example.com/vast_event?label=firstQuartile]]> </Tracking> <Tracking event="midpoint"> <![CDATA[https://tracking.example.com/vast_event?label=midpoint]]> </Tracking> <Tracking event="thirdQuartile"> <![CDATA[https://tracking.example.com/vast_event?label=thirdQuartile]]> </Tracking> <Tracking event="complete"> <![CDATA[https://tracking.example.com/vast_event?label=complete]]> </Tracking> </TrackingEvents> <VideoClicks> <ClickThrough id="gplay-video"> <![CDATA[https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1]]> </ClickThrough> <ClickTracking id="bidder-tracker-video"> <![CDATA[https://tracking.example.com/vast_click]]> </ClickTracking> </VideoClicks> <MediaFiles> <MediaFile delivery="progressive" type="video/mp4" width="640" height="360" bitrate="800" scalable="true" maintainAspectRatio="true"> <![CDATA[https://cdn.example.com/myawesomeapp_video.mp4]]> </MediaFile> </MediaFiles> </Linear> </Creative> <!-- Companion Ad Creative --> <Creative> <CompanionAds> <Companion id="companion1" width="300" height="250" assetWidth="300" assetHeight="250"> <StaticResource creativeType="image/png"> <![CDATA[https://cdn.example.com/companion_banner_300x250.png]]> </StaticResource> <TrackingEvents> <Tracking event="creativeView"> <![CDATA[https://tracking.example.com/vast_companion_view]]> </Tracking> </TrackingEvents> <CompanionClickThrough> <![CDATA[https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1]]> </CompanionClickThrough> <CompanionClickTracking> <![CDATA[https://tracking.example.com/vast_companion_click]]> </CompanionClickTracking> </Companion> </CompanionAds> </Creative> </Creatives> </InLine> </Ad> </VAST>
Natif
{ "ver": "1.2", "assets": [ { "id": 1, "title": { "text": "My Awesome App" } }, { "id": 2, "img": { "url": "https://example.com/path/to/app_icon.png", "w": 60, "h": 60 } }, { "id": 3, "data": { "value": "The best app for doing awesome things! Download now and get started!" } }, { "id": 4, "data": { "value": "Install" } } ], "link": { "url": "https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1", "clicktrackers": [ "https://tracking.example.com/native_click" ] }, "imptrackers": [ "https://tracking.example.com/native_impression" ] }
Spécifier des macros
Les macros sont du texte mis en forme intégré dans certains champs de réponse à l'enchère contenant des URL qui sont remplacées par une valeur pertinente au moment de la diffusion de l'annonce. Par exemple, si votre enchère gagnante incluait la macro AUCTION_PRICE dans l'extrait HTML de la création inclus dans votre enchère, la macro serait remplacée par une valeur que vous pourriez déchiffrer pour déterminer le montant que vous avez payé pour l'impression lors de l'enchère.
Vous pouvez inclure des macros dans les champs suivants :
-
BidResponse.seatbid.bid.admLes macros sont compatibles avec les formats d'extrait HTML, natif, d'URL vidéo et XML VAST vidéo.
-
BidResponse.seatbid.bid.adm_native.eventtrackers.url -
BidResponse.seatbid.bid.adm_native.imptrackers -
BidResponse.seatbid.bid.ext.amp_ad_urlSeules les macros
WINNING_PRICEetWINNING_PRICE_ESCspécifiques à Google sont compatibles avec les créations AMP. -
BidResponse.seatbid.bid.burl -
BidResponse.seatbid.bid.ext.impression_tracking_urlUtilisez cette option au lieu de
BidResponse.seatbid.bid.burlsi vous avez besoin de plusieurs URL de facturation.
Par exemple, vous pouvez inclure une macro dans un extrait HTML en intégrant ${MACRO} dans l'URL utilisée pour récupérer la création, où MACRO est l'une des macros compatibles décrites dans la spécification OpenRTB.
Macros Google
Google accepte d'autres macros que celles de la spécification OpenRTB. Elles sont formatées différemment et s'affichent sous la forme %%MACRO%% si elles sont intégrées à une URL. Le tableau suivant décrit ces macros :
| Macro | Description |
|---|---|
ADVERTISING_IDENTIFIER |
Permet aux acheteurs de recevoir l'IDFA iOS ou l'identifiant publicitaire Android lors de l'affichage de l'impression. Pour en savoir plus, consultez Déchiffrer les identifiants publicitaires. |
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 échappée 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> Lors de la diffusion de l'annonce, cet extrait est remplacé par celui-ci : <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 redirige vers l'URL de suivi des clics tierce. |
CLICK_URL_ESC |
URL de suivi des clics échappée pour l'annonce. Utilisez cette macro à la place de Par exemple, le code suivant peut être utilisé dans un extrait HTML : <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a> Au moment de la diffusion de l'annonce, cet extrait est remplacé par celui-ci : <a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a> Le clic sera ainsi enregistré auprès de Vous pouvez ajouter une URL avec double échappement après |
CLICK_URL_ESC_ESC |
URL de l'annonce avec double échappement. Utilisez cette macro à la place de Par exemple, le code suivant peut être utilisé dans un extrait HTML : <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a> Lors de la diffusion de l'annonce, cet extrait est remplacé par celui-ci : <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é en http: si la demande d'enchère ne nécessite pas de SSL ou en https: si la demande d'enchère nécessite un SSL. |
SITE |
Domaine avec séquence d'échappement dans l'URL de contenu ou ID anonyme pour l'inventaire anonyme. |
SITE_URL |
Obsolète. Remplacée par la macro SITE, qui offre des fonctionnalités identiques. |
TZ_OFFSET |
Décalage de fuseau horaire. |
VERIFICATION |
Différentes valeurs pour la production et lorsque la création est analysée dans le pipeline de validation. Le format est le suivant : Par exemple, si une création inclut |
WINNING_PRICE |
Le coût de l'impression codée (CPI plutôt que CPM) en micro-unités de la devise du compte. Par exemple, une enchère au CPM gagnante d'un montant de 5 USD équivaut à 5 000 000 micro-unités de CPM, soit 5 000 micro-unités de CPI. La valeur décodée de Pour analyser cette macro, vous devez implémenter une application qui déchiffre les confirmations de prix. Pour en savoir plus, consultez la page Déchiffrer les confirmations de prix. |
WINNING_PRICE_ESC |
WINNING_PRICE avec échappement d'URL. |
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 le suivi des clics.
L'échappement d'URL dans les macros utilise le schéma suivant :
- L'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ùXXest le nombre hexadécimal représentant le caractère.
Restrictions et exigences applicables aux éditeurs
La demande d'enchère inclut des informations sur les types de restrictions et d'exigences que les éditeurs imposent aux créations lors de l'enchère.
BidRequest.bcat- Vous pouvez comparer les catégories bloquées spécifiées par ce champ à celles détectées pour les créations que vous avez envoyées à l'aide du champ
detectedCategoriesde l'API d'enchères en temps réel.
- Vous pouvez comparer les catégories bloquées spécifiées par ce champ à celles détectées pour les créations que vous avez envoyées à l'aide du champ
BidRequest.imp.ext.allowed_vendor_typeBidRequest.imp.secure- En pratique, cette valeur est toujours définie sur
true, car Google exige que toutes les créations soient compatibles avec le protocole SSL.
- En pratique, cette valeur est toujours définie sur
BidRequest.imp.{audio/banner/native/video}BidRequest.imp.{audio/banner/native/video}.apiBidRequest.imp.{audio/banner/native/video}.battrBidRequest.imp.{audio/banner/video}.mimes
Ne définissez jamais d'enchère avec une annonce contenant une fonctionnalité soumise à restriction. Pour les fonctionnalités autorisées telles que le type de fournisseur, ne renvoyez une annonce que si son type de fournisseur figure dans la liste allowed_vendor_type de BidRequest. Seuls les formats d'annonces spécifiés dans la demande d'enchère en renseignant des champs tels que BidRequest.imp.banner doivent être inclus dans votre enchère. Pour en savoir plus, consultez les commentaires de ces champs dans la définition du tampon de protocole BidRequest.
Si une annonce est renvoyée dans BidResponse, vous devez définir précisément les champs BidResponse.seatbid.bid.attr, BidResponse.seatbid.bid.cat et BidResponse.seatbid.bid.adomain ou BidResponse.seatbid.bid.adm_native.link.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 de 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.
Open Measurement
Open Measurement vous permet de spécifier des fournisseurs tiers qui proposent des services indépendants de mesure et de vérification pour les annonces diffusées dans des environnements d'applications mobiles.
Les formats d'annonces 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.