Une interaction avec les enchères en temps réel commence lorsque Google envoie une demande d'enchère à
votre application. Ce guide explique comment coder votre application pour traiter la requête d'enchère.
Analyser la requête Protobuf
Google envoie une requête d'enchère sous la forme d'un tampon de protocole sérialisé joint en tant que charge utile binaire d'une requête HTTP POST. Content-Type est défini sur
application/octet-stream Pour voir un exemple, reportez-vous à la section Exemple de demande d'enchère.
Vous devez analyser cette requête dans une instance du message BidRequest. Selon le protocole choisi, BidRequest est défini.
dans openrtb.proto ou dans l'environnement
realtime-bidding.proto, que vous pouvez obtenir à partir de
données de référence. Vous pouvez analyser le message à l'aide de la méthode ParseFromString() dans la classe générée pour BidRequest. Par exemple, le code C++ suivant analyse une requête
à partir d'une charge utile POST dans une chaîne:
string post_payload = /* the payload from the POST request */;
BidRequest bid_request;
if (bid_request.ParseFromString(post_payload)) {
// Process the request.
}
Une fois que vous avez le BidRequest, vous pouvez l'utiliser en tant que
en extrayant et en interprétant les champs dont vous avez besoin. Par exemple, dans
L'itération C++ via les accords dans un "BidRequest" OpenRTB peut ressembler à ceci :
les éléments suivants:
for (const BidRequest::Imp::Pmp::Deal& deal : pmp.deals()) {
DoSomething(deal.id(), deal.wseat());
}
N° compte facturation
Vous recevez une demande d'enchère lorsque l'inventaire publicitaire d'un éditeur est ciblé par
un ou plusieurs de vos
de préciblage. BidRequest.imp.ext.billing_id
est renseigné avec les n° compte facturation des acheteurs éligibles et
de préciblage. De plus, pour l'inventaire des accords, vous pouvez trouver les ID de facturation associés à l'acheteur concerné à l'aide de BidRequest.imp.pmp.deal.ext.billing_id. Uniquement les n° compte facturation de
les acheteurs inclus dans la demande d'enchère peuvent être spécifiés lors de la définition d'une enchère.
Si plusieurs numéros de compte de facturation sont inclus dans la demande d'enchère, vous devez spécifier le numéro de compte de facturation de l'acheteur auquel vous souhaitez attribuer votre enchère à l'aide du champ BidResponse.seatbid.bid.ext.billing_id.
Fichiers de dictionnaire
La requête d'enchère utilise des identifiants définis dans des fichiers de dictionnaire, qui sont disponibles sur la page Données de référence.
Macros d'URL d'enchères au niveau du protocole du système d'enchères en temps réel Google
Si vous le souhaitez, vous pouvez insérer certains champs de BidRequest dans l'URL utilisée dans la requête HTTP POST. Ceci est utile, par exemple, si vous utilisez
Une interface légère qui équilibre la charge sur plusieurs backends à l'aide d'une valeur
de la requête. Contactez votre responsable de compte technique pour demander de l'aide concernant
ou de nouvelles macros.
Macro
Description
%%GOOGLE_USER_ID%%
Remplacé par google_user_id
à partir de BidRequest. Par exemple, l'URL du système d'enchères
Le résultat correspond à l'application Android
slither.io.
Champs Open Bidding
Les demandes d'enchères envoyées aux enchérisseurs de place de marché et de réseau participant à Open Bidding sont similaires à celles d'Authorized Buyers participant aux enchères en temps réel standards. Les clients Open Bidding ne reçoivent qu'un petit nombre
des champs supplémentaires, et quelques champs
existants peuvent avoir d’autres utilisations. Ces
incluent les éléments suivants:
OpenRTB
Authorized Buyers
Détails
BidRequest.imp[].ext.dfp_ad_unit_code
BidRequest.adslot[].dfp_ad_unit_code
Inclut le code de réseau Ad Manager de l'éditeur, suivi de la hiérarchie des blocs d'annonces, séparés par des barres obliques.
Par exemple, il se présenterait sous la forme suivante :
/1234/cruises/mars.
BidRequest.user.data[].segment[]
BidRequest.adslot[].exchange_bidding.key_value[]
Paires clé-valeur répétées envoyées de l'éditeur vers l'enchérisseur sur la place de marché.
Vous pouvez déterminer que les valeurs sont des paires clé-valeur envoyées par
éditeur lorsque BidRequest.user.data[].name est défini sur
“Publisher Passed”
Déclarer des fournisseurs autorisés
Les fournisseurs de technologies qui fournissent des services tels que la recherche, le remarketing et la diffusion d'annonces peuvent jouer un rôle dans l'interaction entre les acheteurs et les vendeurs. Uniquement
Fournisseurs approuvés par Google pour participer au programme Authorized Buyers
les interactions sont autorisées.
Pour comprendre le BidRequest et créer votre
BidResponse, vous devez connaître les deux
possibilité de déclarer des fournisseurs de technologies:
Les autres fournisseurs ne peuvent participer que s'ils sont déclarés dans BidRequest :
Dans BidRequest, le champ BidRequest.imp.ext.allowed_vendor_type spécifie les fournisseurs autorisés par le vendeur. Fournisseurs qui seront envoyés dans le
allowed_vendor_type sont listés dans
vendors.txt
fichier de dictionnaire.
Exemple de demande d'enchère
Les exemples suivants représentent des exemples lisibles par l'homme des requêtes Protobuf et JSON.
Pour convertir la demande d'enchère dans un format binaire, comme avec la méthode
POST dans une requête réelle, vous pouvez effectuer les opérations suivantes (en C++). Remarque :
Toutefois, cela ne s'applique pas au format JSON OpenRTB.
string text_format_example = /* example from above */;
BidRequest bid_request;
if (TextFormat::ParseFromString(text_format_example, &bid_request)) {
string post_payload;
if (bid_request.SerializeToString(&post_payload)) {
// post_payload is a binary serialization of the protocol buffer
}
}
Commentaires en temps réel
Les commentaires en temps réel sont également
disponibles pour Authorized Buyers.
que les places de marché et les réseaux
utilisant Open Bidding.
Les commentaires sur les réponses aux enchères sont acceptés dans la demande d'enchère suivante pour les deux
OpenRTB et le protocole obsolète RTB de Google Pour OpenRTB, il est envoyé
BidRequest.ext.bid_feedback
En plus des champs par défaut envoyés dans les commentaires sur la réponse aux enchères, vous pouvez également envoyer des données personnalisées dans la réponse aux enchères à l'aide du champ BidResponse.seatbid.bid.ext.event_notification_token. La
event_notification_token correspond à des données arbitraires connues uniquement du
qui pourraient faciliter le débogage, par exemple: un nouvel ID de ciblage ou
ID d'enchère représentant une nouvelle stratégie ou métadonnées associées à la création.
ne sont connues que de l'enchérisseur. Pour en savoir plus, consultez le Protocol Buffer des extensions OpenRTB pour OpenRTB ou l'ancien protocole RTB de Google.
Lorsque Authorized Buyers envoie une demande d'enchère à un enchérisseur, celui-ci répond avec un BidResponse. Si les commentaires en temps réel sont activés pour l'enchérisseur, Authorized Buyers envoie des commentaires sur la réponse dans un message BidFeedback lors d'une demande d'enchère ultérieure :
message BidFeedback {
// The unique id from BidRequest.id.
optional string request_id = 1;
// The status code for the ad. See creative-status-codes.txt in the
// technical documentation for a list of ids.
optional int32 creative_status_code = 2;
// If the bid won the auction, this is the price paid in your account
// currency. If the bid participated in the auction but was out-bid, this
// is the CPM that should have been exceeded in order to win. This is not
// set if the bid was filtered prior to the auction, if the publisher or
// winning bidder has opted out of price feedback or if your account has
// opted out of sharing winning prices with other bidders. For first-price
// auctions, minimum_bid_to_win is populated instead of this field.
optional double price = 3;
// The minimum bid value necessary to have the auction, in your account
// currency. If your bid won the auction, this is the second highest bid
// that was not filtered (including the floor price). If your bid did not
// win the auction, this is the winning candidate's bid. This field will
// only be populated if your bid participated in a first-price auction, and
// will not be populated if your bid was filtered prior to the auction.
optional double minimum_bid_to_win = 6;
// The minimum bid value necessary to have won the server-side component of
// the overall auction given that there was also an interest group bidding
// component to the overall auction which ran using the Protected Audience
// API. The value is expressed in CPM of the buyer account currency. The
// minimum bid to win for the overall auction, including bids from the
// server-side and the on-device interest group components, is populated in
// the minimum_bid_to_win field of the same BidFeedback object.
optional double sscminbidtowin = 14;
// Billable event rate multiplier that was applied to this bid during
// ranking. The adjustment reflects the likelihood that your bid would
// generate a billable event (namely, the ad renders successfully) if it won
// the auction, relative to the probability that other bids generate a
// billable event if they won the auction. This adjustment can be larger or
// smaller than 1. This affects the final ranking in the auction only; in
// particular, this multiplier does not affect the payment or whether the
// bid clears any floor price.
optional float billable_event_rate_bid_adjustment = 13 [default = 1];
// When a publisher uses an RTB auction and waterfall-based SDK mediation on
// the same query, the winner of the real-time auction must also compete in
// a mediation waterfall (which is ordered by price) to win the impression.
// If the bid participated in the auction and there was no waterfall, the
// value of this field is 0. If the bid participated in the auction and
// there was a waterfall, the value of this field is a price representing a
// sample bid from the eligible mediation networks that were higher than the
// auction winner, weighted by expected fill rate. This field can be used
// in conjunction with minimum_bid_to_win to train bidding models. The CPM
// is in your account currency.
optional double sampled_mediation_cpm_ahead_of_auction_winner = 8;
message EventNotificationToken {
// The contents of the token.
optional string payload = 1;
}
// The token included in the corresponding bid.
optional EventNotificationToken event_notification_token = 4;
// The creative ID included in the corresponding bid.
optional string buyer_creative_id = 5;
// Possible types of bid response feedback objects.
enum FeedbackType {
FEEDBACK_TYPE_UNSPECIFIED = 0;
// Feedback for a bid that was submitted on a bid response.
BID_FEEDBACK = 1;
// Feedback for an interest group buyer submitted on a bid response to
// particpate in an interest group bidding component of the auction run
// using the Protected Audience API.
INTEREST_GROUP_BUYER_FEEDBACK = 2;
}
// The type of the BidFeedback message. Google will send separate
// BidFeedback objects for:
// a) Each bid submitted on a bid response
// b) Each buyer submitted on a bid response to particpate in an interest
// group bidding component of the auction run using the Protected Audience
// API.
optional FeedbackType feedbacktype = 15;
// Origin of an interest group buyer that was included in the bid response.
// This field is populated only for feedback where a bidder opted in an
// interest group buyer to participate in the interest group bidding
// component of the overall auction run using the Protected Audience API.
// To learn more about origins, see https://www.rfc-editor.org/rfc/rfc6454.
// To learn more about interest group bidding and the Protected Audience
// API, see
// https://developers.google.com/authorized-buyers/rtb/fledge-origin-trial.
optional string buyerorigin = 16;
// The status code for the submitted interest group buyer. This field is
// only populated in the feedback for an interest group buyer that a bidder
// requested to enter into the interest group auction through the bid
// response. Individual creative status codes of bids submitted by the buyer
// in the on-device interest group auction are not available. See
// https://storage.googleapis.com/adx-rtb-dictionaries/interest-group-buyer-status-codes.txt
// for a list of interest group buyer status codes.
optional int32 igbuyerstatus = 17;
}
À partir de ce message, le premier champ à vérifier est
bid_feedback.creative_status_code; vous pouvez trouver le code
signification en
le fichier "creative-status-codes.txt". Notez que si vous remportez l'enchère, vous pouvez
à partir des informations sur le prix. Pour en savoir plus, consultez la section Désactiver.
Les informations en temps réel incluent l'ID de la demande d'enchère et l'une des
suivantes:
Résultat des enchères
Commentaires en temps réel
L'acheteur n'a pas soumis d'enchère.
Rien.
L'acheteur a soumis une enchère qui a été filtrée avant de parvenir
l'enchère.
L'acheteur a soumis une enchère, mais n'a pas remporté la mise aux enchères.
Code d'état de la création 79 (enchère supérieure soumise).
L'acheteur a envoyé une enchère qui a remporté l'enchère.
Le prix de compensation et le code d'état de la création 1.
Pour une impression dans une application et un code d'état de la création 83, l'éditeur de l'application peut avoir utilisé une cascade de médiation. Par conséquent, l'enchère gagnante a donc été en concurrence avec d'autres demandes dans la chaîne de cascade de passback de l'éditeur. Découvrez comment utiliser
sampled_mediation_cpm_ahead_of_auction_winner lorsque
les enchères.
Échantillon
Voici un exemple de commentaires en temps réel dans les protocoles compatibles :
Créer un modèle d'enchères pour les enchères au premier prix
Après avoir défini une enchère dans une mise aux enchères au premier prix, vous recevrez des commentaires en temps réel, y compris les champs minimum_bid_to_win et sampled_mediation_cpm_ahead_of_auction_winner si l'enchère n'a pas été filtrée de la mise aux enchères. Ces signaux peuvent servir à informer
de la logique d'enchères sur l'augmentation
ou la diminution que vous aurait pu atteindre
remporte l'impression.
minimum_bid_to_win: enchère minimale qui aurait pu être
pour remporter les enchères en temps réel. Si vous remportez l'enchère,
l'enchère la plus faible que vous auriez pu définir pour remporter l'enchère. Si vous avez perdu l'enchère, il s'agit de l'enchère gagnante.
sampled_mediation_cpm_ahead_of_auction_winner: si des
d'autres réseaux de la chaîne de médiation,
la valeur de ce champ est un prix représentant un exemple d'enchère pour l'un des
réseaux de médiation éligibles supérieurs au vainqueur de l'enchère, pondéré
en fonction du taux de remplissage attendu. Ce paramètre est défini sur 0 si aucun des réseaux
chaîne de médiation doit remplir, ou si l'éditeur n'utilise pas de SDK
la médiation.
Fonctionnement
Pour décrire les calculs utilisés pour déterminer les valeurs possibles pour minimum_bid_to_win et sampled_mediation_cpm_ahead_of_auction_winner, nous devons d'abord définir les éléments suivants :
Voici les CPM de la chaîne de médiation par ordre décroissant:
\[C_1, C_2, …, C_n\]
Vous trouverez ci-dessous les taux de remplissage correspondant aux CPM dans
chaîne de médiation:
\[f_1, f_2, …, f_n\]
Voici une fonction utilisée pour déterminer le CPM attendu et sa probabilité à partir de l'élément de chaîne de médiation \(i\), en fonction du taux de remplissage donné :
\(X_i = \{C_i\) avec une probabilité de \(f_i\) ; \(0\) avec une probabilité de \(1 - f_i\}\)
La chaîne de médiation gagnante finale sera:
\[\{C_1, C_2, …, C_K, W\}\]
où \(W\) correspond à l'enchère gagnante, et \(C_K > W >= C_{K+1}\)
Le prix de réserve, ou plancher, est indiqué par \(F\).
L'enchère secondaire est notée sous la forme \(R\).
Calculs pour le vainqueur des enchères
Champ
Calcul
minimum_bid_to_win
\(max\{F, R, X_{K+1}, …, X_n\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(\{C_i\) avec une probabilité \(\prod_{j=1}^{i-1}(1-f_j) \cdot f_i \div \prod_{j=1}^{K}(1-f_j)\}\)
Pour \(1 <= i <= K\).
Calculs pour le perdant de la mise aux enchères
Champ
Calcul
minimum_bid_to_win
\(max\{F, W\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(max\{X_1, …, X_K\}\)
Exemple avec une chaîne de médiation simple
Supposons qu'un éditeur utilise à la fois les enchères en temps réel et une chaîne de médiation de SDK comme suit :
Chaîne de médiation SDK
CPM attendu
Taux de remplissage
Réseau 1
\(C_1 = $3.00\)
\(f_1 = 5\%\)
Réseau 2
\(C_2 = $2.00\)
\(f_2 = 45\%\)
Réseau 3
\(C_3 = $0.50\)
\(f_3 = 80\%\)
Réseau 4
\(C_4 = $0.10\)
\(f_4 = 85\%\)
Supposons que les résultats de l'enchère RTB soient les suivants :
Enchères RTB
CPM
Vainqueur des enchères (W)
1,00 $
2e place aux enchères (R)
0,05 $
Prix de réserve / Prix plancher (F)
0 $
Enchère ayant remporté la mise aux enchères
Voici un exemple de la façon dont les valeurs et les probabilités pour
minimum_bid_to_win et
sampled_mediation_cpm_ahead_of_auction_winner sont calculés pour
l'enchère gagnante.
Voici un exemple de calcul des valeurs et des probabilités pour minimum_bid_to_win et sampled_mediation_cpm_ahead_of_auction_winner pour des enchères perdues.
minimum_bid_to_win
Probabilité
\(max(F, W) = $1.00\)
\(100\%\)
sampled_mediation_cpm_ ahead_of_auction_winner
Probabilité
\(C_1 = $3.00\)
\(f_1 = 5\%\)
\(C_2 = $2.00\)
\((1-f_1) \cdot f_2 =~ 42.8\%\)
\(0\)
\((1-f_1) \cdot (1-f_2) =~ 52.2\%\)
Aplatissement des enchères
Le dégroupement des enchères décrit le traitement d'un seul complexe
BidRequest en plusieurs demandes d'enchères envoyées à votre
application. Lorsqu'une demande d'enchères est aplatie, vous pouvez déterminer quelles demandes d'enchères faisaient partie de l'original, car elles auront une valeur identique dans le champ BidRequest.ext.google_query_id.
Le dégroupement des enchères est activé par défaut, mais vous pouvez contacter votre responsable de compte si vous préférez le désactiver.
Formats d'annonces
Certaines opportunités publicitaires peuvent accepter plusieurs formats. Avec le dégroupement des enchères,
est envoyé dans une demande d'enchère distincte dans laquelle les attributs tels que
numéros de compte de facturation correspondent au format spécifié dans la requête.
Les demandes d'enchères contenant les formats suivants seront dégroupées en demandes d'enchères distinctes :
Bannière
Vidéo
Audio
Natif
Exemple de format d'annonce aplati
Vous trouverez ci-dessous un exemple illustrant une demande d'enchère JSON OpenRTB simplifiée sans annonce
format aplati par rapport à un ensemble équivalent de requêtes aplaties:
Une opportunité d'annonce pour un enchérisseur donné peut s'appliquer à différents accords.
en plus des enchères ouvertes. Avec le dégroupement des enchères pour les accords, une enchère
est envoyée pour l'enchère ouverte et une pour chaque type
accord. En pratique, les contraintes des annonces peuvent différer entre enchères et prix fixes.
d'accords spécifiques, par exemple pour une opportunité d'annonce vidéo donnée
à la fois pour les enchères ouvertes et pour un accord à prix fixe, un enchérisseur reçoit
chaque demande d'enchère pour laquelle des contraintes, telles que la durée maximale de l'annonce,
peuvent être différentes. Par conséquent, l'aplatissement appliqué à l'opportunité publicitaire vous permet de discerner plus facilement les contraintes publicitaires pour l'enchère ouverte et l'accord à prix fixe.
Durée maximale des vidéos désactivables
Le protocole Google et l'implémentation OpenRTB acceptent les champs suivants
pour la durée et la désactivation de la vidéo:
Durée
Durée désactivable
Désactivation
Protocole Google
max_ad_duration
skippable_max_ad_duration
video_ad_skippable
OpenRTB
maxduration
n/a
skip
Cela signifie que même si le protocole Google peut comporter
et non désactivable, la mise en œuvre d'OpenRTB ne comporte
la valeur de durée maximale.
Avant l'aplatissement des enchères, maxduration d'OpenRTB était défini sur la valeur la plus basse des champs max_ad_duration et skippable_max_ad_duration du protocole Google. Ce comportement a maintenant changé pour envoyer deux demandes d'enchères distinctes lorsque ces valeurs diffèrent : l'une représentant maxduration pour les opportunités désactivables et l'autre pour les opportunités non désactivables.
Les exemples suivants montrent comment une requête de protocole Google est traduite en OpenRTB avant et après l'aplatissement des enchères. La requête de protocole Google équivalente a un max_ad_duration de 15 et un skippable_max_ad_duration de 60.
Exemple
max_ad_duration
skip (vrai OU faux)
Requête d'origine sans aplatissement
15
true
Demande dégroupée n° 1: annonces non désactivables
15
false
Demande dégroupée n° 2: désactivable
60
true
Le dégroupement des demandes d'enchères en fonction de la durée de la vidéo désactivable n'a lieu que
ces conditions sont remplies:
La demande autorise la vidéo.
Les vidéos désactivables et non désactivables sont autorisées, et les deux durées maximales respectives diffèrent.
Cette demande est compatible avec les enchères privées ou ouvertes.
Le compte du système d'enchères dispose de points de terminaison OpenRTB actifs.
Pour désactiver ce type de regroupement, contactez votre responsable de compte technique.
Séries d'annonces vidéo
Les demandes d'enchères pour une série d'annonces
vidéo avec plusieurs opportunités d'annonces sont dégroupées,
de sorte que chaque demande d'enchère concerne une opportunité d'annonce spécifique au sein de cette série d'annonces.
Cela vous permet de définir des enchères pour plusieurs opportunités d'annonces dans une série donnée.
Open Measurement
Open Measurement vous permet de spécifier des fournisseurs tiers qui fournissent des services de mesure et de validation indépendants pour les annonces diffusées dans les environnements d'applications mobiles.
Vous pouvez déterminer si un éditeur accepte Open Measurement dans le cadre de l'enchère
en vérifiant si l'opportunité d'annonce exclut l'attribut OmsdkType:
OMSDK 1.0 figurant dans la section Exclusible par l'éditeur
les attributs de création. Vous le trouverez sous l'attribut battr pour Bannière ou Vidéo, selon le format.
Pour en savoir plus sur l'interprétation des demandes d'enchères contenant des signaux Open Measurement, consultez l'article du Centre d'aide sur le SDK Open Measurement.
Exemples de demandes d'enchères
Les sections suivantes présentent des exemples de requêtes d'enchères pour différents types d'annonces.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2024/10/16 (UTC).
[null,null,["Dernière mise à jour le 2024/10/16 (UTC)."],[],[]]