This page provides a comparison of native ad implementations between
Google Mobile Ads SDK (Legacy) and GMA Next-Gen SDK.

## Load an ad

The following table compares key implementation when loading a native ad:

| Implementation Goal | Google Mobile Ads SDK (Legacy) | GMA Next-Gen SDK |
|---|---|---|
| Specify native ad types | Through unique methods on `AdLoader`. | Within the ad request. |
| Handle ad load success callback | Each native ad type has a separate callback. | A single interface `NativeAdLoaderCallback` handles ad load success for all native ad types. |
| Handle ad load failure callback | In a separate listener. | Within `NativeAdLoaderCallback`. |

### Load a native ad

The following examples load a native ad:

|---|---|
| Google Mobile Ads SDK (Legacy) | ### Kotlin ```kotlin val adLoader = AdLoader.Builder(this, AD_UNIT_ID) .forNativeAd(object : NativeAd.OnNativeAdLoadedListener { override fun onNativeAdLoaded(nativeAd: NativeAd) { // Native ad loaded. } }) .withAdListener( object : AdListener() { override fun onAdFailedToLoad(loadAdError: LoadAdError) { // Native ad failed to load. } } ) .build() adLoader.loadAd(AdRequest.Builder().build()) ``` ### Java ```java AdLoader adLoader = new AdLoader.Builder(this, AD_UNIT_ID) .forNativeAd(new NativeAd.OnNativeAdLoadedListener() { @Override public void onNativeAdLoaded(NativeAd nativeAd) { // Native ad loaded. } }) .withAdListener(new AdListener() { @Override public void onAdFailedToLoad(@NonNull LoadAdError loadAdError) { // Native ad failed to load. } }) .build(); adLoader.loadAd(new AdRequest.Builder().build()); ``` |
| GMA Next-Gen SDK | ### Kotlin ```kotlin NativeAdLoader.load( NativeAdRequest.Builder(AD_UNIT_ID, listOf(NativeAd.NativeAdType.NATIVE)).build(), object : NativeAdLoaderCallback { override fun onNativeAdLoaded(nativeAd: NativeAd) { // Native ad loaded. } override fun onAdFailedToLoad(adError: LoadAdError) { // Native ad failed to load. } } ) ``` ### Java ```java NativeAdLoader.load( new NativeAdRequest.Builder(AD_UNIT_ID, List.of(NativeAd.NativeAdType.NATIVE)).build(), new NativeAdLoaderCallback() { @Override public void onNativeAdLoaded(NativeAd nativeAd) { // Native ad loaded. } @Override public void onAdFailedToLoad(LoadAdError adError) { // Native ad failed to load. } } ); ``` |

### Load a custom native ad

The following examples load a custom native ad:

|---|---|
| Google Mobile Ads SDK (Legacy) | ### Kotlin ```kotlin val adLoader = AdLoader.Builder(this, AD_UNIT_ID) .forCustomFormatAd(CUSTOM_FORMAT_ID, object: NativeCustomFormatAd.OnCustomFormatAdLoadedListener { override fun onCustomFormatAdLoaded(nativeCustomFormatAd: NativeCustomFormatAd) { // Custom native ad loaded. } }, object: NativeCustomFormatAd.OnCustomClickListener { override fun onCustomClick( nativeCustomFormatAd: NativeCustomFormatAd, assetName: String ) { // Custom native ad recorded a click. } }) .withAdListener( object : AdListener() { override fun onAdFailedToLoad(loadAdError: LoadAdError) { // Custom native ad failed to load. } } ) .build() adLoader.loadAd(AdRequest.Builder().build()) ``` ### Java ```java AdLoader adLoader = new AdLoader.Builder(this, AD_UNIT_ID) .forCustomFormatAd(CUSTOM_FORMAT_ID, new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() { @Override public void onCustomFormatAdLoaded(NativeCustomFormatAd nativeCustomFormatAd) { // Custom native ad loaded. } }, new NativeCustomFormatAd.OnCustomClickListener() { @Override public void onCustomClick(NativeCustomFormatAd nativeCustomFormatAd, String assetName) { // Custom native ad recorded a click. } }) .withAdListener(new AdListener() { @Override public void onAdFailedToLoad(@NonNull LoadAdError loadAdError) { // Custom native ad failed to load. } }) .build(); adLoader.loadAd(new AdRequest.Builder().build()); ``` |
| GMA Next-Gen SDK | ### Kotlin ```kotlin NativeAdLoader.load( NativeAdRequest .Builder(AD_UNIT_ID, listOf(NativeAd.NativeAdType.CUSTOM_NATIVE)) .setCustomFormatIds(listOf(CUSTOM_FORMAT_ID)) .build(), object : NativeAdLoaderCallback { override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) { // Custom native ad loaded. } override fun onAdFailedToLoad(adError: LoadAdError) { // Custom native ad failed to load. } } ) ``` ### Java ```java NativeAdLoader.load( new NativeAdRequest.Builder(AD_UNIT_ID, List.of(NativeAdType.CUSTOM_NATIVE)) .setCustomFormatIds(List.of(CUSTOM_FORMAT_ID)) .build(), new NativeAdLoaderCallback() { @Override public void onCustomNativeAdLoaded(CustomNativeAd customNativeAd) { // Custom native ad loaded. } @Override public void onAdFailedToLoad(LoadAdError adError) { // Custom native ad failed to load. } } ); ``` |

## Set the native ad options

The following examples set the native ad options:

|---|---|
| Google Mobile Ads SDK (Legacy) | In Google Mobile Ads SDK (Legacy), set the native ad options on `AdLoader.Builder`. ### Kotlin ```kotlin val videoOptions = VideoOptions.Builder().setStartMuted(true).build() val adLoader = AdLoader.Builder(this, AD_UNIT_ID) .withNativeAdOptions(NativeAdOptions.Builder().setVideoOptions(videoOptions).build()) .build() ``` ### Java ```java VideoOptions videoOptions = new VideoOptions.Builder() .setStartMuted(true) .build(); AdLoader adLoader = new AdLoader.Builder(this, AD_UNIT_ID) .withNativeAdOptions(new NativeAdOptions.Builder() .setVideoOptions(videoOptions) .build()) .build(); ``` |
| GMA Next-Gen SDK | In GMA Next-Gen SDK, set the native ad options on `NativeAdRequest.Builder`. ### Kotlin ```kotlin val videoOptions = VideoOptions.Builder().setStartMuted(true).build() val nativeAdRequest = NativeAdRequest .Builder(AD_UNIT_ID, listOf(NativeAd.NativeAdType.NATIVE)) .setVideoOptions(videoOptions) .build() ``` ### Java ```java VideoOptions videoOptions = new VideoOptions.Builder().setStartMuted(true).build(); NativeAdRequest nativeAdRequest = new NativeAdRequest .Builder(AD_UNIT_ID, List.of(NativeAd.NativeAdType.NATIVE)) .setVideoOptions(videoOptions) .build(); ``` |

## Set native ad event callbacks

The following examples set the native ad event callbacks:

|---|---|
| Google Mobile Ads SDK (Legacy) | Native ad event callbacks must be registered prior to loading the ad. ### Kotlin ```kotlin val adLoader = AdLoader.Builder(this, AD_UNIT_ID) .forNativeAd(object : NativeAd.OnNativeAdLoadedListener { override fun onNativeAdLoaded(nativeAd: NativeAd) { // Native ad loaded. } }) .withAdListener( object : AdListener() { override fun onAdOpened() { // Native ad opened an overlay that covered the screen. } override fun onAdClosed() { // Native ad closed. } override fun onAdImpression() { // Native ad recorded an impression. } override fun onAdClicked() { // Native ad recorded a click. } } ) .build() adLoader.loadAd(AdRequest.Builder().build()) ``` ### Java ```java AdLoader adLoader = new AdLoader.Builder(this, AD_UNIT_ID) .forNativeAd(new NativeAd.OnNativeAdLoadedListener() { @Override public void onNativeAdLoaded(NativeAd nativeAd) { // Native ad loaded. } }) .withAdListener(new AdListener() { @Override public void onAdOpened() { // Native ad opened an overlay that covered the screen. } @Override public void onAdClosed() { // Native ad closed. } @Override public void onAdImpression() { // Native ad recorded an impression. } @Override public void onAdClicked() { // Native ad recorded a click. } }) .build(); adLoader.loadAd(new AdRequest.Builder().build()); ``` |
| GMA Next-Gen SDK | GMA Next-Gen SDK supports registering ad event callbacks once the native ad is loaded. ### Kotlin ```kotlin NativeAdLoader.load( NativeAdRequest .Builder(AD_UNIT_ID, listOf(NativeAd.NativeAdType.NATIVE)) .build(), object : NativeAdLoaderCallback { override fun onNativeAdLoaded(nativeAd: NativeAd) { // Native ad loaded. nativeAd.adEventCallback = object : NativeAdEventCallback { override fun onAdShowedFullScreenContent() { // Native ad showed full screen content. // Google Mobile Ads SDK (Legacy) equivalent: onAdOpened() } override fun onAdDismissedFullScreenContent() { // Native ad dismissed full screen content. // Google Mobile Ads SDK (Legacy) equivalent: onAdClosed() } override fun onAdFailedToShowFullScreenContent( fullScreenContentError: FullScreenContentError ) { // Native ad failed to show full screen content. // Google Mobile Ads SDK (Legacy) equivalent: N/A } override fun onAdImpression() { // Native ad recorded an impression. } override fun onAdClicked() { // Native ad recorded a click. } } } } ) ``` ### Java ```java NativeAdLoader.load( new NativeAdRequest.Builder(AD_UNIT_ID, List.of(NativeAd.NativeAdType.NATIVE)) .build(), new NativeAdLoaderCallback() { @Override public void onNativeAdLoaded(NativeAd nativeAd) { // Native ad loaded. nativeAd.setAdEventCallback(new NativeAdEventCallback() { @Override public void onAdShowedFullScreenContent() { // Native ad showed full screen content. // Google Mobile Ads SDK (Legacy) equivalent: onAdOpened() } @Override public void onAdDismissedFullScreenContent() { // Native ad dismissed full screen content. // Google Mobile Ads SDK (Legacy) equivalent: onAdClosed() } @Override public void onAdFailedToShowFullScreenContent(FullScreenContentError fullScreenContentError) { // Native ad failed to show full screen content. // Google Mobile Ads SDK (Legacy) equivalent: N/A } @Override public void onAdImpression() { // Native ad recorded an impression. } @Override public void onAdClicked() { // Native ad recorded a click. } }); } } ); ``` |

## Show an ad

This section covers the differences in showing a native ad:

### Use a GMA Next-Gen SDK package name

When creating a `NativeAdView` in XML, update the package name:

|---|---|
| Google Mobile Ads SDK (Legacy) | ```xml <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"> <!-- Layout assets such as the media view and call to action. --> </com.google.android.gms.ads.nativead.NativeAdView> ``` |
| GMA Next-Gen SDK | ```xml <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"> <!-- Layout assets such as the media view and call to action. --> </com.google.android.libraries.ads.mobile.sdk.nativead.NativeAdView> ``` |

### Register the media content asset with `NativeAdView`

The following examples register the media content asset with `NativeAdView`:

|---|---|
| Google Mobile Ads SDK (Legacy) | Google Mobile Ads SDK (Legacy) expects that the media view is registered with the native ad view prior to registering the native ad. However, the API does not enforce this behavior. ### Kotlin ```kotlin private fun displayNativeAd(nativeAd: NativeAd) { // Inflate the NativeAdView layout. val nativeAdBinding = NativeAdBinding.inflate(layoutInflater) // Add the NativeAdView to the view hierarchy. binding.nativeViewContainer.addView(nativeAdBinding.root) val nativeAdView = nativeAdBinding.root // Populate and register the asset views. nativeAdView.mediaView = nativeAdBinding.adMedia // ... // Register the native ad with the NativeAdView. nativeAdView.setNativeAd(nativeAd) } ``` ### Java ```java private void displayNativeAd(NativeAd nativeAd) { // Inflate the NativeAdView layout NativeAdBinding nativeAdBinding = NativeAdBinding.inflate(getLayoutInflater()); // Add the NativeAdView to the view hierarchy binding.nativeViewContainer.addView(nativeAdBinding.getRoot()); NativeAdView nativeAdView = nativeAdBinding.getRoot(); // Populate and register the asset views nativeAdView.setMediaView(nativeAdBinding.adMedia); // ... // Register the native ad with the NativeAdView nativeAdView.setNativeAd(nativeAd); } ``` |
| GMA Next-Gen SDK | GMA Next-Gen SDK enforces registration of the media view with the native ad view at the same time as the native ad. ### Kotlin ```kotlin private fun displayNativeAd(nativeAd: NativeAd) { // Inflate the NativeAdView layout. val nativeAdBinding = NativeAdBinding.inflate(layoutInflater) // Add the NativeAdView to the view hierarchy. binding.nativeViewContainer.addView(nativeAdBinding.root) val nativeAdView = nativeAdBinding.root // Populate and register the asset views. // ... // Register the native ad and media content asset with the NativeAdView. val mediaView = nativeAdBinding.adMedia nativeAdView.registerNativeAd(nativeAd, mediaView) } ``` ### Java ```java private void displayNativeAd(NativeAd nativeAd) { // Inflate the NativeAdView layout. NativeAdBinding nativeAdBinding = NativeAdBinding.inflate(getLayoutInflater()); // Add the NativeAdView to the view hierarchy. binding.nativeViewContainer.addView(nativeAdBinding.getRoot()); NativeAdView nativeAdView = nativeAdBinding.getRoot(); // Populate and register the asset views. // ... // Register the native ad and media content asset with the NativeAdView. MediaView mediaView = nativeAdBinding.adMedia; nativeAdView.registerNativeAd(nativeAd, mediaView); } ``` |