Icona e overlay Scegli Tu!

Tutte le app che mostrano annunci personalizzati ospitati da Google devono implementare l'icona e l'overlay AdChoices, se forniti da Google. Scegli Tu! (anche chiamata "Perché questo annuncio?") è una funzionalità di trasparenza che spiega agli utenti perché viene mostrato loro un particolare annuncio e fornisce informazioni relative alla protezione della privacy.

Per saperne di più, consulta l'articolo Perché vedi un annuncio.

Questa guida spiega come estrarre le informazioni necessarie per implementare correttamente Scegli Tu! dalla risposta XML VAST dell'annuncio o dalla risposta dei metadati del flusso DAI.

Requisiti per il rendering di Scegli Tu!

Per rispettare i requisiti di Google per il rendering delle icone Scegli Tu!, la tua app o il tuo sito web deve soddisfare i seguenti standard:

  1. L'icona Scegli Tu! deve essere visualizzata in overlay su qualsiasi annuncio per cui è fornita.
  2. L'icona Scegli Tu! deve essere visualizzata nella posizione indicata dalle proprietà "Posizione X" e "Posizione Y" incluse nei dati dell'icona e nelle dimensioni definite dalle proprietà di larghezza e altezza, in pixel indipendenti dalla densità (DP).
  3. L'icona Scegli Tu! non deve essere oscurata da altri overlay degli annunci o elementi dell'interfaccia.
  4. Sulle piattaforme con supporto dei clic o equivalente (ad es. selezione tramite tocco o telecomando), l'icona Scegli Tu! deve essere cliccabile.
  5. Sulle piattaforme con supporto del browser, facendo clic sull'icona Scegli Tu! deve aprire una scheda del browser o una finestra con l'URL specificato nella proprietà "ClickThrough" o "click_data".
  6. Sulle piattaforme senza supporto del browser, l'azione di clic sull'icona Scegli Tu! deve aprire un overlay modale che mostra una delle immagini specificate nella proprietà "IconClickFallbackImage" o "click_fallback_images".
  7. Sulle piattaforme senza supporto del browser, l'immagine di riserva deve essere visualizzata con le dimensioni specificate nella proprietà "IconClickFallbackImage" o "click_fallback_images", in pixel indipendenti dalla densità (dp).

Analizzare Scegli Tu! da una risposta VAST XML

Quando lavori con una risposta all'annuncio XML, Scegli Tu! è supportato solo in VAST versione 3.0 e successive. Scegli Tu! viene implementato come icona VAST.

VAST 4.2

Se la risposta all'annuncio XML segue lo standard VAST 4.2, Scegli Tu! viene pubblicato come icona VAST. Se la tua app o il tuo sito web supporta completamente le icone VAST 4.2 (sezione 3.11 dello standard VAST 4.2), il supporto di Scegli Tu! non richiede ulteriori interventi.

Se la tua app non supporta le icone VAST 4.2, devi analizzare manualmente le icone con il nome del programma "GoogleWhyThisAd" dalla risposta VAST, in base a questo standard. Puoi utilizzare questo esempio di XML VAST 4.2 per ulteriori test nella tua app.

Esempio di risposta 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 la risposta all'annuncio XML segue lo standard VAST 3.0, Scegli Tu! viene fornito come combinazione di un'icona VAST e un'estensione VAST personalizzata. Se la tua app o il tuo sito web supportano completamente lo standard VAST 3.0 Icon e se la piattaforma è in grado di navigare e visualizzare l'URL di clickthrough dell'icona, il supporto di Scegli Tu! non richiede ulteriori interventi.

Se la tua piattaforma non è in grado di accedere e visualizzare gli URL clickthrough, ciò si applica principalmente ai dispositivi che non dispongono di un browser web integrato. Devi implementare il supporto dell'estensione "IconFallbackImages". Questa estensione contiene un insieme di tag "IconFallbackImages" in cui l'attributo "program" corrisponde a un'icona inclusa in VAST.

Per supportare completamente Scegli Tu!, il tag IconFallbackImages con il nome del programma "GoogleWhyThisAd" deve essere associato all'icona con il nome del programma "GoogleWhyThisAd", in modo che quando l'utente interagisce con l'icona, venga visualizzata l'immagine di riserva associata.

Per supportare potenziali modifiche future allo standard Scegli Tu!, ti consigliamo vivamente di incorporare il supporto delle immagini di riserva per tutte le icone VAST, se disponibili. Puoi utilizzare questo XML VAST 3.0 di esempio per ulteriori test nella tua app.

Struttura dell'estensione IconFallbackImages

Tag Attributi Descrizione
Estensione tipo Per questa estensione, il tipo contiene sempre il valore IconClickFallbackImages.
-IconClickFallbackImages programma Questo attributo corrisponde sempre all'attributo programma di un'icona VAST 3.0 associata.
La struttura di questo nodo corrisponde allo standard VAST 4.2 per IconClickFallbackImages, ad eccezione dell'aggiunta dell'attributo program.
--IconClickFallbackImage larghezza La larghezza preferita per visualizzare l'immagine.
altezza L'altezza preferita per visualizzare l'immagine.
---AltText Una descrizione accessibile dell'immagine.
---StaticResource creativeType Il tipo MIME dell'immagine di riserva.
Un valore CDATA contenente l'URL dell'immagine di riserva.

Esempio di risposta 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>

Analizzare AdChoices dal JSON dei metadati dell'API DAI

Quando utilizzi l'API DAI, i dettagli di Scelte pubblicitarie vengono trasmessi tramite l'oggetto JSON restituito dalle richieste all'URL dei metadati.

L'oggetto JSON dei metadati contiene un elenco di annunci, indicizzati in base all'ID annuncio. All'interno di ogni oggetto annuncio è presente un array di icone. Se l'annuncio in questione utilizza Scegli Tu!, l'icona Scegli Tu! è contenuta in questo array.

Formato icona JSON

Il formato delle icone JSON è una traduzione 1:1 dallo standard delle icone VAST 4.2 (sezione 3.11), ove possibile. Tuttavia, per supportare il formato JSON più rigoroso, alcuni attributi hanno cambiato nome, se necessario.

Formato JSON dell'icona

programma Per l'icona Scegli Tu!, questo valore contiene sempre la stringa "GoogleWhyThisAd".
x_position La posizione orizzontale dell'angolo in alto a sinistra dell'icona, rispetto all'angolo in alto a sinistra della creatività video, in pixel. Questo campo accetta anche i valori di posizione adattabili "right" o "left".
y_position La posizione verticale dell'angolo in alto a sinistra dell'icona, rispetto all'angolo in alto a sinistra della creatività video, in pixel. Questo campo accetta anche i valori di posizione adattabile "in alto" o "in basso".
larghezza La larghezza dell'icona, in pixel.
altezza L'altezza dell'icona, in pixel.
creative_type Il tipo MIME dell'immagine fornita per l'icona. Il valore predefinito è "image/png".
risorsa L'URL per recuperare l'icona Scegli Tu!.
alt_text Il testo alternativo da eseguire il rendering per l'icona Scegli Tu!.
click_data Un oggetto contenente la proprietà click_data.url che rappresenta l'URL a cui indirizzare gli spettatori se fanno clic sull'icona Scegli Tu! su una piattaforma che supporta la navigazione web.
click_fallback_images Un array di oggetti immagine da mostrare agli spettatori che fanno clic sull'icona AdChoices su piattaforme che non supportano la navigazione web.

Formato JSON dell'immagine di riserva

larghezza La larghezza dell'immagine di riserva, in pixel.
altezza L'altezza dell'immagine di riserva, in pixel.
creative_type Il tipo MIME dell'immagine di riserva. Il valore predefinito è "image/png".
risorsa L'URL per recuperare l'immagine di riserva.
alt_text Il testo alternativo da eseguire il rendering per l'immagine di riserva.

JSON dei metadati di esempio

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