Utiliser des 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 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.

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

Pour charger une annonce native personnalisée :

  1. Incluez le type NativeAdType.CUSTOM_NATIVE en tant que type d'annonce dans le NativeAdRequest.

  2. Définissez l'ID du format de l'annonce native personnalisée.

Kotlin

val adRequest =
  NativeAdRequest.Builder("AD_UNIT_ID", listOf(NativeAdType.CUSTOM_NATIVE))
    .setCustomFormatIds(listOf("CUSTOM_NATIVE_FORMAT_ID"))
    .build()

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
  adRequest,
  object : NativeAdLoaderCallback {
    override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) {
      // TODO: Store the custom native ad.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {}
  },
)
CustomNativeSnippets.kt

Java

NativeAdRequest adRequest =
    new NativeAdRequest.Builder("AD_UNIT_ID", List.of(NativeAd.NativeAdType.CUSTOM_NATIVE))
        .setCustomFormatIds(Arrays.asList("CUSTOM_NATIVE_FORMAT_ID"))
        .build();

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
    adRequest,
    new NativeAdLoaderCallback() {
      @Override
      public void onCustomNativeAdLoaded(@NonNull CustomNativeAd customNativeAd) {
        // TODO: Store the custom native ad.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {}
    });
CustomNativeSnippets.java

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. Cliquez sur l'un des noms pour accéder à un écran de détails affichant des informations sur les champs du format's :

Vous pouvez ajouter, modifier et supprimer des champs individuels. Notez le nom de chacun des composants. Il s'agit de 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 getText() et getImage() getters, 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 comporte un null contenu média si elle ne contient pas de composant vidéo.

Cet exemple vous montre comment afficher un CustomNativeAd :

Kotlin

private fun displayCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  customNativeAdBinding.headline.text = customNativeAd.getText("Headline")
  customNativeAdBinding.caption.text = customNativeAd.getText("Caption")

  // If the main asset is an image, render it with an ImageView.
  val imageView = ImageView(context)
  imageView.adjustViewBounds = true
  imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
  imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
  customNativeAdBinding.mediaPlaceholder.addView(imageView)

  // Render the ad choices icon.
  renderAdChoices(customNativeAd)

  // Record an impression.
  customNativeAd.recordImpression()
}

CustomNativeSnippets.kt

Java

private void displayCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  if (customNativeAdBinding != null) {
    customNativeAdBinding.headline.setText(customNativeAd.getText("Headline"));
    customNativeAdBinding.caption.setText(customNativeAd.getText("Caption"));

    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    imageView.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            customNativeAd.performClick("MainImage");
          }
        });
    customNativeAdBinding.mediaPlaceholder.addView(imageView);

    // Render the ad choices icon.
    renderAdChoices(customNativeAd);

    // Record an impression.
    customNativeAd.recordImpression();
  }
}

CustomNativeSnippets.java

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 CustomNativeAd.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 comporte un contenu média null, prévoyez d'autres solutions pour afficher l'annonce sans vidéo.

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

Kotlin

private fun displayVideoCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Check whether the custom native ad has video content.
  val mediaContent = customNativeAd.mediaContent
  if (mediaContent != null && mediaContent.hasVideoContent) {
    // Render the media content in a MediaView.
    val mediaView = MediaView(context)
    mediaView.mediaContent = mediaContent
    customNativeAdBinding.mediaPlaceholder.addView(mediaView)
  } else {
    // Fall back to other assets defined on your custom native ad.
    val imageView = ImageView(context)
    imageView.adjustViewBounds = true
    imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
    customNativeAdBinding.mediaPlaceholder.addView(imageView)
  }

  // Record an impression.
  customNativeAd.recordImpression()
}

CustomNativeSnippets.kt

Java

private void displayVideoCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Check whether the custom native ad has video content.
  MediaContent mediaContent = customNativeAd.getMediaContent();
  if (mediaContent != null && mediaContent.getHasVideoContent()) {
    // Render the media content in a MediaView.
    MediaView mediaView = new MediaView(context);
    mediaView.setMediaContent(mediaContent);
    customNativeAdBinding.mediaPlaceholder.addView(mediaView);
  } else {
    // Fall back to other assets defined on your custom native ad.
    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    customNativeAdBinding.mediaPlaceholder.addView(imageView);
  }

  // Record an impression.
  customNativeAd.recordImpression();
}

CustomNativeSnippets.java

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

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 implémentez 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 "Choisir sa pub".

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

Kotlin

private fun renderAdChoices(customNativeAd: CustomNativeAd) {
  // Render the AdChoices image.
  val adChoiceAsset = customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
  if (adChoiceAsset != null) {
    customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.drawable)
    customNativeAdBinding.adchoices.visibility = View.VISIBLE
    customNativeAdBinding.adchoices.setOnClickListener {
      // Handle click. See the next section for more details.
      customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
    }
  } else {
    customNativeAdBinding.adchoices.visibility = View.GONE
  }
}

CustomNativeSnippets.kt

Java

private void renderAdChoices(CustomNativeAd customNativeAd) {
  // Render the AdChoices image.
  Image adChoiceAsset =
      customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
  if (adChoiceAsset != null) {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.getDrawable());
      customNativeAdBinding.adchoices.setVisibility(View.VISIBLE);
      customNativeAdBinding.adchoices.setOnClickListener(
          new View.OnClickListener() {
            @Override
            public void onClick(View v) {
              // Handle click.
              customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
            }
          });
    }
  } else {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setVisibility(View.GONE);
    }
  }
}

CustomNativeSnippets.java

Enregistrer les impressions et signaler les clics

Votre application est chargée d'enregistrer les impressions et de signaler les événements de clic au GMA Next-Gen SDK.

Enregistrer les impressions

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

Kotlin

// Record an impression.
customNativeAd.recordImpression()
CustomNativeSnippets.kt

Java

// Record an impression.
customNativeAd.recordImpression();
CustomNativeSnippets.java

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.

Kotlin

imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
CustomNativeSnippets.kt

Java

imageView.setOnClickListener(
    new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        customNativeAd.performClick("MainImage");
      }
    });
CustomNativeSnippets.java

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 ne devait pas cliquer ni appuyer, 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 l'ordre suivant :

  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 :

Kotlin

customNativeAd.onCustomClickListener =
  object : OnCustomClickListener {
    override fun onCustomClick(assetName: String) {
      // Perform your custom action.
    }
  }
CustomNativeSnippets.kt

Java

customNativeAd.setOnCustomClickListener(
    new OnCustomClickListener() {
      @Override
      public void onCustomClick(@NonNull String assetName) {
        // Perform your custom action.
      }
    });
CustomNativeSnippets.java

Au début, il peut sembler étrange que des écouteurs de clics personnalisés existent. 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 définies pour la création et gérer d'autres tâches en arrière-plan, sans aucun code supplémentaire.