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

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

Pré-requisitos

  • ler o guia Primeiros passos;
  • SDK da PAL para Android versão 20.0.1 ou mais recente

Transparência e controles dos anúncios

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

O ícone Anúncios de TV do Google precisa ser renderizado usando o mesmo ícone VAST os requisitos de renderização AdChoices ícone.

Texto alternativo

Clicar no ícone Anúncios de TV do Google mostra ao usuário um URL curto e um QR code 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 ATV

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

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

Declarar a permissão AD_ID

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

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

Integrar com o SDK da PAL

A biblioteca de anúncios do Android TV usa as SignalCollector para coletar identificadores no dispositivo necessário para solicitar anúncios. A PAL O SDK usa o 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 trabalhar com o SDK da 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 resposta VAST

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

Veja um exemplo de estrutura do 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 VAST 3.0. no Guia da PAL para análise de VAST 3.0 de resposta.

Ao analisar o VAST, crie uma IconClickFallbackImage para cada tag <IconClickFallbackImage> e preenchê-lo com o objeto dados usando IconClickFallbackImage.Builder Da mesma forma, use IconClickFallbackImages.Builder para passar a lista de objetos IconClickFallbackImage para um IconClickFallbackImages objeto 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 uma AdsControlsManager.handleIconClick() para renderizar um menu AT&C ou um IconClickFallbackImage padrão do VAST.

O snippet a seguir configura a biblioteca de anúncios do Android TV para renderizar a AT&C e as imagens substitutas de clique do í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 uma Activity do Android para que callbacks do ciclo de vida padrão, como onPause() e onResume() pode ser usado para detectar mudanças no ciclo de vida da atividade.

[Opcional] Fornecer renderizador de imagem substituta personalizado

Se o app tiver requisitos especiais, como restrições de hardware ou UX restrições, é possível definir uma função de retorno de chamada usando AdsControlsManager.setCustomFallbackImageRenderer() A biblioteca de anúncios do Android TV verificará as imagens substitutas para determinar se ele pode usar o renderizador personalizado fornecido. Uma renderização personalizada só é usada para IconClickFallbackImage do VAST, mas 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 saber como foi sua experiência com a integração migração de apps para Android TV. Entre em contato com seu gerente de contas do Google para agendar uma reunião com um de nossos engenheiros.

Histórico de versões

Versão Data do lançamento Observações
1.0.0 2023-05-16
  • Adiciona a geração de registros.
  • Redução do suporte do minSdk para o nível 21 da API.
  • Atualiza o tratamento de erros e as dependências para corrigir falhas.
1.0.0-alpha02 2022-11-17
  • Atualiza o manifesto do Android permitindo que o Leanback como opcional.
1.0.0-alpha01 2022-09-07
  • Versão inicial.