Utiliser des formats personnalisés d'annonces natives

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. Ces formats sont appelés formats d'annonces natives personnalisés et peuvent être utilisés avec les annonces par réservation. 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és.

Charger une annonce native personnalisée

Pour charger une annonce native personnalisée, procédez comme suit :

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

  2. Définissez l'ID du format d'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) {}
  },
)

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) {}
    });

ID du format d'annonce native personnalisée

L'ID de format utilisé pour identifier un format d'annonce native personnalisée est disponible dans l'interface utilisateur d'Ad Manager, dans la section Natif du 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 détaillées sur les champs du format :

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

Formats d'annonces natives personnalisés pour le Réseau Display

Les formats d'annonces natives personnalisés diffèrent de ceux définis par le système, car les éditeurs peuvent définir leur propre liste d'assets qui composent une annonce. Par conséquent, le processus d'affichage d'un format personnalisé diffère de celui 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 les impressions et les clics manuellement.
  3. Une annonce native personnalisée comporte un contenu multimédia null si elle ne contient pas de composant vidéo.

Cet exemple 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()
}

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();
  }
}

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

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 multimédia. Ensuite, appelez setMediaContent() pour définir le contenu multimédia dans votre vue multimédia. Si l'annonce comporte du contenu multimédia null, prévoyez d'autres solutions pour diffuser 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()
}

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();
}

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

Conformément au 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 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 élément <ImageView /> dans la hiérarchie des 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
  }
}

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);
    }
  }
}

Enregistrer les impressions et générer des rapports sur les clics

Votre application est chargée d'enregistrer les impressions et de signaler les événements de clic à 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()

Java

// Record an impression.
customNativeAd.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 demande.

Signaler des clics

Pour signaler au SDK qu'un clic a été effectué sur une vue d'asset, appelez la méthode performClick() de l'annonce. Indiquez le nom de l'élément sur lequel l'utilisateur a cliqué en utilisant la même chaîne que celle que vous avez définie dans l'interface utilisateur d'Ad Manager.

Kotlin

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

Java

imageView.setOnClickListener(
    new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        customNativeAd.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 devait ê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 cet élément.

Répondre aux actions de clic personnalisées

Lorsqu'un utilisateur clique sur une annonce au format personnalisé, le SDK peut répondre de trois manières, dans l'ordre suivant :

  1. Appelez le OnCustomClickListener, le cas échéant.
  2. Pour chacune des URL de lien profond de l'annonce, tentez de localiser un résolveur de contenu et démarrez le premier qui résout.
  3. Ouvrez un navigateur et accédez à 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.
    }
  }

Java

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

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 devrait-il alors 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 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 code supplémentaire.