Se usó la API de Cloud Translation para traducir esta página.

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 su experiencia de anuncios en Google TV. En esta guía, se explica cómo integrar la biblioteca de anuncios de Android TV en tu app de Android TV para PAL existente.

Requisitos previos

Completa la guía de Introducción
Versión 20.0.1 o posterior del SDK de Android PAL

Transparencia y controles de los anuncios

La biblioteca de anuncios de Android TV proporciona funcionalidad para renderizar la transparencia de los anuncios y controlar las funciones (AT&C) durante las pausas publicitarias. Cuando los usuarios interactúan con el ícono de Anuncios de TV de Google durante los anuncios in-stream, la app del selector de TV renderiza el menú de AT&C como una superposición del sistema, que muestra una URL corta, 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 TV Ads by Google se debe renderizar con los mismos requisitos de renderización de íconos de VAST que el ícono de AdChoices.

Texto alternativo

Si 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 de este anuncio (ATA).

Texto alternativo

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 archivo Gradle a nivel de la app, por lo general, app/build.gradle:

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

Declara el permiso `AD_ID`

Para que la biblioteca de anuncios de Android TV acceda al ID de publicidad, agrega la 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 la clase SignalCollector para recopilar los identificadores en el dispositivo necesarios para solicitar anuncios. El SDK de PAL usa la clase NonceRequest.Builder para leer estos indicadores y crear un nonce.

Agrega las líneas en negrita a tu app de PAL para configurar la biblioteca de anuncios de Android TV para que funcione 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();
    ...
  }

Cómo analizar la respuesta de VAST

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

Esta es una estructura de ejemplo 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>

Del mismo modo, <IconClickFallbackImages> se puede analizar con la estructura de ejemplo de VAST 3.0 en la guía de PAL para analizar respuestas de VAST 3.0.

Cuando analices el VAST, crea un objeto IconClickFallbackImage para cada etiqueta <IconClickFallbackImage> y complétalo con los datos analizados con IconClickFallbackImage.Builder. Del mismo modo, usa IconClickFallbackImages.Builder para pasar la lista de objetos IconClickFallbackImage a un objeto IconClickFallbackImages que represente 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;
  }

Términos y Condiciones de Render

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

En el siguiente fragmento, se configura la biblioteca de anuncios de Android TV para renderizar el menú de AT&C y las imágenes de resguardo de clics del í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 para que se puedan usar devoluciones de llamada de ciclo de vida estándar, como onPause() y onResume(), para escuchar los cambios del ciclo de vida de la actividad.

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

Si tu app tiene requisitos especiales, como restricciones de hardware o de UX, puedes configurar 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
      ...
    }
  }
  ...
}

Envía comentarios a Google sobre la biblioteca de anuncios de Android TV

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

Historial de versiones

Versión	Fecha de lanzamiento	Notas
1.0.1	2025-01-09	Se actualizaron los formatos de transparencia y controles de anuncios admitidos.
1.0.0	2023-05-16	Agrega registro. Se reduce la compatibilidad con minSdk al nivel de API 21. Se actualiza el manejo de errores y las dependencias para corregir fallas.
1.0.0-alpha02	2022-11-17	Se actualiza el manifiesto de Android para que la función Leanback sea opcional.
1.0.0-alpha01	2022-09-07	Versión inicial

Cómo comenzar a usar la biblioteca de anuncios de Android TV Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.