Iniziare a utilizzare la raccolta di annunci di Android TV

La raccolta degli annunci di Android TV offre un'interfaccia utente che consente agli utenti di controllare esperienza pubblicitaria su Google TV. Questa guida spiega come integrare Android TV raccolta di annunci nell'app PAL per Android TV esistente.

Prerequisiti

• Completa la guida introduttiva
• SDK PAL per Android versione 20.0.1 o successive

Trasparenza e controlli degli annunci

La raccolta degli annunci di Android TV consente di visualizzare la trasparenza degli annunci e controlla le funzionalità (AT&C) durante le interruzioni pubblicitarie. Quando gli utenti interagiscono con gli annunci TV di Google durante gli annunci in-stream, il menu AT&C viene visualizzato come un sistema overlay dell'app Avvio app TV, che mostra un URL breve e una risposta rapida (codice QR) per saperne di più sull'annuncio e un pulsante per interrompere la pubblicazione dello stesso annuncio.

L'icona Annunci TV di Google dovrebbe essere visualizzata utilizzando la stessa icona VAST. i requisiti di rendering AdChoices .

Facendo clic sull'icona Annunci TV di Google, vengono mostrati all'utente un URL breve e un codice QR per la pagina web Informazioni su questo annuncio (ATA).

Integrare la raccolta di annunci Android TV

Importare la libreria degli annunci ATV

Aggiungi la seguente dipendenza per la raccolta di annunci di Android TV a livello di app File Gradle, in genere app/build.gradle:

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

Dichiara l'autorizzazione AD_ID

Affinché la raccolta di annunci Android TV possa accedere alla sezione Pubblicità ID, aggiungi il parametro seguente al tuo AndroidManifest.xml:

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

Integrazione con l'SDK PAL

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

Aggiungi le righe in grassetto all'app PAL per configurare la raccolta di annunci di Android TV in funziona 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 risposta VAST

Quando viene effettuata una richiesta di annuncio con gli indicatori della raccolta di annunci Android TV, invieranno una risposta VAST contenente il tag <Icon> con uno o più <IconClickFallbackImage> secondari per diverse risoluzioni dello schermo. Seguire le risposte del file XML VAST di analisi istruzioni per analizzare il modello VAST.

Di seguito è riportato un esempio di struttura VAST 4.2 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 l'esempio di VAST 3.0 nella guida PAL per l'analisi di VAST 3.0 risposte predefinite.

Durante l'analisi del modello VAST, crea un IconClickFallbackImage per ogni tag <IconClickFallbackImage> e compilalo con il codice i dati utilizzando IconClickFallbackImage.Builder. Analogamente, utilizza IconClickFallbackImages.Builder per passare l'elenco di IconClickFallbackImage oggetti in un IconClickFallbackImages 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;
  }

Visualizza AT&C

La raccolta degli annunci di Android TV offre AdsControlsManager.handleIconClick() per il rendering di un menu AT&C o di un'immagine VAST IconClickFallbackImage standard.

Il seguente snippet configura la raccolta di annunci di Android TV per eseguire il rendering dell'AT&C e sull'icona VAST, fai clic sulle immagini di riserva.

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, quindi i callback standard del ciclo di vita, onPause(): e onResume() può essere utilizzato per ascoltare le modifiche al ciclo di vita delle attività.

[Facoltativo] Fornisci un renderer personalizzato delle immagini di riserva

Se la tua app ha requisiti speciali, ad esempio limitazioni hardware o UX puoi impostare una funzione di callback AdsControlsManager.setCustomFallbackImageRenderer() La raccolta degli annunci di Android TV verifica le immagini di riserva per determinare se può utilizzare il renderer personalizzato fornito. Il rendering personalizzato viene utilizzato solo per VAST IconClickFallbackImage e non 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
      ...
    }
  }
  ...
}

Inviare feedback a Google sulla raccolta di annunci di Android TV

Vorremmo conoscere la tua esperienza con l'integrazione e migrazione delle app per Android TV. Contatta il tuo account manager Google per programmare durante un incontro con uno dei nostri ingegneri.

Cronologia release

Versione	Data di uscita	Note
1.0.0	2023-05-16	Aggiunge il logging. Riduce il supporto 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 manifest Android consentendo Leanback in modo che sia facoltativa.
1.0.0-alpha01	2022-09-07	Rilascio iniziale.