Cómo comenzar a usar la biblioteca de anuncios de Android TV

La biblioteca de anuncios de Android TV proporciona una interfaz de usuario para que los usuarios controlen sus experiencia de anuncios en Google TV. En esta guía, se explica cómo integrar el dispositivo Android TV biblioteca de anuncios en tu app PAL de Android TV existente.

Requisitos previos

• Completar la guía de primeros pasos
• SDK de PAL de Android versión 20.0.1 o posterior

Transparencia y control de los anuncios

La biblioteca de anuncios de Android TV brinda funciones para renderizar la transparencia de anuncios y controla funciones (AT&C) durante las pausas publicitarias. Cuando los usuarios interactúan con los anuncios de televisión by Google en los anuncios in-stream, el menú de AT&C se renderiza como un sistema superposición de la app de selector de TV, que muestra una URL corta y una respuesta rápida (código QR) para obtener más información sobre el anuncio y un botón para dejar de mostrar el mismo anuncio.

El ícono de Anuncios de TV de Google se debe renderizar con el mismo ícono de VAST. los requisitos de renderización AdChoices ícono.

Cuando el usuario hace clic en el ícono de Anuncios de TV de Google, se le muestra una URL corta y un código QR para la página web Acerca del anuncio (ATA).

Cómo integrar la biblioteca de anuncios de Android TV

Importa la biblioteca de anuncios de ATV

Agrega la siguiente dependencia para la biblioteca de anuncios de Android TV a tu nivel de app Archivo Gradle, normalmente app/build.gradle:

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

Declara el permiso AD_ID

Para que la biblioteca de anuncios de Android TV acceda a la página de Publicidad de la aplicación, agrega siguiente línea a tu AndroidManifest.xml:

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

Cómo realizar la integración con el SDK de PAL

La biblioteca de anuncios de Android TV usa el SignalCollector para recopilar identificadores en el dispositivo requerido para solicitar anuncios. La PAL SDK usa NonceRequest.Builder para leer estas señales y crear un nonce.

Agrega las líneas negritas a tu app de PAL para configurar la biblioteca de anuncios de Android TV. trabajar con el SDK de 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();
    ...
  }

Analiza la respuesta de VAST

Cuando se realiza una solicitud de anuncio con los indicadores de la biblioteca de anuncios de Android TV, enviarán una respuesta de VAST que contiene la etiqueta <Icon> con uno o varios elementos secundarios <IconClickFallbackImage> para diferentes resoluciones de pantalla. Sigue el análisis de las respuestas XML de VAST instrucciones para analizar el formato VAST.

A continuación, se muestra un ejemplo de una estructura de VAST 4.2 de la etiqueta <Icon> y sus elementos secundarios, con los datos relevantes en negrita.

<?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>

De manera similar, <IconClickFallbackImages> se puede analizar con el ejemplo de VAST 3.0 Estructura en la guía PAL para analizar VAST 3.0 respuestas.

Cuando analices el anuncio de VAST, crea IconClickFallbackImage objeto de cada etiqueta <IconClickFallbackImage> y propágalo con los atributos datos con IconClickFallbackImage.Builder De manera similar, usa IconClickFallbackImages.Builder para pasar la lista de objetos IconClickFallbackImage a una IconClickFallbackImages objeto que representa la etiqueta <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;
  }

Renderizar AT&C

La biblioteca de anuncios de Android TV ofrece AdsControlsManager.handleIconClick() para renderizar un menú de AT&C o una IconClickFallbackImage estándar de VAST.

El siguiente fragmento configura la biblioteca de anuncios de Android TV para renderizar el AT&C. y las imágenes de resguardo en el ícono de 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);
    ...
  }
}

Llamar a AdsControlsManager.handleIconClick() inicia un Activity de Android, de modo que devoluciones de llamada de ciclo de vida estándar, onPause() y onResume() se puede usar para escuchar los cambios en el ciclo de vida de la actividad.

[Opcional] Proporciona un procesador de imágenes de resguardo personalizado

Si tu app tiene requisitos especiales, como restricciones de hardware o UX restricciones, puedes establecer una función de devolución de llamada con AdsControlsManager.setCustomFallbackImageRenderer() La biblioteca de anuncios de Android TV verificará las imágenes de resguardo para determinar si puede usar el renderizador personalizado proporcionado. Solo se usará una renderización personalizada para IconClickFallbackImage de VAST y no para el menú de 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
      ...
    }
  }
  ...
}

Cómo enviar comentarios a Google sobre la biblioteca de anuncios de Android TV

Esperamos recibir comentarios sobre tu experiencia con la integración y migración de apps para Android TV. Comunícate con tu administrador de cuentas de Google para programar la cita una reunión con uno de nuestros ingenieros.

Historial de versiones

Versión	Fecha de lanzamiento	Notas
1.0.0	2023-05-16	Agrega registros. Se reduce la compatibilidad con minSdk al nivel de API 21. Se actualizaron el manejo de errores y las dependencias para corregir fallas.
1.0.0-alpha02	2022-11-17	Actualiza el manifiesto de Android, lo que permite que se Leanback esta función sea opcional.
1.0.0-alpha01	2022-09-07	Versión inicial