Processar a solicitação

Uma interação de lances em tempo real começa quando o Google envia uma solicitação de lance para seu app. Este guia explica como programar seu aplicativo para processar a solicitação de lance.

Analisar solicitação

O Google envia uma solicitação de lance serializada nos formatos JSON ou Protobuf do OpenRTB, anexada como a carga útil de uma solicitação POST HTTP. O formato recebido depende da configuração do seu endpoint. Confira um exemplo em Exemplo de solicitação de lance.

Você precisa analisar essa solicitação para receber o BidRequest serializado. Se você estiver usando o formato Protobuf, faça o download de openrtb.proto e openrtb-adx.proto na página de dados de referência e use-os para gerar uma biblioteca que possa ser usada para analisar a mensagem BidRequest. Por exemplo, o código C++ a seguir 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 C++, a iteração de ofertas em uma "BidRequest" do OpenRTB pode ser semelhante a esta:

for (const BidRequest::Imp::Pmp::Deal& deal : pmp.deals()) {
  DoSomething(deal.id(), deal.wseat());
}

IDs de 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 o inventário de transações, você pode encontrar IDs de faturamento associados ao comprador relevante usando BidRequest.imp.pmp.deal.ext.billing_id. Só é possível especificar os IDs de faturamento dos compradores incluídos na solicitação de lance ao dar 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 proponente

Opcionalmente, algumas informações do BidRequest podem ser inseridas nos URLs de endpoint de lances usando macros. Se você configurar um URL de endpoint com uma ou mais macros, elas serão expandidas se essas informações estiverem presentes na solicitação de lance. Isso pode ser útil, por exemplo, se você quiser fazer o balanceamento de carga com base nas informações no BidRequest. Entre em contato com o gerente da sua conta para solicitar suporte para novas macros.

MacroDescrição
%%GOOGLE_USER_ID%%

Substituído pelo ID do usuário do Google encontrado em BidRequest.user.id. Por exemplo, o URL do bidder http://google.bidder.com/path?gid=%%GOOGLE_USER_ID%% será substituído por algo como http://google.bidder.com/path?gid=dGhpyBhbiBleGFtGxl no momento da solicitação.

Se o ID do usuário do Google for desconhecido, a string vazia será substituída, com um resultado semelhante a

http://google.bidder.com/path?gid=
%%HAS_MOBILE%%

Substituído por 1 para indicar que a solicitação de lance é de um dispositivo móvel ou 0, caso contrário. Isso é baseado no valor de BidRequest.device.devicetype, em que os dispositivos móveis são indicados por HIGHEND_PHONE (4) ou Tablet (5).
%%HAS_VIDEO%%

Substituído por 1 para indicar que a solicitação de lance contém inventário de vídeo ou 0. Isso é baseado em se BidRequest.imp.video está preenchido na solicitação de lance.
%%HOSTED_MATCH_DATA%%

Substituído por um valor com base em BidRequest.user.buyeruid.

%%MOBILE_IS_APP%%

Substituído por 1 para indicar que a solicitação de lance é para inventário de apps para dispositivos móveis ou 0. Isso é baseado em se BidRequest.app está preenchido.

Encontrar o ID do app para dispositivos móveis no URL da transação

As transações de aplicativos para dispositivos móveis vão informar URLs parecidos com este:

mbappgewtimrzgyytanjyg4888888.com

Use um decodificador de base 32 para decodificar a parte da string em negrito (gewtimrzgyytanjyg4888888).

É possível usar um decodificador on-line, mas você terá que colocar letras maiúsculas e substituir 8s finais por valores =.

A decodificação desse valor: 

GEWTIMRZGYYTANJYG4======
 resulta em: 
1-429610587
 A string 429610587 é o ID do app iOS iFunny.

Veja outro exemplo. O URL denunciado é: 

mbappgewtgmjug4ytmmrtgm888888.com
 Decodificação desse valor: 
GEWTGMJUG4YTMMRTGM======
 resulta em: 
1-314716233
 O resultado 314716233 é o ID do app iOS TextNow.

Encontrar o nome do app para dispositivos móveis pelo URL da transação

Confira um exemplo de como conseguir o nome do app. O URL informado é o seguinte: 

mbappMFUXELTDN5WS42DZOBQWQLTJN4XHG3DJORUGK4Q888.com
 Decodificação desse valor: 
MFUXELTDN5WS42DZOBQWQLTJN4XHG3DJORUGK4Q===
 resulta em: 
air.com.hypah.io.slither
 O resultado é equivalente ao app Android slither.io.

Campos do Open Bidding

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 vão receber um pequeno número de campos adicionais, e alguns campos atuais podem ter usos alternativos. Isso inclui o seguinte:

OpenRTB Detalhes
BidRequest.imp.ext.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

Pares de chave-valor repetidas enviadas 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

Os fornecedores de tecnologia que oferecem serviços como pesquisa, remarketing e veiculação de anúncios podem desempenhar um papel na interação entre compradores e vendedores. Somente fornecedores que o Google verificou para participação nas interações do Authorized Buyers são permitidos.

Para entender o BidRequest e criar o BidResponse, você precisa conhecer as duas possibilidades de declaração de fornecedores de tecnologia:

  1. Alguns fornecedores não precisam ser declarados. Eles estão listados em Fornecedores externos certificados do Ad Manager.
  2. Outros fornecedores só podem participar se forem declarados no BidRequest:
    • Em BidRequest, 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 por humanos das solicitações Protobuf e JSON.

Protobuf do OpenRTB

JSON do OpenRTB

Para converter a solicitação de lance em um formato binário, como você faria com o payload POST em uma solicitação real, faça o seguinte (em C++). 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 está disponível para Authorized Buyers, bem como para trocas e redes que usam o Open Bidding.

O feedback em tempo real preenche BidRequest.ext.bid_feedback com base no resultado de um ou mais lances que você fez anteriormente e pode ser usado para encontrar detalhes, como se o lance venceu o leilão ou o lance mínimo necessário para ter vencido o leilão. Entre em contato com seu gerente de contas para ativar o feedback em tempo real.

Além dos campos padrão enviados no feedback da resposta do lance, você também pode enviar dados personalizados na resposta do lance usando o campo BidResponse.seatbid.bid.ext.event_notification_token. O event_notification_token é um dado arbitrário conhecido apenas pelo licitante que pode ajudar na depuração, por exemplo: um novo ID de segmentação ou de lance que representa uma nova tática ou metadados associados ao criativo conhecidos apenas pelo licitante. Para saber mais, consulte o arquivo de buffer de protocolo das extensões do OpenRTB.

Quando o Authorized Buyers envia uma solicitação de lance para um bidder, ele 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;

  // Deprecated. This field is not populated and will be removed after March,
  // 2025. 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 [deprecated = true];

  // The minimum bid value necessary to have won 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 didn't 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;
}

Nesta mensagem, o primeiro campo que você precisa verificar é bid_feedback.creative_status_code. Você pode encontrar o significado do código em creative-status-codes.txt. Se você ganhar o lance, poderá desativar o feedback de preço. Para mais informações, consulte Como desativar o recurso.

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 (creative-status-codes.txt).
O comprador enviou um lance, mas perdeu o leilão. O código de status do criativo 79 (superação de lance no 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 app e um código de status do criativo de 83, o editor do app pode ter usado uma hierarquia de mediação. Portanto, o lance vencedor teria competido com outras demandas na cadeia de hierarquia de retransmissão do editor. 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:

Protobuf do OpenRTB

JSON do OpenRTB

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ê vai receber um feedback em tempo real, incluindo os campos minimum_bid_to_win e sampled_mediation_cpm_ahead_of_auction_winner, se o lance não tiver sido filtrado 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 feito para ganhar 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 de 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 seguir, as taxas de preenchimento correspondentes para os CPMs na cadeia de mediação:
    \[f_1, f_2, …, f_n\]
  • A seguir, há uma função usada para determinar o CPM esperado e a probabilidade dele no elemento da cadeia de mediação \(i\), com base na taxa de preenchimento:
    \(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 mínimo é indicado como \(F\).
  • O lance do segundo colocado é 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 do SDK da seguinte maneira:

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 RTB CPM
Vencedor do leilão (W) US$ 1,00
Segundo colocado do leilão (R) US$ 0,05
Preço de reserva / preço mínimo (F) US$ 0
Lance que venceu o leilão

Confira a seguir um exemplo de como os valores e as probabilidades de minimum_bid_to_win e sampled_mediation_cpm_ahead_of_auction_winner são calculados para um lance vencedor.

minimum_bid_to_win Probabilidade
\(max(F, R, C_3) = $0.50\) \(f_3 = 80\%\)
\(max(F, R, C_4) = $0.10\) \((1-f_3) \cdot f_4 = 17\%\)
\(max(F, R, 0) = $0.05\) \((1-f_3) \cdot (1-f_4) = 3\%\)
sampled_mediation_cpm_
ahead_of_auction_winner		 Probabilidade
\(C_1 = $3.00\) \(f_1 \div (1-(1-f_1) \cdot (1-f_2)) =~ 10.5\%\)
\(C_2 = $2.00\) \(((1-f_1) \cdot f_2) \div (1-(1-f_1) \cdot (1-f_2)) =~ 89.5\%\)
Lances que perderam o leilão

Confira a seguir um exemplo de como os valores e as probabilidades de minimum_bid_to_win e sampled_mediation_cpm_ahead_of_auction_winner são calculados para 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

O achatamento de lances descreve o processamento de um único BidRequest complexo em várias solicitações de lance enviadas para o aplicativo. Quando uma solicitação de lance é simplificada, é possível saber quais solicitações de lance fizeram parte do original porque elas têm um valor idêntico no campo BidRequest.ext.google_query_id.

A redução de lances está ativada por padrão, mas você pode entrar em contato com seu gerente de contas se preferir desativar esse recurso.

Formatos de anúncio

Algumas oportunidades de anúncio podem aceitar vários formatos. Com a compactação de lances, cada formato é enviado em uma solicitação de lance distinta, em que atributos como IDs de faturamento qualificados 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 de formato de 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:

Pré-achatar

Pós-achatamento

Ofertas

Uma oportunidade de anúncio para um determinado bidder pode ser aplicável a vários tipos de transação, além do leilão aberto. Com a separação de lances para transações, um pedido de lance é enviado para o leilão aberto e outro para cada tipo de transação de preço fixo. Na prática, as restrições de anúncio podem variar entre os leilões e os tipos de transação de preço fixo. Por exemplo, para uma determinada oportunidade de anúncio em vídeo disponível para o leilão aberto e uma transação de preço fixo, um proponente vai receber solicitações de lance diferentes para cada um, em que restrições como a duração máxima do anúncio e se anúncios puláveis são permitidos podem variar. Como resultado, a compactação aplicada à oportunidade de anúncio permite que você identifique com mais facilidade as restrições de anúncio para o leilão aberto e a transação de preço fixo.

Pulabilidade e duração do vídeo

A especificação do OpenRTB não tem campos separados para especificar as durações máximas de vídeos de anúncios puláveis e não puláveis. A implementação do Google usa a padronização de lances para diferenciar esses campos usando os campos BidRequest.video.maxduration e BidRequest.video.skip.

Confira abaixo um exemplo de como o inventário de vídeo é achatado quando a duração máxima de um anúncio não pulável é 15 e a duração máxima de um anúncio pulável é 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 puláveis e não puláveis são permitidos, e as duas durações máximas diferem no valor.
  • Essa solicitação está qualificada para leilão privado ou leilão aberto.

Para desativar esse tipo de nivelamento, entre em contato com o gerente técnico de contas. Quando desativado, e o editor permite anúncios em vídeo puláveis e não puláveis com durações máximas diferentes com base na capacidade de pular, skip é definido como true e maxduration é definido como a duração mais curta entre as restrições de anúncios puláveis e não puláveis.

Conjuntos de vídeos

As solicitações de lance para um conjunto de vídeos com várias oportunidades de anúncio são achatadas, de modo que cada solicitação de lance é para uma oportunidade de anúncio individual desse conjunto. Assim, você pode dar lances em várias oportunidades de anúncio para um determinado conjunto.

Open Measurement

Com o Open Measurement, você pode especificar fornecedores terceirizados que oferecem serviços de medição e verificação independentes para anúncios veiculados em ambientes de apps para dispositivos móveis.

É 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 atributo battr para Banner ou Vídeo, dependendo do formato.

Para mais informações sobre como interpretar solicitações de lances com sinais do Open Measurement, consulte o artigo da Central de Ajuda sobre o SDK do Open Measurement.

Exemplos de solicitações de lance

As seções a seguir mostram solicitações de lance de exemplo para diferentes tipos de anúncios.

Banner de aplicativo

Protobuf do OpenRTB

JSON do OpenRTB

Intersticial de app

Protobuf do OpenRTB

JSON do OpenRTB

Vídeo intersticial do app

Protobuf do OpenRTB

JSON do OpenRTB

App nativo

Protobuf do OpenRTB

JSON do OpenRTB

Vídeo na Web

Protobuf do OpenRTB

JSON do OpenRTB

Banner da Web para dispositivos móveis para o participante da troca

Protobuf do OpenRTB

JSON do OpenRTB

Vídeo e nativo multiformato

Protobuf do OpenRTB

JSON do OpenRTB