Formats d'annonces natives personnalisés

Formats personnalisés d'annonces natives

En plus des formats natifs définis par le système, les éditeurs Ad Manager ont la possibilité de créer leurs propres formats d'annonces natives en définissant des listes personnalisées d'éléments. Ces formats sont appelés formats personnalisés d'annonces natives et peuvent être utilisés avec des 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 personnalisés d'annonces natives.

Créer un AdLoader

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

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/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, "/6499/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és. Trois paramètres sont transmis dans la méthode:

  • ID du format personnalisé d'annonce native que AdLoader doit demander. Chaque format personnalisé d'annonce native est associé à un ID. Ce paramètre indique le format que votre application souhaite que AdLoader demande.
  • Une OnCustomFormatAdLoadedListener à appeler lorsqu'une annonce a bien été chargée.
  • Élément 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 pour plusieurs formats d'annonces natives personnalisés possibles.

ID du format d'annonce native personnalisé

Vous trouverez l'ID de format permettant d'identifier un format personnalisé d'annonce native dans l'interface utilisateur d'Ad Manager, sous la section Native du menu déroulant Diffusion:

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

Vous pouvez alors 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 élément lors de l'affichage de votre format personnalisé d'annonce native.

Formats personnalisés d'annonces natives display

Les formats d'annonces natives personnalisés diffèrent de ceux définis par le système dans la mesure où les éditeurs peuvent définir leur propre liste d'éléments qui composent une annonce. Par conséquent, le processus d'affichage diffère des formats définis par le système de plusieurs manières:

  1. Étant donné que la classe NativeCustomFormatAd est destinée à gérer l'un des formats d'annonces natives personnalisés que vous définissez dans Ad Manager, elle ne comporte pas de "getters" pour les éléments. À la place, 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 d'affichage d'annonce dédiée comme NativeAdView à utiliser avec NativeCustomFormatAd. Vous êtes libre d'utiliser n'importe quelle mise en page pertinente 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 l'affichage de l'annonce, mais vous devrez également effectuer un peu plus de travail pour gérer les clics ultérieurement.

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

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

Lorsque vous créez un format personnalisé, vous pouvez le rendre éligible pour 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 de votre vue multimédia sur votre vue multimédia. Si l'annonce ne comporte pas de contenu vidéo, envisagez d'autres plans afin de la diffuser sans vidéo.

L'exemple ci-dessous vérifie si l'annonce comporte du 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 de vidéo native.

Clics et impressions personnalisés pour les formats d'annonces natives

Avec les formats d'annonces natives personnalisés, votre application se charge d'enregistrer les impressions et de signaler les événements de clic au SDK Google Mobile Ads.

Enregistrer des 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 même requête.

Enregistrer les clics

Pour signaler au SDK qu'un clic s'est produit sur une vue d'élément, appelez la méthode performClick au niveau de l'élément NativeCustomFormatAd correspondant et transmettez le nom de l'élément sur lequel l'utilisateur a cliqué. Par exemple, si vous disposez d'un élément dans votre format personnalisé appelé "MainImage" et que vous souhaitez signaler un clic sur l'élément ImageView correspondant à cet élément, votre code se présente 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 un autre champ appelé "Caption" est censé être affiché, mais que l'utilisateur n'a pas cliqué dessus, votre application n'a pas besoin d'appeler performClick pour l'affichage de cet élément.

Répondre aux actions de clic personnalisé

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

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

La méthode forCustomFormatAd accepte un élément OnCustomClickListener. Si vous transmettez un objet écouteur, le SDK appelle 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 clics 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 s'est produit:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/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, "/6499/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

Au premier abord, l'existence d'écouteurs de clics personnalisés peut sembler étrange. Après tout, votre application vient d'indiquer au SDK qu'un clic s'est produit. Pourquoi le SDK doit-il donc faire le tour et le signaler à l'application ?

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