Cette page a été traduite par l'API Cloud Translation.

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 leur expérience publicitaire sur Google TV. Ce guide explique comment intégrer la bibliothèque d'annonces Android TV à votre application Android TV PAL existante.

Prérequis

Suivez le guide de démarrage.
SDK Android PAL version 20.0.1 ou ultérieure

Transparence et commandes des annonces

La bibliothèque d'annonces Android TV permet d'afficher la transparence des annonces et de contrôler les fonctionnalités (AT&C) pendant les coupures publicitaires. Lorsque les utilisateurs interagissent avec l'icône Annonces TV par Google pendant les annonces InStream, le menu AT&C est affiché en superposition système par l'application de lanceur de TV. Il affiche 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 Annonces TV Google doit être affichée en utilisant les mêmes exigences d'affichage des icônes VAST que l'icône AdChoices.

Texte alternatif

Si l'utilisateur clique sur l'icône Annonces TV de Google, une URL courte et un code QR s'affichent pour 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 à votre fichier Gradle au niveau de l'application, généralement app/build.gradle:

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

Déclarer l'autorisation `AD_ID`

Pour que la bibliothèque d'annonces Android TV puisse accéder à l'identifiant publicitaire, ajoutez la ligne suivante à votre AndroidManifest.xml:

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

Intégrer le SDK PAL

La bibliothèque d'annonces Android TV utilise la classe SignalCollector pour collecter les identifiants sur l'appareil requis pour demander des annonces. Le SDK PAL utilise la classe 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 afin qu'elle fonctionne 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, les serveurs publicitaires Google envoient une réponse VAST contenant la balise <Icon> avec un ou plusieurs enfants <IconClickFallbackImage> pour différentes résolutions d'écran. Suivez les instructions pour analyser les réponses XML VAST afin d'analyser le VAST.

Voici un exemple de structure VAST 4.2 de la balise <Icon> et de ses 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, <IconClickFallbackImages> peut être analysé à l'aide de l'exemple de structure VAST 3.0 dans le guide PAL pour l'analyse des réponses VAST 3.0.

Lors de l'analyse du VAST, créez un objet IconClickFallbackImage pour chaque balise <IconClickFallbackImage> et remplissez-le avec les données analysées à l'aide de IconClickFallbackImage.Builder. De même, utilisez IconClickFallbackImages.Builder pour transmettre la liste des objets IconClickFallbackImage à un objet IconClickFallbackImages représentant la balise <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;
  }

Conditions d'utilisation de la fonctionnalité de rendu

La bibliothèque d'annonces Android TV fournit une méthode AdsControlsManager.handleIconClick() pour 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 menu AT&C et les images de remplacement en cas de clic sur l'icône 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);
    ...
  }
}

L'appel de AdsControlsManager.handleIconClick() démarre un Activity Android. Les rappels de cycle de vie standards tels que onPause() et onResume() peuvent donc être utilisés pour écouter les modifications du cycle de vie de l'activité.

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

Si votre application présente des exigences particulières, telles que des restrictions matérielles ou des contraintes d'expérience utilisateur, vous pouvez définir une fonction de rappel à l'aide de AdsControlsManager.setCustomFallbackImageRenderer(). La bibliothèque d'annonces Android TV vérifie les images de remplacement pour déterminer si elle peut utiliser le moteur de rendu personnalisé fourni. Un rendu personnalisé ne sera utilisé que pour l'élément 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 des commentaires à Google sur la bibliothèque d'annonces Android TV

Nous souhaitons recueillir vos commentaires sur votre expérience concernant 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.1	2025-01-09	Mise à jour des formats de transparence et de contrôle des annonces compatibles.
1.0.0	2023-05-16	Ajoute la journalisation. Réduction de la prise en charge de minSdk au niveau d'API 21. Mise à jour du traitement des erreurs et des dépendances pour corriger les plantages.
1.0.0-alpha02	2022-11-17	Mise à jour du fichier manifeste Android pour que la fonctionnalité Leanback soit facultative.
1.0.0-alpha01	2022-09-07	Version initiale.

Premiers pas avec la bibliothèque d'annonces Android TV Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.