Questa pagina è stata tradotta dall'API Cloud Translation.

Icona e overlay Scegli Tu!

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

Per ulteriori informazioni, consulta la sezione 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 ai metadati dello stream 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 devono soddisfare i seguenti standard:

L'icona Scegli Tu! deve essere visualizzata in sovrapposizione a qualsiasi annuncio per cui viene fornita.
L'icona Scegli Tu! deve essere visualizzata nella posizione indicata dalle proprietà "Posizione X" e "Posizione Y" incluse nei dati dell'icona, e con le dimensioni definite dalle proprietà di larghezza e altezza, in Pixel indipendenti dalla densità.
L'icona Scegli Tu! non deve essere nascosta da altri overlay dell'annuncio o elementi dell'interfaccia.
Sulle piattaforme che supportano i clic o una soluzione equivalente (ad es. tocco o selezione remota), l'icona Scegli Tu! deve essere cliccabile.
Sulle piattaforme che supportano i browser, se fai clic sull'icona Scegli Tu! devi aprire una scheda o una finestra del browser con l'URL specificato nella proprietà "Click-through" o "click_data".
Sulle piattaforme che non supportano il browser, facendo clic sull'icona Scegli Tu! devi aprire un overlay modale che mostra una delle immagini specificate nella proprietà "IconClickFallbackImage" o "click_fallback_images".
Sulle piattaforme che non supportano il browser, l'immagine di riserva deve essere visualizzata nelle dimensioni specificate all'interno della proprietà "IconClickFallbackImage" o "click_fallback_images", in pixel indipendenti dalla densità (DP).

Analizzare Scegli Tu! da una risposta XML VAST

Quando utilizzi una risposta di annuncio XML, Scegli Tu! è supportato solo in VAST 3.0 e versioni successive. Scegli Tu! è implementato come icona VAST.

VAST 4.2

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

Se l'app non supporta le icone VAST 4.2, devi analizzare manualmente le icone con il nome di programma "GoogleWhyThisAd" nella tua risposta VAST, in base a questo standard. Puoi utilizzare questo file xml VAST 4.2 di esempio 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 dell'annuncio XML è conforme allo standard VAST 3.0, Scegli Tu! viene pubblicato come combinazione di un'icona VAST e un'estensione VAST personalizzata. Se la tua app o il tuo sito web supporta completamente lo standard dell'icona VAST 3.0 e se la piattaforma è in grado di raggiungere 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 raggiungere e visualizzare gli URL di clickthrough (ciò vale principalmente per i dispositivi che non dispongono di un browser web integrato), devi implementare il supporto per l'estensione "IconFallbackImages". Questa estensione contiene un insieme di tag "IconFallbackImages" in cui l'attributo "programma" corrisponde a un'icona inclusa nel 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 disponibile. Puoi utilizzare questo file xml VAST 3.0 di esempio per ulteriori test nella tua app.

Struttura delle estensioni IconFallbackImages

Tag	Attributi	Descrizione
Estensione	digita	Per questa estensione, il tipo contiene sempre il valore `IconClickFallbackImages`.
- Immagini delle icone di riserva	programma	Questo attributo corrisponde sempre all'attributo di programma di un'icona VAST 3.0 associata.
- Immagini delle icone di riserva		La struttura di questo nodo corrisponde allo standard VAST 4.2 per IconClickFallbackImages, tranne per l'aggiunta dell'attributo `program`.
--IconClickFallbackImage	width	La larghezza preferita per la visualizzazione dell'immagine.
--IconClickFallbackImage	altezza	L'altezza preferita per la visualizzazione dell'immagine.
---AltText		Una descrizione accessibile dell'immagine.
---StaticResource	creativeType	Il tipo MIME dell'immagine di riserva.
---StaticResource		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>

Analizza Scegli Tu! dal JSON dei metadati dell'API DAI

Quando utilizzi l'API DAI, i dettagli di Scegli Tu! vengono trasmessi attraverso l'oggetto JSON che viene restituito dalle richieste all'URL dei metadati.

L'oggetto JSON Metadata contiene un elenco di annunci, digitati dall'adID. All'interno di ogni oggetto annuncio è presente un array di icone. Se l'annuncio in questione utilizza Scegli Tu!, l'icona Scegli Tu! è contenuta nell'array.

Formato icona JSON

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

Formato JSON icona

programma	Per l'icona Scegli Tu!, questo valore contiene sempre la stringa "GoogleWhyThisAd".
x_position	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 in pixel dell'angolo in alto a sinistra dell'icona rispetto all'angolo in alto a sinistra della creatività video. Questo campo accetta anche i valori di posizione adattabili "top" o "bottom".
width	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 visualizzare 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 sul web.
click_fallback_images	Un array di oggetti immagine da mostrare a chi fa clic sull'icona Scegli Tu! sulle piattaforme che non supportano la navigazione sul web.

Formato JSON dell'immagine di riserva

width	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 visualizzare per l'immagine di riserva.

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