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

Todos os apps que veiculam anúncios personalizados hospedados pelo Google precisam implementar o ícone e a sobreposição Opções de anúncios, 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 um anúncio específico está sendo exibido e fornece informações sobre como a privacidade deles está sendo protegida.

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

Este guia explica como extrair as informações necessárias para implemente as Opções de anúncios com base na resposta XML do VAST do seu anúncio ou no fluxo da DAI a uma resposta rápida de metadados.

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

Para obedecer aos requisitos do Google para renderizar ícones das 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 pelo símbolo localização" e "local Y" incluídas nos dados do ícone e no tamanho definido pelas propriedades de largura e altura, no caso de densidade independente Pixels (DP).
  3. O ícone das 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, toque ou seleção remota), o ícone "Opções de anúncios" precisa ser clicável.
  5. Em plataformas com suporte a navegador, clicar no ícone da AdChoices precisa abrir uma guia ou janela do navegador com o URL especificado na propriedade "ClickThrough" ou "click_data".
  6. Em plataformas sem suporte a navegadores, clicar no ícone "Opções de anúncios" precisa abrir uma sobreposição modal, que exibe uma das imagens especificadas no "IconClickFallbackImage" ou "click_fallback_images" .
  7. Em plataformas sem suporte ao navegador, a imagem substituta precisa ser exibida no tamanho especificado na propriedade "IconClickFallbackImage" ou "click_fallback_images", em pixels de densidade independente (DPI).

Analisar as Opções de anúncios com base em uma resposta XML do VAST

Ao trabalhar com uma resposta de anúncio XML, as Opções de anúncios são compatíveis somente com anúncios VAST a versão 3.0 ou mais recente. O AdChoices é implementado 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 enviadas como um ícone VAST. Se o app ou site for totalmente compatível com os ícones VAST 4.2 (seção 3.11 do padrão VAST 4.2), o suporte ao AdChoices não vai exigir mais trabalho.

Se o app não oferecer suporte aos ícones VAST 4.2, será necessário analisar manualmente os ícones com o nome do programa "GoogleWhyThisAd" da resposta VAST, com base nesse padrão. Use este exemplo de xml VAST 4.2. para outros testes no app.

Exemplo de resposta do 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 de anúncio em XML seguir o padrão VAST 3.0, as Opções de anúncios serão encaminhadas 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 a plataforma puder navegar até o URL de clique do ícone e exibi-lo, o suporte do AdChoices não vai exigir mais trabalho.

Se a plataforma não conseguir navegar até e mostrar URLs de clique, o que se aplica principalmente a dispositivos que não têm um navegador da Web integrado, será necessário implementar 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 ao AdChoices, a tag IconFallbackImages com o nome do programa "GoogleWhyThisAd" deve estar associado ao ícone com o nome do programa "GoogleWhyThisAd", de modo que, quando o usuário interagir com o ícone, imagem substituta associada é exibida.

Para oferecer suporte a possíveis mudanças futuras no padrão AdChoices, recomendamos incorporar o suporte de imagem de substituição para todos os ícones VAST, quando disponível. É possível usar esta amostra de VAST 3.0 xml para outros testes no app.

Estrutura de extensão IconFallbackImages

Tag Atributos Descrição
Extensão tipo Para esta extensão, o tipo sempre contém o valor IconClickFallbackImages:
-IconClickFallbackImages programa Esse atributo sempre corresponde ao atributo de 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 preferencial para exibir a imagem.
altura A altura preferencial para exibir 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 JSON das Opções de anúncios com base nos metadados da API DAI

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

O objeto JSON de metadados contém uma lista de anúncios, com chave pelo adID. Em cada de anúncio é uma matriz de ícones. Se o anúncio em questão utilizar Opções de anúncios, o O ícone "Opções de anúncios" está 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 rígido, alguns atributos mudaram de nome, quando necessário.

Formato JSON do ícone

programa Para o ícone de 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" (direita) ou "left" (esquerda).
y_position A posição vertical do canto superior esquerdo do ícone, em relação ao no canto superior esquerdo do criativo de vídeo em pixels. Esse campo também aceita a valores de posição responsivos "top" ou "inferior".
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 das Opções de anúncios.
alt_text O texto alternativo a ser renderizado no ícone "Opções de anúncios".
click_data Um objeto que contém a propriedade click_data.url, que representa o URL para onde os espectadores serão direcionados se clicarem no ícone "Opções de anúncios" em uma com suporte para navegação na Web.
click_fallback_images Uma matriz de objetos de imagem para mostrar aos espectadores que clicam no ícone da AdChoices em plataformas que não oferecem suporte à navegação na Web.

Formato JSON da imagem substituta

largura A largura da imagem de substituição, 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 metadados do 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"
        }
        ...
      ]
      ...
    },
    ...
  }
  ...
}