Premiers pas avec la bibliothèque d'annonces Android TV

La bibliothèque d'annonces Android TV fournit une interface utilisateur permettant aux utilisateurs de contrôler sur Google TV. Ce guide explique comment intégrer Android TV dans votre application PAL Android TV existante.

Prérequis

Transparence des annonces et contrôles

La bibliothèque d'annonces Android TV fournit une fonctionnalité permettant d'afficher la transparence des annonces et contrôle des fonctionnalités (AT&C) pendant les coupures publicitaires. Lorsque les utilisateurs interagissent avec les annonces TV par Google pendant les annonces InStream, le menu AT&C est affiché sous forme de système en superposition à côté de l'application TV launcher, affichant une URL courte, une réponse rapide (code QR) pour en savoir plus sur l'annonce et un bouton pour arrêter de diffuser la même annonce.

L'icône TV Ads by Google doit être affichée à l'aide de la même icône VAST les exigences d'affichage AdChoices .

Texte alternatif

Lorsque l'utilisateur clique sur l'icône TV Ads by Google, une URL courte et un code QR leur sont présentés. la page Web À propos de cette annonce.

Texte alternatif

Intégrer la bibliothèque d'annonces Android TV

Importer la bibliothèque d'annonces ATV

Ajoutez la dépendance suivante pour la bibliothèque d'annonces Android TV au niveau de votre application Gradle, normalement app/build.gradle:

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

Déclarer l'autorisation AD_ID

Pour que la bibliothèque d'annonces Android TV puisse accéder au module Publicité ID, ajoutez le la ligne suivante à votre AndroidManifest.xml:

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

Effectuer une intégration avec le SDK PAL

La bibliothèque d'annonces Android TV utilise le SignalCollector pour collecter les identifiants sur l'appareil requis pour demander des annonces. La PAL Le SDK utilise NonceRequest.Builder pour lire ces signaux et créer un nonce.

Ajoutez les lignes en gras à votre application PAL pour configurer la bibliothèque d'annonces Android TV : travailler avec le 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();
    ...
  }

Analyser la réponse VAST

Lorsqu'une demande d'annonce est effectuée avec les signaux de la bibliothèque d'annonces Android TV, envoient une réponse VAST contenant le tag <Icon> avec un ou plusieurs enfants <IconClickFallbackImage> pour différentes résolutions d'écran. Suivez les instructions d'analyse des réponses XML VAST. instructions pour analyser le contenu VAST.

Voici un exemple de structure VAST 4.2 pour le tag <Icon> et ses éléments enfants, avec les données pertinentes en gras.

<?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 même, vous pouvez analyser <IconClickFallbackImages> à l'aide de l'exemple VAST 3.0. dans le guide PAL pour l'analyse VAST 3.0 réponses.

Lors de l'analyse du fichier VAST, IconClickFallbackImage pour chaque balise <IconClickFallbackImage> et le remplir avec la requête de données en utilisant IconClickFallbackImage.Builder De même, utilisez IconClickFallbackImages.Builder pour transmettre la liste des objets IconClickFallbackImage dans une IconClickFallbackImages représentant le 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;
  }

Rendu AT&C

La bibliothèque d'annonces Android TV fournit AdsControlsManager.handleIconClick() permettant d'afficher un menu AT&C ou une image IconClickFallbackImage VAST standard.

L'extrait de code suivant configure la bibliothèque d'annonces Android TV pour afficher le texte AT&C et sur l'icône VAST pour les images de remplacement.

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);
    ...
  }
}

Appeler AdsControlsManager.handleIconClick() lance un Activity Android. des rappels de cycle de vie standards, tels que onPause() et onResume() permet d'écouter les modifications du cycle de vie d'une activité.

[Facultatif] Fournir un moteur de rendu d'image de remplacement personnalisé

Si votre application présente des exigences particulières, telles que des restrictions matérielles ou des exigences en matière d'expérience utilisateur vous pouvez définir une fonction de rappel en utilisant AdsControlsManager.setCustomFallbackImageRenderer() La bibliothèque d'annonces Android TV vérifiera les images de remplacement pour déterminer si il peut utiliser le moteur de rendu personnalisé fourni. Un affichage personnalisé ne sera utilisé pour VAST IconClickFallbackImage, et non pour le 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
      ...
    }
  }
  ...
}

Envoyer à Google des commentaires sur la bibliothèque d'annonces Android TV

Nous souhaitons connaître votre avis sur l'intégration et la migration des applications Android TV. Contactez votre responsable de compte Google pour planifier une réunion avec l'un de nos ingénieurs.

Historique des versions

Version Date de sortie Remarques
1.0.0 2023-05-16
  • Ajoute la journalisation.
  • Réduit la compatibilité de minSdk au niveau d'API 21.
  • Mise à jour de la gestion des erreurs et des dépendances pour corriger les plantages.
1.0.0-alpha02 2022-11-17
  • Met à jour le fichier manifeste Android autorisant l'accès Leanback fonctionnalité soit facultative.
1.0.0-alpha01 2022-09-07
  • Version initiale.