Criar a resposta
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Depois que seu aplicativo processa a solicitação de lance do Google, ele precisa criar e enviar uma resposta. Este guia explica como programar seu aplicativo para criar
a resposta.
Criar mensagem BidResponse
Para enviar um lance, seu aplicativo precisa responder a uma solicitação com
um BidResponse que contenha um Bid no formato
configurado. Se você estiver usando o formato JSON, a resposta precisará definir o cabeçalho
Content-Type como
application/json; charset=utf-8 e incluir o
BidResponse JSON no corpo. Se você estiver usando o formato Protobuf, o
aplicativo precisará definir o cabeçalho Content-Type como
application/octet-stream e incluir o
BidResponse serializado no corpo.
Para criar e serializar um BidResponse no formato Protobuf, gere e use bibliotecas Protobuf com base em openrtb.proto e openrtb-adx.proto, que implementam os campos padrão BidResponse do OpenRTB e as extensões do Google no Protobuf, respectivamente. Eles podem ser encontrados em
Protos e dados de referência.
Se você não quiser fazer um lance em uma impressão, retorne uma resposta HTTP
204 vazia. O aplicativo precisa retornar uma resposta para cada
BidRequest. Tempos limite e respostas que não podem ser analisadas são considerados erros, e o Google restringe os bidders com altas taxas de erro.
ID do criativo
Seu BidResponse especifica um criativo pelo campo
BidResponse.seatbid.bid.crid (limite de 128 bytes). Mesmo criativos semelhantes precisam ter valores exclusivos para esse campo se forem diferentes em alguma característica notável, incluindo, entre outras: tamanho, URL declarado, atributos do criativo e tipos de fornecedor. Em outras palavras, você precisa atribuir IDs de criativo diferentes a dois anúncios que:
Parecer ou agir de maneira diferente.
Renderizar para diferentes imagens.
Renderizar por meios diferentes (por exemplo, um anúncio consiste em uma imagem e o outro é um vídeo).
Ao projetar seu aplicativo, decida uma maneira sistemática de
gerar identificadores que façam sentido para os tipos de criativos que você planeja
enviar.
Atributos do anúncio
O Google recomenda declarar atributos de criativo para descrever as características do seu anúncio e a segmentação dele usando uma combinação de BidResponse.seatbid.bid.apis e BidResponse.seatbid.bid.attr ou a extensão BidResponse.seatbid.bid.ext.attribute. A seguir, descrevemos como declarar atributos:
VPAID
Defina BidResponse.seatbid.bid.apis como VPAID_1 ou VPAID_2. Para o formato JSON, isso pode ser definido como
1 ou 2, respectivamente.
MRAID
Defina BidResponse.seatbid.bid.apis como MRAID_1 ou 3 para o formato JSON.
SIZELESS
Defina BidResponse.seatbid.bid.attr como RESPONSIVE ou 18 para o formato JSON.
PLAYABLE
Isso é indicado definindo BidResponse.seatbid.bid.attr
como USER_INTERACTIVE ou 13 para o formato
JSON.
Consulte o recurso "Criativos" para saber como receber feedback sobre as propriedades detectadas dos seus criativos.
Campos do Open Bidding
As respostas de lance enviadas pelos bidders de troca e rede que participam do Open Bidding são semelhantes às do Authorized Buyers que participam do lance em tempo real padrão. Os clientes do Open Bidding podem especificar um pequeno número de campos adicionais, e alguns campos atuais podem ter usos alternativos. Isso inclui o seguinte:
Campo
Detalhes
BidResponse.imp.pmp.deals.id
O ID da transação do namespace da troca associado a este lance e informado aos publishers.
BidResponse.seatbid.bid.ext.exchange_deal_type
O tipo de transação informado aos publishers, afetando como ela é tratada no leilão.
Token usado para identificar informações do comprador terceirizado final se a troca como um bidder do Open Bidding for um intermediário. Ele é obtido do comprador terceirizado e precisa ser transmitido ao Google sem alterações na resposta do lance.
Recomendações
Ative conexões HTTPS persistentes (também conhecidas como "keep-alive" ou
"reutilização de conexão") nos seus servidores. Defina o tempo limite como 10 segundos no mínimo. Valores mais altos são benéficos em muitos casos. O Google verifica
isso durante os testes iniciais de latência do aplicativo, porque
o Authorized Buyers envia solicitações em uma taxa alta e precisa evitar a
sobrecarga de latência de estabelecer uma conexão TCP separada para cada
solicitação.
Inclua o URL de rastreamento de impressões opcional para acompanhar quando a impressão é renderizada, e não quando o bidder vence. Devido à queda entre vitórias e renderizações, isso gera estatísticas de rastreamento mais precisas.
Mantenha seu código de bidder livre de dependências em campos descontinuados, o que pode causar falhas nos lances com erros.
Inclua BidResponse.seatbid.bid.w e BidResponse.seatbid.bid.h no seu BidResponse. Um BidResponse para uma solicitação que inclui vários tamanhos de anúncio precisa incluir esses campos, caso contrário, será descartado do leilão.
Limite o tamanho da resposta a menos de 8K. Respostas muito grandes podem aumentar a latência da rede e causar tempos limite.
Importante:as mensagens Protobuf mostradas nos exemplos são representadas aqui como texto legível por humanos. No entanto, não é assim que as mensagens são enviadas pela rede. Ao usar o formato OpenRTB Protobuf, apenas mensagens BidResponse serializadas serão aceitas.
É possível criar e serializar uma mensagem BidResponse usando o seguinte código em C++:
BidResponse bid_response;
// fill in bid response with bid information
string post_response;
if (bid_response.SerializeToString(&post_response)) {
// respond to the POST with post_response as the content
} else {
// return an error to the POST
}
Especificar criativo
Sua resposta de lance especifica o criativo a ser veiculado se o lance vencer. Seu lance precisa incluir um dos formatos de anúncio aceitos (AMP, vídeo, nativo). Neste exemplo, especificamos o criativo usando o campo html_snippet.
Como alternativa, especifique o criativo usando um dos seguintes campos, com base no formato do anúncio:
Anúncio renderizado pelo SDK
BidResponse.seatbid.bid.ext.sdk_rendered_ad
AMP
BidResponse.seatbid.bid.amp_ad_url
Vídeo
BidResponse.seatbid.bid.adm
Nativo
BidResponse.seatbid.bid.adm_native
Especifique um anúncio hospedado nos seus próprios servidores usando um snippet HTML no campo BidResponse.seatbid.bid.adm. O snippet fica dentro de um iFrame inserido na página da Web, o que faz com que o anúncio seja recuperado e renderizado quando a página é carregada. Você precisa criar o snippet HTML para que o
anúncio (banner ou intersticial) seja renderizado corretamente em um iframe e em um
tamanho adequado para o espaço de anúncio em que você está um lance.
Além disso, o tamanho do anúncio declarado na resposta do lance precisa corresponder exatamente a uma das combinações de tamanho na solicitação de lance quando:
Um anúncio é um banner comum (não vídeo, nativo ou intersticial).
O bidder declarou o tamanho na resposta do lance. A declaração de tamanho é obrigatória sempre que mais de um tamanho estiver presente na solicitação.
Uma exceção é feita para anúncios intersticiais. Para intersticiais, a largura precisa ser de pelo menos 50% da largura da tela e a altura de pelo menos 40% da altura da tela.
É possível especificar um criativo de snippet HTML usando qualquer código HTML válido que seja renderizado corretamente. No entanto, não se esqueça das restrições ao especificar o campo crid na seção Criar mensagem BidResponse.
Uma das utilidades é inserir informações extras nos argumentos dos URLs buscados dos seus servidores como parte da renderização do anúncio. Isso permite transmitir
dados arbitrários sobre a impressão de volta aos seus próprios servidores.
Macros são textos formatados incorporados em alguns campos de resposta ao lance que contêm URLs substituídos por um valor relevante no momento da veiculação do anúncio. Por exemplo, se o lance vencedor incluísse a macro AUCTION_PRICE no snippet HTML do criativo incluído com o lance, a macro seria substituída por um valor que você poderia descriptografar para determinar o valor pago pela impressão no leilão.
É possível incluir macros nos seguintes campos:
BidResponse.seatbid.bid.adm
As macros são compatíveis com formatos de snippet HTML, nativo, URL de vídeo e XML VAST
de vídeo.
Use isso em vez de BidResponse.seatbid.bid.burl se você precisar de mais de um URL de faturamento.
Por exemplo, você pode incluir uma macro como parte de um snippet HTML incorporando ${MACRO} no URL usado para buscar o criativo, em que MACRO é uma das macros compatíveis descritas na especificação OpenRTB.
Macros do Google
O Google é compatível com outras macros além daquelas encontradas na especificação OpenRTB. Elas são formatadas de maneira diferente e aparecem como %%MACRO%% se incorporadas a um URL. A tabela a seguir descreve essas macros:
Uma representação de string de um número inteiro aleatório, sem sinal e de quatro bytes.
CLICK_URL_UNESC
O URL de clique sem escape do anúncio. No snippet, uma versão
de escape do URL de clique de terceiros precisa seguir diretamente a
macro.
Por exemplo, se o URL de clique de terceiros for
http://my.adserver.com/some/path/handleclick?click=clk,
o código a seguir poderá ser usado com a versão com escape único
do URL de clique de terceiros após a invocação da macro:
Primeiro, o URL vai registrar o clique no Google e depois redirecionar para o URL de clique de terceiros.
CLICK_URL_ESC
O URL de clique de escape do anúncio. Use esse URL em vez de
CLICK_URL_UNESC caso você precise passar primeiro o valor por
outro servidor que vai acabar retornando um redirecionamento.
Por exemplo, o código a seguir pode ser usado em um snippet HTML:
Isso vai registrar o clique com my.adserver.com, que
será responsável por redirecionar para o URL transmitido no parâmetro
google_click_url. Isso pressupõe que
my.adserver.com remova o escape do parâmetro
google_click_url.
É possível anexar um URL com escape duplo depois de
%%CLICK_URL_ESC%%. Depois que o escape é removido por
my.adserver.com, resta uma versão com escape único do
URL anexada ao google_click_url. Quando o
google_click_url for buscado, ele será desencapsulado mais uma vez
e depois redirecionado.
CLICK_URL_ESC_ESC
O URL com escape duplo do anúncio. Use esse URL em vez de
CLICK_URL_UNESC caso você precise passar primeiro o valor
por outro servidor que vai acabar retornando um redirecionamento.
Por exemplo, o código a seguir pode ser usado em um snippet HTML:
Expandido para http: se a solicitação de lance não exigir SSL ou para https: se a solicitação de lance exigir SSL.
SITE
É o domínio do URL de conteúdo com escape ou o ID anônimo para inventário anônimo.
SITE_URL
Obsoleto. Substituída pela macro SITE, que oferece funcionalidade idêntica.
TZ_OFFSET
O deslocamento de fuso horário.
VERIFICATION
Os diferentes valores para produção e quando o criativo é verificado no pipeline de verificação. O formato é:
%%?VERIFICATION:true-val:false-val%% em que qualquer valor
exceto macros pode ser usado para true-val e
false-val, incluindo strings vazias. Para o Open Bidding, recomendamos que as exchanges usem essa macro. Depois disso, as plataformas do lado da demanda não precisam fazer mudanças.
Por exemplo, se um criativo incluir
%%?VERIFICATION:-1:5000%%, a substituição de texto
será 5000 na veiculação e -1 no
pipeline de verificação. Isso ajuda a diferenciar esses dois conjuntos de pings.
WINNING_PRICE
O custo de impressão codificado (ou seja, CPI e não CPM) em micros da moeda da conta. Por exemplo, um CPM vencedor de US $5 corresponde a 5.000.000 de micros de CPM ou 5.000 micros de CPI. O valor decodificado de WINNING_PRICE nesse caso seria de 5.000.
O preço vencedor é especificado no CPI.
Para analisar essa macro, é necessário implementar um aplicativo que
descriptografe as confirmações de preço. Consulte a página Descriptografar confirmações de preço para mais informações.
WINNING_PRICE_ESC
WINNING_PRICE com escape de URL.
O Google exige que você use a macro CLICK_URL_UNESC ou CLICK_URL_ESC no criativo do anúncio veiculado por terceiros. O Google usa as macros CLICK_URL para rastreamento de cliques.
O escape de URL em macros usa o seguinte esquema:
O caractere de espaço é substituído por um sinal de adição (+).
Caracteres alfanuméricos (0-9, a-z, A-Z) e caracteres do conjunto !()*,-./:_~ permanecem inalterados.
Todos os outros caracteres são substituídos por %XX, em que XX é o número hexadecimal que representa o caractere.
Restrições e requisitos para publishers
A solicitação de lance inclui informações sobre os tipos de restrições e requisitos que os editores impõem aos criativos no leilão.
BidRequest.bcat
É possível comparar as categorias bloqueadas especificadas por esse campo com as detectadas para seus criativos enviados usando o campo detectedCategories da API Real-time Bidding.
BidRequest.imp.ext.allowed_vendor_type
BidRequest.imp.secure
Na prática, esse valor sempre será definido como true porque o Google exige suporte a SSL para todos os criativos.
BidRequest.imp.{audio/banner/native/video}
BidRequest.imp.{audio/banner/native/video}.api
BidRequest.imp.{audio/banner/native/video}.battr
BidRequest.imp.{audio/banner/video}.mimes
Nunca faça lances com um anúncio que tenha um recurso restrito. Para recursos permitidos, como tipo de fornecedor, retorne um anúncio somente se o tipo de fornecedor estiver na lista allowed_vendor_type em BidRequest. Inclua no seu lance apenas os formatos de anúncio especificados na solicitação de lance preenchendo campos como BidRequest.imp.banner. Consulte os
comentários desses campos na definição do buffer de protocolo BidRequest
para mais detalhes.
Se um anúncio for retornado em BidResponse, você precisará definir com precisão os campos BidResponse.seatbid.bid.attr, BidResponse.seatbid.bid.cat e BidResponse.seatbid.bid.adomain ou BidResponse.seatbid.bid.adm_native.link.url em BidResponse. Se um anúncio tiver vários valores aplicáveis para esses campos, inclua todos eles. Consulte os comentários desses campos na definição do buffer de protocolo BidResponse para mais detalhes.
As respostas que não têm esses campos definidos são descartadas.
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.
Os formatos de anúncio compatíveis incluem anúncios em vídeo, de banner e intersticiais. Para mais informações sobre como usar o Open Measurement em uma resposta de bid que contenha esses formatos, consulte o artigo da Central de Ajuda sobre o SDK do Open Measurement.
Exemplos de respostas de lances
As seções a seguir mostram exemplos de respostas de bid para diferentes tipos de anúncio.
id:"550102L8So5v6gi4C00T36"seatbid{bid{id:"U796oSA426V3U666ue8"impid:"1"price:1.057860016822815crid:"test_creative_id_395811"dealid:"0"adm_native{ver:"1.2"assets{id:6img{url:"https://native.test.com/logo?id=123456"w:200h:200type:LOGO}}assets{id:5img{url:"https://native.test.com/image?id=123456"w:800h:800type:MAIN}}assets{id:4data{value:"Galactic Luxury Cruises"type:SPONSORED}}assets{id:3data{value:"Book today"type:CTATEXT}}assets{id:1title{text:"Luxury Mars Cruises"}}assets{id:2data{value:"Visit the planet in a luxury spaceship."type:DESC}}link{url:"https://www.google.com"}}[com.google.doubleclick.bid]{impression_tracking_url:"https://test.com/impression?id=123456"impression_tracking_url:"https://test.com/impression?id=123456"ad_choices_destination_url:"https://test.com/preferences"event_notification_token{payload:"token"}billing_id:73917825312dsa{adrender:true}clickurl:"google.com"}}}cur:"JPY"[com.google.doubleclick.bid_response]{processing_time_ms:17}
JSON do OpenRTB
Mostrar o exemplo
{"id":"550102L8So5v6gi4C00T36","seatbid":[{"bid":[{"id":"U796oSA426V3U666ue8","impid":"1","price":1.057860016822815,"crid":"test_creative_id_395811","dealid":"0","ext":{"impression_tracking_url":["https://test.com/impression?id=123456","https://test.com/impression?id=123456"],"ad_choices_destination_url":"https://test.com/preferences","event_notification_token":{"payload":"token"},"billing_id":"73917825312","dsa":{"adrender":1},"clickurl":["google.com"]},"adm":"{\"ver\":\"1.2\",\"assets\":[{\"id\":6,\"img\":{\"url\":\"https://native.test.com/logo?id=123456\",\"w\":200,\"h\":200,\"type\":2}},{\"id\":5,\"img\":{\"url\":\"https://native.test.com/image?id=123456\",\"w\":800,\"h\":800,\"type\":3}},{\"id\":4,\"data\":{\"value\":\"Galactic Luxury Cruises\",\"type\":1}},{\"id\":3,\"data\":{\"value\":\"Book today\",\"type\":12}},{\"id\":1,\"title\":{\"text\":\"Luxury Mars Cruises\"}},{\"id\":2,\"data\":{\"value\":\"Visit the planet in a luxury spaceship.\",\"type\":2}}],\"link\":{\"url\":\"https://www.google.com\"}}"}]}],"cur":"JPY","ext":{"processing_time_ms":17}}
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2026-02-23 UTC."],[],["Applications must respond to each `BidRequest` with a parsable `BidResponse`, using Protobuf or an HTTP 204 for no bids. Creatives are identified by a unique `crid`. Ad attributes, such as VPAID and MRAID, are declared in specific fields. Utilize impression tracking URLs and avoid deprecated fields. Open Bidding bid responses are similar to Authorized Buyers. Ad sizes in the response must match the request. Macros are used in URLs. Publisher requirements are specified in the `BidRequest`. The response must accurately reflect these requirements and provide the accurate ad attributes and links.\n"]]
