Depois que seu aplicativo processar a solicitação de lance do Google, ele deverá 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
um POST
HTTP. A resposta enviada por seu 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 protocolo
buffer é uma mensagem BidResponse
, conforme definido em
realtime-bidding.proto
. Seu aplicativo precisa retornar um
BidResponse
em resposta a cada BidRequest
. Tempos limite
e as respostas que não podem ser analisadas são consideradas erros, e as limitações do Google
proponentes com altas taxas de erro.
Se não quiser dar um lance em uma impressão, defina o
processing_time_ms
sozinho e deixa todos os outros campos
vazio. Você pode acessar o realtime-bidding.proto
no
dados de referência.
ID do criativo
Seu BidResponse
especifica um criativo por meio da
Campo buyer_creative_id
(limite de 64 bytes). Até mesmo criativos semelhantes
precisam ter valores exclusivos para buyer_creative_id
se forem diferentes
características notáveis, incluindo, mas não se limitando a: tamanho, URL declarado,
atributos de criativo e tipos de fornecedor. Em outras palavras, você deve dar diferentes
IDs de criativo a dois anúncios que:
- Ter uma aparência ou um comportamento diferente.
- Renderizar para imagens diferentes.
- Renderizar por meios diferentes (por exemplo, um anúncio consiste em uma imagem, enquanto o outro contém Flash).
Ao projetar seu aplicativo, é preciso definir uma forma sistemática de gerar identificadores que façam sentido para os tipos de criativos que você planeja para enviar.
Atributos do anúncio
Você deve declarar os atributos do criativo que descrevem completamente
características e sua segmentação em BidResponse.Ad.attribute
. A
atributos que devem ser declarados são (veja também a lista completa de
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 o remarketing subsequente.8 Remarketing: IsRemarketing
O anúncio segmenta consumidores com base no ID do cookie ou do dispositivo, em que a lista de IDs de cookies ou IDs de dispositivos representam 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 dispositivo, em que a lista de IDs de cookies ou de IDs de dispositivos representam um conjunto de consumidores que o comprador definidos como um grupo de interesse comum.30 InstreamVastVideoType: Vpaid
O anúncio exige compatibilidade com VPAID para ser renderizado.32 MraidType: MRAID
O anúncio requer a API MRAID para ser renderizado.
Além disso, os seguintes atributos são aceitos, mas sua declaração é não é necessária, porque o Authorized Buyers as detecta automaticamente e bloqueia (ou permitem) seus criativos com base nos valores detectados, e não em sua declaração. Consulte API Creatives para saber como receber feedback sobre as propriedades detectadas do seu 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 os criativos com valores declarados diferentes desse atributo (eles serão analisados separadamente e têm status de aprovação distintos). Assim, se você definir lances com SSL e versões não SSL do mesmo criativo, você deverá declarar esse atributo de acordo, para que essa distinção seja devidamente refletida no AdX.
Campos do Open Bidding
Respostas de lance enviadas por bidders de troca e rede que participam do Open Bidding Os lances são semelhantes aos dos Authorized Buyers que participam das campanhas padrão lances em tempo real. Os clientes do Open Bidding podem especificar um pequeno número campos adicionais, e alguns campos existentes podem ter usos alternativos. Esses incluem 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 esta lance e informados aos editores. |
BidResponse.seatbid[].bid[].ext.exchange_deal_type |
BidResponse.ad[].adslot[].exchange_deal_type |
O tipo de transação informado aos editores, afetando o modo como ela é tratados 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 de terceiros final se os de rede como um Open Bidding é um intermediário. Ele é obtido do comprador de terceiros e deve ser passado ao Google sem alterações no lance resposta. |
Recomendações
- Ative conexões HTTPS persistentes (também conhecidas como "reutilização de conexão") nos seus servidores. Defina o tempo limite em 10 segundos no mínimo; valores mais altos são benéficos em muitos casos. Verificação do Google durante os testes de latência iniciais do seu aplicativo, porque O Authorized Buyers envia solicitações com uma taxa alta e precisa evitar o 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 rastrear quando o a impressão é renderizada, e não quando o proponente vence. Por causa da desistência entre vitórias e renderizações, isso gera um rastreamento estatísticas.
- Mantenha seu código do bidder sem dependências em campos descontinuados, o que pode causar a falha dos lances com erros.
- Inclua
BidResponse.Ad.width
eBidResponse.Ad.height
no seuBidResponse
. UmBidResponse
a uma solicitação que inclui vários tamanhos de anúncio deve incluir os valoreswidth
eheight
, ou eles serão caíram do leilão. - A resposta precisa ter menos de 8 mil. Respostas muito grandes podem aumentar latência de rede e causar tempos limite.
- Siga as diretrizes para lances em inventário do iOS que exigem atribuição da SKAdNetwork.
Exemplo de resposta do lance
Os exemplos a seguir representam amostras legíveis do Protobuf e Solicitações JSON.
JSON do OpenRTB
Protobuf do OpenRTB
Importante:as mensagens do Protobuf mostradas na os exemplos estão representados aqui como texto legível por humanos. No entanto, não é assim que as mensagens são enviadas pela rede. Ao usar o Google ou o Protobuf 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 do lance especifica o criativo a ser veiculado se o seu lance vencer. Seu lance
precisa incluir um dos formatos de anúncio compatíveis (AMP, vídeo, nativo). Neste
especificamos o criativo usando o campo html_snippet
.
Como alternativa, é possível especificar o criativo usando um dos métodos campos a seguir, com base no formato do anúncio:
- Anúncio renderizado do 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 em seus próprios servidores usando um snippet HTML na
o campo html_snippet
do BidResponse
. A
snippet está em um iframe inserido na página da web, resultando na inserção
sendo recuperados e renderizados quando a página é carregada. Você precisa criar o HTML
snippet para que o anúncio (banner ou intersticial) seja renderizado corretamente dentro de um
iframe e um tamanho apropriado para o espaço de anúncio para o qual você está definindo lances.
Além disso, o tamanho do anúncio declarado na resposta do lance precisa corresponder exatamente a um das combinações de tamanho na solicitação de lance quando:
- Um anúncio é um banner regular (não é um vídeo, nativo ou intersticial).
- O bidder declarou o tamanho na resposta do lance. A declaração de tamanho é obrigatório sempre que mais de um tamanho estiver presente na solicitação.
- Há uma exceção para anúncios intersticiais. Para intersticiais, a largura precisa ter pelo menos 50% da largura da tela e a altura de pelo menos 40% do a altura da tela.
O campo html_snippet
aceita qualquer código HTML válido que
é renderizado corretamente, mas lembre-se das restrições de especificação do
buyer_creative_id
na seção Criar mensagem do BidResponse. Um
para isso é colocar informações extras em argumentos dos URLs que estão
buscados em seus servidores como parte da renderização do anúncio. Isso permite que você transmita
dados arbitrários sobre a impressão de volta para seus próprios servidores.
A maioria das políticas para snippets HTML retornados nas respostas de lance é a mesma das para anúncios de terceiros. Consulte Authorized Buyers Diretrizes do programa, Requisitos para terceiros veiculação de anúncios e Declarar URLs de clique nos anúncios para mais informações.
Especificar macros
O snippet HTML que define um criativo pode incluir uma ou mais
construções chamadas macros. No momento da veiculação do anúncio, os valores são substituídos por
. Por exemplo, seu aplicativo de lances cliente poderia usar a
WINNING_PRICE
para determinar quanto foi pago pelo anúncio,
se ele vencer o leilão. Para analisar essa macro, é preciso implementar uma
aplicativo que descriptografa confirmações de preço. Consulte a seção Preço para descriptografia
Confirmações para mais informações.
Especifique uma macro como parte de um snippet HTML no formato
%%MACRO%%
, em que MACRO
é um dos
listadas na tabela abaixo.
O Google exige que você use as APIs CLICK_URL_UNESC
ou
CLICK_URL_ESC
no criativo do terceiro veiculado
anúncio. 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 recuperado quando
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 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 do anúncio. No snippet, uma versão com escape do de terceiros deverá 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 registrará o clique no Google e depois redirecionará para o URL de clique de terceiros. |
CLICK_URL_ESC |
O URL de clique com escape do anúncio. Use esta opçã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 registrará o clique com Você pode anexar um URL com escape duplo após
|
CLICK_URL_ESC_ESC |
O URL com escape duplo para o anúncio. Use esta opçã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 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 do fuso horário. |
VERIFICATION |
Os diferentes valores para produção e quando o criativo é verificado na verificação
pipeline. O formato é %%?VERIFICATION:true-val:false-val%% , em que:
valores, exceto macros, podem ser usados para true-val e false-val ,
incluindo strings vazias. Para o Open Bidding, recomendamos que as trocas usem essa macro.
as plataformas de demanda não precisarão fazer mudanças.Por exemplo, se um criativo incluir %%?VERIFICATION:-1:5000%%
a substituição do texto seria 5000 na veiculação e -1 na
pipeline de verificação. Isso ajuda a diferenciar entre esses 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 micros de CPM ou 5.000 micros de CPI. O decodificado
o valor de WINNING_PRICE , neste caso, seria 5.000.
O preço vencedor é especificado em CPI.
|
WINNING_PRICE_ESC |
WINNING_PRICE com escape do 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 caracteres do conjunto !()*,-./:_~ permanecem inalterados.
- Todos os outros caracteres são substituídos por
%XX
, em queXX
é o hexadecimal número que representa o caractere.
Restrições do editor
Os editores usam a BidRequest
para restringir quais anúncios
que permitirão. É 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
não permitidos. Nunca retorne um anúncio com um recurso não permitido. Para permitidos
recursos como tipo de fornecedor, retornam um anúncio somente se o tipo de fornecedor estiver no
Lista allowed_vendor_type
no BidRequest
. Consulte a
comentários para esses campos no buffer de protocolo BidRequest
para mais detalhes.
Se um snippet HTML for retornado em BidResponse
, será
necessário para definir com precisão os attribute
, category
,
e click_through_url
no BidResponse
.
Se um anúncio tiver vários valores aplicáveis para esses campos, você deverá
inclua todos os valores. 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
Não são permitidos anúncios que contenham um pixel ou um web beacon com a finalidade de criar uma lista de IDs de cookies para remarketing subsequente.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 já interagiram com um site de propriedade 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 que o comprador definiu como um grupo de interesse comum.21 CreativeType: Html
Os anúncios não têm permissão para usarhtml_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 renderização.32 MraidType: MRAID
Os anúncios não são permitidos a exigir a API MRAID para serem processadas.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 têm permissão para fazer solicitações não SSL.
Portanto, se o campo excluded_attribute
tiver o valor
7, você não deve retornar um anúncio que usa um pixel ou um web beacon para
criar uma lista. Se um anúncio fizer isso, deverá definir o valor 7 no
o campo de atributo da 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, consequentemente,
declare o atributo 47 RichMediaCapabilityType: RichMediaCapabilitySSL).
Além disso, o campo excluded_sensitive_category
na
O BidRequest
usa códigos da
ad-sensitive-categories.txt
disponível na página de dados de referência. Aqui estão estendidos
descrições de alguns desses códigos:
3 Politics
Inclui política ou questões sociais polêmicas. não inclui anúncios de empresas 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 anúncios 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 serviços para download, como protetores de tela e planos de fundo para computadores, além de gráficos e modelos de layout de perfil para redes sociais.10 Get Rich Quick
Esquemas que prometem ganhos rápidos18 Weight Loss
Inclui perda de peso, dietas e 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 drogas.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, desde o esterno até a metade da coxa, não está coberta. ou o corpo está vestindo roupas íntimas, trajes de banho, lingerie ou outras roupas transparentes ou com itens que não são vestuário, como toalhas e lençóis.37 Sensationalism
Anúncios que visam induzir os usuários a clicar neles através da curiosidade, muitas vezes 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 têm como objetivo chocar o usuário.
Open Measurement
Com o Open Measurement, você pode especificar fornecedores terceirizados que oferecem medição independente e de verificação para anúncios veiculados em ambientes de apps para dispositivos móveis.Os formatos de anúncios compatíveis atualmente incluem anúncios intersticiais, em vídeo e de banner. Para mais informações sobre como usar o Open Measurement em uma resposta de lance com esses formatos, consulte a Central de Ajuda do SDK do Open Measurement artigo.
Exemplos de respostas de lance
As seções a seguir mostram exemplos de respostas de lance para diferentes tipos de anúncio.