Esta página foi traduzida pela API Cloud Translation.

Comece a usar a biblioteca de anúncios do Android TV

A biblioteca de anúncios do Android TV oferece uma interface para os usuários controlarem a experiência de anúncios no Google TV. Este guia explica como integrar a biblioteca de anúncios do Android TV ao seu app PAL Android TV.

Pré-requisitos

Conclua o guia Primeiros passos.
SDK do Android PAL versão 20.0.1 ou mais recente

Controles e transparência dos anúncios

A biblioteca de anúncios do Android TV oferece funcionalidade para renderizar a transparência dos anúncios e controlar recursos (AT&C) durante intervalos de anúncios. Quando os usuários interagem com o ícone TV Ads by Google durante anúncios in-stream, o menu AT&C é renderizado como uma sobreposição do sistema pelo app de inicialização da TV, mostrando um URL curto, uma resposta rápida (código QR) para saber mais sobre o anúncio e um botão para interromper a exibição do mesmo anúncio.

O ícone TV Ads by Google precisa ser renderizado usando os mesmos requisitos de renderização de ícones VAST do ícone AdChoices.

Texto alternativo

Ao clicar no ícone TV Ads by Google, o usuário recebe um URL curto e um código QR para a página da Web Sobre este anúncio (ATA).

Texto alternativo

Integrar a biblioteca de anúncios do Android TV

Importar a biblioteca de anúncios de ATV

Adicione a dependência da biblioteca de anúncios do Android TV ao arquivo do Gradle no nível do app, geralmente app/build.gradle:

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

Declarar a permissão `AD_ID`

Para que a biblioteca de anúncios do Android TV acesse o ID de publicidade, adicione a linha a seguir ao AndroidManifest.xml:

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

Integrar com o SDK do PAL

A biblioteca de anúncios do Android TV usa a classe SignalCollector para coletar identificadores no dispositivo necessários para solicitar anúncios. O SDK PAL usa a classe NonceRequest.Builder para ler esses sinais e criar um valor de uso único.

Adicione as linhas em negrito ao app PAL para configurar a biblioteca de anúncios do Android TV para funcionar com o SDK do 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();
    ...
  }

Analisar a resposta VAST

Quando uma solicitação de anúncio é feita com os indicadores da biblioteca de anúncios do Android TV, os servidores de anúncios do Google enviam uma resposta VAST contendo a tag <Icon> com um ou vários filhos <IconClickFallbackImage> para diferentes resoluções de tela. Siga as instruções de análise de respostas VAST em XML para analisar o VAST.

Confira um exemplo de estrutura VAST 4.2 da tag <Icon> e das filhas dela, com os dados relevantes em negrito.

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

Da mesma forma, <IconClickFallbackImages> pode ser analisado usando o exemplo de estrutura VAST 3.0 no guia do PAL para analisar respostas VAST 3.0.

Ao analisar o VAST, crie um objeto IconClickFallbackImage para cada tag <IconClickFallbackImage> e preencha-o com os dados analisados usando IconClickFallbackImage.Builder. Da mesma forma, use IconClickFallbackImages.Builder para transmitir a lista de objetos IconClickFallbackImage a um objeto IconClickFallbackImages que representa a 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;
  }

Renderizar AT&C

A biblioteca de anúncios do Android TV oferece um método AdsControlsManager.handleIconClick() para renderizar um menu AT&C ou uma VAST IconClickFallbackImage padrão.

O snippet a seguir configura a biblioteca de anúncios do Android TV para renderizar o menu AT&C e as imagens de fallback de clique no ícone 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);
    ...
  }
}

Chamar AdsControlsManager.handleIconClick() inicia um Activity do Android para que callbacks de ciclo de vida padrão, como onPause() e onResume() possam ser usados para detectar mudanças no ciclo de vida da atividade.

[Opcional] Fornecer um renderizador de imagem substituto personalizado

Se o app tiver requisitos especiais, como restrições de hardware ou de UX, é possível definir uma função de callback usando AdsControlsManager.setCustomFallbackImageRenderer(). A biblioteca de anúncios para Android TV vai verificar as imagens de substituição para determinar se ela pode usar o renderizador personalizado fornecido. Uma renderização personalizada só será usada para VAST IconClickFallbackImage, e não para o 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
      ...
    }
  }
  ...
}

Enviar feedback ao Google sobre a biblioteca de anúncios do Android TV

Queremos receber feedback sobre sua experiência com a integração e migração de apps para Android TV. Entre em contato com seu gerente de contas do Google para agendar uma reunião com um dos nossos engenheiros.

Histórico de versões

Versão	Data do lançamento	Observações
1.0.1	2025-01-09	Atualizações de transparência e controles de anúncios com suporte.
1.0.0	2023-05-16	Adiciona a geração de registros. O suporte para minSdk foi reduzido para o nível 21 da API. Atualização do tratamento de erros e dependências para corrigir falhas.
1.0.0-alpha02	2022-11-17	Atualiza o manifesto do Android para permitir que o recurso Leanback seja opcional.
1.0.0-alpha01	2022-09-07	Versão inicial.

Comece a usar a biblioteca de anúncios do Android TV Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.