Formats personnalisés d'annonces natives

Formats d'annonces natives personnalisés

En plus des formats natifs définis par le système, les éditeurs Ad Manager peuvent créer leurs propres formats d'annonces natives en définissant des listes d'assets personnalisées. Il s'agit des formats d'annonces natives personnalisées, qui peuvent être utilisés avec les annonces réservées. Cela permet aux éditeurs de transmettre des données structurées arbitraires à leurs applications. Ces annonces sont représentées par l'objet NativeCustomFormatAd.

Charger des formats d'annonces natives personnalisés

Ce guide explique comment charger et afficher des formats d'annonces natives personnalisées.

Créer un AdLoader

Comme les annonces natives, les formats d'annonces natives personnalisés sont chargés à l'aide de la classe AdLoader:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
          @Override
          public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
              // Show the custom format and record an impression.
          }
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String s) {
              // Handle the click action
          }
      })
    .withAdListener( ... )
    .withNativeAdOptions( ... )
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
        .forCustomFormatAd("10063170",
            { ad ->
                // Show the custom format and record an impression.
            },
            { ad, s ->
            // Handle the click action
            })
        .withAdListener( ... )
        .withNativeAdOptions( ... )
        .build()

La méthode forCustomFormatAd configure AdLoader pour demander des formats d'annonces natives personnalisées. Trois paramètres sont transmis à la méthode:

• ID du format d'annonce native personnalisée que AdLoader doit demander. Chaque format d'annonce native personnalisée est associé à un ID. Ce paramètre indique le format que votre application souhaite que AdLoader demande.
• Un OnCustomFormatAdLoadedListener à appeler lorsqu'une annonce a bien été chargée.
• OnCustomClickListener facultatif à appeler lorsque l'utilisateur appuie ou clique sur l'annonce. Pour en savoir plus sur cet écouteur, consultez la section "Gérer les clics et les impressions" ci-dessous.

Étant donné qu'un même bloc d'annonces peut être configuré pour diffuser plusieurs formats de création, forCustomFormatAd peut être appelé plusieurs fois avec des ID de format uniques afin de préparer le chargeur d'annonces à plusieurs formats d'annonces natives personnalisées possibles.

Remarque :forNativeAd et forCustomFormatAd peuvent être utilisés simultanément avec un seul AdLoader si vous disposez d'un bloc d'annonces configuré pour diffuser plusieurs formats d'annonces.

ID du format d'annonce native personnalisé

L'ID de format utilisé pour identifier un format d'annonce native personnalisé se trouve dans l'interface utilisateur d'Ad Manager, sous la section Native dans le menu déroulant Diffusion:

L'ID de chaque format d'annonce native personnalisée s'affiche à côté de son nom. Cliquez sur l'un des noms pour accéder à un écran d'informations sur les champs du format:

Vous pouvez ensuite ajouter, modifier et supprimer des champs individuels. Notez le nom de chacun des éléments. Le nom est la clé utilisée pour obtenir les données de chaque composant lorsque vous affichez votre format d'annonce native personnalisée.

Afficher des formats d'annonces natives personnalisés

Les formats d'annonces natives personnalisés diffèrent des formats définis par le système en ce sens que les éditeurs peuvent définir leur propre liste d'assets qui composent une annonce. Par conséquent, le processus d'affichage d'un tel format diffère de celui des formats définis par le système de plusieurs manières:

1. Étant donné que la classe NativeCustomFormatAd est destinée à gérer tous les formats d'annonces natives personnalisées que vous définissez dans Ad Manager, elle ne comporte pas de "getters" nommés pour les composants. Au lieu de cela, il propose des méthodes telles que getText et getImage qui utilisent le nom du champ comme paramètre.
2. Il n'existe pas de classe de vue d'annonce dédiée comme NativeAdView à utiliser avec NativeCustomFormatAd. Vous êtes libre d'utiliser n'importe quelle mise en page qui a du sens pour votre expérience utilisateur.
3. Comme il n'existe pas de classe ViewGroup dédiée, vous n'avez pas besoin d'enregistrer les vues que vous utilisez pour afficher les composants de l'annonce. Cela permet d'économiser quelques lignes de code lors de la diffusion de l'annonce, mais vous devrez également effectuer un peu plus de travail pour gérer les clics plus tard.

Voici un exemple de fonction qui affiche un NativeCustomFormatAd:

Java

public void displayCustomFormatAd (ViewGroup parent,
                                     NativeCustomFormatAd customFormatAd) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View adView = inflater.inflate(R.layout.custom_format_ad, parent);

    // Locate the TextView that will hold the value for "Headline" and
    // set its text.
    TextView myHeadlineView = (TextView) adView.findViewById(R.id.headline);
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    Button myMainImageView = (ImageView) adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").getDrawable());

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Kotlin

public fun displayCustomFormatAd (parent: ViewGroup,
                                customFormatAd: NativeCustomFormatAd) {
    val adView = layoutInflater
            .inflate(R.layout.ad_simple_custom_format, null)

    val myHeadlineView = adView.findViewById<TextView>(R.id.headline)
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    val myMainImageView = adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").drawable);

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Afficher l'icône Choisir sa pub

Pour respecter le règlement sur les services numériques (DSA), les annonces par réservation diffusées dans l'Espace économique européen (EEE) doivent inclure une icône Choisir sa pub et un lien vers la page "À propos de cette annonce" de Google. Lorsque vous intégrez des annonces natives personnalisées, l'affichage de l'icône Choisir sa pub relève de votre responsabilité. Nous vous recommandons de prendre les mesures nécessaires pour afficher et définir l'écouteur de clics pour l'icône Choisir sa pub lors de l'affichage des principaux composants d'annonce.

L'exemple suivant suppose que vous avez défini un élément <ImageView /> dans votre hiérarchie de vues pour contenir le logo AdChoices.

Important :Définissez l'icône "Choisir sa pub" sur au moins 15 x 15 pixels.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android">
    <ImageView
        android:id="@+id/adChoices"
        android:layout_width="15dp"
        android:layout_height="15dp"
        android:adjustViewBounds="true"
        android:contentDescription="AdChoices icon." />
</LinearLayout>

Les exemples suivants affichent l'icône Choisir sa pub et configurent le comportement de clic approprié.

Java

private AdSimpleCustomTemplateBinding customTemplateBinding;

private void populateAdView(final NativeCustomFormatAd nativeCustomFormatAd) {
  // Render the AdChoices icon.
  String adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW;
  NativeAd.Image adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey);
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.setVisibility(View.GONE);
  } else {
    customTemplateBinding.adChoices.setVisibility(View.VISIBLE);
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.getDrawable());

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            nativeCustomFormatAd.performClick(adChoicesKey);
          }
        });
  }
  ...
}

Kotlin

private lateinit var customTemplateBinding: AdSimpleCustomTemplateBinding

private fun populateAdView(nativeCustomFormatAd: NativeCustomFormatAd) {
  // Render the AdChoices icon.
  val adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW
  val adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey)
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.visibility = View.GONE
  } else {
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.drawable)
    customTemplateBinding.adChoices.visibility = View.VISIBLE

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener {
      nativeCustomFormatAd.performClick(adChoicesKey)
    }
  }
  ...
}

Important :Si vous utilisez le contrôle du téléchargement d'images pour ne demander que des URL d'image, l'asset AdChoices respecte ce paramètre et ne renvoie que l'URL de l'image.

Vidéo native pour les formats d'annonces natives personnalisés

Lorsque vous créez un format personnalisé, vous pouvez le rendre compatible avec les vidéos.

Dans l'implémentation de votre application, vous pouvez utiliser NativeCustomFormatAd.getMediaContent() pour obtenir le contenu multimédia. Appelez ensuite setMediaContent() pour définir le contenu multimédia dans votre vue multimédia. Si l'annonce ne comporte pas de contenu vidéo, prévoyez d'autres options pour la diffuser sans vidéo.

Remarque :Contrairement aux annonces natives, qui contiennent une image dans la vue multimédia lorsque la vidéo n'est pas disponible, la vue multimédia d'une annonce native personnalisée ne contient aucun contenu si elle ne contient pas de vidéo.

L'exemple ci-dessous vérifie si l'annonce comporte un contenu vidéo et affiche une image à la place si aucune vidéo n'est disponible:

Java

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(final NativeCustomFormatAd ad) {

  MediaContent mediaContent = ad.getMediaContent();

  // Assumes you have a FrameLayout in your view hierarchy with the id media_placeholder.
  FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
    mediaView.setMediaContent(mediaContent);
    mediaPlaceholder.addView(mediaView);

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    VideoController vc = mediaContent.getVideoController();
    vc.setVideoLifecycleCallbacks(
        new VideoController.VideoLifecycleCallbacks() {
          @Override
          public void onVideoEnd() {
            // Publishers should allow native ads to complete video playback before
            // refreshing or replacing them with another ad in the same UI location.
            super.onVideoEnd();
          }
        });
  } else {
    ImageView mainImage = new ImageView(this);
    mainImage.setAdjustViewBounds(true);
    mainImage.setImageDrawable(ad.getImage("MainImage").getDrawable());
    mediaPlaceholder.addView(mainImage);
    mainImage.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View view) {
            ad.performClick("MainImage");
          }
        });
  }
}

Kotlin

// Called when a custom native ad loads.
NativeCustomFormatAd.OnCustomFormatAdLoadedListener { ad ->

  val mediaContent = ad.mediaContent

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    val mediaView = MediaView(mediaPlaceholder.getContest())
    mediaView.mediaContent = mediaContent

    val videoController = mediaContent.videoController

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    if (videoController != null) {
      videoController.videoLifecycleCallbacks =
        object : VideoController.VideoLifecycleCallbacks() {
          override fun onVideoEnd() {
            // Publishers should allow native ads to complete video playback before refreshing
            // or replacing them with another ad in the same UI location.
            super.onVideoEnd()
          }
        }
    }
  } else {
    val mainImage = ImageView(this)
    mainImage.adjustViewBounds = true
    mainImage.setImageDrawable(ad.getImage("MainImage")?.drawable)

    mainImage.setOnClickListener { ad.performClick("MainImage") }
    customTemplateBinding.simplecustomMediaPlaceholder.addView(mainImage)
  }
}

Pour savoir comment personnaliser l'expérience vidéo d'une annonce native personnalisée, consultez MediaContent.

Téléchargez l'exemple d'affichage personnalisé Ad Manager pour voir un exemple concret d'annonce vidéo native.

Clics et impressions des formats d'annonces natives personnalisés

Avec les formats d'annonces natives personnalisées, votre application est chargée d'enregistrer les impressions et de signaler les événements de clic au SDK Google Mobile Ads.

Enregistrer les impressions

Pour enregistrer une impression pour une annonce au format personnalisé, appelez la méthode recordImpression sur le NativeCustomFormatAd correspondant:

myCustomFormatAd.recordImpression();

Si votre application appelle accidentellement la méthode deux fois pour la même annonce, le SDK empêche automatiquement l'enregistrement d'une impression en double pour une seule demande.

Signaler les clics

Pour signaler au SDK qu'un clic a été effectué sur une vue d'élément, appelez la méthode performClick sur le NativeCustomFormatAd correspondant et transmettez le nom de l'élément sur lequel l'utilisateur a cliqué. Par exemple, si vous aviez un élément dans votre format personnalisé appelé "MainImage" et que vous souhaitiez enregistrer un clic sur le ImageView correspondant à cet élément, votre code se présenterait comme suit:

myCustomFormatAd.performClick("MainImage");

Notez que vous n'avez pas besoin d'appeler cette méthode pour chaque vue associée à votre annonce. Si vous aviez un autre champ appelé "Caption" qui devait être affiché, mais sur lequel l'utilisateur n'a pas cliqué ou appuyé, votre application n'aurait pas besoin d'appeler performClick pour l'affichage de cet élément.

Répondre aux actions personnalisées de clic

Lorsqu'un clic est effectué sur une annonce au format personnalisé, trois réponses sont possibles du SDK, dans l'ordre suivant:

1. Appelez OnCustomClickListener à partir de AdLoader, le cas échéant.
2. Pour chacune des URL de lien profond de l'annonce, essayez de trouver un résolveur de contenu et lancez le premier qui résout le problème.
3. Ouvrez un navigateur et accédez à l'URL de destination traditionnelle de l'annonce.

La méthode forCustomFormatAd accepte un OnCustomClickListener. Si vous transmettez un objet écouteur, le SDK appelle plutôt sa méthode onCustomClick et n'effectue aucune autre action. Toutefois, si vous transmettez une valeur nulle en tant qu'écouteur, le SDK utilise le lien profond et/ou les URL de destination enregistrés avec l'annonce.

Les écouteurs de clic personnalisés permettent à votre application de décider de la meilleure action à effectuer en réponse à un clic, qu'il s'agisse de mettre à jour l'UI, de lancer une nouvelle activité ou simplement de consigner le clic. Voici un exemple qui consigne simplement qu'un clic a eu lieu:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
        // Display the ad.
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String assetName) {
            Log.i("MyApp", "A custom click just happened for " + assetName + "!");
          }
      }).build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

Au premier abord, il peut sembler étrange que des écouteurs de clics personnalisés existent. Après tout, votre application vient de dire au SDK qu'un clic s'est produit. Pourquoi le SDK devrait-il à son tour le signaler à l'application ?

Ce flux d'informations est utile pour plusieurs raisons, mais surtout, il permet au SDK de garder le contrôle de la réponse au clic. Il peut par exemple envoyer automatiquement des requêtes ping aux URL de suivi tierces définies pour la création et gérer d'autres tâches en arrière-plan, sans code supplémentaire.