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

Todos os apps que exibem anúncios personalizados hospedados pelo Google precisam implementar o ícone e a sobreposição das AdChoices, quando fornecidos pelo Google. "Opções de anúncios" (ou "Por que esse anúncio?") é um recurso de transparência que explica aos usuários por que um anúncio específico está sendo exibido e oferece informações sobre como a privacidade deles é protegida.

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

Neste guia, explicamos como extrair as informações necessárias para implementar adequadamente as Opções de anúncios usando a resposta XML VAST do anúncio ou a resposta de metadados do stream DAI.

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

Para obedecer aos requisitos do Google para renderizar í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 exibido 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 "Local X" e "Local Y" incluídas nos dados do ícone e no tamanho definido pelas propriedades de largura e altura em pixels de densidade independente (DP, na sigla em inglês).
  3. O ícone "Opções de anúncios" não pode ser obscurecido por outras sobreposições de anúncios ou elementos da interface.
  4. Em plataformas compatíveis com cliques ou equivalentes (por exemplo, seleção remota ou por toque), é necessário que o ícone "Opções de anúncios" seja clicável.
  5. Em plataformas compatíveis com navegadores, clicar no ícone "Opções de anúncios" precisa abrir uma guia ou janela do navegador com o URL especificado na propriedade "ClickThrough" ou "click_data".
  6. Em plataformas sem suporte ao navegador, clicar no ícone "Opções de anúncios" precisa abrir uma sobreposição modal e exibir uma das imagens especificadas na propriedade "IconClickReplaceImage" ou "click_fallback_images".
  7. Em plataformas que não oferecem suporte ao navegador, a imagem substituta precisa ser exibida no tamanho especificado na propriedade "IconClick fallbackImage" ou "click_fallback_images", em pixels de densidade independente (DP, na sigla em inglês).

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

Ao trabalhar com uma resposta de anúncio XML, as Opções de anúncios são compatíveis somente com o VAST versão 3.0 e posterior. "Opções de anúncios" é implementada como um ícone VAST.

VAST 4.2;

Se a resposta do anúncio XML seguir o padrão VAST 4.2, as Opções de anúncios serão exibidas como um ícone VAST. Caso seu app ou site seja totalmente compatível com os ícones VAST 4.2 (seção 3.11 do padrão VAST 4.2), não vai ser necessário fazer mais nada.

Caso seu app não ofereça suporte a ícones VAST 4.2, analise manualmente os ícones com o nome do programa "GoogleWhyThisAd" na resposta do VAST, com base nesse padrão. Use essa amostra de xml VAST 4.2 para fazer outros 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

Caso sua resposta de anúncio XML siga o padrão VAST 3.0, as Opções de anúncios serão exibidas como uma combinação de um ícone VAST e uma extensão VAST personalizada. Caso seu app ou site seja totalmente compatível com o padrão de ícone VAST 3.0 e a plataforma possa navegar até o URL de clique do ícone e mostrar o URL de clique, a compatibilidade com as Opções de anúncios não vai ser mais necessária.

Se a plataforma não conseguir navegar e exibir URLs de clique, o que se aplica principalmente a dispositivos que não têm um navegador da Web integrado, é necessário implementar a compatibilidade com a extensão "IconReplaceImages". Essa extensão contém um conjunto de tags "IconOverrideImages" 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 IconSubImages com o nome de programa "GoogleWhyThisAd" precisa ser associada ao ícone com o nome de programa "GoogleWhyThisAd". Assim, quando o usuário interage com o ícone, a imagem substituta associada é exibida.

Para possíveis mudanças futuras no padrão das Opções de anúncios, é altamente recomendável incorporar compatibilidade com imagens substitutas para todos os ícones VAST, quando disponíveis. Use esse exemplo de xml VAST 3.0 para fazer outros testes no seu app.

Estrutura da extensão IconReplaceImages

Tag Atributos Descrição
Extensão digitar Para essa extensão, o tipo sempre contém o valor IconClickFallbackImages.
-IconClickReplaceImages 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 IconClickDelegateImages, exceto pela adição do atributo program.
--IconClickReplaceImage largura A largura preferencial para exibir a imagem.
altura A altura preferida para exibir a imagem.
---AltText Uma descrição acessível da imagem.
---StaticResource creativeType O tipo MIME da imagem substituta.
Um valor limite 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 Opções de anúncios do JSON de metadados da API DAI

Ao trabalhar com a API DAI, os detalhes das Opções de anúncios são transmitidos pelo objeto JSON retornado pelas solicitações para o URL de metadados.

O objeto JSON de metadados contém uma lista de anúncios codificados pelo adID. Dentro de cada objeto de anúncio há uma matriz de ícones. Se o anúncio em questão utilizar Opções de anúncios, o ícone correspondente estará contido na matriz.

Formato do ícone JSON

O formato do ícone JSON é uma tradução 1:1 do padrão de ícones do VAST 4.2 (seção 3.11), sempre que possível. No entanto, para oferecer suporte ao formato JSON mais rigoroso, 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 pixels, em relação ao canto superior esquerdo do criativo de vídeo. Esse campo também aceita os valores de posição responsivos "right" ou "left".
y_position É a posição vertical do canto superior esquerdo do ícone em pixels, em relação ao canto superior esquerdo do criativo de vídeo. Esse campo também aceita os valores de posição responsivo "top" ou "bottom".
largura A largura do ícone, em pixels.
altura A altura do ícone, em pixels.
creative_type Tipo MIME da imagem fornecida para o ícone. O padrão é "image/png".
resource 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 com 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 compatível com a navegação na Web.
click_fallback_images Uma matriz de objetos de imagem que vão aparecer para os espectadores que clicarem no ícone "Opções de anúncios" em plataformas incompatíveis com a 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".
resource O URL para recuperar a imagem substituta.
alt_text O texto alternativo a ser renderizado para a imagem substituta.

Exemplo de metadados JSON

{
  ...
  "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"
        }
        ...
      ]
      ...
    },
    ...
  }
  ...
}