Uma interação de lances em tempo real começa quando o Google envia uma solicitação de lance para
seu aplicativo. Este guia explica como codificar seu aplicativo para
a solicitação de lance.
Analisar solicitação do Protobuf
O Google envia uma solicitação de lance como um buffer de protocolo serializado anexado como o
payload binário de uma solicitação POST HTTP. O Content-Type é definido como
application/octet-stream. Consulte Exemplo de solicitação de lance para ver um exemplo.
Você precisa analisar a solicitação em uma instância do BidRequest
mensagem. Dependendo do protocolo escolhido, BidRequest é definido
em openrtb.proto ou no realtime-bidding.proto
descontinuado, que pode ser encontrado na página
dados de referência. É possível analisar a mensagem
usando o método ParseFromString() na classe gerada para a
BidRequest. Por exemplo, o código C++ abaixo analisa uma solicitação
com um payload POST em uma string:
string post_payload = /* the payload from the POST request */;
BidRequest bid_request;
if (bid_request.ParseFromString(post_payload)) {
// Process the request.
}
Depois de ter o BidRequest, você pode trabalhar com ele como um
objeto, extraindo e interpretando os campos necessários. Por exemplo, em
A iteração do C++ por transações em um "BidRequest" do OpenRTB pode parecer
o seguinte:
for (const BidRequest::Imp::Pmp::Deal& deal : pmp.deals()) {
DoSomething(deal.id(), deal.wseat());
}
IDs do faturamento
Você recebe uma solicitação de lance quando o inventário de anúncios de um editor é segmentado por
uma ou mais das suas
configurações de pré-segmentação. BidRequest.imp.ext.billing_id
será preenchido com os IDs de faturamento de todos os compradores qualificados e as configurações
de segmentação por predefinição relevantes. Além disso, para
oferta
inventário, é possível encontrar os IDs de faturamento associados ao comprador relevante
usando BidRequest.imp.pmp.deal.ext.billing_id. Somente os IDs de faturamento de
os compradores incluídos na solicitação de lance podem ser especificados ao fazer um lance.
Se vários IDs de faturamento forem incluídos na solicitação de lance, especifique
o ID de faturamento do comprador a que você quer atribuir seu lance com o
campo BidResponse.seatbid.bid.ext.billing_id.
Arquivos de dicionário
A solicitação de lance usa identificadores definidos em arquivos de dicionário, que estão
disponíveis na página dados de referência.
Macros de URL do lance do protocolo RTB do Google
Opcionalmente, alguns campos do BidRequest podem ser inseridos no
o URL usado na solicitação POST HTTP. Isso é útil, por exemplo, se você usa
um front-end leve que balanceia a carga em vários back-ends usando um valor
da solicitação. Entre em contato com seu gerente técnico de contas para solicitar suporte para
novas macros.
Macro
Descrição
%%GOOGLE_USER_ID%%
Substituído por google_user_id
do BidRequest. Por exemplo, o URL do bidder
As solicitações de lance enviadas para os bidders de troca e de rede que participam do Open Bidding são semelhantes às dos Authorized Buyers que participam dos lances em tempo real padrão. Os clientes do Open Bidding receberão um pequeno número de
campos adicionais, e alguns campos existentes podem ter usos alternativos. Esses
incluem o seguinte:
OpenRTB
Authorized Buyers
Detalhes
BidRequest.imp[].ext.dfp_ad_unit_code
BidRequest.adslot[].dfp_ad_unit_code
Contém o código de rede do Ad Manager do editor seguido pela hierarquia do bloco de anúncios, separados por barras.
Por exemplo, isso apareceria com uma formatação semelhante a:
/1234/cruises/mars.
BidRequest.user.data[].segment[]
BidRequest.adslot[].exchange_bidding.key_value[]
Pares de chave-valor repetidos enviados do editor para o bidder da troca.
É possível determinar que os valores são pares de chave-valor enviados pelo
editor quando BidRequest.user.data[].name está definido como
“Publisher Passed”.
Declarar fornecedores permitidos
Fornecedores de tecnologia que prestam serviços como pesquisa, remarketing e
a veiculação de anúncios pode desempenhar um papel na interação entre compradores e vendedores. Somente
fornecedores com participação verificada pelo Google no Authorized Buyers
são permitidas.
Para entender o BidRequest e criar seu
BidResponse, você precisa conhecer os dois
de declarar fornecedores de tecnologia:
Outros fornecedores só podem participar se forem declarados no
BidRequest:
No BidRequest, a
O campo BidRequest.imp.ext.allowed_vendor_type especifica
quais fornecedores o vendedor permite. Os fornecedores que serão enviados no
allowed_vendor_type são listados no arquivo de dicionário
vendors.txt.
Exemplo de solicitação de lance
Os exemplos a seguir representam amostras legíveis do Protobuf e
Solicitações JSON.
Para converter a solicitação de lance em um formato binário, da mesma forma que você faria com o
POST em uma solicitação real, faça o seguinte (em C++). Observação:
No entanto, isso não se aplica ao JSON do 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 em tempo real
O feedback em tempo real também está disponível para o Authorized Buyers.
como trocas e redes que usam o Open Bidding.
O feedback da resposta do lance é compatível com a solicitação de lance subsequente para ambos
OpenRTB e o protocolo descontinuado RTB do Google. Para o OpenRTB, ele é enviado
BidRequest.ext.bid_feedback:
Além dos campos padrão enviados no Feedback da resposta do lance, é possível
também enviar dados personalizados na resposta de lance usando o
BidResponse.seatbid.bid.ext.event_notification_token. O
event_notification_token são dados arbitrários conhecidos apenas pelas
proponente que pode ajudar na depuração, por exemplo: um novo ID de segmentação ou
ID de lances que representa uma nova tática ou os metadados associados ao criativo.
conhecidas apenas pelo bidder. Para saber mais, consulte o
OpenRTB Extensions Protocol Buffer
para o OpenRTB ou o
protocolo RTB do Google descontinuado.
Quando o Authorized Buyers envia uma solicitação de lance para um bidder, o bidder responde
com um BidResponse. Se o bidder tiver o feedback em tempo real ativado,
em uma solicitação de lance subsequente, o Authorized Buyers vai enviar feedback sobre a
resposta em uma mensagem 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;
}
A partir dessa mensagem, o primeiro campo a ser verificado é
bid_feedback.creative_status_code; você encontra o código
significado em
criativo-status-codes.txt. Se você ganhar o lance, poderá desativar
com base no feedback sobre o preço. Para mais informações, consulte
de não participar.
O feedback em tempo real inclui o ID da solicitação de lance e uma das seguintes
informações:
Resultado do leilão
Feedback em tempo real
O comprador não enviou um lance.
Nada
O comprador enviou um lance que foi filtrado antes de chegar
ao leilão.
O código de status do criativo 79 (lance superado em
leilão).
O comprador enviou um lance que venceu o leilão.
O preço de liquidação e o código de status do criativo 1.
Para uma impressão de aplicativo e um código de status do criativo de 83, o
editor de apps poderia estar usando uma hierarquia de mediação e, portanto, o
lance vencedor teria competido com outra demanda na campanha
na hierarquia de passbacks. Saiba como usar
sampled_mediation_cpm_ahead_of_auction_winner ao
dar lances.
Exemplo
Confira a seguir um exemplo de feedback em tempo real nos protocolos
compatíveis:
Criar um modelo de lances para leilões de primeiro preço
Depois de dar um lance em um leilão de primeiro preço, você receberá
feedback, incluindo minimum_bid_to_win e
sampled_mediation_cpm_ahead_of_auction_winner se o lance
não foi filtrada do leilão. Esses indicadores podem ser usados para informar a
lógica de lances sobre o quanto seu lance poderia ser maior ou menor para
ganhar a impressão.
minimum_bid_to_win: o lance mínimo que poderia ter sido
para vencer o leilão de lances em tempo real. Se você venceu o leilão, esse será
o lance mais baixo que você poderia ter feito. Se você perdeu o
leilão, esse será o lance vencedor.
sampled_mediation_cpm_ahead_of_auction_winner: se houver
outras redes na cadeia de mediação, o
valor desse campo será um preço que representa um lance de exemplo de uma das
redes de mediação qualificadas que foi maior que o vencedor do leilão, ponderado
pela taxa de preenchimento esperada. O valor será definido como 0 se nenhuma das redes na
cadeia de mediação for preenchida ou se o editor não usar a mediação
do SDK.
Como funciona
Para descrever os cálculos usados para determinar os valores possíveis
para minimum_bid_to_win e
sampled_mediation_cpm_ahead_of_auction_winner, primeiro precisamos
definir o seguinte:
A seguir, os CPMs na cadeia de mediação em ordem decrescente:
\[C_1, C_2, …, C_n\]
A tabela a seguir representa as taxas de preenchimento correspondentes para os CPMs na
cadeia de mediação:
\[f_1, f_2, …, f_n\]
A seguir, temos uma função usada para determinar o CPM esperado e seu
probabilidade do elemento da cadeia de mediação \(i\), com base no preenchimento fornecido
taxa:
\(X_i = \{C_i\) com probabilidade \(f_i\); \(0\) com probabilidade \(1 - f_i\}\)
A cadeia de mediação vencedora final será:
\[\{C_1, C_2, …, C_K, W\}\]
em que \(W\) é o lance vencedor e \(C_K > W >= C_{K+1}\)
O preço de reserva, ou mínimo, é indicado como \(F\).
O lance secundário é indicado como \(R\).
Cálculos para o vencedor do leilão
Campo
Cálculo
minimum_bid_to_win
\(max\{F, R, X_{K+1}, …, X_n\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(\{C_i\) com probabilidade \(\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 o perdedor do leilão
Campo
Cálculo
minimum_bid_to_win
\(max\{F, W\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(max\{X_1, …, X_K\}\)
Exemplo com uma cadeia de mediação simples
Suponha que um editor use lances em tempo real e uma cadeia de mediação de SDK como
segue:
Cadeia de mediação do SDK
CPM esperado
Taxa de preenchimento
Rede 1
\(C_1 = $3.00\)
\(f_1 = 5\%\)
Rede 2
\(C_2 = $2.00\)
\(f_2 = 45\%\)
Rede 3
\(C_3 = $0.50\)
\(f_3 = 80\%\)
Rede 4
\(C_4 = $0.10\)
\(f_4 = 85\%\)
Considere o seguinte como resultado do leilão de RTB:
Leilão de RTB
CPM
Vencedor do leilão (W)
US$ 1,00
Segundo o leilão (R)
US$ 0,05
Preço de reserva / mínimo (F)
US$ 0
Lance que venceu o leilão
Veja a seguir um exemplo de como os valores e as probabilidades
minimum_bid_to_win e
sampled_mediation_cpm_ahead_of_auction_winner são calculados para uma
de lance que venceu.
Veja a seguir um exemplo de como os valores e as probabilidades
minimum_bid_to_win e
sampled_mediation_cpm_ahead_of_auction_winner são calculados para uma
lances perdidos.
minimum_bid_to_win
Probabilidade
\(max(F, W) = $1.00\)
\(100\%\)
sampled_mediation_cpm_ ahead_of_auction_winner
Probabilidade
\(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\%\)
Separação de lances
A separação de lances descreve o processamento de um único
BidRequest em várias solicitações de lance que são enviadas aos seus
para o aplicativo. Quando uma solicitação de lance é separada, é possível saber quais solicitações
fazem parte do original porque terão um valor idêntico no
BidRequest.ext.google_query_id.
A separação de lances está ativada por padrão, mas você pode entrar em contato com sua conta
se você preferir desativá-la.
Formatos de anúncio
Algumas oportunidades de anúncio podem aceitar vários formatos. Com a separação de lances, cada
formato é enviado em uma solicitação de lance distinta em que atributos como
IDs de faturamento são relevantes para o formato especificado na solicitação.
As solicitações de lance com os seguintes formatos serão agrupadas em
solicitações de lance distintas:
Banner
Vídeo
Áudio
Nativo
Exemplo de nivelamento do formato do anúncio
Confira abaixo um exemplo que mostra uma solicitação de lance JSON simplificada do OpenRTB sem nivelamento de formato de anúncio em comparação com um conjunto equivalente de solicitações niveladas:
Uma oportunidade de anúncio para determinado bidder pode ser aplicável a várias transações
diferentes, além do leilão aberto. Com a separação de lances para transações, um lance
solicitação será enviada para o leilão aberto e uma para cada tipo de item de linha
negócios. Na prática, as restrições de anúncios podem variar entre leilões e preços fixos
de transações, por exemplo, para uma determinada oportunidade de anúncio em vídeo disponível para
no leilão aberto e na transação de preço fixo, um proponente receberá diferentes
solicitações de lance para cada um, em que restrições como duração máxima do anúncio e se
os anúncios puláveis permitidos podem ser diferentes. Como resultado, a separação é aplicada ao anúncio
permite que você discuta mais facilmente as restrições de anúncios para a campanha
leilão e a transação de preço fixo.
Duração máxima do vídeo pulável
O protocolo do Google e a implementação do OpenRTB oferecem suporte aos seguintes campos
para duração e capacidade de pular o vídeo:
Duração
Duração do trecho pulável
Recurso para pular
Protocolo do Google
max_ad_duration
skippable_max_ad_duration
video_ad_skippable
OpenRTB
maxduration
N/A
skip
Isso significa que, embora o protocolo do Google possa ter uma duração granular
com e sem a opção de pular, a implementação do OpenRTB tem apenas um
valor de duração máxima.
Antes da separação de lances, o maxduration do OpenRTB era definido como
o menor dos max_ad_duration do protocolo do Google e
Campos skippable_max_ad_duration. Esse comportamento mudou para
enviar duas solicitações de lance separadas quando esses valores forem diferentes: uma representando
os campos maxduration para puláveis e os não puláveis
oportunidades.
Os exemplos a seguir mostram como uma solicitação de protocolo do Google é convertida
em OpenRTB antes e depois do nivelamento de lances. A solicitação de protocolo do Google equivalente
tem um max_ad_duration de 15 e um
skippable_max_ad_duration de 60.
Exemplo
max_ad_duration
skip (verdadeiro OU falso)
Solicitação original sem nivelamento
15
true
Solicitação simplificada 1: não pulável
15
false
Solicitação simplificada 2: que pode ser ignorada
60
true
A redução da solicitação de lance de duração de vídeo pulável só vai acontecer quando
estas condições forem atendidas:
A solicitação permite vídeos.
Vídeos pulados e não puláveis são permitidos, e os dois respectivos
e durações diferentes em termos de valor.
Esta solicitação está qualificada para leilões privados ou abertos.
A conta do bidder tem endpoints OpenRTB ativos.
Você pode desativar esse tipo de nivelamento entrando em contato com seu
gerente de contas.
Conjuntos de vídeos
As solicitações de lance para um conjunto de vídeos com várias oportunidades de anúncio são separadas,
de modo que cada solicitação de lance seja para uma oportunidade de anúncio individual desse conjunto.
Isso permite que você dê lances em várias oportunidades de anúncio para um determinado conjunto.
Open Measurement
Com o Open Measurement, você pode especificar fornecedores terceirizados que
serviços independentes de medição e verificação para anúncios veiculados em apps para dispositivos móveis
e ambientes de teste.
É possível determinar se um editor oferece suporte ao Open Measurement na solicitação de lance
verificando se a oportunidade de publicidade exclui o atributo OmsdkType:
OMSDK 1.0 encontrado em Atributos de criativo
exigíveis pelo editor. Isso pode ser encontrado no battr
Atributo para Banner
ou Vídeo, dependendo
sobre o formato.
Para mais informações sobre como interpretar solicitações de lance que contêm
indicadores de medição, consulte a documentação do
do SDK da Central de Ajuda.
Exemplos de solicitações de lance
As seções a seguir mostram exemplos de solicitações de lance para diferentes tipos de anúncio.
