Depois que o 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 a mensagem BidResponse do Protobuf
O Authorized Buyers envia o BidRequest como o corpo da mensagem de
um POST HTTP. Se o endpoint de lances estiver configurado para usar o
formato Protobuf, o aplicativo precisará enviar uma resposta com o
cabeçalho Content-Type definido como application/octet-stream
e um corpo de mensagem que consiste em um buffer de protocolo serializado. O buffer de protocolo
é uma mensagem BidResponse, conforme definido em
openrtb.proto. Seu aplicativo precisa retornar um BidResponse
analisável em resposta a cada BidRequest. Tempos limite
e respostas que não podem ser analisadas são considerados erros, e o Google limita
os proponentes com altas taxas de erros.
Se você não quiser dar lances em uma impressão, retorne uma resposta HTTP 204 vazia. É possível acessar openrtb.proto na página dados de referência.
ID do criativo
O BidResponse especifica um criativo pelo campo
BidResponse.seatbid.bid.crid (limite de 64 bytes). Mesmo criativos semelhantes precisam ter valores exclusivos para esse campo se diferirem em qualquer característica notável, incluindo, mas não se limitando a: tamanho, URL declarado, atributos do criativo e tipos de fornecedor. Em outras palavras, é preciso atribuir IDs de criativo diferentes a dois anúncios que:
Aparecer ou se comportar de maneira diferente.
Renderizar em imagens diferentes.
Renderização por meios diferentes (por exemplo, um anúncio consiste em uma imagem,
enquanto 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 usando uma combinação de BidResponse.seatbid.bid.apis e BidResponse.seatbid.bid.attr ou a extensão BidResponse.seatbid.bid.ext.attribute. Confira a seguir
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 Creatives
para saber como receber feedback sobre as propriedades detectadas dos
seus criativos.
Campos do Open Bidding
As respostas de lances enviadas por 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 podem especificar um pequeno número de
campos adicionais, e alguns campos atuais podem ter usos alternativos. Isso
inclui o seguinte:
OpenRTB
Authorized Buyers
Detalhes
BidResponse.imp[].pmp.deals[].id
BidResponse.ad[].adslot[].exchange_deal_id
O ID da transação do namespace da troca associado a esse lance e informado aos editores.
Token usado para identificar as informações finais do comprador de terceiros se a troca como um bidder do Open Bidding for um intermediário. Ele é obtido do
comprador externo e precisa ser transmitido ao Google sem alterações na resposta
do lance.
Recomendações
Ative as conexões HTTPS persistentes (também conhecidas como "sinal de atividade" ou
"reutilização de conexão") nos seus servidores. Defina o tempo limite como mínimo de 10 segundos. Valores mais altos são benéficos em muitos casos. O Google verifica
isso durante os testes iniciais de latência do seu aplicativo, porque
o Authorized Buyers envia solicitações a uma taxa alta e precisa evitar a
sobrecarga de latência ao 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 o código do bidder sem dependências de campos descontinuados,
que podem causar erros nos lances.
Inclua BidResponse.seatbid.bid.w e
BidResponse.seatbid.bid.h no BidResponse. Uma
BidResponse para uma solicitação que inclui vários tamanhos de anúncio precisa
incluir esses campos ou será removida do leilão.
Limite o tamanho da resposta para menos de 8 KB. 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 Protobuf do Google ou do OpenRTB, somente mensagens BidResponse serializadas serão aceitas.
É possível criar e serializar uma mensagem BidResponse usando o
seguinte código 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 o criativo
Sua resposta de lance especifica o criativo que será veiculado se o lance for vencedor. 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, você pode especificar seu criativo usando um dos
campos a seguir, 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 servidores usando um snippet HTML no campo BidResponse.seatbid.bid.adm. O snippet é incluído em
um iFrame inserido na página da Web, resultando na recuperação e renderização do anúncio
quando a página é carregada. Você deve criar o snippet HTML para que o
anúncio (banner ou intersticial) é renderizado corretamente dentro de um iFrame e em um
tamanho apropriado para o espaço de anúncio em que você está licitando.
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 em vídeo, nativo ou intersticial).
O bidder declarou o tamanho na resposta do lance. A declaração de tamanho é
necessária sempre que mais de um tamanho está 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, mas lembre-se das restrições para especificar o
campo crid na seção
Criar mensagem BidResponse.
Um uso para isso é colocar informações extras nos argumentos dos URLs que
são 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 servidores.
As macros são textos formatados incorporados a alguns campos de resposta de 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 incluir a macro AUCTION_PRICE no criativo de snippet
HTML incluído no lance, ela será substituída por um
valor que pode ser descriptografado 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 os 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, é possível 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 do OpenRTB.
Macros de RTB do Google
O Google oferece suporte a macros adicionais além das encontradas na especificação do OpenRTB. Elas têm um formato 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 assinatura e de quatro bytes.
CLICK_URL_UNESC
O URL de clique sem escape do anúncio. No snippet, uma versão escapada 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:
O URL vai registrar o clique com o Google e redirecionar para o URL de clique de terceiros.
CLICK_URL_ESC
O URL de clique com escape do anúncio. Use esse valor em vez de
CLICK_URL_UNESC se você precisar transmitir primeiro o valor por
outro servidor que vai retornar 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 pelo redirecionamento para o URL transmitido no parâmetro google_click_url. Isso pressupõe que
my.adserver.com escape do parâmetro
google_click_url.
É possível anexar um URL com escape duplo após
%%CLICK_URL_ESC%%. Depois que o escape é feito por
my.adserver.com, uma versão com escape único do
URL é anexada ao google_click_url. Quando o
google_click_url for buscado, ele vai escapar mais uma vez
e depois redirecionar.
CLICK_URL_ESC_ESC
O URL com escape duplo do anúncio. Use esse valor em vez de
CLICK_URL_UNESC se você precisar transmitir primeiro o valor
por outro servidor que vai retornar 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 ela exigir SSL.
SITE
É o domínio do URL de conteúdo com escape ou o ID anônimo do inventário anônimo.
SITE_URL
Obsoleto. Substituído pela macro SITE, que oferece funcionalidade idêntica.
TZ_OFFSET
A diferença 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 trocas 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 5.000.
O preço vencedor é especificado no CPI.
Para analisar essa macro, você precisa implementar um aplicativo que
descriptografa as confirmações de preço. Consulte a página
Como descriptografar confirmações de preço
para mais informações.
WINNING_PRICE_ESC
WINNING_PRICE com codificação 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 o 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 (+).
Os caracteres alfanuméricos (0-9, a-z, A-Z) e os 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 colocam nos criativos no leilão.
BidRequest.bcat
É possível comparar as categorias bloqueadas especificadas por esse campo com as
detectadas para os 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á 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 dê lances com um anúncio que tenha um recurso restrito. Para recursos permitidos,
como o tipo de fornecedor, retorne um anúncio somente se o tipo de fornecedor estiver na
lista allowed_vendor_type no BidRequest. Somente os formatos de
anúncio especificados na solicitação de lance preenchendo campos como
BidRequest.imp.banner precisam ser incluídos no lance. Consulte os
comentários sobre esses campos na definição do buffer de protocolo
BidRequest para mais detalhes.
Se um anúncio for retornado em BidResponse, será necessário definir corretamente 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, você precisará incluir todos os valores. Consulte os comentários desses campos na
definição do buffer de protocolo BidResponse para mais detalhes.
As respostas que não tiverem esses campos definidos serão descartadas.
Open Measurement
Com o Open Measurement, você pode 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, banner e intersticiais. Para mais
informações sobre como usar o Open Measurement em uma resposta de lance que contém esses
formatos, consulte o artigo da Central de Ajuda SDK do Open Measurement.
Exemplos de respostas de lances
As seções a seguir mostram exemplos de respostas de lances para diferentes tipos de anúncios.
id:"96Z599PGNvp7Mr99138Fm0"seatbid{bid{id:"NQb32Ge7Rtt84wFn2p8"impid:"1"price:0.153584adid:"test_creative_id_272596"adomain:"google.com"crid:"test_creative_id_272596"cat:"IAB13-7"burl:"https://test.com/imp?id=123456"adm_native{ver:"1.2"assets{id:1required:truetitle{text:"Luxury Mars Cruises"}}assets{id:2required:truedata{value:"Visit the planet in a luxury spaceship."}}assets{id:3required:falsedata{value:"Book today"}}assets{id:4required:truedata{value:"Galactic Luxury Cruises"}}assets{id:5required:trueimg{url:"https://native.test.com/image?id=123456"w:1200h:627}}link{url:"https://www.google.com"}eventtrackers{event:IMPRESSIONmethod:IMGurl:"https://test.com/event?id=123456"}privacy:"https://adssettings.google.com/whythisad?source=display&reasons=OMITTED"}[com.google.doubleclick.bid]{ad_choices_destination_url:"https://test.com/preferences"billing_id:29846056590dsa{behalf:"TEST_ADVERTISER"paid:"TEST_PAYING_ENTITY"adrender:false}}}bid{id:"4vwb23qm6iqU6w6G978"impid:"1"price:0.153584adid:"test_creative_id_272596"adomain:"google.com"crid:"test_creative_id_272596"cat:"IAB21"burl:"https://test.com/imp?id=123456"adm_native{ver:"1.2"assets{id:1required:truetitle{text:"Luxury Mars Cruises"}}assets{id:2required:truedata{value:"Visit the planet in a luxury spaceship."}}assets{id:3required:falsedata{value:"Book today"}}assets{id:4required:truedata{value:"Galactic Luxury Cruises"}}assets{id:5required:trueimg{url:"https://native.test.com/image?id=123456"w:1200h:627}}link{url:"https://www.google.com"}eventtrackers{event:IMPRESSIONmethod:IMGurl:"https://test.com/event?id=123456"}privacy:"https://adssettings.google.com/whythisad?source=display&reasons=OMITTED"}[com.google.doubleclick.bid]{ad_choices_destination_url:"https://test.com/preferences"dsa{behalf:"TEST_ADVERTISER"paid:"TEST_PAYING_ENTITY"adrender:false}}}seat:"4528:1161:591635"group:false}bidid:"hgu4ev7j-ZK929XM0-79f7-0A23O0VN2CFC"cur:"USD"
JSON do OpenRTB
Mostrar o exemplo
{"id":"96Z599PGNvp7Mr99138Fm0","seatbid":[{"bid":[{"id":"NQb32Ge7Rtt84wFn2p8","impid":"1","price":0.153584,"adid":"test_creative_id_272596","adomain":["google.com"],"crid":"test_creative_id_272596","cat":["IAB13-7"],"burl":"https://test.com/imp?id=123456","ext":{"ad_choices_destination_url":"https://test.com/preferences","billing_id":"29846056590","dsa":{"behalf":"TEST_ADVERTISER","paid":"TEST_PAYING_ENTITY","adrender":0}},"adm":"{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"text\":\"Luxury Mars Cruises\"}},{\"id\":2,\"required\":1,\"data\":{\"value\":\"Visit the planet in a luxury spaceship.\"}},{\"id\":3,\"required\":0,\"data\":{\"value\":\"Book today\"}},{\"id\":4,\"required\":1,\"data\":{\"value\":\"Galactic Luxury Cruises\"}},{\"id\":5,\"required\":1,\"img\":{\"url\":\"https://native.test.com/image?id=123456\",\"w\":1200,\"h\":627}}],\"link\":{\"url\":\"https://www.google.com\"},\"eventtrackers\":[{\"event\":1,\"method\":1,\"url\":\"https://test.com/event?id=123456\"}],\"privacy\":\"https://adssettings.google.com/whythisad?source=display&reasons=OMITTED\"}"},{"id":"4vwb23qm6iqU6w6G978","impid":"1","price":0.153584,"adid":"test_creative_id_272596","adomain":["google.com"],"crid":"test_creative_id_272596","cat":["IAB21"],"burl":"https://test.com/imp?id=123456","ext":{"ad_choices_destination_url":"https://test.com/preferences","dsa":{"behalf":"TEST_ADVERTISER","paid":"TEST_PAYING_ENTITY","adrender":0}},"adm":"{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"text\":\"Luxury Mars Cruises\"}},{\"id\":2,\"required\":1,\"data\":{\"value\":\"Visit the planet in a luxury spaceship.\"}},{\"id\":3,\"required\":0,\"data\":{\"value\":\"Book today\"}},{\"id\":4,\"required\":1,\"data\":{\"value\":\"Galactic Luxury Cruises\"}},{\"id\":5,\"required\":1,\"img\":{\"url\":\"https://native.test.com/image?id=123456\",\"w\":1200,\"h\":627}}],\"link\":{\"url\":\"https://www.google.com\"},\"eventtrackers\":[{\"event\":1,\"method\":1,\"url\":\"https://test.com/event?id=123456\"}],\"privacy\":\"https://adssettings.google.com/whythisad?source=display&reasons=OMITTED\"}"}],"seat":"4528:1161:591635","group":0}],"bidid":"hgu4ev7j-ZK929XM0-79f7-0A23O0VN2CFC","cur":"USD"}
ad{adslot{id:1max_cpm_micros:158000billing_id:41106584355deal_id:1}click_through_url:"google.com"attribute:70buyer_creative_id:"test_creative_id_251451"advertiser_name:"Google"native_ad{headline:"Luxury Mars Cruises"body:"Visit the planet in a luxury spaceship."call_to_action:"Book today"advertiser:"Galactic Luxury Cruises"image{url:"https://native.test.com/image?id=123456"width:1200height:222}app_icon{url:"https://native.test.com/icon?id=123456"width:512height:512}star_rating:4.300000190734863click_link_url:"https://www.google.com"}impression_tracking_url:"https://test.com/imp?id=123456"impression_tracking_url:"https://test.com/imp?id=123456"event_notification_token:"token"skadn{version:"4.0"network:"l6x39K4z"itunesitem:"731305960"sourceapp:"627009739"fidelities{fidelity_type:STOREKIT_RENDERED_ADSnonce:"9216faff-74a9-4b35-badc-66878c35f67c"timestamp:1728975919221signature:"b0USXkmg02Q3v6p301kYOHG36CCOWWdEo52RHRttB9t8PTNi79qL17E4D6h7UeUSuq479oTK13G2Ev34MJlU86C5vY1SMVw2"}fidelities{fidelity_type:VIEW_THROUGH_ADSnonce:"9216faff-74a9-4b35-badc-66878c35f67c"timestamp:1728975919221signature:"4Cf4NH6239z9f3wa8j6420Z7H0UISYxyxN5720444dkq6457I5FY0Jg8bk1xge2P8YgiDp74l2738136v2g1A8D50331IRm0"}source_identifier:1}click_tracking_urls:"https://google.com/rtb/click?imp_id=55d2112c-4947-4da5-bc37-b79ebf4577dd"advertised_app_id:"APP_ID_OMITTED"app_promotion_type:INSTALLS}processing_time_ms:63
[null,null,["Última atualização 2025-02-12 UTC."],[[["Bid responses must be serialized `BidResponse` protocol buffers with the `Content-Type` header set to `application/octet-stream` for Protobuf, and a parsable `BidResponse` is required for each `BidRequest`, while an empty HTTP 204 response signals no bid."],["Each creative needs a unique `crid` (creative ID) limited to 64 bytes, and this ID must be unique across creatives if there are differences in size, declared URL, attributes, vendor types, appearance, behavior, or rendering method."],["Ad characteristics should be declared using `BidResponse.seatbid.bid.apis`, `BidResponse.seatbid.bid.attr`, or `BidResponse.seatbid.bid.ext.attribute`, with specific values indicating VPAID, MRAID, SIZELESS, or PLAYABLE attributes, respectively, and additional attributes from `buyer-declarable-creative-attributes.txt`."],["Responses should remain under 8KB, utilize persistent HTTPS connections with at least a 10-second timeout, and employ `BidResponse.seatbid.bid.burl` or `BidResponse.seatbid.bid.ext.impression_tracking_url` for tracking impressions."],["The `BidResponse` must accurately set creative attributes (`BidResponse.seatbid.bid.attr`), categories (`BidResponse.seatbid.bid.cat`), and advertiser domain (`BidResponse.seatbid.bid.adomain`) or native ad link (`BidResponse.seatbid.bid.adm_native.link.url`), as responses lacking these are discarded."]]],[]]
