Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
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.
Analizar solicitud
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. El Content-Type se establece en application/octet-stream. Consulta Ejemplo de solicitud de oferta para ver un ejemplo.
Debes analizar esta solicitud en una instancia del mensaje BidRequest. BidRequest se define en 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 el BidRequest. Por ejemplo, el siguiente código de C++ analiza una solicitud a partir de una carga útil POST en una string:
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 BidRequest, podrás trabajar con él como un objeto mediante la extracción y la interpretación de los campos que necesitas. Por ejemplo, en C++:
for (int i = 0; i < bid_request.adslot_size(); ++i) {
const BidRequest_AdSlot& adslot = bid_request.adslot(i);
// Decide what to bid on adslot.
}
Parte de la información que se envía en un objeto BidRequest, como el ID de usuario de Google, el idioma o la ubicación geográfica, no siempre está disponible. Si tienes
grupos de anuncios con segmentación previa que usan información desconocida para una impresión determinada, esos grupos de anuncios no coincidirán. En los casos en que la información que falta no importa para las condiciones de segmentación previa, las solicitudes de ofertas se envían con la información omitida.
La información sobre el grupo de anuncios de segmentación previa está disponible en el grupo MatchingAdData de cada AdSlot. Contiene el
ID del primer grupo de anuncios coincidente del grupo de anuncios de segmentación previa que le pidió a Google
que enviara la solicitud de oferta, es decir, el grupo de anuncios y la campaña que se cobran
si tu respuesta gana la subasta por la impresión. En determinadas circunstancias, debes especificar explícitamente el billing_id para la atribución en BidResponse.AdSlot, por ejemplo, cuando BidRequest.AdSlot tiene más de un matching_ad_data.
Para obtener más información sobre las restricciones del contenido de la oferta, consulta realtime-bidding.proto.
Archivos de diccionario
La solicitud de oferta utiliza identificadores definidos en los archivos de diccionario, que están disponibles en la página de datos de referencia.
Macros de URL de oferta
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 de varios backends con un valor de la solicitud. Comunícate con tu administrador técnico de cuentas a fin de solicitar asistencia para las macros nuevas.
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 que se envían a los ofertantes de red y de intercambio que participan en Open Bidding son similares a las de Authorized Buyers que participan en las ofertas estándar en tiempo real. Los clientes de Open Bidding recibirán una pequeña cantidad de campos adicionales, y es posible que algunos de los campos existentes tengan usos alternativos. Estos son algunos ejemplos:
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 de la jerarquía de la
unidad de anuncios, separado por barras diagonales.
Por ejemplo, esto aparecería con un formato similar a: /1234/cruises/mars.
BidRequest.user.data[].segment[]
BidRequest.adslot[].exchange_bidding.key_value[]
Son los pares clave-valor repetidos que se envían del publicador al ofertante de intercambio.
Puedes determinar si 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 una función en la interacción entre compradores y vendedores. Solo se permiten los proveedores que Google aprobó para participar en interacciones de Authorized Buyers.
Para comprender el BidRequest y crear tu BidResponse, debes tener en cuenta las dos posibilidades diferentes para declarar proveedores de tecnología:
Otros proveedores solo pueden participar si se declaran en BidRequest y BidResponse:
En el BidRequest, el campo allowed_vendor_type especifica qué proveedores permite el vendedor. Los proveedores que se enviarán en el campo allowed_vendor_type de BidRequest se enumeran en el archivo de diccionario Vendors.txt.
En BidResponse, el campo vendor_type especifica cuál de esos proveedores permitidos es el que el comprador desea usar.
Ejemplo de solicitud de oferta
Los siguientes ejemplos representan muestras legibles de las solicitudes de Protobuf y JSON.
Para convertir la solicitud de oferta en un formato binario, como obtendrías de la carga útil POST en una solicitud real, puedes hacer lo siguiente (en C++). Sin embargo, ten en cuenta que esto no es aplicable a OpenRTB JSON.
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
}
}
Remarketing
Authorized Buyers pasa un ID de publicidad para dispositivos móviles en las solicitudes de oferta de una aplicación para dispositivos móviles. El ID de publicidad para dispositivos móviles puede ser un IDFA de iOS o un
ID de publicidad de Android, que se envía a través de la macro %%EXTRA_TAG_DATA%% en la etiqueta de JavaScript administrada por Authorized Buyers.
La macro %%ADVERTISING_IDENTIFIER%% permite a los compradores recibir el IDFA de iOS o el ID de publicidad de Android durante la renderización de impresiones. Muestra un búfer de proto encriptado MobileAdvertisingId, como %%EXTRA_TAG_DATA%%:
Puedes crear listas de usuarios a partir de los ID de publicidad para dispositivos móviles mediante los ID de publicidad que recopilaste durante la renderización de impresiones. Estas listas de usuarios se pueden mantener
en tu servidor o en el nuestro. Para crear listas de usuarios en los servidores de Google, puedes usar nuestro servicio de carga masiva.
Cuando el ID de publicidad para dispositivos móviles coincide con una lista de usuarios, puedes usarlo para ejecutar el remarketing.
Comentarios en tiempo real
Los comentarios en tiempo real están disponibles para Authorized Buyers, así como para intercambios y redes que usan Open Bidding.
Se admiten comentarios de respuesta a la oferta en la solicitud de oferta posterior para el protocolo de AdX y OpenRTB. Para OpenRTB, se envía en BidRequestExt.
Además de los campos predeterminados que se envían en los comentarios de respuestas a la oferta, también puedes enviar datos personalizados en la respuesta de la oferta (en OpenRTB o AdX Proto) con un event_notification_token que se muestra en BidResponse. event_notification_token son datos arbitrarios conocidos solo por el ofertante que podrían ayudar a depurar, por ejemplo: un nuevo ID de segmentación o de oferta que representa una táctica nueva, o metadatos asociados con la creatividad que solo el ofertante conoce. Para obtener información detallada, consulta Búfer de protocolo de extensiones de OpenRTB para RTB y Proto de AdX para AdX.
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 enviará comentarios sobre la respuesta en un mensaje BidResponseFeedback, como se muestra a continuación:
message BidResponseFeedback {
// The unique id from BidRequest.id
optional bytes request_id = 1;
// The index of the BidResponse_Ad if there was more than one. The index
// starts at zero for the first creative.
optional int32 creative_index = 2;
// 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 = 3;
// 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 int64 cpm_micros = 4;
// The minimum bid value necessary to have won the auction, in micros of
// 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 int64 minimum_bid_to_win = 7;
// 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 micros 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 BidResponseFeedback object.
optional int64 server_side_component_minimum_bid_to_win = 16;
// 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 = 15 [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 micros of your account currency.
optional int64 sampled_mediation_cpm_ahead_of_auction_winner = 10;
// Event notification token that was included in the bid response.
optional bytes event_notification_token = 5;
// Buyer creative ID that was included in the bid response.
optional string buyer_creative_id = 6;
// 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 BidResponseFeedback message. Google will send separate
// BidResponseFeedback 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 feedback_type = 17;
// 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 buyer_origin = 18;
// 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 interest_group_buyer_status_code = 19;
}
A partir de este mensaje, el primer campo que debes verificar es bid_response_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 los comentarios sobre precios. Para obtener más información, consulta Cómo inhabilitar esta opción.
Los comentarios en tiempo real incluyen el ID de solicitud de oferta y uno de los siguientes elementos:
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 a la subasta.
El comprador envió una oferta, pero perdió la subasta.
El código de estado de la creatividad 79 (se superó 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.
Para una impresión de aplicaciones y un código de estado de creatividad de 83, el publicador de la app podría haber usado una cascada de mediación y, por lo tanto, la oferta ganadora habría compitido contra otra demanda en la cadena de cascada de devoluciones del publicador. Obtén información para usar sampled_mediation_cpm_ahead_of_auction_winner cuando ofertes.
Ejemplo
El siguiente es un ejemplo de comentarios en tiempo real como se ve en los protocolos compatibles:
Crea un modelo de ofertas para las subastas de primer precio
Después de colocar una oferta en una subasta de primer precio, recibirás comentarios en tiempo real que incluyen los campos minimum_bid_to_win y sampled_mediation_cpm_ahead_of_auction_winner si la oferta no se filtró en la subasta. Estos indicadores se pueden usar para informar a tu lógica de ofertas cuánto más alta o más baja podría haber sido tu oferta para ganar la impresión.
minimum_bid_to_win: Es la oferta mínima que se podría haber
realizado para ganar la subasta de ofertas en tiempo real. Si ganaste la subasta, esta será la oferta más baja que podrías haber hecho mientras ganaste. 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 fueron superiores a la ganadora de la subasta, ponderada por la tasa de relleno esperada. Esto se establecerá en 0 si se espera que ninguna de las redes de la cadena de mediación se complete o si el publicador no usa la mediación del SDK.
Cómo funciona
Con el fin de 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\]
Lo siguiente representa las tasas de relleno correspondientes para los CPM en 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 a partir del elemento de la cadena de mediación \(i\), según la tasa de relleno determinada:
\(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\}\]
donde \(W\) es la oferta ganadora, y \(C_K > W >= C_{K+1}\)
El precio de reserva, o mínimo, se denota como \(F\).
La oferta de 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 del 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 ofertas en tiempo real y una cadena de mediación de SDK de la siguiente manera:
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\%\)
Supongamos lo siguiente como resultado de la subasta de RTB:
Subasta de RTB
CPM
Ganador de la subasta (sem.)
USD 1.00
Segundo final de la subasta (D)
USD 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 se calculan los valores y las probabilidades de minimum_bid_to_win y sampled_mediation_cpm_ahead_of_auction_winner para ofertas que perdieron.
minimum_bid_to_win
Probability
\(max(F, W) = $1.00\)
\(100\%\)
sampled_mediation_cpm_ ahead_of_auction_winner
Probability
\(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\%\)
Acoplamiento de ofertas
La compactación de ofertas describe el procesamiento de un único BidRequest complejo en varias solicitudes de oferta que se envían a tu aplicación. Debido a que conservan IDs idénticos (BidRequest.google_query_id en el protocolo de RTB de Authorized Buyers o BidRequestExt.google_query_id en el protocolo de OpenRTB), puedes determinar qué solicitudes de oferta se correlacionan después de la compactación.
Formatos de anuncio
Algunas oportunidades de anuncios pueden aceptar varios formatos. Con la compactación de ofertas, cada formato se envía en una solicitud de oferta distinta en la que los atributos, como los IDs de facturación aptos, 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 de formatos de anuncios
A continuación, se muestra un ejemplo de una solicitud de oferta JSON de OpenRTB simplificada sin compactar el formato del anuncio en comparación con un conjunto equivalente de solicitudes dispensadas:
Una oportunidad de anuncio para un ofertante determinado puede ser aplicable a varios tipos de acuerdos, además de la subasta abierta. Con la compactación de ofertas para los acuerdos, se enviará una solicitud de oferta para la subasta abierta y una para cada tipo de acuerdo de precio fijo. En la práctica, las restricciones de anuncios pueden diferir entre subastas y tipos de acuerdos de precio fijo. Por ejemplo, para una oportunidad de anuncio de video determinada que está disponible tanto para la subasta abierta como para un acuerdo de precio fijo, un ofertante recibirá solicitudes de oferta distintas para cada una, en las que las restricciones, como la duración máxima del anuncio y la opción de permitir anuncios que se pueden omitir, pueden diferir. Como resultado, la compactación aplicada a la oportunidad publicitaria te permite discernir con mayor facilidad las restricciones de los 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 omisión del 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 duración detallada que se puede omitir y que no se puede omitir, la implementación de OpenRTB solo tiene un único valor de duración máxima.
Antes de la compactación de ofertas, el maxduration de OpenRTB se configuraba en el valor más bajo de los campos max_ad_duration y skippable_max_ad_duration del protocolo de Google. Este comportamiento ahora cambió al envío de dos solicitudes de oferta independientes cuando estos valores difieren: una representa el maxduration para las oportunidades que se pueden omitir y la otra para las oportunidades que no se pueden omitir.
En los siguientes ejemplos, se muestra cómo una solicitud del protocolo de Google se traduce en OpenRTB antes y después de la compactació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 compactar
15
true
Solicitud separada núm. 1: No se puede omitir
15
false
Solicitud separada núm. 2: Se puede omitir
60
true
La compactación de solicitudes de oferta de duración de video que se puede omitir solo se llevará a cabo cuando se cumplan las siguientes condiciones:
La solicitud permite el uso de video.
Se permiten los videos que se pueden omitir y los 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 de OpenRTB activos.
Si deseas inhabilitar este tipo de compactación, comunícate con tu administrador técnico de cuentas.
Grupos de anuncios de video
Las solicitudes de oferta para un grupo de anuncios de video con varias oportunidades de anuncios se separan, de modo que cada solicitud de oferta corresponda a una oportunidad de anuncio individual de ese grupo.
Esto te permite ofertar en varias oportunidades de anuncios para un grupo determinado.
Open Measurement
Open Measurement te permite especificar proveedores de terceros que proporcionan servicios independientes de medición y verificación para los anuncios que se publican en entornos de apps para dispositivos móviles.
Para determinar si un publicador admite Open Measurement en la solicitud de oferta, verifica si la oportunidad de anuncio excluye el atributo OmsdkType:
OMSDK 1.0, que se encuentra en Atributos de creatividades excluyendos por el publicador. En el caso del protocolo de Authorized Buyers, esto se encuentra en BidRequest.adslot[].excluded_attribute. En el protocolo OpenRTB, esto se encuentra en el atributo battr para Banner o Video, según el formato.
Si deseas obtener más información para interpretar las solicitudes de ofertas que contienen indicadores de Open Measurement, consulta el artículo del Centro de ayuda SDK de Open Measurement.
Ejemplos de solicitudes de oferta
Las siguientes secciones muestran ejemplos de solicitudes de oferta para diferentes tipos de anuncios.