Una interacción de ofertas en tiempo real comienza cuando Google envía una solicitud de oferta a
tu aplicación. En esta guía, se explica cómo codificar tu aplicación para
procesar la solicitud de oferta.
Cómo analizar la solicitud de Protobuf
Google envía una solicitud de oferta como un búfer de protocolo serializado adjunto como la carga útil binaria de una solicitud HTTP POST. Content-Type se establece en
application/octet-stream Consulta Ejemplo de solicitud de oferta para obtener un ejemplo.
Debes analizar esta solicitud en una instancia de BidRequest.
mensaje. Según el protocolo que hayas elegido, se definirá BidRequest
en openrtb.proto o la versión obsoleta
realtime-bidding.proto, que se puede obtener de la
página de datos de referencia. Puedes analizar el mensaje con el método ParseFromString() en la clase generada para BidRequest. Por ejemplo, el siguiente código C++ analiza una solicitud
dada una carga útil POST en una cadena:
string post_payload = /* the payload from the POST request */;
BidRequest bid_request;
if (bid_request.ParseFromString(post_payload)) {
// Process the request.
}
Una vez que tengas el elemento BidRequest, podrás trabajar con él como un
extraiga y, luego, interprete los campos que necesites. Por ejemplo, en C++, iterar por las ofertas en una "BidRequest" de OpenRTB podría verse de la siguiente manera:
for (const BidRequest::Imp::Pmp::Deal& deal : pmp.deals()) {
DoSomething(deal.id(), deal.wseat());
}
IDs de facturación
Recibirás una solicitud de oferta cuando una o más de tus configuraciones de orientación previa se segmenten para el inventario de anuncios de un publicador. BidRequest.imp.ext.billing_id se propagará con los IDs de facturación de los compradores aptos y las configuraciones de segmentación previa relevantes. Además, para el inventario de ofertas, puedes encontrar los IDs de facturación asociados con el comprador relevante con BidRequest.imp.pmp.deal.ext.billing_id. Cuando se realiza una oferta, solo se pueden especificar los IDs de facturación de los compradores incluidos en la solicitud de oferta.
Si se incluyen varios IDs de facturación en la solicitud de oferta, debes especificar
el ID de facturación del comprador al que quieres atribuir tu oferta con el
BidResponse.seatbid.bid.ext.billing_id.
Archivos de diccionario
La solicitud de oferta utiliza identificadores definidos en archivos de diccionario, que se
disponible en los datos de referencia
.
Macros de URL de oferta del protocolo de RTB de Google
De manera opcional, algunos campos de BidRequest se pueden insertar en la URL que se usa en la solicitud HTTP POST. Esto es útil, por ejemplo, si usas
un frontend ligero que balancea las cargas en múltiples backends usando un valor
de la solicitud. Comunícate con tu administrador técnico de cuentas para solicitar asistencia
las nuevas macros.
Macro
Descripción
%%GOOGLE_USER_ID%%
Se reemplazó por el google_user_id de BidRequest. Por ejemplo, la URL del ofertante
El resultado equivale a la app para Android
slither.io.
Campos de Open Bidding
Las solicitudes de oferta se envían a los ofertantes de intercambio y de red que participan en Open Bidding
Las ofertas son similares a las de los compradores de Authorized Buyers que participan en el
con las ofertas en tiempo real. Los clientes de Open Bidding recibirán una pequeña cantidad de campos adicionales, y algunos campos existentes pueden tener usos alternativos. Entre estas, se incluyen las siguientes:
OpenRTB
Authorized Buyers
Detalles
BidRequest.imp[].ext.dfp_ad_unit_code
BidRequest.adslot[].dfp_ad_unit_code
Contiene el código de red de Ad Manager del publicador seguido del anuncio.
de unidades, separadas por barras diagonales.
A modo de ejemplo, esto aparecería con un formato similar al siguiente:
/1234/cruises/mars
BidRequest.user.data[].segment[]
BidRequest.adslot[].exchange_bidding.key_value[]
Pares clave-valor repetidos que se envían del publicador al ofertante del intercambio.
Puedes determinar que los valores son pares clave-valor que envía el publicador cuando BidRequest.user.data[].name se establece en “Publisher Passed”.
Cómo declarar proveedores permitidos
Los proveedores de tecnología que proporcionan servicios como investigación, remarketing y publicación de anuncios pueden desempeñar un papel en la interacción entre compradores y vendedores. Solo
proveedores que Google aprobó para participar en Authorized Buyers
se permiten interacciones.
Para comprender el BidRequest y crear tu BidResponse, debes conocer las dos posibilidades diferentes para declarar proveedores de tecnología:
Otros proveedores solo pueden participar si se declaran en BidRequest:
En BidRequest, el campo BidRequest.imp.ext.allowed_vendor_type especifica qué proveedores permite el vendedor. Los proveedores que se enviarán en el
allowed_vendor_type se incluyen en la
vendors.txt
de diccionario.
Ejemplo de solicitud de oferta
En los siguientes ejemplos, se representan muestras legibles por humanos de las solicitudes de Protobuf y JSON.
Para convertir la solicitud de oferta en un formato binario, como lo harías con la carga útil POST en una solicitud real, puedes hacer lo siguiente (en C++). Sin embargo, ten en cuenta que esto no se aplica a JSON de 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
}
}
Comentarios en tiempo real
Los comentarios en tiempo real también están disponibles para Authorized Buyers
como intercambios y redes con Open Bidding.
Los comentarios de la respuesta a la oferta se admiten en la solicitud de oferta posterior tanto para
OpenRTB y el protocolo RTB de Google obsoleto. Para OpenRTB, se envía en
BidRequest.ext.bid_feedback
Además de los campos predeterminados que se envían en los comentarios de la respuesta de la oferta, también puedes enviar datos personalizados en la respuesta de la oferta con el campo BidResponse.seatbid.bid.ext.event_notification_token. event_notification_token son datos arbitrarios que solo conoce el ofertante y que pueden ayudar con la depuración, por ejemplo, un nuevo ID de segmentación o ID de oferta que representa una táctica nueva, o metadatos asociados con la creatividad que solo conoce el ofertante. Para obtener más información, consulta el Búfer de protocolo de extensiones de OpenRTB para OpenRTB o el protocolo de RTB de Google obsoleto.
Cuando Authorized Buyers envía una solicitud de oferta a un ofertante, este responde con un BidResponse. Si el ofertante tiene habilitados los comentarios en tiempo real, en una solicitud de oferta posterior, Authorized Buyers envía comentarios sobre la respuesta en un mensaje 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;
}
En este mensaje, el primer campo que debes verificar es bid_feedback.creative_status_code. Puedes encontrar el significado del código en creative-status-codes.txt. Ten en cuenta que si ganas la oferta, puedes inhabilitar
a partir de los comentarios sobre el precio. Para obtener más información, consulta Cómo
el rechazo de las comunicaciones.
Los comentarios en tiempo real incluyen el ID de solicitud de oferta y una de las
lo siguiente:
Resultado de la subasta
Comentarios en tiempo real
El comprador no envió una oferta.
Nada.
El comprador envió una oferta que se filtró antes de llegar
durante la subasta.
El comprador envió una oferta, pero perdió la subasta.
El código de estado de la creatividad 79 (se superó la oferta en la subasta)
El comprador envió una oferta que ganó la subasta.
El precio de liquidación y el código de estado de la creatividad 1
En el caso de una impresión de aplicación y un código de estado de creatividad de 83, la
el publicador de aplicaciones podría haber usado una cascada de mediación y, por lo tanto,
ganadora habría compitido contra otra demanda en la
de una cadena de cascada de devoluciones. Aprende a utilizar
sampled_mediation_cpm_ahead_of_auction_winner cuando
con las ofertas.
Muestra
El siguiente es un ejemplo de comentarios en tiempo real, como se ve en los protocolos compatibles:
Crea un modelo de ofertas para subastas de primer precio
Después de realizar una oferta en una subasta de primer precio, recibirás comentarios en tiempo real, incluidos los campos minimum_bid_to_win y sampled_mediation_cpm_ahead_of_auction_winner, si la oferta no se filtró de la subasta. Estos indicadores se pueden usar para fundamentar tu lógica de ofertas sobre qué tan alta o baja podría haber sido tu oferta para ganar la impresión.
minimum_bid_to_win: la oferta mínima que se podría haber
para ganar la subasta de ofertas en tiempo real. Si ganaste la subasta, esto
sería la oferta más baja que podrías haber hecho y, al mismo tiempo, seguir ganando. Si perdiste la subasta, esta será la oferta ganadora.
sampled_mediation_cpm_ahead_of_auction_winner: Si hay otras redes en la cadena de mediación, el valor de este campo es un precio que representa una oferta de muestra de una de las redes de mediación aptas que fue más alta que la oferta ganadora de la subasta, ponderada por la tasa de relleno esperada. Este valor se establecerá en 0 si ninguna de las redes de la
se espera que llene la cadena de mediación, o si el publicador no usa un SDK
mediación.
Cómo funciona
Para describir los cálculos que se usan para determinar los valores posibles para minimum_bid_to_win y sampled_mediation_cpm_ahead_of_auction_winner, primero debemos definir lo siguiente:
A continuación, se muestran los CPM de la cadena de mediación en orden descendente:
\[C_1, C_2, …, C_n\]
A continuación, se muestran las tasas de relleno correspondientes a los CPM de la
cadena de mediación:
\[f_1, f_2, …, f_n\]
La siguiente es una función que se usa para determinar el CPM esperado y su
probabilidad del elemento de la cadena de mediación \(i\), según el relleno especificado
calificación:
\(X_i = \{C_i\) con probabilidad \(f_i\); \(0\) con probabilidad \(1 - f_i\}\)
La última cadena de mediación ganadora será la siguiente:
\[\{C_1, C_2, …, C_K, W\}\]
en el que \(W\) es la oferta ganadora y \(C_K > W >= C_{K+1}\)
El precio de reserva, o mínimo, se indica como \(F\).
La oferta en segundo lugar se indica como \(R\).
Cálculos para el ganador de la subasta
Campo
Cálculo
minimum_bid_to_win
\(max\{F, R, X_{K+1}, …, X_n\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(\{C_i\) con probabilidad \(\prod_{j=1}^{i-1}(1-f_j) \cdot f_i \div \prod_{j=1}^{K}(1-f_j)\}\)
Para \(1 <= i <= K\).
Cálculos para el perdedor de la subasta
Campo
Cálculo
minimum_bid_to_win
\(max\{F, W\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(max\{X_1, …, X_K\}\)
Ejemplo con una cadena de mediación simple
Supongamos que un publicador usa licitación en tiempo real
y una cadena de mediación de SDK
sigue:
Cadena de mediación de SDK
CPM esperado
Tasa de relleno
Red 1
\(C_1 = $3.00\)
\(f_1 = 5\%\)
Red 2
\(C_2 = $2.00\)
\(f_2 = 45\%\)
Red 3
\(C_3 = $0.50\)
\(f_3 = 80\%\)
Red 4
\(C_4 = $0.10\)
\(f_4 = 85\%\)
Como resultado de la subasta de RTB, supón lo siguiente:
Subasta de RTB
CPM
Ganador de la subasta (W)
USD 1.00
Subcampeón de la subasta (R)
$0.05
Precio de reserva/precio mínimo (F)
USD 0
Oferta que ganó la subasta
El siguiente es un ejemplo de cómo se calculan los valores y las probabilidades de minimum_bid_to_win y sampled_mediation_cpm_ahead_of_auction_winner para una oferta que ganó.
El siguiente es un ejemplo de cómo los valores y las probabilidades para
minimum_bid_to_win y
sampled_mediation_cpm_ahead_of_auction_winner se calculan para un
ofertas que perdieron.
minimum_bid_to_win
Probabilidad
\(max(F, W) = $1.00\)
\(100\%\)
sampled_mediation_cpm_ ahead_of_auction_winner
Probabilidad
\(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\%\)
Separación de ofertas
La separación de ofertas describe el procesamiento de una única estrategia
BidRequest en varias solicitudes de oferta que se envían a su
y mantener la integridad de su aplicación. Cuando se aplana una solicitud de oferta, puedes saber cuáles solicitudes de oferta formaron parte de la original, ya que tendrán un valor idéntico en el campo BidRequest.ext.google_query_id.
La separación de ofertas está habilitada de forma predeterminada, pero puede comunicarse con su cuenta
de administrador si prefieres inhabilitarla.
Formatos de anuncios
Algunas oportunidades de anuncios pueden aceptar varios formatos. Con la separación de ofertas, cada
se envía en una solicitud de oferta distinta en la que los atributos como
Los IDs de facturación son relevantes para el formato especificado en la solicitud.
Las solicitudes de oferta que contengan los siguientes formatos se separarán en solicitudes de oferta distintas:
Banner
Video
Audio
Nativo
Ejemplo de compactación del formato del anuncio
A continuación, se muestra un ejemplo de una solicitud de oferta JSON de OpenRTB simplificada sin aplanar el formato del anuncio en comparación con un conjunto equivalente de solicitudes aplanadas:
Una oportunidad de anuncio para un ofertante determinado puede aplicarse a varios acuerdos.
nuevos, además de la subasta abierta. Con la separación de ofertas para los acuerdos, una oferta
una solicitud para la subasta abierta y una para cada tipo de precio fijo
de un acuerdo de precios. En la práctica, las restricciones de anuncios pueden diferir entre las subastas y las de precio fijo
tipos de acuerdos, por ejemplo, para una determinada oportunidad de anuncio de video que esté disponible para
en la subasta abierta y en el acuerdo de precio fijo, el ofertante recibirá
solicitudes de oferta para cada una en las que existan restricciones, como la duración máxima del anuncio y si
que se permiten los anuncios que se pueden omitir pueden variar. Como resultado, la aplanación aplicada a la oportunidad de anuncios te permite discernir con mayor facilidad las restricciones de anuncios para la subasta abierta y el acuerdo de precio fijo.
Duración máxima de video que se puede omitir
El protocolo de Google y la implementación de OpenRTB admiten los siguientes campos para la duración y la posibilidad de omitir el video:
Duración
Duración que se puede omitir
Posibilidad de omitir
Protocolo de Google
max_ad_duration
skippable_max_ad_duration
video_ad_skippable
OpenRTB
maxduration
N/A
skip
Esto significa que, si bien el protocolo de Google puede tener una capa
y de duración que no se puede omitir, la implementación de OpenRTB solo tiene un
de duración máxima.
Antes de la compactación de ofertas, el valor maxduration de OpenRTB se configuraba como
el valor inferior de la max_ad_duration del protocolo de Google y
skippable_max_ad_duration. Este comportamiento ahora cambió para enviar dos solicitudes de oferta independientes cuando estos valores difieren: una que representa el maxduration para las oportunidades que se pueden omitir y la otra para las que no se pueden omitir.
En los siguientes ejemplos, se muestra cómo se traduce una solicitud de protocolo de Google
con OpenRTB antes y después de la separación de ofertas. La solicitud de protocolo de Google equivalente tiene un max_ad_duration de 15 y un skippable_max_ad_duration de 60.
Ejemplo
max_ad_duration
skip (verdadero O falso)
Solicitud original sin aplanar
15
true
Solicitud plana n° 1: No se puede omitir
15
false
Solicitud nivelada n° 2: Se puede omitir
60
true
La separación de solicitudes de ofertas de duración de video que se puede omitir solo se realizará cuando se cumplan estas condiciones:
La solicitud permite el video.
Se permiten videos que se pueden omitir y que no se pueden omitir, y las dos duraciones máximas respectivas difieren en valor.
Esta solicitud es apta para subasta privada o subasta abierta.
La cuenta del ofertante tiene extremos OpenRTB activos.
Para inhabilitar este tipo de compactación, comunícate con tu
administrador de cuentas.
Grupos de anuncios de video
Las solicitudes de oferta para un grupo de anuncios de video con varias oportunidades de anuncios se aplanan, de modo que cada solicitud de oferta sea para una oportunidad de anuncio individual de ese grupo.
Esto te permite ofertar por varias oportunidades de anuncios para un grupo determinado.
Open Measurement
Open Measurement te permite especificar proveedores externos que ofrecen
servicios independientes de medición y verificación para los anuncios que se publican en aplicaciones para dispositivos móviles
entornos de prueba.
Puede determinar si un publicador admite Open Measurement en la oferta.
solicitud comprobando si la oportunidad de anuncio excluye el atributo OmsdkType:
OMSDK 1.0 que se encuentra en Exclusivo por el publicador
atributos de creatividades. Se encuentra en el atributo battr para Banner o Video, según el formato.
Para obtener más información sobre cómo interpretar las solicitudes de oferta que contienen Open
Indicadores de medición, consulta Open Measurement
SDK.
Ejemplos de solicitudes de oferta
Las siguientes secciones muestran solicitudes de oferta de ejemplo para diferentes tipos de anuncios.
