Utiliser des formats personnalisés d'annonces natives

Sélectionnez une plate-forme : Android (bêta) Android iOS

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 personnalisées de composants. Ces formats sont appelés formats personnalisés d'annonces natives, et peuvent être utilisés avec des annonces réservées. Les éditeurs peuvent ainsi transmettre des données structurées arbitraires à leurs applications. Ces annonces sont représentées par l' NativeCustomFormatAd objet.

Remarque : La classe NativeCustomFormatAd n'est pas compatible avec la réception de l'objet ResponseInfo ni du bundle extras.

Charger des formats personnalisés d'annonces natives

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

Charger une annonce native personnalisée

Comme 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(this, "/21775744923/example/native")
    .forCustomFormatAd("12387226",
        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
          }
        })
    .forCustomFormatAd("12406343",
        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
          }
        })
    .build();

Kotlin

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

La méthode forCustomFormatAd configure AdLoader pour demander des formats personnalisés d'annonces natives. Vous pouvez appeler la méthode plusieurs fois pour différents ID de format personnalisé. La méthode accepte les paramètres suivants :

• L'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.
• Un OnCustomFormatAdLoadedListener à appeler lorsqu'une annonce a été chargée correctement.
• Un facultatif OnCustomClickListener à 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.

Étant donné qu'un seul 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 personnalisés d'annonces natives 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 personnalisé d'annonce native

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

L'ID de chaque format personnalisé d'annonce native s'affiche à côté de son nom. En cliquant sur l'un des noms, vous accédez à un écran de détails affichant des informations sur les champs du format :

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

Afficher des formats personnalisés d'annonces natives

Les formats personnalisés d'annonces natives diffèrent de ceux définis par le système, car les éditeurs peuvent définir leur propre liste de composants 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. Les composants texte et image sont disponibles via les getters getText() et getImage() qui prennent le nom du champ comme paramètre.
2. Comme il n'existe pas de classe ViewGroup dédiée à enregistrer auprès de Google, vous devez enregistrer manuellement les impressions et les clics.
3. Une annonce native personnalisée a un contenu média null si elle ne contient pas de composant vidéo.

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 personnalisés d'annonces natives

Lorsque vous créez un format personnalisé, vous pouvez le rendre éligible aux vidéos.

Dans l'implémentation de votre application, vous pouvez utiliser NativeCustomFormatAd.getMediaContent() pour obtenir le contenu média. Appelez ensuite setMediaContent() pour définir le contenu média dans votre vue média. Si l'annonce a un contenu média null, prévoyez d'autres solutions pour l'afficher sans vidéo.

L'exemple suivant vérifie si l'annonce contient 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)
  }
}

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

Consultez Annonces vidéo pour en savoir plus sur la personnalisation de l'expérience vidéo d'une annonce native personnalisée.

Afficher l'icône Choisir sa pub

Dans le cadre de la prise en charge du règlement sur les services numériques, 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 pub" 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 <ImageView /> élément dans votre hiérarchie de vues pour contenir le logo Choisir sa pub.

Important : Définissez l'icône Choisir sa pub sur au moins 15 pixels par 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'images, le composant Choisir sa pub respecte ce paramètre et ne renvoie que l'URL de l'image.

Enregistrer les impressions et signaler les clics

Votre application est chargée d'enregistrer les impressions et de signaler les événements de clic à Google Mobile Ads SDK.

Enregistrer les impressions

Pour enregistrer une impression pour une annonce native personnalisée, appelez la méthode recordImpression() de l'annonce :

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 de composant, appelez la méthode performClick() de l'annonce. Indiquez le nom du composant sur lequel l'utilisateur a cliqué en utilisant la même chaîne que celle que vous avez définie dans l'interface utilisateur Ad Manager.

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é "Légende" qui était destiné à être affiché, mais sur lequel l'utilisateur n'a pas cliqué ni appuyé, votre application n'aurait pas besoin d'appeler performClick pour la vue de ce composant.

Répondre aux actions de clic personnalisées

Lorsqu'un clic est effectué sur une annonce au format personnalisé, le SDK peut répondre de trois manières différentes, dans cet ordre :

1. Appeler OnCustomClickListener si un écouteur a été fourni.
2. Pour chacune des URL de lien profond de l'annonce, tenter de localiser un résolveur de contenu et démarrer le premier qui se résout.
3. Ouvrir un navigateur et accéder à l'URL de destination de l'annonce.

Pour implémenter une action de clic personnalisée, fournissez un OnCustomClickListener :

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 début, il peut sembler étrange qu'il existe des écouteurs de clics personnalisés. Après tout, votre application vient d'indiquer au SDK qu'un clic a eu lieu. Pourquoi le SDK devrait-il le signaler à l'application ?

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