Criar a resposta

Depois que o aplicativo processar a solicitação de lance do Google, ele precisará 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 de lances precisa responder a uma solicitação de lance com um BidResponse que contenha um Bid no formato configurado. Se você estiver usando o formato JSON, sua resposta precisará definir o cabeçalho Content-Type como application/json; charset=utf-8 e incluir o JSON BidResponse 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 para o formato Protobuf, gere e use bibliotecas do Protobuf com base em openrtb.proto e openrtb-adx.proto, que implementam os campos padrão do OpenRTB BidResponse 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 dar um lance em uma impressão, retorne uma resposta HTTP 204 vazia. Seu aplicativo precisa retornar uma resposta para cada BidRequest. Os tempos limite e as respostas que não podem ser analisadas são considerados erros, e o Google limita os bidders com altas taxas de erro.

ID do criativo

O BidResponse especifica um criativo pelo campo BidResponse.seatbid.bid.crid (limite de 128 bytes). Até mesmo criativos semelhantes precisam ter valores exclusivos para esse campo se forem diferentes 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, você precisa atribuir IDs de criativo diferentes a dois anúncios que:

  • Aparência ou comportamento diferente.
  • Renderizar em imagens diferentes.
  • Renderizar 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ça 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. Veja 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 Criativos para saber como receber feedback sobre as propriedades detectadas dos seus criativos.

Campos do Open Bidding

As respostas à solicitação de lance enviadas por bidders de troca e de rede que participam do Open Bidding são semelhantes às dos compradores do Authorized Buyers que participam de 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:

Campo Detalhes
BidResponse.imp.pmp.deals.id

O ID da transação do namespace da troca que está associado a esse lance e é informado aos editores.
BidResponse.seatbid.bid.ext.exchange_deal_type

O tipo de transação informado aos editores, que afeta como ela é tratada no leilão.
BidResponse.seatbid.bid.ext.third_party_buyer_token Token usado para identificar as informações do comprador terceirizado final se a troca como um Open Bidder for um intermediário. Ele é recebido do comprador terceirizado e precisa ser transmitido ao Google sem alterações na resposta à solicitação de 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 de latência inicial do aplicativo, porque o Authorized Buyers envia solicitações em alta taxa 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, em vez de quando o bidder vence. Devido à queda entre as vitórias e as renderizações, isso gera estatísticas de acompanhamento mais precisas.

  • Mantenha o código do bidder livre de 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. Caso contrário, ela será removida do leilão.
  • 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 em inventários do iOS que exigem atribuição da SKAdNetwork.

Exemplo de resposta à 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

Importante:as mensagens do 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 OpenRTB, somente as 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 criativo

Sua resposta à solicitação de lance especifica o criativo que será veiculado se o 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.

Como alternativa, você pode especificar seu 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 é incluído em 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. É necessário 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 do anúncio em que você está lances.

Além disso, o tamanho do anúncio declarado na resposta à solicitação de 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 é um vídeo, nativo ou intersticial).
  • O bidder declarou o tamanho na resposta à solicitação de lance. A declaração de tamanho é obrigatória sempre que mais de um tamanho estiver presente na solicitação.
  • Há uma exceção 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 ao especificar o campo crid na seção Criar mensagem 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 transmitir dados arbitrários sobre a impressão de volta aos seus próprios servidores.

A maioria das políticas para snippets HTML retornados em respostas à solicitação de lance é a mesma dos anúncios de terceiros. Consulte as Diretrizes do programa Authorized Buyers, os Requisitos para veiculação de anúncios terceirizada e Declarar URLs de clique em anúncios para mais informações.

Usar URLs de clique consistentes

O URL de clique que você especificar no campo BidResponse.seatbid.bid.ext.clickurl precisa ser idêntico ao URL da página de destino especificado no criativo. Confira a seguir exemplos de criativos em formatos compatíveis que são consistentes com o campo clickurl definido como https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1:

HTML

<div id="my-app-install-ad"
     style="font-family: sans-serif; border: 1px solid #ddd; padding: 10px;
            display: flex; align-items: center; width: 100%; height: 100%;
            box-sizing: border-box; cursor: pointer;"
     onclick="window.open('https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1', '_blank')">
  <img src="https://example.com/path/to/app_icon.png" alt="App Icon"
       style="width: 60px; height: 60px; margin-right: 10px;
              border-radius: 8px;">
  <div style="flex-grow: 1;">
    <h4 style="margin: 0 0 5px 0; font-size: 16px; color: #1a73e8;">
      My Awesome App
    </h4>
    <p style="margin: 0 0 10px 0; font-size: 14px; color: #5f6368;">
      The best app for doing awesome things! Download now and get started!
    </p>
    <span style="background-color: #1a73e8; color: white; padding: 8px 12px;
                 text-align: center; text-decoration: none;
                 display: inline-block; border-radius: 4px; font-size: 14px;
                 font-weight: bold;">Install</span>
  </div>
</div>

XML VAST

<VAST version="3.0">
  <Ad id="creative_id_789">
    <InLine>
      <AdSystem>MyBidderSystem</AdSystem>
      <AdTitle>My Awesome App Install Video</AdTitle>
      <Description>Install My Awesome App now!</Description>
      <Error>
        <![CDATA[https://tracking.example.com/vast_error?errorcode=[ERRORCODE]]]>
      </Error>
      <Impression>
        <![CDATA[https://tracking.example.com/vast_impression]]>
      </Impression>
      <Creatives>
        <!-- Main Video Creative -->
        <Creative>
          <Linear>
            <Duration>00:00:15</Duration>
            <TrackingEvents>
              <Tracking event="start">
                <![CDATA[https://tracking.example.com/vast_event?label=start]]>
              </Tracking>
              <Tracking event="firstQuartile">
                <![CDATA[https://tracking.example.com/vast_event?label=firstQuartile]]>
              </Tracking>
              <Tracking event="midpoint">
                <![CDATA[https://tracking.example.com/vast_event?label=midpoint]]>
              </Tracking>
              <Tracking event="thirdQuartile">
                <![CDATA[https://tracking.example.com/vast_event?label=thirdQuartile]]>
              </Tracking>
              <Tracking event="complete">
                <![CDATA[https://tracking.example.com/vast_event?label=complete]]>
              </Tracking>
            </TrackingEvents>
            <VideoClicks>
              <ClickThrough id="gplay-video">
                <![CDATA[https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1]]>
              </ClickThrough>
              <ClickTracking id="bidder-tracker-video">
                <![CDATA[https://tracking.example.com/vast_click]]>
              </ClickTracking>
            </VideoClicks>
            <MediaFiles>
              <MediaFile delivery="progressive" type="video/mp4" width="640"
                         height="360" bitrate="800" scalable="true"
                         maintainAspectRatio="true">
                <![CDATA[https://cdn.example.com/myawesomeapp_video.mp4]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
        <!-- Companion Ad Creative -->
        <Creative>
          <CompanionAds>
            <Companion id="companion1" width="300" height="250"
                       assetWidth="300" assetHeight="250">
              <StaticResource creativeType="image/png">
                <![CDATA[https://cdn.example.com/companion_banner_300x250.png]]>
              </StaticResource>
              <TrackingEvents>
                <Tracking event="creativeView">
                  <![CDATA[https://tracking.example.com/vast_companion_view]]>
                </Tracking>
              </TrackingEvents>
              <CompanionClickThrough>
                <![CDATA[https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1]]>
              </CompanionClickThrough>
              <CompanionClickTracking>
                <![CDATA[https://tracking.example.com/vast_companion_click]]>
              </CompanionClickTracking>
            </Companion>
          </CompanionAds>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

Nativo

{
  "ver": "1.2",
  "assets": [
    {
      "id": 1,
      "title": {
        "text": "My Awesome App"
      }
    },
    {
      "id": 2,
      "img": {
        "url": "https://example.com/path/to/app_icon.png",
        "w": 60,
        "h": 60
      }
    },
    {
      "id": 3,
      "data": {
        "value":
          "The best app for doing awesome things! Download now and get started!"
      }
    },
    {
      "id": 4,
      "data": {
        "value": "Install"
      }
    }
  ],
  "link": {
    "url": "https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1",
    "clicktrackers": [
      "https://tracking.example.com/native_click"
    ]
  },
  "imptrackers": [
    "https://tracking.example.com/native_impression"
  ]
}

Especificar macros

As macros são textos formatados incorporados a alguns campos de resposta à solicitação de lance que contêm URLs que são 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 do snippet de HTML incluído no lance, a macro será substituída por um valor que você poderá 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 os formatos de snippet HTML, nativo, URL de vídeo e XML VAST de vídeo.

  • BidResponse.seatbid.bid.adm_native.eventtrackers.url

  • BidResponse.seatbid.bid.adm_native.imptrackers

  • BidResponse.seatbid.bid.ext.amp_ad_url

    Somente as macros WINNING_PRICE e WINNING_PRICE_ESC específicas do Google são compatíveis com criativos AMP.

  • BidResponse.seatbid.bid.burl

  • BidResponse.seatbid.bid.ext.impression_tracking_url

    Use essa métrica 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} ao URL usado para buscar o criativo, em que MACRO é uma das macros compatíveis descritas na especificação do OpenRTB.

Macros do Google

O Google aceita outras macros além daquelas encontradas na especificação do OpenRTB. Elas são formatadas de maneira diferente e aparecem como %%MACRO%% se incorporadas a um URL. A tabela a seguir descreve essas macros:

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 Descriptografar identificadores de publicidade para mais detalhes.
CACHEBUSTER Uma representação de string de um número inteiro aleatório, não assinado e de quatro bytes.
CLICK_URL_UNESC

O URL de clique sem escape do 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 http://my.adserver.com/some/path/handleclick?click=clk, o código a seguir poderá ser usado com a versão de escape único do URL de clique de terceiros após a invocação da macro:

<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, isso é expandido para:

<a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

O URL primeiro vai registrar o clique no Google e, em seguida, redirecionar para o URL de clique de terceiros.
CLICK_URL_ESC

O URL de clique com 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: 

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a>

No momento da veiculação do anúncio, isso é 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 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 após %%CLICK_URL_ESC%%. Depois que o my.adserver.com remove o escape, uma versão com escape único do URL é anexada ao google_click_url. Quando o google_click_url for buscado, ele vai remover o escape mais uma vez e redirecionar.
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: 

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a>

No momento da veiculação do anúncio, isso é 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 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 uma 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 de 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, você precisa implementar um aplicativo que descriptografe 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 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 (+).
  • 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 para publishers e requisitos

A solicitação de lance inclui informações sobre os tipos de restrições e requisitos que os publishers impõem aos 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, isso sempre será definido como true, porque o Google exige compatibilidade com 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 em BidRequest. Somente os formatos de anúncio especificados na solicitação de lance ao preencher campos como BidRequest.imp.banner devem ser incluídos no seu lance. 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 à solicitação de lance que contenha esses formatos, consulte o artigo da Central de Ajuda sobre o SDK de medição do Open Measurement.

Exemplos de respostas a solicitações de lance

As seções a seguir mostram exemplos de respostas a solicitações de lances para diferentes tipos de anúncio.

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

Nativo do app

Protobuf do OpenRTB

JSON do OpenRTB

Vídeo na Web

Protobuf do OpenRTB

JSON do OpenRTB

Banner da Web para dispositivos móveis para lances de troca

Protobuf do OpenRTB

JSON do OpenRTB