Processar a solicitação

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

Solicitação de análise

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

É preciso analisar essa solicitação para receber o BidRequest serializado. Se você estiver usando o formato Protobuf, baixe openrtb.proto e openrtb-adx.proto na página dados de referência e use-os para gerar uma biblioteca que pode ser usada para analisar a mensagem BidRequest. Por exemplo, o código C++ a seguir analisa uma solicitação usando uma carga útil 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 transações em um `BidRequest` do OpenRTB pode ser assim:

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 publisher é 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 relevantes de pré-segmentação. Além disso, para inventário de transação, é possível encontrar os IDs de faturamento associados aos compradores relevantes usando BidRequest.imp.pmp.deal.ext.billing_id. Ao fazer um lance, só é possível especificar os IDs de faturamento dos compradores incluídos na solicitação de lance.

Se vários IDs de faturamento forem incluídos na solicitação de lance, especifique o ID do comprador a quem você quer atribuir seu lance com o campo BidResponse.seatbid.bid.ext.billing_id.

imp {
  ext {
    // The billing IDs of all of your matching pretargeting configs and eligible child seats are
    // stored in a flat list here.
    billing_id: 123
    billing_id: 456
    billing_id: 789
  }
  pmp {
    // All eligible deals are stored in a single flat list.
    deal {
      id: 1000
      ext {
        // The specific billing IDs eligible to bid on this deal are indicated here.
        billing_id: 789
      }
      ...
    }
    deal {
      id: 2000
      ext {
        billing_id: 123
        billing_id: 456
      }
      ...
    }
  }
  ...
}
...

Determinar categorias bloqueadas

Quando você faz um lance, o criativo incluído não pode ter categorias detectadas que o publisher bloqueou. Caso contrário, o lance será filtrado do leilão.

Para encontrar as categorias bloqueadas de uma impressão, revise o campo BidRequest.bcat, que é preenchido com as categorias da taxonomia configurada para sua conta.

O exemplo a seguir mostra categorias bloqueadas com base em uma taxonomia de categoria de anúncio configurada:

Taxonomia de conteúdo 1.0 do IAB

// Bid request
{
  // Indicates the blocked categories using IAB Content 1.0 Taxonomy.
  "bcat": [
    "IAB9-9",  // Cigars
    "IAB8-18"  // Wine
  ]
  "imp": {
    ...
  }
}
      
// Bid request
{
  // Indicates the blocked categories using Google Ad Category Taxonomy.
  "bcat": [
    "10138",  // Cigar and tobacco collecting
    "10080",  // Tobacco
    "11649",  // Wine
    "10674",  // Wine collecting
    "13008"   // Wine clubs
  ]
  "imp": {
    ...
  }
}

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 de dados de referência.

Macros de URL do bidder

Também é possível inserir algumas informações do BidRequest 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 em informações no BidRequest. Entre em contato com seu gerente de contas para solicitar suporte a 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 se baseia 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 caso contrário. Isso é baseado no fato de BidRequest.imp.video ser 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, caso contrário. Isso depende de BidRequest.app estar 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 gerar URLs assim:

mbappgewtimrzgyytanjyg4888888.com

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

Você pode usar um decodificador on-line, mas terá que colocar as letras em maiúsculas e substituir os 8s finais por valores =.

Portanto, ao decodificar esse 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 TextNow para iOS.

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

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

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

Campos do Open Bidding

As solicitações de lance enviadas aos bidders de troca e rede que participam do Open Bidding são semelhantes às do 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 publisher no Ad Manager seguido pela hierarquia de blocos 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 repetidos enviados do publisher para o bidder da troca.

É possível determinar que os valores são pares de chave-valor enviados pelo publisher 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 ter um papel na interação entre compradores e vendedores. Somente fornecedores aprovados pelo Google para participação em interações do Authorized Buyers são permitidos.

Para entender o BidRequest e criar seu BidResponse, você precisa conhecer as duas possibilidades diferentes de declarar 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 são permitidos pelo vendedor. Os fornecedores que serão enviados no allowed_vendor_type estã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 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 o 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 feitos anteriormente e pode ser usado para encontrar detalhes, como se o lance venceu o leilão ou o lance mínimo necessário para vencer. Entre em contato com seu gerente de contas para ativar o feedback em tempo real.

Além dos campos padrão enviados no feedback de 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 são dados arbitrários conhecidos apenas pelo bidder que podem ajudar na depuração. Por exemplo, um novo ID de segmentação ou ID de lances que representa uma nova tática ou metadados associados ao criativo conhecidos apenas pelo bidder. Para mais detalhes, consulte o arquivo de buffer de protocolo de extensões do OpenRTB.

Quando o Authorized Buyers envia uma solicitação de lance a 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 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;

  // 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;
}

Na mensagem, o primeiro campo que você precisa verificar é bid_feedback.creative_status_code. Encontre 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 feedback em tempo real inclui o ID da solicitação de lance e um dos seguintes itens:

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 (superado no leilão).
O comprador enviou um lance que venceu o leilão. O preço de compensação e o código de status do criativo 1.

Para uma impressão de app e um código de status do criativo 83, o editor do app pode ter usado uma cascata de mediação. Portanto, o lance vencedor teria competido com outras demandas na cadeia de cascata de devolução do editor. Saiba como usar sampled_mediation_cpm_ahead_of_auction_winner ao fazer lances.

Exemplo

Confira a seguir um exemplo de feedback em tempo real, como visto em protocolos compatíveis:

Protobuf do OpenRTB

JSON do OpenRTB

Criar um modelo de lances para leilões de primeiro preço

Depois de fazer um lance em um leilão de primeiro preço, você vai receber 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 sua lógica de lances sobre o quanto seu lance poderia ter sido maior ou menor para ganhar a impressão.

  • minimum_bid_to_win: o lance mínimo que poderia ter sido feito para vencer o leilão de lances em tempo real. Se você venceu o leilão, esse é o menor lance que poderia ter feito e ainda assim vencer. 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 amostra de uma das redes de mediação qualificadas que foi maior que o vencedor do leilão, ponderado pela taxa de preenchimento esperada. Esse 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, estão as taxas de preenchimento correspondentes aos CPMs na cadeia de mediação:
    \[f_1, f_2, …, f_n\]
  • Esta é uma função usada para determinar o CPM esperado e a probabilidade dele com base no elemento \(i\)da cadeia de mediação e na taxa de preenchimento fornecida:
    \(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 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 de SDK da seguinte forma:

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\%\)

Suponha o seguinte 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 / mínimo (F) US$ 0
Lance que venceu o leilão

Confira 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 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 perdido.

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 nivelamento de lances descreve o processamento de um único BidRequest complexo em várias solicitações de lance enviadas ao seu aplicativo. Quando uma solicitação de lance é simplificada, é possível saber quais solicitações faziam parte da original porque elas têm um valor idêntico no campo BidRequest.ext.google_query_id.

A redução de lances é ativada por padrão, mas você pode entrar em contato com seu gerente de contas se preferir desativá-la.

Formatos de anúncio

Algumas oportunidades de publicidade aceitam 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 qualificados são relevantes para o formato especificado na solicitação.

As solicitações de lance com os seguintes formatos serão separadas em solicitações de lance distintas:

  • Banner
  • Vídeo
  • Áudio
  • Nativo

Exemplo de redução de formato de anúncio

Confira abaixo um exemplo que mostra uma solicitação de lances JSON OpenRTB simplificada sem o achatamento do formato do anúncio em comparação com um conjunto equivalente de solicitações achatadas:

Pré-achatamento

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, uma solicitação de lance será enviada para o leilão aberto e uma para cada tipo de transação de preço fixo. Na prática, as restrições de anúncios podem variar entre leilões e 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 bidder vai receber solicitações de lance distintas para cada um, em que restrições como duração máxima do anúncio e se anúncios puláveis são permitidos podem variar. Como resultado, o achatamento aplicado à oportunidade de anúncio facilita a identificação das restrições de publicidade para o leilão aberto e a transação de preço fixo.

Recurso pulável e duração do vídeo

A especificação OpenRTB não tem campos separados para especificar as durações máximas de vídeo de anúncios puláveis e não puláveis. A implementação do Google usa o nivelamento de lances para distinguir entre eles usando os campos BidRequest.video.maxduration e BidRequest.video.skip atuais.

Confira um exemplo de como o inventário de vídeo é reduzido 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 simplificação 15 true
Solicitação separada nº 1: não pulável 15 false
Solicitação separada nº 2: pulável 60 true

A redução das solicitações de lance de duração de vídeo pulável só vai ocorrer quando estas condições forem atendidas:

  • A solicitação permite vídeo.
  • Vídeos puláveis e não puláveis são permitidos, e as duas durações máximas respectivas têm valores diferentes.
  • Essa solicitação é qualificada para leilão privado ou aberto.

Para desativar esse tipo de separação, entre em contato com seu gerente técnico de contas. Quando desativado, e o publisher 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 seria definido como true e maxduration seria 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 separadas, de modo que cada solicitação seja para uma oportunidade de anúncio individual desse conjunto. Assim, você pode fazer lances em várias oportunidades de anúncio para um determinado conjunto.

Open Measurement

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

Para determinar se um editor aceita a Open Measurement na solicitação de lance, verifique se a oportunidade de anúncio exclui o atributo OmsdkType: OMSDK 1.0 encontrado em Atributos de criativo que podem ser excluídos 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 que contêm 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 exemplos de solicitações de lances 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 de 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 um bidder de troca

Protobuf do OpenRTB

JSON do OpenRTB

Anúncios nativos e em vídeo multiformato

Protobuf do OpenRTB

JSON do OpenRTB