Format natif avancé

Sélectionnez une plate-forme : Android iOS

Afficher une annonce NativeAd

Lorsqu'une annonce native est chargée, le SDK Google Mobile Ads appelle l'écouteur pour le format d'annonce correspondant. Votre application est alors responsable de l'affichage de l'annonce, mais elle n'est pas nécessairement tenue de le faire immédiatement. Pour faciliter l'affichage des formats d'annonces définis par le système, le SDK propose des ressources utiles, comme décrit ci-dessous.

Définir la classe NativeAdView

Définissez une classe NativeAdView. Cette classe est une classe ViewGroup et constitue le conteneur de niveau supérieur pour une classe NativeAdView. Chaque vue d'annonce native contient des composants d'annonce native, tels que l'élément de vue MediaView ou l'élément de vue Title, qui doivent être des enfants de l'objet NativeAdView.

Mise en page XML

Ajoutez un NativeAdView XML à votre projet :

<com.google.android.gms.ads.nativead.NativeAdView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">
    <LinearLayout
    android:orientation="vertical">
        <LinearLayout
        android:orientation="horizontal">
          <ImageView
          android:id="@+id/ad_app_icon" />
          <TextView
            android:id="@+id/ad_headline" />
        </LinearLayout>
        <!--Add remaining assets such as the image and media view.-->
    </LinearLayout>
</com.google.android.gms.ads.nativead.NativeAdView>

Jetpack Compose

Incluez le module JetpackComposeDemo/compose-util qui inclut des assistants pour composer NativeAdView et ses composants.

À l'aide du module compose-util, composez un NativeAdView :

  import com.google.android.gms.compose_util.NativeAdAttribution
  import com.google.android.gms.compose_util.NativeAdView

  @Composable
  /** Display a native ad with a user defined template. */
  fun DisplayNativeAdView(nativeAd: NativeAd) {
      NativeAdView {
          // Display the ad attribution.
          NativeAdAttribution(text = context.getString("Ad"))
          // Add remaining assets such as the image and media view.
        }
    }

Gérer l'annonce native chargée

Lorsqu'une annonce native est chargée, gérez l'événement de rappel, gonflez la vue de l'annonce native et ajoutez-la à la hiérarchie des vues :

Java

AdLoader.Builder builder = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
        @Override
        public void onNativeAdLoaded(NativeAd nativeAd) {
            // Assumes you have a placeholder FrameLayout in your View layout
            // (with ID fl_adplaceholder) where the ad is to be placed.
            FrameLayout frameLayout =
                findViewById(R.id.fl_adplaceholder);
            // Assumes that your ad layout is in a file call native_ad_layout.xml
            // in the res/layout folder
            NativeAdView adView = (NativeAdView) getLayoutInflater()
                .inflate(R.layout.native_ad_layout, null);
            // This method sets the assets into the ad view.
            populateNativeAdView(nativeAd, adView);
            frameLayout.removeAllViews();
            frameLayout.addView(adView);
        }
});

Kotlin

val builder = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd { nativeAd ->
        // Assumes you have a placeholder FrameLayout in your View layout
        // (with ID fl_adplaceholder) where the ad is to be placed.
        val frameLayout: FrameLayout = findViewById(R.id.fl_adplaceholder)
        // Assumes that your ad layout is in a file call native_ad_layout.xml
        // in the res/layout folder
        val adView = layoutInflater
                .inflate(R.layout.native_ad_layout, null) as NativeAdView
        // This method sets the assets into the ad view.
        populateNativeAdView(nativeAd, adView)
        frameLayout.removeAllViews()
        frameLayout.addView(adView)
    }

Jetpack Compose

@Composable
/** Load and display a native ad. */
fun NativeScreen() {
  var nativeAd by remember { mutableStateOf<NativeAd?>(null) }
  val context = LocalContext.current
  var isDisposed by remember { mutableStateOf(false) }

  DisposableEffect(Unit) {
    // Load the native ad when we launch this screen
    loadNativeAd(
      context = context,
      onAdLoaded = { ad ->
        // Handle the native ad being loaded.
        if (!isDisposed) {
          nativeAd = ad
        } else {
          // Destroy the native ad if loaded after the screen is disposed.
          ad.destroy()
        }
      },
    )
    // Destroy the native ad to prevent memory leaks when we dispose of this screen.
    onDispose {
      isDisposed = true
      nativeAd?.destroy()
      nativeAd = null
    }
  }

  // Display the native ad view with a user defined template.
  nativeAd?.let { adValue -> DisplayNativeAdView(adValue) }
}

fun loadNativeAd(context: Context, onAdLoaded: (NativeAd) -> Unit) {
  val adLoader =
    AdLoader.Builder(context, NATIVE_AD_UNIT_ID)
      .forNativeAd { nativeAd -> onAdLoaded(nativeAd) }
      .withAdListener(
        object : AdListener() {
          override fun onAdFailedToLoad(error: LoadAdError) {
            Log.e(TAG, "Native ad failed to load: ${error.message}")
          }

          override fun onAdLoaded() {
            Log.d(TAG, "Native ad was loaded.")
          }

          override fun onAdImpression() {
            Log.d(TAG, "Native ad recorded an impression.")
          }

          override fun onAdClicked() {
            Log.d(TAG, "Native ad was clicked.")
          }
        }
      )
      .build()
  adLoader.loadAd(AdRequest.Builder().build())
}

Notez que tous les assets d'une annonce native donnée doivent être affichés dans la mise en page NativeAdView. Le SDK Google Mobile Ads tente de consigner un avertissement lorsque des éléments natifs sont affichés en dehors d'une mise en page de vue d'annonce native.

Les classes de vue d'annonce fournissent également des méthodes permettant d'enregistrer la vue utilisée pour chaque élément individuel, ainsi qu'une méthode permettant d'enregistrer l'objet NativeAd lui-même. L'enregistrement des vues de cette manière permet au SDK de gérer automatiquement des tâches telles que :

  • Enregistrement des clics
  • Enregistrement des impressions lorsque le premier pixel est visible à l'écran
  • Afficher la superposition "Choisir sa pub"

Superposition "Choisir sa pub"

Le SDK ajoute une superposition "Choisir sa pub" à chaque vue d'annonce. Laissez de l'espace dans l'angle de votre choix de votre vue d'annonce native pour le logo "Choisir sa pub" inséré automatiquement. Il est également important que cette superposition soit facile à voir. Choisissez donc des couleurs et des images d'arrière-plan appropriées. Pour en savoir plus sur l'apparence et le fonctionnement de l'overlay, consultez Descriptions des champs des annonces natives.

Attribution des annonces

Vous devez afficher une attribution d'annonce pour indiquer que la vue est une publicité. Pour en savoir plus, consultez nos Consignes relatives au règlement.

Exemple de code

Voici les étapes à suivre pour afficher une annonce native :

  1. Créez une instance de la classe NativeAdView.
  2. Pour que chaque composant d'annonce s'affiche :

    1. Renseignez la vue du composant avec le composant dans l'objet d'annonce.
    2. Enregistrez la vue de l'élément avec la classe NativeAdView.
  3. Enregistrez MediaView si la mise en page de votre annonce native inclut un grand élément multimédia.

  4. Enregistrez l'objet d'annonce avec la classe NativeAdView.

Voici un exemple de fonction qui affiche un NativeAd :

Java

private void displayNativeAd(ViewGroup parent, NativeAd ad) {

  // Inflate a layout and add it to the parent ViewGroup.
  LayoutInflater inflater = (LayoutInflater) parent.getContext()
          .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
  NativeAdView adView = (NativeAdView) inflater
          .inflate(R.layout.ad_layout_file, parent);

  // Locate the view that will hold the headline, set its text, and call the
  // NativeAdView's setHeadlineView method to register it.
  TextView headlineView = adView.findViewById<TextView>(R.id.ad_headline);
  headlineView.setText(ad.getHeadline());
  adView.setHeadlineView(headlineView);

  // Repeat the process for the other assets in the NativeAd
  // using additional view objects (Buttons, ImageViews, etc).

  // If the app is using a MediaView, it should be
  // instantiated and passed to setMediaView. This view is a little different
  // in that the asset is populated automatically, so there's one less step.
  MediaView mediaView = (MediaView) adView.findViewById(R.id.ad_media);
  adView.setMediaView(mediaView);

  // Call the NativeAdView's setNativeAd method to register the
  // NativeAdObject.
  adView.setNativeAd(ad);

  // Ensure that the parent view doesn't already contain an ad view.
  parent.removeAllViews();

  // Place the AdView into the parent.
  parent.addView(adView);
}

Kotlin

fun displayNativeAd(parent: ViewGroup, ad: NativeAd) {

  // Inflate a layout and add it to the parent ViewGroup.
  val inflater = parent.getContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
          as LayoutInflater
  val adView = inflater.inflate(R.layout.ad_layout_file, parent) as NativeAdView

  // Locate the view that will hold the headline, set its text, and use the
  // NativeAdView's headlineView property to register it.
  val headlineView = adView.findViewById<TextView>(R.id.ad_headline)
  headlineView.text = ad.headline
  adView.headlineView = headlineView

  // Repeat the process for the other assets in the NativeAd using
  // additional view objects (Buttons, ImageViews, etc).

  val mediaView = adView.findViewById<MediaView>(R.id.ad_media)
  adView.mediaView = mediaView

  // Call the NativeAdView's setNativeAd method to register the
  // NativeAdObject.
  adView.setNativeAd(ad)

  // Ensure that the parent view doesn't already contain an ad view.
  parent.removeAllViews()

  // Place the AdView into the parent.
  parent.addView(adView)
}

Jetpack Compose

@Composable
/** Display a native ad with a user defined template. */
fun DisplayNativeAdView(nativeAd: NativeAd) {
  val context = LocalContext.current
  Box(modifier = Modifier.padding(8.dp).wrapContentHeight(Alignment.Top)) {
    // Call the NativeAdView composable to display the native ad.
    NativeAdView {
      // Inside the NativeAdView composable, display the native ad assets.
      Column(Modifier.align(Alignment.TopStart).wrapContentHeight(Alignment.Top)) {
        // Display the ad attribution.
        NativeAdAttribution(text = context.getString(R.string.attribution))
        Row {
          // If available, display the icon asset.
          nativeAd.icon?.let { icon ->
            NativeAdIconView(Modifier.padding(5.dp)) {
              icon.drawable?.toBitmap()?.let { bitmap ->
                Image(bitmap = bitmap.asImageBitmap(), "Icon")
              }
            }
          }
          Column {
            // If available, display the headline asset.
            nativeAd.headline?.let {
              NativeAdHeadlineView {
                Text(text = it, style = MaterialTheme.typography.headlineLarge)
              }
            }
            // If available, display the star rating asset.
            nativeAd.starRating?.let {
              NativeAdStarRatingView {
                Text(text = "Rated $it", style = MaterialTheme.typography.labelMedium)
              }
            }
          }
        }

        // If available, display the body asset.
        nativeAd.body?.let { NativeAdBodyView { Text(text = it) } }
        // Display the media asset.
        NativeAdMediaView(Modifier.fillMaxWidth().height(500.dp).fillMaxHeight())

        Row(Modifier.align(Alignment.End).padding(5.dp)) {
          // If available, display the price asset.
          nativeAd.price?.let {
            NativeAdPriceView(Modifier.padding(5.dp).align(Alignment.CenterVertically)) {
              Text(text = it)
            }
          }
          // If available, display the store asset.
          nativeAd.store?.let {
            NativeAdStoreView(Modifier.padding(5.dp).align(Alignment.CenterVertically)) {
              Text(text = it)
            }
          }
          // If available, display the call to action asset.
          // Note: The Jetpack Compose button implements a click handler which overrides the native
          // ad click handler, causing issues. Use the NativeAdButton which does not implement a
          // click handler. To handle native ad clicks, use the NativeAd AdListener onAdClicked
          // callback.
          nativeAd.callToAction?.let { callToAction ->
            NativeAdCallToActionView(Modifier.padding(5.dp)) { NativeAdButton(text = callToAction) }
          }
        }
      }
    }
  }
}

Voici les tâches individuelles :

  1. Gonfler la mise en page

    Java

    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    NativeAdView adView = (NativeAdView) inflater
            .inflate(R.layout.ad_layout_file, parent);
    

    Kotlin

    val inflater = parent.getContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
            as LayoutInflater
    val adView = inflater.inflate(R.layout.ad_layout_file, parent) as NativeAdView
    

    Ce code gonfle une mise en page XML qui contient des vues pour afficher une annonce native, puis localise une référence à NativeAdView. Notez que vous pouvez également réutiliser un NativeAdView existant s'il y en a un dans votre fragment ou activité, ou même créer une instance de manière dynamique sans utiliser de fichier de mise en page.

  2. Remplir et enregistrer les vues de composants

    Cet exemple de code localise la vue utilisée pour afficher le titre, définit son texte à l'aide du composant de chaîne fourni par l'objet d'annonce et l'enregistre auprès de l'objet NativeAdView :

    Java

    TextView headlineView = adView.findViewById<TextView>(R.id.ad_headline);
    headlineView.setText(ad.getHeadline());
    adView.setHeadlineView(headlineView);
    

    Kotlin

    val headlineView = adView.findViewById<TextView>(R.id.ad_headline)
    headlineView.text = ad.headline
    adView.headlineView = headlineView
    

    Ce processus de localisation de la vue, de définition de sa valeur et d'enregistrement auprès de la classe de vue d'annonce doit être répété pour chacun des composants fournis par l'objet d'annonce native que l'application affichera.

  3. Gérer les clics

    N'implémentez aucun gestionnaire de clics personnalisé sur les vues au-dessus ou à l'intérieur de la vue d'annonce native. Les clics sur les composants de la vue d'annonce sont gérés par le SDK à condition que vous remplissiez et enregistriez correctement les vues de composants, comme indiqué dans la section précédente.

    Pour écouter les clics, implémentez le rappel de clic du SDK Google Mobile Ads :

    Java

    AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110")
        // ...
        .withAdListener(new AdListener() {
            @Override
            public void onAdFailedToLoad(LoadAdError adError) {
                // Handle the failure by logging.
            }
            @Override
            public void onAdClicked() {
                // Log the click event or other custom behavior.
            }
        })
        .build();
    

    Kotlin

    val adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        // ...
        .withAdListener(object : AdListener() {
            override fun onAdFailedToLoad(adError: LoadAdError) {
                // Handle the failure.
            }
            override fun onAdClicked() {
                // Log the click event or other custom behavior.
            }
        })
        .build()
    
  4. Enregistrer MediaView

    Vous devez utiliser l'asset MediaView plutôt que l'asset ImageView si vous souhaitez inclure une image principale dans la mise en page de votre annonce native.

    MediaView est un View spécial conçu pour afficher le composant média principal, qu'il s'agisse d'une vidéo ou d'une image.

    MediaView peut être défini dans une mise en page XML ou construit de manière dynamique. Il doit être placé dans la hiérarchie des vues d'un NativeAdView, comme n'importe quelle autre vue d'asset. Les applications utilisant un MediaView doivent l'enregistrer auprès de NativeAdView :

    Java

     // Populate and register the media asset view.
     nativeAdView.setMediaView(nativeAdBinding.adMedia);
    

    Kotlin

     // Populate and register the media asset view.
     nativeAdView.mediaView = nativeAdBinding.adMedia
    

    ImageScaleType

    La classe MediaView possède une propriété ImageScaleType lors de l'affichage des images. Si vous souhaitez modifier la façon dont une image est mise à l'échelle dans MediaView, définissez le ImageView.ScaleType correspondant à l'aide de la méthode setImageScaleType() de MediaView :

    Java

    mediaView.setImageScaleType(ImageView.ScaleType.CENTER_CROP);
    

    Kotlin

    mediaView.imageScaleType = ImageView.ScaleType.CENTER_CROP
    

    MediaContent

    La classe MediaContent contient les données liées au contenu multimédia de l'annonce native, qui est affiché à l'aide de la classe MediaView. Lorsque la propriété MediaView mediaContent est définie avec une instance MediaContent :

    • Si un élément vidéo est disponible, il est mis en mémoire tampon et la lecture commence dans le MediaView. Pour savoir si un composant vidéo est disponible, vérifiez hasVideoContent().

    • Si l'annonce ne contient pas d'asset vidéo, l'asset mainImage est téléchargé et placé dans MediaView.

    Par défaut, mainImage est le premier composant Image téléchargé. Si setReturnUrlsForImageAssets(true) est utilisé, mainImage est défini sur null et vous devez définir la propriété mainImage sur l'image que vous avez téléchargée manuellement. Notez que cette image ne sera utilisée qu'en l'absence d'élément vidéo.

  5. Enregistrer l'objet d'annonce native

    Cette dernière étape enregistre l'objet d'annonce native auprès de la vue chargée de l'afficher.

    Java

    adView.setNativeAd(ad);
    

    Kotlin

    adView.setNativeAd(ad)
    

Détruire une annonce

Une fois que vous avez affiché une annonce native, détruisez-la. L'exemple suivant détruit une annonce native :

Java

nativeAd.destroy();

Kotlin

nativeAd.destroy()

Exemples sur GitHub

Exemple d'implémentation complète d'annonces natives :

Java Kotlin JetpackCompose

Étapes suivantes

Consultez les rubriques suivantes :