Questa pagina è stata tradotta dall'API Cloud Translation.

Iniziare a utilizzare la raccolta di annunci di Android TV

La raccolta di annunci Android TV fornisce un'interfaccia utente che consente agli utenti di controllare la loro esperienza pubblicitaria su Google TV. Questa guida spiega come integrare la raccolta di annunci Android TV nella tua app per Android TV PAL esistente.

Prerequisiti

Completa la guida Inizia
SDK Android PAL versione 20.0.1 o successive

Trasparenza e controlli degli annunci

La libreria di annunci Android TV fornisce funzionalità per rendere trasparenti gli annunci e controllare le funzionalità (AT&C) durante le interruzioni pubblicitarie. Quando gli utenti interagiscono con l'icona Annunci TV di Google durante gli annunci in-stream, il menu AT&C viene visualizzato come overlay di sistema dall'app di avvio della TV, mostrando un URL breve, una risposta rapida (codice QR) per scoprire di più sull'annuncio e un pulsante per interrompere la visualizzazione dello stesso annuncio.

L'icona Annunci TV di Google deve essere visualizzata utilizzando gli stessi requisiti di rendering dell'icona VAST dell'icona AdChoices.

Testo alternativo

Se fa clic sull'icona Annunci TV di Google, l'utente visualizza un URL breve e un codice QR per la pagina web Informazioni su questo annuncio (ATA).

Testo alternativo

Integrare la libreria di annunci per Android TV

Importa la raccolta di annunci per TV connesse a internet (ATV)

Aggiungi la seguente dipendenza per la libreria Android TV Ads al file Gradle a livello di app, in genere app/build.gradle:

dependencies {
   ...
   implementation 'com.google.android.tv:tv-ads:1.0.1'
}

Dichiarare l'autorizzazione `AD_ID`

Affinché la raccolta di annunci Android TV possa accedere all'ID pubblicità, aggiungi la seguente riga al tuo AndroidManifest.xml:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Integrazione con l'SDK PAL

La libreria di annunci per Android TV utilizza la classe SignalCollector per raccogliere gli identificatori sul dispositivo necessari per richiedere gli annunci. L'SDK PAL utilizza la classe NonceRequest.Builder per leggere questi indicatori e creare un nonce.

Aggiungi le righe in grassetto all'app PAL per configurare la libreria di annunci Android TV in modo che funzioni con l'SDK PAL:

public class VideoPlayerActivity extends Activity {
  ...
  private SignalCollector signalCollector;
  ...
  @Override
  public void onCreate(Bundle savedInstanceState) {
    ...
    signalCollector = new SignalCollector();
    ...
  }
  ...
  public generateNonceForAdRequest() {
    ...
    NonceRequest nonceRequest = NonceRequest.builder()
        ...
        .platformSignalCollector(signalCollector)
        .build();
    ...
  }

Analizza la risposta VAST

Quando viene effettuata una richiesta di annuncio con gli indicatori della raccolta di annunci Android TV, i server pubblicitari di Google inviano una risposta VAST contenente il tag <Icon> con uno o più elementi <IconClickFallbackImage> secondari per risoluzioni dello schermo diverse. Segui le istruzioni per l'analisi delle risposte XML VAST per analizzare il VAST.

Di seguito è riportata una struttura VAST 4.2 di esempio del tag <Icon> e dei relativi elementi secondari, con i dati pertinenti in grassetto.

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="4.2">
 <Ad id="123456">
  <Wrapper>
   ...
   <Creatives>
    ...
    <Creative id="7891011" AdID="ABCD123456EF" sequence="1">
     ...
     <Linear>
      ...
      <Icons>
       ...
       <Icon program="TV Ads by Google" width="106" height="20" xPosition="24" yPosition="20"
        duration="00:00:10" offset="00:00:00" apiFramework="VAST" altText="Why This Ad?">
        <StaticResource creativeType="image/png">
         <![CDATA[https://imasdk.googleapis.com/formats/ata/gtv_ads_badge.png]]>
        </StaticResource>
        <IconClicks>
         ...
         <IconClickThrough><![CDATA[https://myadcenter.google.com]]></IconClickThrough>
         <IconClickFallbackImages>
          <IconClickFallbackImage width="950" height="600">
           <AltText>Sample alt text</AltText>
           <StaticResource creativeType="image/png">
            <![CDATA[https://google.com?atvatc=1&atvatcmd=Eg8KDQoLbXV0ZV9hZF91cmwKAgoA]]>
           </StaticResource>
          </IconClickFallbackImage>
          ...
         </IconClickFallbackImages>
        </IconClicks>
       </Icon>
       ...
      </Icons>
     ...
     </Linear>
     ...
    </Creative>
    ...
   </Creatives>
   ...
  </Wrapper>
  ...
 </Ad>
</VAST>

Analogamente, <IconClickFallbackImages> può essere analizzato utilizzando la struttura VAST 3.0 di esempio riportata nella guida PAL per l'analisi delle risposte VAST 3.0.

Durante l'analisi del VAST, crea un oggetto IconClickFallbackImage per ogni tag <IconClickFallbackImage> e compilalo con i dati analizzati utilizzando IconClickFallbackImage.Builder. Analogamente, utilizza IconClickFallbackImages.Builder per passare l'elenco di oggetti IconClickFallbackImage a un IconClickFallbackImages oggetto che rappresenta il tag <IconClickFallbackImages>.

import com.google.android.tv.ads.IconClickFallbackImage;
import com.google.android.tv.ads.IconClickFallbackImages;
import java.util.Arrays;
...
  IconClickFallbackImages getIconClickFallbackImages(...) {
    // Use parsed VAST IconClickFallbackImages data to build a list of
    // IconClickFallbackImage objects.

    int parsedWidth;
    int parsedHeight;
    String parsedAltText;
    String parsedCreativeType;
    String parsedStaticResourceUri;
    // Read the <IconClickFallbackImage> node and its children to set
    // parsedWidth, parsedHeight, ...

    IconClickFallbackImages iconClickFallbackImages =
        IconClickFallbackImages.builder(
                Arrays.asList(
                    IconClickFallbackImage.builder()
                        .setWidth(parsedWidth)
                        .setHeight(parsedHeight)
                        .setAltText(parsedAltText)
                        .setCreativeType(parsedCreativeType)
                        .setStaticResourceUri(parsedStaticResourceUri)
                        .build()))
            .build();

    return iconClickFallbackImages;
  }

Render AT&C

La libreria di annunci Android TV fornisce un metodo AdsControlsManager.handleIconClick() per il rendering di un menu AT&C o di un'immagine IconClickFallback standard VAST.

Il seguente snippet configura la raccolta di annunci Android TV per eseguire il rendering delle immagini di riserva per i clic sul menu AT&C e sulle icone VAST.

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import com.google.android.tv.ads.AdsControlsManager;
import com.google.android.tv.ads.IconClickFallbackImage;
import com.google.android.tv.ads.IconClickFallbackImages;
import java.util.ArrayList;
import java.util.List;

public final class VideoPlayerActivity extends Activity {
  ...
  private AdsControlsManager adsControlsManager;
  ...
  @Override
  public void onCreate(Bundle savedInstanceState) {
    ...
    adsControlsManager = new AdsControlsManager(this);
    ...
  }
  ...

  /**
   * Called when the user interacts with any VAST Icon.
   * @param view.
   */
  public void onVastIconClicked(View view) {
    IconClickFallbackImages iconClickFallbackImages;
    // Populate the IconClickFallbackImages object from the parsed VAST data.
    ...
    adsControlsManager.handleIconClick(iconClickFallbackImages);
    ...
  }
}

La chiamata a AdsControlsManager.handleIconClick() avvia un Activity Android, pertanto i callback del ciclo di vita standard come onPause() e onResume() possono essere utilizzati per ascoltare le modifiche del ciclo di vita dell'attività.

[Facoltativo] Fornisci un visualizzatore di immagini di riserva personalizzato

Se la tua app ha requisiti speciali, ad esempio limitazioni hardware o vincoli UX, puoi impostare una funzione di callback utilizzando AdsControlsManager.setCustomFallbackImageRenderer(). La libreria di annunci Android TV verificherà le immagini di riserva per determinare se può utilizzare il renderer personalizzato fornito. Un rendering personalizzato verrà utilizzato solo per IconClickFallbackImage VAST e non per il menu AT&C.

import android.app.Activity;
import android.os.Bundle;
import com.google.android.tv.ads.AdsControlsManager;
import com.google.android.tv.ads.CustomFallbackImageRenderer;
import com.google.android.tv.ads.IconClickFallbackImages;
import java.util.List;

public final class VideoPlayerActivity extends Activity {
  ...
  private AdsControlsManager adsControlsManager;
  ...
  @Override
  public void onCreate(Bundle savedInstanceState) {
    ...
    adsControlsManager = new AdsControlsManager(this);
    adsControlsManager.setCustomFallbackImageRenderer(
        new CustomFallbackImageRendererImpl());
    ...
  }

  private static class CustomFallbackImageRendererImpl implements CustomFallbackImageRenderer {
    @Override
    public void render(IconClickFallbackImages iconClickFallbackImages) {
      // Render the fallback images using a custom layout
      ...
    }
  }
  ...
}

Fornire a Google un feedback sulla raccolta di annunci per Android TV

Siamo alla ricerca di feedback sulla tua esperienza con l'integrazione e la migrazione delle app per Android TV. Contatta il tuo account manager Google per fissare un appuntamento con uno dei nostri tecnici.

Cronologia release

Versione	Data di uscita	Note
1.0.1	2025-01-09	Aggiorna i formati della trasparenza degli annunci e dei controlli supportati.
1.0.0	2023-05-16	Aggiunge il logging. Abbassa il supporto di minSdk al livello API 21. Aggiorna la gestione degli errori e le dipendenze per correggere gli arresti anomali.
1.0.0-alpha02	2022-11-17	Aggiorna il file Android Manifest in modo da consentire di impostare la funzionalità Leanback come facoltativa.
1.0.0-alpha01	2022-09-07	Lancio iniziale.

Iniziare a utilizzare la raccolta di annunci di Android TV Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.