Í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 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 deu às
  2. O ícone da AdChoices precisa ser mostrado 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 (DPI, na sigla em inglês).
  3. O ícone "Opções de anúncios" não pode ser ocultado por outras sobreposições de anúncios ou interface os elementos.
  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 compatíveis com navegadores, clicar no ícone "Opções de anúncios" precisa abrir uma guia ou janela do navegador com o URL especificado no campo 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 deve ser exibida em o tamanho especificado dentro do "IconClickFallbackImage" ou "click_fallback_images" em pixels independentes de densidade (DP).

Analisar as opções de anúncio 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 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 a ícones VAST 4.2, será necessário analisar manualmente os ícones. com o nome "GoogleWhyThisAd" da sua resposta VAST, com base 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 do anúncio XML seguir o VAST 3.0 padrão, as Opções de anúncios são exibidos como uma combinação de um ícone VAST e uma extensão VAST personalizada. Se as aplicativo ou site é totalmente compatível com o padrão de ícone VAST 3.0 e, se a plataforma for navegar e exibir o URL de clique do ícone, o suporte às Opções de anúncios não exige mais nenhum 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 alterações futuras no padrão das Opções de anúncios, é altamente recomendamos incorporar o suporte à imagem substituta para todos os ícones VAST, quando disponíveis. Use este exemplo de VAST 3.0 xml 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 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 com 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, codificados pelo adID. Em cada de anúncio é uma matriz de ícones. Se o anúncio em questão usa o AdChoices, o ícone "Opções de anúncios" está contido nessa matriz.

Formato de ícone JSON

O formato do ícone JSON é uma conversão 1:1 do ícone VAST 4.2 padrão (seção 3.11), sempre que possível. No entanto, para aceitar o JSON mais rigoroso, formato, alguns atributos tiveram nomes alterados, 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" (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 "Opções de anúncios".
alt_text O texto alternativo a ser renderizado para o ícone de 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 a serem exibidos para os usuários que clicam nas Opções de anúncios em plataformas que não são compatíveis com a navegação na Web.

Formato JSON da imagem de substituição

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