Ícone e sobreposição das Opções de anúncios

Todos os apps que mostram anúncios personalizados hospedados pelo Google precisam implementar o ícone e a sobreposição AdChoices, quando fornecidos pelo Google. As Opções de anúncios (também chamadas de "Por que esse anúncio?") são um recurso de transparência que explica aos usuários por que determinado anúncio está sendo exibido, além de fornecer informações sobre como a privacidade deles está sendo protegida.

Para mais informações, consulte Por que você está vendo um anúncio.

Este guia explica como extrair as informações necessárias para implementar corretamente o AdChoices na resposta XML VAST do seu anúncio ou na resposta de metadados do fluxo de DAI.

Requisitos para renderização das Opções de anúncios

Para obedecer aos requisitos do Google para renderização de ícones de Opções de anúncios, seu app ou site precisa atender aos seguintes padrões:

  1. O ícone Opções de anúncios precisa ser mostrado sobreposto a qualquer anúncio para o qual ele é fornecido.
  2. O ícone "Opções de anúncios" precisa ser exibido na posição indicada pelas propriedades "Localização X" e "Localização Y" incluídas nos dados do ícone e no tamanho definido pelas propriedades de largura e altura, em pixels independentes de densidade (DP).
  3. O ícone das Opções de anúncios não pode ser ocultado por outras sobreposições de anúncios ou elementos de interface.
  4. Em plataformas com suporte a cliques ou equivalente (por exemplo, toque ou seleção remota), o ícone "Opções de anúncios" precisa ser clicável.
  5. Em plataformas com suporte a navegadores, clicar no ícone "Opções de anúncios" precisa abrir uma guia do navegador ou janela com o URL especificado na propriedade "ClickThrough" ou "click_data".
  6. Em plataformas sem suporte do navegador, clicar no ícone "Opções de anúncios" precisa abrir uma sobreposição modal, mostrando uma das imagens especificadas na propriedade "IconClickFallbackImage" ou "click_fallback_images".
  7. Em plataformas sem suporte do navegador, a imagem substituta precisa ser mostrada no tamanho especificado na propriedade "IconClickFallbackImage" ou "click_fallback_images", em pixels independentes de densidade (DP).

Analisar as Opções de anúncios de uma resposta XML VAST

Ao trabalhar com uma resposta de anúncio em XML, o AdChoices é compatível apenas com a versão 3.0 do VAST e mais recentes. As Opções de anúncios são implementadas como um ícone VAST.

VAST 4.2

Se a resposta do anúncio em XML seguir o padrão VAST 4.2, as Opções de anúncios serão veiculadas como um ícone VAST. Se o app ou site for totalmente compatível com os ícones do VAST 4.2 (seção 3.11 do padrão VAST 4.2), não será necessário fazer mais nada para usar o suporte às Opções de anúncios.

Se o app não for compatível com ícones VAST 4.2, analise manualmente os ícones com o nome do programa "GoogleWhyThisAd" da resposta VAST, com base nesse padrão. Você pode usar este exemplo de XML VAST 4.2 para fazer mais testes no seu app.

Exemplo de resposta VAST 4.2

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="4.2">
  <Ad id="20011">
    <Wrapper>
      ...
      <Creatives>
        ...
        <Creative id="5480" sequence="1">
          ...
          <Linear>
            ...
            <Icons>
              ...
              <Icon program="GoogleWhyThisAd" width="40" height="30" xPosition="left" yPosition="100" duration="00:00:10" offset="00:00:00" apiFramework="VAST" altText="AdChoices icon">
                <StaticResource creativeType="image/png">
                  <![CDATA[ https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices.png ]]>
                </StaticResource>
                <IconClicks>
                  <IconClickThrough>
                    <![CDATA[ https://g.co/adsettings ]]>
                  </IconClickThrough>
                  <IconClickFallbackImages>
                    <IconClickFallbackImage width="950" height="600">
                      <AltText>
                        <![CDATA[ This ad was shown to you based on: * Google's estimation of your interests, based on your activity on Google on this device (for example, your searches) * the information on the website you were viewing. ]]>
                      </AltText>
                      <StaticResource creativeType="image/png">
                        <![CDATA[ https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices_fallback_image.png ]]>
                      </StaticResource>
                    </IconClickFallbackImage>
                    ...
                  </IconClickFallbackImages>
                </IconClicks>
              </Icon>
              ...
            </Icons>
            ...
          </Linear>
          ...
        </Creative>
        ...
      </Creatives>
      ...
    </Wrapper>
    ...
  </Ad>
</VAST>

VAST 3.0

Se a resposta do anúncio em XML seguir o padrão VAST 3.0, as Opções de anúncios serão veiculadas como uma combinação de um ícone VAST e uma extensão VAST personalizada. Se o app ou site for totalmente compatível com o padrão de ícone VAST 3.0 e se a plataforma conseguir navegar até o URL de click-through do ícone e mostrá-lo, não será necessário fazer mais nada para ter suporte às Opções de anúncios.

Se a plataforma não conseguir navegar até os URLs de clique e mostrá-los (isso se aplica principalmente a dispositivos sem um navegador da Web integrado), implemente o suporte à extensão "IconFallbackImages". Essa extensão contém um conjunto de tags "IconFallbackImages" em que o atributo "program" corresponde a um ícone incluído no VAST.

Para oferecer suporte total às Opções de anúncios, a tag IconFallbackImages com o nome do programa "GoogleWhyThisAd" precisa estar associada ao ícone com o nome do programa "GoogleWhyThisAd". Assim, quando o usuário interage com o ícone, a imagem substituta associada é exibida.

Para oferecer suporte a possíveis mudanças futuras no padrão "Opções de anúncios", recomendamos incorporar suporte a imagens substitutas para todos os ícones VAST, quando disponíveis. Você pode usar este exemplo de XML VAST 3.0 para fazer mais testes no seu app.

Estrutura da extensão IconFallbackImages

Tag Atributos Descrição
Extensão tipo Para essa extensão, o tipo sempre contém o valor IconClickFallbackImages.
-IconClickFallbackImages programa Esse atributo sempre corresponde ao atributo do programa de um ícone VAST 3.0 associado.
A estrutura desse nó corresponde ao padrão VAST 4.2 para IconClickFallbackImages, exceto pela adição do atributo program.
--IconClickFallbackImage largura A largura preferida para mostrar a imagem.
altura A altura preferida para mostrar a imagem.
---AltText Uma descrição acessível da imagem.
---StaticResource creativeType O tipo MIME da imagem substituta.
Um valor CDATA que contém o URL da imagem substituta.

Exemplo de resposta VAST 3.0

<?xml version="1.0" encoding="UTF-8"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
 <Ad id="123456">
  <InLine>
   ...
   <Creatives>
    ...
    <Creative id="7891011" AdID="ABCD123456EF" sequence="1">
     ...
     <Linear>
      ...
      <Icons>
       ...
       <Icon program="GoogleWhyThisAd" width="50" height="50" xPosition="20" yPosition="bottom" duration="00:00:10" offset="00:00:00" apiFramework="VAST" altText="Why This Ad?">
        <StaticResource creativeType="image/png">
         <![CDATA[https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices.png]]>
        </StaticResource>
        <IconClicks>
         ...
         <IconClickThrough><![CDATA[https://g.co/adsettings]]></IconClickThrough>
        </IconClicks>
       </Icon>
       ...
      </Icons>
     ...
     </Linear>
     ...
    </Creative>
    ...
   </Creatives>
   <Extensions>
    ...
    <Extension type="IconClickFallbackImages">
     ...
     <IconClickFallbackImages program="GoogleWhyThisAd">
      <IconClickFallbackImage width="400" height="150">
       <AltText>Alt icon fallback</AltText>
       <StaticResource creativeType="image/png"><![CDATA[https://storage.googleapis.com/gvabox/nickchavez/media/png/wta_dialog.png]]></StaticResource>
      </IconClickFallbackImage>
      ...
     </IconClickFallbackImages>
     ...
    </Extension>
    ...
   </Extensions>
   ...
  </InLine>
  ...
 </Ad>
</VAST>

Analisar as opções de anúncios do JSON de metadados da API DAI

Ao trabalhar com a API DAI, os detalhes do AdChoices são transmitidos pelo objeto JSON retornado por solicitações ao URL de metadados.

O objeto JSON de metadados contém uma lista de anúncios, com chave pelo adID. Dentro de cada objeto de anúncio, há uma matriz de ícones. Se o anúncio em questão usar o ícone "Opções de anúncios", ele estará contido nessa matriz.

Formato de ícone JSON

O formato de ícone JSON é uma tradução 1:1 do padrão de ícone VAST 4.2 (seção 3.11), sempre que possível. No entanto, para oferecer suporte ao formato JSON mais estrito, alguns atributos mudaram de nome, quando necessário.

Formato JSON do ícone

programa Para o ícone Opções de anúncios, esse valor sempre contém a string "GoogleWhyThisAd".
x_position A posição horizontal do canto superior esquerdo do ícone, em relação ao canto superior esquerdo do criativo de vídeo, em pixels. Esse campo também aceita os valores de posição responsiva "right" ou "left".
y_position A posição vertical do canto superior esquerdo do ícone, em relação ao canto superior esquerdo do criativo de vídeo, em pixels. Esse campo também aceita os valores de posição responsiva "top" ou "bottom".
largura A largura do ícone, em pixels.
altura A altura do ícone, em pixels.
creative_type O tipo MIME da imagem fornecida para o ícone. O padrão é "image/png".
recurso O URL para recuperar o ícone "Opções de anúncios".
alt_text O texto alternativo a ser renderizado para o ícone "Opções de anúncios".
click_data Um objeto que contém a propriedade click_data.url, que representa o URL para direcionar os espectadores se eles clicarem no ícone "Opções de anúncios" em uma plataforma que oferece suporte à navegação na Web.
click_fallback_images Uma matriz de objetos de imagem para mostrar aos espectadores que clicam no ícone "Opções de anúncio" em plataformas que não são compatíveis com navegação na Web.

Formato JSON da imagem substituta

largura A largura da imagem substituta, em pixels.
altura A altura da imagem substituta, em pixels.
creative_type O tipo MIME da imagem substituta. O padrão é "image/png".
recurso O URL para recuperar a imagem substituta.
alt_text O texto alternativo a ser renderizado para a imagem substituta.

Exemplo de JSON de metadados

{
  ...
  "ads": {
    ...
    "0002640412_ad1": {
      ...
      "icons": [
        ...
        {
          "alt_text": "AdChoices icon",
          "click_data": {
            "url": "https://g.co/adsettings"
          },
          "click_fallback_images": [
            {
              "alt_text": "This ad was shown to you based on: * Google's estimation of your interests, based on your activity on Google on this device (for example, your searches) * the information on the website you were viewing.",
              "creative_type": "image/jpg",
              "height": 600,
              "resource": "https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices_fallback_image.png",
              "width": 950
            }
          ],
          "creative_type": "image/png",
          "height": 30,
          "program": "AdChoices",
          "resource": "https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices.png",
          "type": "static",
          "width": 40,
          "x_position": "0",
          "y_position": "100"
        }
        ...
      ]
      ...
    },
    ...
  }
  ...
}