Native ads

AI-generated Key Takeaways

The Google Mobile Ads SDK (beta) invokes a listener when a native ad loads, making your app responsible for displaying it.
The NativeAdView class is a ViewGroup that serves as the top-level container for native ad assets.
You can handle loaded native ads by inflating the native ad view and adding it to the view hierarchy.
The SDK automatically handles click and impression recording as long as asset views are populated and registered within the NativeAdView.
Remember to destroy native ads after they are shown and follow guidelines for displaying AdChoices and ad attribution for programmatic native ads.

When a native ad loads, Google Mobile Ads SDK (beta) invokes the listener for the corresponding ad format. Your app is then responsible for displaying the ad, though it doesn't necessarily have to do so immediately. To make displaying system-defined ad formats easier, the SDK offers some useful resources, as described below.

Define the `NativeAdView` class

Define a NativeAdView class. This class is a ViewGroup class and is the top level container for a NativeAdView class. Each native ad view contains native ad assets, such as the MediaView view element or the Title view element, which must be a child of the NativeAdView object.

XML Layout

Add a XML NativeAdView to your project:

<com.google.android.libraries.ads.mobile.sdk.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.libraries.ads.mobile.sdk.nativead.NativeAdView>

Jetpack Compose

Include JetpackComposeDemo/compose-util module which includes helpers for composing the NativeAdView and its assets.

Using the compose-util module, compose a 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.
        }
    }

Handle the loaded native ad

When a native ad loads, handle the callback event, inflate the native ad view, and add it to the view hierarchy:

Kotlin

// Build an ad request with native ad options to customize the ad.
val adTypes = listOf(NativeAd.NativeAdType.NATIVE)
val adRequest = NativeAdRequest
  .Builder("/21775744923/example/native", adTypes)
  .build()

val adCallback =
  object : NativeAdLoaderCallback {
    override fun onNativeAdLoaded(nativeAd: NativeAd) {
      activity?.runOnUiThread {

        val nativeAdBinding = NativeAdBinding.inflate(layoutInflater)
        val adView = nativeAdBinding.root
        val frameLayout = myActivityLayout.nativeAdPlaceholder

        // Populate and register the native ad asset views.
        displayNativeAd(nativeAd, nativeAdBinding)

        // Remove all old ad views and add the new native ad
        // view to the view hierarchy.
        frameLayout.removeAllViews()
        frameLayout.addView(adView)
      }
    }
  }

// Load the native ad with our request and callback.
NativeAdLoader.load(adRequest, adCallback)

Java

// Build an ad request with native ad options to customize the ad.
List<NativeAd.NativeAdType> adTypes = Arrays.asList(NativeAd.NativeAdType.NATIVE);
NativeAdRequest adRequest = new NativeAdRequest
                                .Builder("/21775744923/example/native", adTypes)
                                .build();

NativeAdLoaderCallback adCallback = new NativeAdLoaderCallback() {
    @Override
    public void onNativeAdLoaded(NativeAd nativeAd) {
      if (getActivity() != null) {
        getActivity()
          .runOnUiThread(() -> {
            // Inflate the native ad view and add it to the view hierarchy.
            NativeAdBinding nativeAdBinding = NativeAdBinding.inflate(getLayoutInflater());
            NativeAdView adView = (NativeAdView) nativeAdBinding.getRoot();
            FrameLayout frameLayout = myActivityLayout.nativeAdPlaceholder;

            // Populate and register the native ad asset views.
            displayNativeAd(nativeAd, nativeAdBinding);

            // Remove all old ad views and add the new native ad
            // view to the view hierarchy.
            frameLayout.removeAllViews();
            frameLayout.addView(adView);
        });
      }
    }
};

// Load the native ad with our request and callback.
NativeAdLoader.load(adRequest, adCallback);

Note that all assets for a given native ad should be rendered inside the NativeAdView layout. Google Mobile Ads SDK (beta) attempts to log a warning when native assets are rendered outside of a native ad view layout.

The ad view classes also provide methods used to register the view used for each individual asset, and one to register the NativeAd object itself. Registering the views in this way allows the SDK to automatically handle tasks such as:

Recording clicks
Recording impressions when the first pixel is visible on the screen
Displaying the AdChoices overlay for native backfill creatives—currently limited to a select group of publishers

Display the native ad

The following example demonstrates how to display a native ad:

Kotlin

private fun displayNativeAd(nativeAd: NativeAd, nativeAdBinding : NativeAdBinding) {
  // Set the native ad view elements.
  val nativeAdView = nativeAdBinding.root
  nativeAdView.advertiserView = nativeAdBinding.adAdvertiser
  nativeAdView.bodyView = nativeAdBinding.adBody
  nativeAdView.callToActionView = nativeAdBinding.adCallToAction
  nativeAdView.headlineView = nativeAdBinding.adHeadline
  nativeAdView.iconView = nativeAdBinding.adAppIcon
  nativeAdView.priceView = nativeAdBinding.adPrice
  nativeAdView.starRatingView = nativeAdBinding.adStars
  nativeAdView.storeView = nativeAdBinding.adStore

  // Set the view element with the native ad assets.
  nativeAdBinding.adAdvertiser.text = nativeAd.advertiser
  nativeAdBinding.adBody.text = nativeAd.body
  nativeAdBinding.adCallToAction.text = nativeAd.callToAction
  nativeAdBinding.adHeadline.text = nativeAd.headline
  nativeAdBinding.adAppIcon.setImageDrawable(nativeAd.icon?.drawable)
  nativeAdBinding.adPrice.text = nativeAd.price
  nativeAd.starRating?.toFloat().let { value ->
    nativeAdBinding.adStars.rating = value
  }
  nativeAdBinding.adStore.text = nativeAd.store

  // Hide views for assets that don't have data.
  nativeAdBinding.adAdvertiser.visibility = getAssetViewVisibility(nativeAd.advertiser)
  nativeAdBinding.adBody.visibility = getAssetViewVisibility(nativeAd.body)
  nativeAdBinding.adCallToAction.visibility = getAssetViewVisibility(nativeAd.callToAction)
  nativeAdBinding.adHeadline.visibility = getAssetViewVisibility(nativeAd.headline)
  nativeAdBinding.adAppIcon.visibility = getAssetViewVisibility(nativeAd.icon)
  nativeAdBinding.adPrice.visibility = getAssetViewVisibility(nativeAd.price)
  nativeAdBinding.adStars.visibility = getAssetViewVisibility(nativeAd.starRating)
  nativeAdBinding.adStore.visibility = getAssetViewVisibility(nativeAd.store)

  // Inform Google Mobile Ads SDK (beta) that you have finished populating
  // the native ad views with this native ad.
  nativeAdView.registerNativeAd(nativeAd, nativeAdBinding.adMedia)
}

/**
* Determines the visibility of an asset view based on the presence of its asset.
*
* @param asset The native ad asset to check for nullability.
* @return [View.VISIBLE] if the asset is not null, [View.INVISIBLE] otherwise.
*/
private fun getAssetViewVisibility(asset: Any?): Int {
  return if (asset == null) View.INVISIBLE else View.VISIBLE
}

Java

private void displayNativeAd(ad: NativeAd, nativeAdBinding : NativeAdBinding) {
  // Set the native ad view elements.
  NativeAdView nativeAdView = nativeAdBinding.getRoot();
  nativeAdView.setAdvertiserView(nativeAdBinding.adAdvertiser);
  nativeAdView.setBodyView(nativeAdBinding.adBody);
  nativeAdView.setCallToActionView(nativeAdBinding.adCallToAction);
  nativeAdView.setHeadlineView(nativeAdBinding.adHeadline);
  nativeAdView.setIconView(nativeAdBinding.adAppIcon);
  nativeAdView.setPriceView(nativeAdBinding.adPrice);
  nativeAdView.setStarRatingView(nativeAdBinding.adStars);
  nativeAdView.setStoreView(nativeAdBinding.adStore);

  // Set the view element with the native ad assets.
  nativeAdBinding.adAdvertiser.setText(nativeAd.getAdvertiser());
  nativeAdBinding.adBody.setText(nativeAd.getBody());
  nativeAdBinding.adCallToAction.setText(nativeAd.getCallToAction());
  nativeAdBinding.adHeadline.setText(nativeAd.getHeadline());
  if (nativeAd.getIcon() != null) {
      nativeAdBinding.adAppIcon.setImageDrawable(nativeAd.getIcon().getDrawable());
  }
  nativeAdBinding.adPrice.setText(nativeAd.getPrice());
  if (nativeAd.getStarRating() != null) {
      nativeAdBinding.adStars.setRating(nativeAd.getStarRating().floatValue());
  }
  nativeAdBinding.adStore.setText(nativeAd.getStore());

  // Hide views for assets that don't have data.
  nativeAdBinding.adAdvertiser.setVisibility(getAssetViewVisibility(nativeAd.getAdvertiser()));
  nativeAdBinding.adBody.setVisibility(getAssetViewVisibility(nativeAd.getBody()));
  nativeAdBinding.adCallToAction.setVisibility(getAssetViewVisibility(nativeAd.getCallToAction()));
  nativeAdBinding.adHeadline.setVisibility(getAssetViewVisibility(nativeAd.getHeadline()));
  nativeAdBinding.adAppIcon.setVisibility(getAssetViewVisibility(nativeAd.getIcon()));
  nativeAdBinding.adPrice.setVisibility(getAssetViewVisibility(nativeAd.getPrice()));
  nativeAdBinding.adStars.setVisibility(getAssetViewVisibility(nativeAd.getStarRating()));
  nativeAdBinding.adStore.setVisibility(getAssetViewVisibility(nativeAd.getStore()));

  // Inform Google Mobile Ads SDK (beta) that you have finished populating
  // the native ad views with this native ad.
  nativeAdView.registerNativeAd(nativeAd, nativeAdBinding.adMedia);
}

/**
* Determines the visibility of an asset view based on the presence of its asset.
*
* @param asset The native ad asset to check for nullability.
* @return {@link View#VISIBLE} if the asset is not null, {@link View#INVISIBLE} otherwise.
*/
private int getAssetViewVisibility(Object asset) {
    return (asset == null) ? View.INVISIBLE : View.VISIBLE;
}

AdChoices overlay

An AdChoices overlay is added as an ad view by the SDK when a backfill ad is returned. If your app uses native ads backfill, leave space in your preferred corner of your native ad view for the automatically inserted AdChoices logo. Also, it's important that the AdChoices overlay is seen, so choose background colors and images appropriately. For more information on the overlay's appearance and function, refer to the programmatic native ads implementation guidelines.

Ad attribution for programmatic native ads

When displaying programmatic native ads, you must display an ad attribution to denote that the view is an advertisement. Learn more in our policy guidelines.

Handle clicks

Don't implement any custom click handlers on any views over or within the native ad view. Clicks on the ad view assets are handled by the SDK as long as you correctly populate and register the asset views.

To listen for clicks, implement Google Mobile Ads SDK (beta) click callback:

Kotlin

private fun setEventCallback(nativeAd: NativeAd) {
  nativeAd.adEventCallback =
    object : NativeAdEventCallback {
      override fun onAdClicked() {
        Log.d(Constant.TAG, "Native ad recorded a click.")
      }
    }
}

Java

private void setEventCallback(NativeAd nativeAd) {
  nativeAd.setAdEventCallback(new NativeAdEventCallback() {
      @Override
      public void onAdClicked() {
        Log.d(Constant.TAG, "Native ad recorded a click.");
      }
  });
}

ImageScaleType

The MediaView class has an ImageScaleType property when displaying images. If you want to change how an image is scaled in the MediaView, set the corresponding ImageView.ScaleType using the setImageScaleType() method of the MediaView:

Kotlin

nativeAdViewBinding.mediaView.imageScaleType = ImageView.ScaleType.CENTER_CROP

Java

nativeAdViewBinding.mediaView.setImageScaleType(ImageView.ScaleType.CENTER_CROP);

MediaContent

The MediaContent class holds the data related to the media content of the native ad, which is displayed using the MediaView class. When the MediaView mediaContent property is set with a MediaContent instance:

If a video asset is available, it's buffered and starts playing inside the MediaView. You can tell if a video asset is available by checking hasVideoContent().
If the ad does not contain a video asset, the mainImage asset is downloaded and placed inside the MediaView instead.

Destroy an ad

After you show a native ad, destroy the ad. The following example destroys a native ad:

Kotlin

nativeAd.destroy()

Java

nativeAd.destroy();

Test native ad code

Direct-sold ads

If you'd like to test out what direct-sold native ads are like, you can make use of this Ad Manager ad unit ID:

/21775744923/example/native

It's configured to serve sample app install and content ads, as well as a custom native ad format with the following assets:

Headline (text)
MainImage (image)
Caption (text)

The template ID for the custom native ad format is 10063170.

Native backfill ads

Ad Exchange backfill is limited to a select group of publishers. To test the behavior of native backfill ads, use this Ad Manager ad unit:

/21775744923/example/native-backfill

It serves sample app install and content ads that include the AdChoices overlay.

Remember to update your code to refer to your actual ad unit and template IDs before going live.

Next steps

Explore the following topics:

User privacy

Example

Download and run the example app that demonstrates the use of the Google Mobile Ads SDK (beta).

Native ads Stay organized with collections Save and categorize content based on your preferences.

AI-generated Key Takeaways

Define the NativeAdView class

XML Layout

Jetpack Compose

Handle the loaded native ad

Kotlin

Java

Display the native ad

Kotlin

Java

AdChoices overlay

Ad attribution for programmatic native ads

Handle clicks

Kotlin

Java

ImageScaleType

Kotlin

Java

MediaContent

Destroy an ad

Kotlin

Java

Test native ad code

Direct-sold ads

Native backfill ads

Next steps

Example

Native ads

Define the `NativeAdView` class