Esta página foi traduzida pela API Cloud Translation.

Í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 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 um 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 as Opções de anúncios na resposta XML VAST do anúncio ou na resposta de metadados do fluxo DAI.

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:

O ícone "Opções de anúncios" precisa ser mostrado sobreposto a qualquer anúncio para o qual ele é fornecido.
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).
O ícone das Opções de anúncios não pode ser obscurecido por outras sobreposições de anúncios ou elementos da interface.
Em plataformas com suporte a cliques ou equivalente (por exemplo, toque ou seleção remota), o ícone da AdChoices precisa ser clicável.
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".
Em plataformas sem suporte ao navegador, clicar no ícone das Opções de anúncios precisa abrir uma sobreposição modal, mostrando uma das imagens especificadas na propriedade "IconClickFallbackImage" ou "click_fallback_images".
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úncio de uma resposta XML VAST

Ao trabalhar com uma resposta de anúncio XML, o AdChoices é compatível apenas com a versão VAST 3.0 e mais recentes. A AdChoices é implementada 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 VAST 4.2 xml 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 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" precisa ser 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 AdChoices, recomendamos incorporar o suporte de imagem de substituição para todos os ícones VAST, quando disponível. Use este exemplo de VAST 3.0 xml para fazer mais testes no seu app.

Estrutura de 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.
-IconClickFallbackImages		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.
--IconClickFallbackImage	altura	A altura preferencial para exibir a imagem.
---AltText		Uma descrição acessível da imagem.
---StaticResource	creativeType	O tipo MIME da imagem substituta.
---StaticResource		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 AdChoices 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 para o URL de metadados.

O objeto JSON de metadados contém uma lista de anúncios, com chave pelo adID. Em cada objeto de anúncio, há 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 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 "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 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 das 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 direcionar os espectadores se eles clicarem no ícone de 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 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 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"
        }
        ...
      ]
      ...
    },
    ...
  }
  ...
}