Depois que o aplicativo processar a solicitação de lance do Google, ele precisará criar e enviar uma resposta. Este guia explica como codificar seu aplicativo para criar a resposta.
Criar mensagem do BidResponse
O Authorized Buyers envia BidRequest
como o corpo da mensagem de
uma POST
HTTP. A resposta enviada pelo aplicativo precisa ter o cabeçalho Content-Type
definido como application/octet-stream
e o corpo da mensagem consistindo em um buffer de protocolo serializado. O buffer
de protocolo é uma mensagem BidResponse
, conforme definido em
realtime-bidding.proto
. O app precisa retornar um BidResponse
analisável em resposta a cada BidRequest
. Os tempos limite
e as respostas que não podem ser analisados são considerados erros, e o Google limita
os bidders com altas taxas de erro.
Se você não quiser dar lances em uma impressão, defina apenas o campo processing_time_ms
e deixe todos os outros em branco. Você pode conseguir realtime-bidding.proto
na página de dados de referência.
ID do criativo
Seu BidResponse
especifica um criativo por meio do campo buyer_creative_id
(limite de 64 bytes). Mesmo criativos semelhantes
precisam ter valores exclusivos de buyer_creative_id
se forem diferentes em
características notáveis, incluindo, mas não se limitando a: tamanho, URL declarado, atributos do criativo e tipos de fornecedor. Ou seja, você precisa dar IDs de criativo diferentes
a dois anúncios que tenham:
- Ter a aparência ou o comportamento diferente.
- Renderize em imagens diferentes.
- Renderize por meios diferentes (por exemplo, um anúncio consiste em uma imagem, enquanto o outro contém Flash).
Ao projetar seu aplicativo, escolha uma maneira sistemática de gerar identificadores que faça sentido para os tipos de criativos que você planeja enviar.
Atributos do anúncio
É necessário declarar os atributos do criativo que descrevem totalmente as características
do anúncio e a segmentação dele no BidResponse.Ad.attribute
. Os
atributos que precisam ser declarados são (consulte também a lista completa de atributos
compatíveis em
buyer-declarable-creative-attributes.txt):
7 Tagging: IsTagged
O anúncio contém um pixel ou um beacon da Web com a finalidade de criar uma lista de IDs de cookies para as atividades de remarketing subsequentes.8 Remarketing: IsRemarketing
O anúncio segmenta consumidores com base no ID do cookie ou do dispositivo, em que a lista desses IDs representa um conjunto de consumidores que interagiram anteriormente com um site de propriedade do comprador ou representado por ele.9 UserInterestTargeting: IsUserInterestTargeted
O anúncio segmenta consumidores com base no ID do cookie ou do ID do dispositivo, em que a lista desses IDs representa um conjunto de consumidores definido pelo comprador como um grupo de interesse comum.30 InstreamVastVideoType: Vpaid
O anúncio exige suporte a VPAID para ser renderizado.32 MraidType: MRAID
O anúncio exige a API MRAID para ser renderizado.
Além disso, os atributos a seguir são compatíveis, mas a declaração deles não é necessária, já que o Authorized Buyers os detecta automaticamente e bloqueia (ou permite) seus criativos com base nos valores detectados, e não na sua declaração. Consulte a API Creatives para saber como receber feedback sobre as propriedades detectadas dos seus criativos.
34 RichMediaCapabilityType: RichMediaCapabilityFlash
O anúncio requer suporte para Flash para ser renderizado.50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
O anúncio não requer Flash para ser renderizado.47 RichMediaCapabilityType: RichMediaCapabilitySSL
O anúncio pode ser renderizado em uma página SSL. O Authorized Buyers trata criativos com diferentes valores declarados desse atributo como diferentes. Eles serão analisados separadamente e têm um status de aprovação distinto. Portanto, se você der lances com versões SSL e não SSL da mesma peça criativa, declare esse atributo adequadamente para que essa distinção seja refletida corretamente no AdX.
Campos do Open Bidding
As respostas de lance enviadas pelos bidders da troca e da rede que participam do Open Lances são semelhantes às dos Authorized Buyers que participam dos lances padrão em tempo real. Os clientes do Open Bidding podem especificar um pequeno número de campos adicionais, e alguns campos existentes podem ter usos alternativos. Elas incluem:
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. |
BidResponse.seatbid[].bid[].ext.exchange_deal_type |
BidResponse.ad[].adslot[].exchange_deal_type |
É o tipo de transação informado aos editores, afetando como a transação é tratada no leilão. |
BidResponse.seatbid[].bid[].ext.third_party_buyer_token |
BidResponse.ad[].adslot[].third_party_buyer_token |
Token usado para identificar as informações do comprador terceirizado final se a troca como um Open Bidding for uma intermediária. Ela é recebida do comprador terceirizado e precisa ser transmitida ao Google sem mudanças na resposta do lance. |
Recomendações
- Ativar conexões HTTPS persistentes (também conhecidas como "keep-alive" ou "reutilização de conexão") nos seus servidores. Defina o tempo limite para no mínimo 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 opcional de rastreamento de impressões para rastrear quando a impressão é renderizada, e não quando o bidder vence. Devido à desistência entre vitórias e renderizações, isso produz estatísticas de rastreamento mais precisas.
- Mantenha seu código do bidder livre de dependências em campos descontinuados, o que pode causar falhas nos lances.
- Inclua
BidResponse.Ad.width
eBidResponse.Ad.height
noBidResponse
. UmBidResponse
em uma solicitação que inclui vários tamanhos de anúncio precisa incluir os valoreswidth
eheight
. Caso contrário, ela será descartada. - Limite o tamanho da resposta a menos de 8 mil. Respostas muito grandes podem aumentar a latência da rede e causar tempos limite.
- Siga as diretrizes para lances no inventário do iOS que exigem atribuição da SKAdNetwork.
Exemplo de resposta do lance
Os exemplos a seguir representam amostras legíveis das solicitações Protobuf e JSON.
JSON do OpenRTB
Protobuf do OpenRTB
Importante: as mensagens Protobuf retratadas nos exemplos estão representadas aqui como texto legível. No entanto, não é assim que as mensagens são enviadas. Ao usar o formato do Google ou do Protobuf do OpenRTB, somente mensagens do 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
A resposta do lance especifica o criativo que será veiculado caso seu lance vencer. Seu lance precisa incluir um dos formatos de anúncio compatíveis (AMP, vídeo, nativo). Neste exemplo, especificamos o criativo usando o campo html_snippet
.
Também é possível especificar o criativo usando um dos seguintes campos, com base no formato do anúncio:
- Anúncio renderizado pelo SDK
BidResponse.Ad.sdk_rendered_ad
- AMP
BidResponse.Ad.amp_ad_url
- Vídeo
BidResponse.Ad.video_url
ouBidResponse.Ad.video_vast_xml
- Nativo
BidResponse.Ad.native_ad
Especifique um anúncio hospedado nos seus próprios servidores usando um snippet HTML no
campo html_snippet
de BidResponse
. O snippet está em um iframe inserido na página da Web, resultando na recuperação e renderização do anúncio quando a página é carregada. Crie o snippet de HTML para que o anúncio (banner ou intersticial) seja renderizado corretamente dentro de um iframe e em um tamanho adequado para o espaço de anúncio para o qual você está fazendo 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 quando:
- Um anúncio é um banner normal (não em vídeo, nativo ou intersticial).
- O bidder declarou o tamanho na resposta do lance. A declaração de tamanho é obrigatória quando há mais de um tamanho 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.
O campo html_snippet
é compatível com qualquer código HTML válido que seja renderizado corretamente, mas lembre-se das restrições de especificação do campo buyer_creative_id
na seção Criar mensagem do BidResponse. Um
uso para isso é colocar informações extras em argumentos dos URLs que são
buscados nos seus servidores como parte da renderização do anúncio. Isso permite que você transmita
dados arbitrários sobre a impressão para seus próprios servidores.
A maioria das políticas para snippets HTML retornados nas respostas de lance é igual à dos anúncios de terceiros. Para mais informações, consulte Diretrizes do programa Authorized Buyers, Requisitos para veiculação de anúncios de terceiros e Declarar URLs de clique em anúncios.
Especificar macros
O snippet HTML que define um criativo pode incluir uma ou mais construções especiais chamadas macros. No momento da veiculação do anúncio, os valores são substituídos por
macros. Por exemplo, o aplicativo de lances cliente pode usar a
macro WINNING_PRICE
para determinar quanto pagou pelo anúncio
se ele vencer o leilão. Para analisar essa macro, é necessário implementar um
aplicativo que descriptografe confirmações de preço. Consulte a página Como descriptografar confirmações de preço para mais informações.
Especifique uma macro como parte de um snippet HTML no formato %%MACRO%%
, em que MACRO
é uma das macros compatíveis listadas na tabela abaixo.
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 acompanhamento de cliques.
Para usar uma macro, inclua-a no anúncio para que o URL seja buscado quando
alguém clicar nele. O valor de retorno da busca é um redirecionamento para outro
URL anexado ao CLICK_URL
.
Macro | Descrição |
---|---|
ADVERTISING_IDENTIFIER |
Permite que os compradores recebam o IDFA do iOS ou o ID de publicidade do Android na renderização de impressões. Consulte Como descriptografar identificadores de anunciante para ver mais detalhes. |
CACHEBUSTER |
Uma representação de string de um número inteiro de quatro bytes aleatório não assinado. |
CLICK_URL_UNESC |
O URL de clique sem escape para o anúncio. No snippet, uma versão com escape do URL de clique de terceiros precisa seguir diretamente a macro. Por exemplo, se o URL de clique de terceiros for <a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> No momento da veiculação do anúncio, ele é expandido para: <a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> Primeiro, o URL registra o clique com o Google e, em seguida, redireciona para o URL de clique de terceiros. |
CLICK_URL_ESC |
O URL de clique com escape do anúncio. Use-o em vez de
Por exemplo, o código a seguir pode ser usado em um snippet HTML: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a> No momento da veiculação do anúncio, ele é expandido para: <a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a> Isso vai registrar o clique com É possível anexar um URL com escape duplo após
|
CLICK_URL_ESC_ESC |
O URL com escape duplo para o anúncio. Use-o em vez de
Por exemplo, o código a seguir pode ser usado em um snippet HTML: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a> No momento da veiculação do anúncio, ele é expandido para: <a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a> |
SCHEME |
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 com escape do URL do URL de conteúdo ou o ID anônimo do inventário anônimo. |
SITE_URL |
Obsoleto. Substituída pela macro SITE, que fornece 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 trocas usem essa macro.
Depois disso, as plataformas de demanda não vão precisar fazer mudanças.Por exemplo, se um criativo incluísse %%?VERIFICATION:-1:5000%% , a substituição de texto seria 5000 na veiculação e -1 no pipeline de verificação. Isso ajuda a diferenciar entre os dois conjuntos de pings. |
WINNING_PRICE |
O custo de impressão codificado (ou seja, CPI em vez de 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. Nesse caso,o valor decodificado de WINNING_PRICE seria 5.000.
O preço vencedor é especificado em CPI.
|
WINNING_PRICE_ESC |
WINNING_PRICE com escape de URL. |
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 queXX
é o número hexadecimal que representa o caractere.
Restrições do editor
Os editores usam o BidRequest
para transmitir restrições sobre os anúncios
permitidos. É necessário aplicar as restrições nestes campos:
allowed_vendor_type
excluded_attribute
excluded_sensitive_category
Um campo especifica os recursos permitidos do anúncio, e o outro especifica
os recursos não permitidos. Nunca retorne um anúncio com um recurso não permitido. Para recursos
permitidos, como tipo de fornecedor, retorne um anúncio somente se o tipo dele estiver na
lista allowed_vendor_type
no BidRequest
. Consulte os
comentários sobre esses campos na definição do buffer de protocolo
BidRequest
para mais detalhes.
Se um snippet HTML for retornado em BidResponse
, será necessário definir com precisão os campos attribute
, category
e click_through_url
em BidResponse
.
Se um anúncio tiver vários valores aplicáveis a esses campos, você precisará incluir todos eles. Leia os comentários sobre esses campos na definição do buffer de protocolo BidResponse
para mais detalhes.
As respostas que não tiverem esses campos definidos serão descartadas.
Os valores possíveis de BidRequest.excluded_attribute
são (consulte publisher-excludable-creative-attributes.txt):
7 Tagging: IsTagged
Os anúncios não serão permitidos se tiverem um pixel ou um beacon da Web com a finalidade de criar uma lista de IDs de cookies para as atividades de remarketing subsequentes.8 CookieTargeting: IsCookieTargeted
Os anúncios não serão permitidos se segmentarem consumidores com base no ID do cookie, em que a lista de IDs do cookie representa um conjunto de consumidores que interagiram anteriormente com um site de propriedade do comprador ou representado pelo comprador.9 UserInterestTargeting: IsUserInterestTargeted
Os anúncios não serão permitidos se segmentarem consumidores com base no ID do cookie, em que a lista de IDs do cookie representa um conjunto de consumidores definido pelo comprador como um grupo de interesse comum.21 CreativeType: Html
Os anúncios não têm permissão para usar o campohtml_snippet
ousnippet_template
emBidResponse.Ad
.22 CreativeType: VastVideo
Os anúncios não têm permissão para usar o campovideo_url
emBidResponse.Ad
.30 InstreamVastVideoType: Vpaid
Os anúncios não podem exigir compatibilidade com VPAID para serem renderizados.32 MraidType: MRAID
Os anúncios não podem exigir a API MRAID para renderizar.34 RichMediaCapabilityType: RichMediaCapabilityFlash
Os anúncios não podem exigir suporte para Flash para serem renderizados.39 RichMediaCapabilityType: RichMediaCapabilityHTML5
Os anúncios não podem exigir recursos HTML5 para serem renderizados.48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
Os anúncios não são permitidos para fazer solicitações não SSL.
Portanto, se o campo excluded_attribute
tiver o valor 7, não retorne um anúncio que use um pixel ou um beacon da Web para criar uma lista. Se um anúncio fizer isso, ele precisará definir o valor 7 no
campo de atributo do BidResponse
.
Da mesma forma, se o campo excluded_attribute
contiver o valor 48, retorne apenas anúncios que possam ser renderizados em uma página SSL e declare o atributo 47 AppCompatCapabilityType: AppCompatCapabilitySSL.
Além disso, o campo excluded_sensitive_category
em
BidRequest
usa códigos do arquivo
ad-sensitive-categories.txt
disponível na página de dados de referência. Veja a seguir as descrições estendidas de alguns desses códigos:
3 Politics
Inclui política ou questões sociais polêmicas. Não inclui anúncios de agências de notícias que geralmente não têm relação com opiniões de ativistas sobre essas questões.4 Dating
Inclui serviços de relacionamento e comunidades de namoro on-line.5 Religion
Inclui anúncios religiosos e que fazem apologia ou crítica a pontos de vista religiosos. Não inclui astrologia nem formas alternativas de espiritualidade.7 Video Games (Casual & Online)
Inclui videogames, jogos on-line e jogos para download. Não inclui consoles de videogame.8 Ringtones & Downloadables
Complementos para dispositivos móveis, incluindo toques e outros produtos para download, como protetores de tela e planos de fundo para PCs, além de gráficos e modelos de layout para redes sociais.10 Get Rich Quick
Esquemas que prometem ganhos rápidos18 Weight Loss
Inclui perda de peso, dietas, produtos e programas relacionados. Não inclui anúncios sobre alimentação saudável ou boa forma em geral.19 Cosmetic Procedures & Body Modification
Inclui lifting, lipoaspiração, laser, remoção de pelos e implante capilar, tatuagens e modificação do corpo.23 Drugs & Supplements:
Inclui produtos farmacêuticos, vitaminas, suplementos e varejistas relacionados. Não inclui recursos que fornecem informações sobre medicamentos.24 Sexual & Reproductive Health
Inclui anúncios sobre desempenho sexual e fertilidade. Não inclui produtos comuns de gravidez.35 Social Casino Games
Inclui simulações de jogos de azar (incluindo, sem limitação, pôquer, máquinas caça-níqueis, bingo, loterias, apostas esportivas, apostas em corridas, bem como outros jogos de cartas e de cassino) em que não é possível ganhar itens de valor (como dinheiro ou prêmios).36 Significant Skin Exposure
Imagens de anúncios em que qualquer parte do corpo humano, do esterno até o meio da coxa, não esteja vestida ou com roupas íntimas, trajes de banho, lingerie ou outras roupas transparentes ou itens que não sejam de vestuário, como toalhas ou lençóis.37 Sensationalism
Anúncios que têm como objetivo induzir os usuários a clicar neles despertando a curiosidade deles, geralmente usando uma mensagem teaser com linguagem ou imagens exageradas. Inclui anúncios que abordam assuntos sensacionalistas (como óbito, divórcio ou prisão de celebridades) ou que têm como objetivo chocar o usuário.
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.No momento, os formatos de anúncio compatíveis incluem anúncios intersticiais, de banner e em vídeo. Para mais informações sobre como usar o Open Measurement em uma resposta de lance com esses formatos, consulte o artigo da Central de Ajuda SDK do Open Measurement.
Exemplos de respostas de lance
As seções a seguir mostram exemplos de respostas de lance para diferentes tipos de anúncio.