Un'interazione con le offerte in tempo reale inizia quando Google invia una richiesta di offerta alla tua applicazione. Questa guida spiega come codificare l'applicazione per elaborare la richiesta di offerta.
Analizza la richiesta protobuf
Google invia una richiesta di offerta come buffer di protocollo serializzato allegato come
payload binario di una richiesta POST HTTP. L'opzione Content-Type è impostata su
application/octet-stream. Per un esempio, consulta Esempio di richiesta di offerta.
Devi analizzare questa richiesta in un'istanza del messaggio BidRequest. A seconda del protocollo scelto, BidRequest è definito in openrtb.proto o nel deprecated realtime-bidding.proto, che può essere ottenuto dalla pagina Dati di riferimento. Puoi analizzare il messaggio
utilizzando il metodo ParseFromString() nella classe generata per il
BidRequest. Ad esempio, il seguente codice C++ analizza una richiesta
dato un payload POST in una stringa:
string post_payload = /* the payload from the POST request */;
BidRequest bid_request;
if (bid_request.ParseFromString(post_payload)) {
// Process the request.
}
Una volta ottenuto il BidRequest, puoi utilizzarlo come oggetto, estraendo e interpretando i campi di cui hai bisogno. Ad esempio, nel
L'iterazione C++ attraverso i deal in una "BidRequest" di OpenRTB potrebbe avere il seguente aspetto:
le seguenti:
for (const BidRequest::Imp::Pmp::Deal& deal : pmp.deals()) {
DoSomething(deal.id(), deal.wseat());
}
ID fatturazione
Ricevi una richiesta di offerta quando l'inventario pubblicitario di un publisher viene scelto come target
uno o più dei tuoi
configurazioni di pretargeting. BidRequest.imp.ext.billing_id
viene compilato con gli ID fatturazione di tutti gli acquirenti idonei e con le configurazioni di pretargeting pertinenti. Inoltre, per
offerta
inventario, puoi trovare gli ID fatturazione associati all'acquirente pertinente
utilizzando BidRequest.imp.pmp.deal.ext.billing_id. Solo gli ID fatturazione di
gli acquirenti inclusi nella richiesta di offerta possono essere specificati al momento di presentare un'offerta.
Se nella richiesta di offerta sono inclusi più ID fatturazione, devi specificare
L'ID fatturazione dell'acquirente a cui intendi attribuire l'offerta con
campo BidResponse.seatbid.bid.ext.billing_id.
File di dizionario
La richiesta di offerta utilizza gli identificatori definiti nei file di dizionario, disponibili nella pagina Dati di riferimento.
Macro dell'URL dell'offerta del protocollo RTB di Google
Facoltativamente, alcuni campi del BidRequest possono essere inseriti nell'URL utilizzato nella richiesta POST HTTP. Questo è utile, ad esempio, se utilizzi
un frontend leggero che viene bilanciato su più backend utilizzando un valore
dalla richiesta. Contatta il tuo Technical Account Manager per richiedere assistenza per le nuove macro.
Macro
Descrizione
%%GOOGLE_USER_ID%%
Sostituito con google_user_id
dal BidRequest. Ad esempio, l'URL dell'offerente
Il risultato corrisponde all'app per Android
slither.io.
Campi di Open Bidding
Le richieste di offerta inviate agli offerenti di piattaforme di scambio e reti che partecipano a Open Bidding sono simili a quelle di Authorized Buyers che partecipano alle offerte in tempo reale standard. I clienti Open Bidding riceveranno un numero limitato di campi aggiuntivi e alcuni campi esistenti potrebbero avere utilizzi alternativi. tra cui:
OpenRTB
Authorized Buyers
Dettagli
BidRequest.imp[].ext.dfp_ad_unit_code
BidRequest.adslot[].dfp_ad_unit_code
Contiene il codice di rete Ad Manager del publisher seguito dalla gerarchia delle unità pubblicitarie, separata da barre.
Ad esempio, verrà visualizzato con una formattazione simile a:
/1234/cruises/mars.
BidRequest.user.data[].segment[]
BidRequest.adslot[].exchange_bidding.key_value[]
Coppie chiave-valore ripetute inviate dal publisher all'offerente della piattaforma di scambio.
Puoi stabilire che i valori sono coppie chiave-valore inviate dall'editore quando BidRequest.user.data[].name è impostato su “Publisher Passed”.
Dichiara i fornitori consentiti
I fornitori di tecnologia che offrono servizi come ricerca, remarketing e pubblicazione di annunci possono svolgere un ruolo nell'interazione tra acquirenti e venditori. Sono consentiti solo i fornitori che sono stati sottoposti a verifica da parte di Google per la partecipazione alle interazioni con Authorized Buyers.
Per comprendere il BidRequest e creare i tuoi
BidResponse, è necessario conoscere le due diverse
possibilità di dichiarare i fornitori di tecnologia:
Altri fornitori possono partecipare solo se sono dichiarati in
BidRequest:
In BidRequest,
Il campo BidRequest.imp.ext.allowed_vendor_type specifica
i fornitori consentiti dal venditore. I fornitori che verranno inviati
allowed_vendor_type sono elencati in
vendors.txt
del dizionario.
Esempio di richiesta di offerta
Gli esempi riportati di seguito rappresentano esempi leggibili delle richieste Protobuf e JSON.
Per convertire la richiesta di offerta in un formato binario, come si ottiene
payload POST in una richiesta reale, puoi fare quanto segue (in C++). Tieni presente che
tuttavia, questo non è applicabile al file 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
}
}
Feedback in tempo reale
Authorized Buyers ha a disposizione anche il feedback in tempo reale,
delle piattaforme di scambio pubblicitario e delle reti
usando Open Bidding.
Il feedback sulla risposta all'offerta è supportato nella richiesta di offerta successiva sia per OpenRTB sia per il protocollo Google RTB deprecato. Per OpenRTB, viene inviato in
BidRequest.ext.bid_feedback.
Oltre ai campi predefiniti inviati in Feedback sulle risposte all'offerta, puoi
anche inviare dati personalizzati nella risposta all'offerta utilizzando
campo BidResponse.seatbid.bid.ext.event_notification_token. La
event_notification_token è un dato arbitrario noto solo al
strumento di offerta che potrebbe essere utile per il debug, ad esempio un nuovo ID targeting oppure
ID asta che rappresenta una nuova tattica o metadati associati alla creatività
noti solo all'offerente. Per maggiori dettagli, consulta
OpenRTB Extensions Protocol Buffer
per OpenRTB o il deprecated
Google RTB protocol.
Quando Authorized Buyers invia una richiesta di offerta a un offerente, quest'ultimo risponde con un BidResponse. Se per l'offerente è attivato
il feedback in tempo reale,
in una successiva richiesta di offerta, Authorized Buyers invia un feedback
risposta in un messaggio BidFeedback:
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;
}
Da questo messaggio, il primo campo da controllare è
bid_feedback.creative_status_code; puoi trovare il codice
significato in
creative-status-codes.txt. Tieni presente che se vinci l'offerta, puoi disattivarla
dal feedback sul prezzo. Per ulteriori informazioni, consulta la sezione Come disattivare.
Il feedback in tempo reale include l'ID richiesta di offerta e uno dei seguenti elementi:
Risultato dell'asta
Feedback in tempo reale
L'acquirente non ha inviato un'offerta.
Niente.
L'acquirente ha inviato un'offerta che è stata filtrata prima di raggiungere
l'asta.
L'acquirente ha presentato un'offerta, ma ha perso l'asta.
Il codice di stato della creatività 79 (offerta superiore nell'asta).
L'acquirente ha inviato un'offerta che ha vinto l'asta.
Il prezzo di compensazione e il codice di stato della creatività 1.
Per un'impressione dell'app e un codice di stato della creatività pari a 83, il valore
che il publisher di app potrebbe aver utilizzato una struttura a cascata di mediazione.
un'offerta vincente sarebbe stata in concorrenza con un'altra domanda nel campo
una struttura a cascata di pass-back. Scopri come utilizzare
sampled_mediation_cpm_ahead_of_auction_winner quando
fai offerte.
Esempio
Di seguito è riportato un esempio di feedback in tempo reale come visualizzato nei protocolli supportati:
Creare un modello di offerta per le aste al primo prezzo
Dopo aver fatto un'offerta nell'asta al primo prezzo, riceverai in tempo reale
feedback tra cui minimum_bid_to_win e
sampled_mediation_cpm_ahead_of_auction_winner campi se l'offerta
non è stato filtrato dall'asta. Questi indicatori possono essere utilizzati per
logica di offerta su quanto avrebbe potuto essere più o meno alta la tua offerta per
conquistare l'impressione.
minimum_bid_to_win: l'offerta minima che avrebbe potuto essere
posizionati per vincere l'asta con offerte in tempo reale. Se hai vinto l'asta, questa sarà
l'offerta più bassa che avresti potuto fare per vincere. Se perdi
questa sarà l'offerta vincente.
sampled_mediation_cpm_ahead_of_auction_winner: se nella catena di mediazione sono presenti altre reti, il valore di questo campo è un prezzo che rappresenta un'offerta di esempio di una delle reti di mediazione idonee superiore a quella del vincitore dell'asta, ponderato in base al tasso di riempimento previsto. Questo valore verrà impostato su 0 se non è previsto che nessuna delle reti nella catena di mediazione venga riempita o se il publisher non utilizza la mediazione tramite SDK.
Come funziona
Al fine di descrivere i calcoli utilizzati per determinare i valori possibili,
per minimum_bid_to_win e
sampled_mediation_cpm_ahead_of_auction_winner, per prima cosa dobbiamo
definire quanto segue:
Di seguito sono riportati i CPM nella catena di mediazione in ordine decrescente:
\[C_1, C_2, …, C_n\]
Di seguito sono riportati i tassi di riempimento corrispondenti per i CPM nella
catena di mediazione:
\[f_1, f_2, …, f_n\]
Di seguito è riportata una funzione utilizzata per determinare il CPM previsto e i relativi
probabilità dall'elemento della catena di mediazione \(i\), in base al riempimento specificato
conv.:
\(X_i = \{C_i\) con probabilità \(f_i\); \(0\) con probabilità \(1 - f_i\}\)
La catena di mediazione vincente finale sarà:
\[\{C_1, C_2, …, C_K, W\}\]
dove \(W\) è l'offerta vincente e \(C_K > W >= C_{K+1}\)
Il prezzo di riserva, o minimo, è indicato come \(F\).
L'offerta secondo la classifica è indicata come \(R\).
Calcoli per il vincitore dell'asta
Campo
Calcolo
minimum_bid_to_win
\(max\{F, R, X_{K+1}, …, X_n\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(\{C_i\) con probabilità \(\prod_{j=1}^{i-1}(1-f_j) \cdot f_i \div \prod_{j=1}^{K}(1-f_j)\}\)
Per \(1 <= i <= K\).
Calcoli per la persona perdente dell'asta
Campo
Calcolo
minimum_bid_to_win
\(max\{F, W\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(max\{X_1, …, X_K\}\)
Esempio con una catena di mediazione semplice
Supponiamo che un publisher utilizzi sia le offerte in tempo reale sia una catena di mediazione SDK come segue:
Catena di mediazione SDK
CPM previsto
Tasso di riempimento
Rete 1
\(C_1 = $3.00\)
\(f_1 = 5\%\)
Rete 2
\(C_2 = $2.00\)
\(f_2 = 45\%\)
Rete 3
\(C_3 = $0.50\)
\(f_3 = 80\%\)
Rete 4
\(C_4 = $0.10\)
\(f_4 = 85\%\)
Supponiamo che il risultato dell'asta RTB sia il seguente:
Asta RTB
CPM
Vincitore dell'asta (M)
1,00 $
Secondo classificato dell'asta (R)
$ 0,05
Prezzo di riserva / minimo (F)
0 $
Offerta che ha vinto l'asta
Di seguito è riportato un esempio di come vengono calcolati i valori e le probabilità per minimum_bid_to_win e sampled_mediation_cpm_ahead_of_auction_winner per un'offerta vincente.
Di seguito è riportato un esempio di come valori e probabilità per
minimum_bid_to_win e
Il valore sampled_mediation_cpm_ahead_of_auction_winner viene calcolato per
le offerte perse.
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\%\)
Appiattimento delle offerte
La suddivisione delle offerte descrive l'elaborazione di un singolo BidRequest complesso in più richieste di offerta inviate alla tua applicazione. Quando una richiesta di offerta viene appiattita, puoi capire quali richieste di offerta fanno parte dell'originale perché avranno un valore identico nel campo BidRequest.ext.google_query_id.
La suddivisione delle offerte è attivata per impostazione predefinita, ma puoi contattare il tuo account
se preferisci disattivarlo.
Formati degli annunci
Alcune opportunità di annunci possono accettare più formati. Con la semplificazione delle offerte, ogni formato viene inviato in una richiesta di offerta distinta in cui gli attributi come gli ID fatturazione idonei sono pertinenti al formato specificato nella richiesta.
Le richieste di offerta contenenti i seguenti formati verranno suddivise in
richieste di offerta distinte:
Banner
Video
Audio
Nativo
Esempio di suddivisione dei formati dell'annuncio
Di seguito è riportato un esempio che mostra una richiesta di offerta JSON OpenRTB semplificata senza annuncio
suddivisione del formato rispetto a un insieme equivalente di richieste suddivise:
Un'opportunità di annuncio per un determinato offerente può essere applicabile a diversi deal
di archiviazione, oltre che all'asta aperta. Con la suddivisione delle offerte per i deal, verrà inviata una richiesta di offerta per l'asta aperta e una per ogni tipo di deal a prezzo fisso. In pratica, i vincoli degli annunci possono differire tra le aste e il prezzo fisso
tipi di deal, ad esempio per una determinata opportunità di annunci video disponibile
sia l'asta aperta sia un'offerta a prezzo fisso, l'offerente riceve
richieste di offerta per ciascuno, in cui vincoli come la durata massima degli annunci e
gli annunci ignorabili possono variare. Di conseguenza, l'appiattimento applicato all'opportunità pubblicitaria ti consente di distinguere più facilmente i vincoli degli annunci per l'asta aperta e il deal a prezzo fisso.
Durata massima video ignorabile
Il protocollo di Google e l'implementazione di OpenRTB supportano i seguenti campi
per conoscere la durata del video e la possibilità di ignorare:
Durata
Durata ignorabile
Possibilità di ignorare gli annunci
Protocollo Google
max_ad_duration
skippable_max_ad_duration
video_ad_skippable
OpenRTB
maxduration
n/a
skip
Ciò significa che, mentre il protocollo Google può avere una durata granulare ignorabile e non ignorabile, l'implementazione OpenRTB ha un solo valore di durata massima.
Prima dell'appiattimento delle offerte, il valore maxduration di OpenRTB veniva impostato sul valore più basso dei campi max_ad_duration e skippable_max_ad_duration del protocollo Google. Questo comportamento è cambiato in
inviando due richieste di offerta distinte quando questi valori sono diversi: una che rappresenta
maxduration per gli annunci ignorabili e l'altro per quelli non ignorabili
di Google Cloud.
Gli esempi riportati di seguito mostrano come una richiesta di protocollo Google viene tradotta in OpenRTB prima e dopo l'appiattimento delle offerte. Il protocollo Google equivalente
ha un valore max_ad_duration di 15 e un
skippable_max_ad_duration di 60.
Esempio
max_ad_duration
skip (vero OR falso)
Richiesta originale senza suddivisione
15
true
Richiesta uniforme n. 1: non ignorabile
15
false
Richiesta uniformata n. 2: ignorabile
60
true
La suddivisione delle richieste di offerta in base alla durata dei video ignorabili viene eseguita solo se sono soddisfatte queste condizioni:
Questa richiesta consente l'uso di video.
Sono consentiti sia i video ignorabili che quelli non ignorabili e le due rispettive durate massime differiscono nel valore.
Questa richiesta è idonea per l'asta privata o l'asta aperta.
L'account dell'offerente dispone di endpoint OpenRTB attivi.
Per disattivare questo tipo di suddivisione, contatta il tuo team
account manager.
Pod video
Le richieste di offerta per un pod video con più opportunità pubblicitarie vengono appiattite,
in modo che ogni richiesta di offerta riguardi una singola opportunità pubblicitaria del pod.
In questo modo puoi fare offerte per più opportunità pubblicitarie per un determinato pod.
Open Measurement
Con Open Measurement puoi specificare i fornitori di terze parti che offrono
servizi indipendenti di misurazione e verifica per gli annunci pubblicati in app mobile
ambienti cloud-native.
Puoi determinare se un publisher supporta Open Measurement nella richiesta di offerta controllando se l'opportunità pubblicitaria esclude l'attributo OmsdkType:
OMSDK 1.0 presente negli attributi della creatività escludibili dal publisher. Questo valore si trova nell'attributo battr per banner o video, a seconda del formato.
Per ulteriori informazioni su come interpretare le richieste di offerta contenenti
Per gli indicatori di misurazione, consulta Open Measurement
SDK.
Esempi di richieste di offerta
Le sezioni seguenti mostrano richieste di offerta di esempio per diversi tipi di annunci.
