原生高级广告单元

Display a NativeAd

When a native ad loads, the Google Mobile Ads SDK 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.

Key Point: Learn more about native ads in our Native Ads Playbook. Also, review the Native ads policies and guidelines for guidance on how to render your native ads.

NativeAdView class

For the NativeAd format, there is the corresponding NativeAdView class. This class is a ViewGroup that publishers should use as the root for the NativeAd. A single NativeAdView corresponds to a single native ad. Each view used to display that ad's assets (the ImageView that displays the screenshot asset, for instance) should be a child of the NativeAdView object.

The view hierarchy for a native ad that uses a LinearLayout to display its asset views might look like this:

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


         // Other assets such as image or media view, call to action, etc follow.
         ...
    </LinearLayout>
</com.google.android.gms.ads.nativead.NativeAdView>

Here is an example that creates a NativeAdView and populates it with a NativeAd:

Java

AdLoader.Builder builder = new AdLoader.Builder(this, "<your ad unit ID>")
    .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 text, images and the native ad, etc into the ad
            // view.
            populateNativeAdView(nativeAd, adView);
            frameLayout.removeAllViews();
            frameLayout.addView(adView);
        }
});

Kotlin

val builder = AdLoader.Builder(this, "<your ad unit ID>")
    .forNativeAd { nativeAd ->
        // 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 text, images and the native ad, etc into the ad
        // view.
        populateNativeAdView(nativeAd, adView)
        // Assumes you have a placeholder FrameLayout in your View layout
        // (with id ad_frame) where the ad is to be placed.
        ad_frame.removeAllViews()
        ad_frame.addView(adView)
    }

Key Point: Note that all assets for a given native ad should be rendered inside the NativeAdView layout. The Google Mobile Ads SDK 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

AdChoices overlay

An AdChoices overlay is added to each ad view by the SDK. 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 be easily seen, so choose background colors and images appropriately. For more information on the overlay's appearance and function, see Native ads advanced field descriptions.

Ad attribution

You must display an ad attribution to denote that the view is an advertisement. Learn more in our policy guidelines.

Code example

These are the steps for displaying a native ad:

1. Create an instance of the NativeAdView class.
2. For each ad asset to be displayed:
   1. Populate the asset view with the asset in the ad object.
   2. Register the asset view with the ViewGroup class.
3. Register the MediaView if your native ad layout includes a large media asset.
4. Register the ad object with the ViewGroup class.

Here is an example function that displays a 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.my_ad_layout, 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 above 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.my_ad_layout, 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 above 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)
}

Let's take a look at the individual tasks:

Inflate the layout

Java

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

Kotlin

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

In this example, we're inflating an XML layout that contains views for displaying a native ad and then locating a reference to the NativeAdView. Note that you could also reuse an existing NativeAdView if there's one in your fragment or activity, or even create an instance dynamically without using a layout file.

Populate and register the asset views

This sample code locates the view used to display the headline, sets its text using the string asset provided by the ad object, and registers it with the NativeAdView object:

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

This process of locating the view, setting its value, and registering it with the ad view class should be repeated for each of the assets provided by the native ad object that the app will display.

Click handling

Key Point: Do not implement any custom click handlers on any views over or within the native ad view. To observe click events yourself, use the ad listener.

Clicks on the ad view assets are handled by the SDK as long as you correctly populate and register the asset views, as discussed in the previous section.

Here is an example that uses an ad listener to observe click events:

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, altering the UI, and so on.
        }
        @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 by logging, altering the UI, and so on.
        }
    })
    .build()

Register the MediaView

Key Point: You are required to use the MediaView asset instead of the ImageView asset if you want to include a main image asset in the layout for your native ad.

The MediaView is a special View designed to display the main media asset, either video or image.

MediaView can be defined in an XML layout or constructed dynamically. It should be placed within the view hierarchy of a NativeAdView, just like any other asset view. Apps using a MediaView must register it with the NativeAdView like this:

Java

MediaView mediaView = adView.findViewById(R.id.ad_media);
adView.setMediaView(mediaView);

Kotlin

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

As with all asset views, the media view needs to have its content populated. This is done using the getMediaContent() method to retrieve media content that can be passed to a MediaView. Here is a code snippet setting the media content for the media view:

Java

mediaView.setMediaContent(nativeAd.getMediaContent());

Kotlin

mediaView.mediaContent = nativeAd.mediaContent

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

For example, to fill the MediaView when an image is displayed (ad has no video):

Java

mediaView.setImageScaleType(ImageView.ScaleType.CENTER_CROP);

Kotlin

mediaView.imageScaleType = ImageView.ScaleType.CENTER_CROP

GitHub Sample

Our GitHub repository has the complete implementations for Native Advanced ads written in both Java and Kotlin.

Download Native Advanced Example

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.

Note: By default, mainImage is the first downloaded image asset. If setReturnUrlsForImageAssets(true) is used, mainImage is null and you must set the mainImage property to your manually downloaded image. Note that this image will be used only when there is no video asset available.

Register the native ad object

This final step registers the native ad object with the view that's responsible for displaying it:

Java

adView.setNativeAd(ad);

Kotlin

adView.setNativeAd(ad)

Destroy ad

When you are done showing your native ad, you should destroy it so that the ad is properly garbage collected.

Java

nativeAd.destroy();

Kotlin

nativeAd.destroy()