Native

The native ads are a kind of ad that can be shown using the same visual style like the rest of the app, which allows a natural and non-intrusive integration with the user interface.

Unlike the other formats, the app provides the layout and the SDK fills it with the assets of the ad, no matter which demand source has filled it.

Ad layout

The first step is to create the layout that will be used to display the ads. It is a regular layout file, where each view that will show an asset of the ad needs an identifier:

<LinearLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical">

    <TextView
        android:id="@+id/ad_headline"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    <FrameLayout
        android:id="@+id/ad_media"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:minHeight="120dp" />

    <Button
        android:id="@+id/ad_call_to_action"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content" />
</LinearLayout>

Caution

The view that shows the media content must be at least 120x120dp. Smaller sizes make the ad ineligible for video demand, which reduces the revenue of the ad unit.

Once the layout is ready, a NativeAdViewBinder instance connects it with the SDK. Only the layoutId is required, so you can bind just the assets that your layout displays:

Kotlin

val binder = NativeAdViewBinder.Builder(R.layout.native_ad)
    .setAdvertiserTextViewId(R.id.ad_advertiser)
    .setBodyTextViewId(R.id.ad_body)
    .setCallToActionButtonId(R.id.ad_call_to_action)
    .setHeadlineTextViewId(R.id.ad_headline)
    .setIconImageViewId(R.id.ad_app_icon)
    .setMediaContentViewId(R.id.ad_media)
    .setPriceTextViewId(R.id.ad_price)
    .setRatingContentViewId(R.id.ad_rating)
    .setStoreTextViewId(R.id.ad_store)
    .build()

Java

NativeAdViewBinder binder = new NativeAdViewBinder.Builder(R.layout.native_ad)
    .setAdvertiserTextViewId(R.id.ad_advertiser)
    .setBodyTextViewId(R.id.ad_body)
    .setCallToActionButtonId(R.id.ad_call_to_action)
    .setHeadlineTextViewId(R.id.ad_headline)
    .setIconImageViewId(R.id.ad_app_icon)
    .setMediaContentViewId(R.id.ad_media)
    .setPriceTextViewId(R.id.ad_price)
    .setRatingContentViewId(R.id.ad_rating)
    .setStoreTextViewId(R.id.ad_store)
    .build();

The builder accepts the following assets:

Method	Required	Description
setAdChoicesContentViewId(int)	No	Container for the AdChoices icon
setAdvertiserTextViewId(int)	No	Name of the advertiser
setBodyTextViewId(int)	No	Description of the ad
setCallToActionButtonId(int)	No	Button that invites the user to interact with the ad
setHeadlineTextViewId(int)	No	Headline of the ad
setIconImageViewId(int)	No	Icon of the ad
setMediaContentViewId(int)	No	Container for the media content (image or video)
setOptionsContentViewId(int)	No	Container for the options view of the ad
setPriceTextViewId(int)	No	Price of the promoted product
setRatingContentViewId(int)	No	Container for the rating of the promoted product
setStoreTextViewId(int)	No	Store of the promoted product

Integration

To request a native ad, you need to make an integration by code as shown in the example below:

Kotlin

class MainActivity : Activity() {

    private var nativeAd: NativeAd? = null

    private var nativeAdLoader: NativeAdLoader? = null

    // The binder created in the previous section
    private val binder = NativeAdViewBinder.Builder(R.layout.native_ad)
        .setCallToActionButtonId(R.id.ad_call_to_action)
        .setHeadlineTextViewId(R.id.ad_headline)
        .setMediaContentViewId(R.id.ad_media)
        .build()

    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        nativeAdLoader = NativeAdLoader(
                         this, "Wortise Ad Unit ID", nativeListener).also {
            it.loadAd()
        }
    }

    override fun onDestroy() {
        ...
        nativeAd?.destroy()
        nativeAdLoader?.destroy()
    }

    private val nativeListener = object : NativeAdLoader.Listener {

        override fun onNativeClicked(ad: NativeAd) {
            // Invoked when the ad has been clicked
        }

        override fun onNativeFailedToLoad(error: AdError) {
            // Invoked when the ad could not be loaded
            // (because of an error or no fill)
        }

        override fun onNativeImpression(ad: NativeAd) {
            // Invoked when the ad has generated an impression
        }

        override fun onNativeLoaded(ad: NativeAd) {
            // Invoked when the ad has been loaded
            nativeAd?.destroy()
            nativeAd = ad

            val adView = NativeAdView(this@MainActivity, binder)

            // For example, we add the NativeAdView into a FrameLayout
            val frameLayout = findViewById<FrameLayout>(R.id.frame)
            frameLayout.removeAllViews()
            frameLayout.addView(adView)

            nativeAdLoader?.renderAd(adView, ad)
        }

        override fun onNativeRevenuePaid(ad: NativeAd, data: RevenueData) {
            // Invoked when the ad has generated revenue
        }
    }
}

Java

public class MainActivity extends Activity {

    private NativeAd mNativeAd;

    private NativeAdLoader mNativeAdLoader;

    // The binder created in the previous section
    private final NativeAdViewBinder binder =
            new NativeAdViewBinder.Builder(R.layout.native_ad)
                    .setCallToActionButtonId(R.id.ad_call_to_action)
                    .setHeadlineTextViewId(R.id.ad_headline)
                    .setMediaContentViewId(R.id.ad_media)
                    .build();

    @Override
    public void onCreate(Bundle savedInstanceState) {
        ...
        mNativeAdLoader = new NativeAdLoader(
                this, "Wortise Ad Unit ID", mNativeListener);
        mNativeAdLoader.loadAd();
    }

    @Override
    public void onDestroy() {
        ...
        if (mNativeAd != null) {
            mNativeAd.destroy();
        }

        mNativeAdLoader.destroy();
    }

    private final NativeAdLoader.Listener mNativeListener =
            new NativeAdLoader.Listener() {

        @Override
        public void onNativeClicked(@NonNull NativeAd ad) {
            // Invoked when the ad has been clicked
        }

        @Override
        public void onNativeFailedToLoad(@NonNull AdError error) {
            // Invoked when the ad could not be loaded
            // (because of an error or no fill)
        }

        @Override
        public void onNativeImpression(@NonNull NativeAd ad) {
            // Invoked when the ad has generated an impression
        }

        @Override
        public void onNativeLoaded(@NonNull NativeAd ad) {
            // Invoked when the ad has been loaded
            if (mNativeAd != null) {
                mNativeAd.destroy();
            }

            mNativeAd = ad;

            NativeAdView adView = new NativeAdView(MainActivity.this, binder);

            // For example, we add the NativeAdView into a FrameLayout
            FrameLayout frameLayout = findViewById(R.id.frame);
            frameLayout.removeAllViews();
            frameLayout.addView(adView);

            mNativeAdLoader.renderAd(adView, ad);
        }

        @Override
        public void onNativeRevenuePaid(@NonNull NativeAd ad,
                                        @NonNull RevenueData data) {
            // Invoked when the ad has generated revenue
        }
    };
}

The renderAd method fills the views of the layout with the assets of the ad and registers them to track the clicks and the impressions. It returns false when the ad could not be rendered.

Caution

Both the ad and the loader must be destroyed when they are no longer needed, as shown in the example above. Reusing a NativeAdView for a new ad is supported: just call renderAd again with the new ad.

Ad assets

The NativeAd class exposes the assets of the ad, which can be used to customise the layout before rendering it:

Property	Type	Description
advertiser	String?	Name of the advertiser
body	String?	Description of the ad
callToAction	String?	Text of the call to action
headline	String?	Headline of the ad
icon	Image?	Icon of the ad
images	List<Image>	Images of the ad
mediaContent	MediaContent?	Media content of the ad (image or video)
price	String?	Price of the promoted product
rating	Double?	Rating of the promoted product
store	String?	Store of the promoted product

Request parameters

The loadAd method also accepts a RequestParameters instance, in the same way as the rest of the formats:

Kotlin

nativeAdLoader?.loadAd(RequestParameters(agent = "your agent"))

Java

RequestParameters parameters = new RequestParameters();
parameters.setAgent("your agent");

mNativeAdLoader.loadAd(parameters);

Migration from GoogleNativeAd

If your app already integrated the deprecated GoogleNativeAd class, these are the equivalences with the new integration:

Deprecated	Replacement
GoogleNativeAd(context, adUnitId, listener)	NativeAdLoader(context, adUnitId, listener)
GoogleNativeAd.Listener	NativeAdLoader.Listener
load()	loadAd() (or loadAd(parameters))
onNativeLoaded(ad, nativeAd)	onNativeLoaded(ad) — a NativeAd, no Google type
onNativeFailedToLoad(ad, error)	onNativeFailedToLoad(error)
withNativeAdOptions(options)	removed — the SDK configures the request
Your own Google NativeAdView and asset wiring	NativeAdViewBinder + NativeAdView + renderAd

In practice, the changes are:

1. Drop the Google types. There is no com.google.android.gms.ads.nativead.NativeAd in the callbacks anymore, so the app no longer imports the Google Mobile Ads classes for native ads.
2. Describe the layout once. Instead of finding every view and assigning it to Google’s NativeAdView, declare the identifiers in a NativeAdViewBinder as explained in the Ad layout section.
3. Render through the loader. Where the app used to configure Google’s NativeAdView and assign the ad to it, now it creates a NativeAdView with the binder and calls renderAd.

Before

Kotlin

override fun onNativeLoaded(ad: GoogleNativeAd, nativeAd: NativeAd) {
    val adView = // your Google NativeAdView

    adView.headlineView     = adView.findViewById(R.id.ad_headline)
    adView.callToActionView = adView.findViewById(R.id.ad_call_to_action)
    adView.mediaView        = adView.findViewById(R.id.ad_media)
    // ... one line per asset ...

    adView.setNativeAd(nativeAd)
}

After

Kotlin

override fun onNativeLoaded(ad: NativeAd) {
    val adView = NativeAdView(context, binder)

    nativeAdLoader?.renderAd(adView, ad)
}

Legacy integration

Caution

The GoogleNativeAd class is deprecated since version 1.8.0. It is still available for the apps that already integrated it, but it only supports Google’s demand and it will be removed in a future version. New integrations must use the NativeAdLoader class described above.

Apps that still use GoogleNativeAd receive Google’s NativeAd instance in the onNativeLoaded callback, and are responsible for building the NativeAdView and registering every asset, as described in Google’s documentation.