SDK Migration

This page covers migrations for current and previous versions.

Migrate from v22 to v23

The minimum Android API level is 21

Starting in version 23.0.0, the Google Mobile Ads SDK requires all apps to be on a minimum Android API level 21 to run. To adjust the API level, change the value of minSdkVersion in your app-level build.gradle file to 21 or higher.

AdManagerAdRequest.Builder methods inherited from superclass can be chained

In version 23.0.0, AdManagerAdRequest.Builder methods inherited from its parent can be chained together to build an AdManagerAdRequest using a single call:

AdManagerAdRequest request = new AdManagerAdRequest.Builder()
    .addCustomTargeting("age", "25") // AdManagerAdRequest.Builder method.
    .setContentUrl("https://www.example.com") // Method inherited from parent.
    .build(); // Builds an AdManagerAdRequest.

var request = AdManagerAdRequest.Builder()
  .addCustomTargeting("age", "25") // AdManagerAdRequest.Builder method.
  .setContentUrl("https://www.example.com") // Method inherited from parent.
  .build() // Builds an AdManagerAdRequest.

Deprecated Methods Removed/Replaced

Migrate from v21 to v22

Use MobileAds.getVersion() to get the Google Mobile Ads SDK version

The MobileAds.getVersionString() method is removed in version 22.0.0 in favor of MobileAds.getVersion().

The new method returns the expected external version number—for example, 22.0.0. For more information about this change, see Use the new Google Mobile Ads SDK getVersion() method.

Removal of deprecated NativeCustomFormatAd.getVideoMediaView()

In version 21, the Google Mobile Ads SDK provided you the NativeCustomFormatAd.getVideoMediaView() method to get the media asset for a native custom ad format.

Starting in version 22, you create your own MediaView and set its media content, and use MediaContent.getVideoController() to get the video controls.

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
    // Assumes you have a FrameLayout in your view hierarchy with the id media_placeholder.
    FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

    MediaContent mediaContent = ad.getMediaContent();
    if (mediaContent != null && mediaContent.hasVideoContent()) {
        // Create a MediaView and set its media content.
        MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
        mediaView.setMediaContent(mediaContent);
        mediaPlaceholder.addView(mediaView);
    }
}

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
    // Assumes you have a FrameLayout in your view hierarchy with the id media_placeholder.
    FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

    VideoController videoController = ad.getVideoController();
    if (videoController.hasVideoContent()) {
        // Add the media view provided by the native ad.
        mediaPlaceholder.addView(ad.getVideoMediaView());
    }
}

See the custom native ad guide for more information.

Removed or replaced methods

The table below lists the specific changes in version 22.0.0.

Migrate from v20 to v21

Update minSdkVersion to 19 or higher

Starting from version 21.0.0, the Google Mobile Ads SDK requires all apps to be on a minimum Android API level 19 to run. To adjust the API level, change the value of minSdkVersion in your app's build file to 19 or higher.

Enforce strict nullability

In preparation for enforcing strict nullability, @NonNull annotations are added in all the APIs that previously did not explicitly define nullability.

This change may break the Kotlin apps and apps that use Java null checking frameworks if there are null safety violations and did not previously handle null values in a safe way (see the Kotlin documentation on Null-safety ).

Removal of addNetworkExtras() method

The addNetworkExtras() method that passes extra parameters as a NetworkExtras instance to a specific ad network adapter was deprecated in SDK version 20.3.0, and will be removed in version 21.0.0. Use the addNetworkExtrasBundle() method from the same AdRequest.Builder class instead.

Removal of location methods

The following location methods will be removed in version 21.0.0:

• The setLocation(Location location) method in the AdRequest.Builder class that sets the user's location for mediation targeting purposes.
• The getLocation() method in the AdRequest class that returns the user's location targeting information previously passed to the setLocation(Location location) method.
• The getLocation() method in the MediationAdConfiguration class that returns the location of the user, if defined by the AdRequest.

The location data is not used by Google to target ads. You should use third-party APIs to provide the information to third-party ad networks if required.

Custom event interfaces deprecation

Custom events enable publishers using mediation to set up a waterfall ad source that isn't one of Ad Manager's supported ad sources.

All the custom event interfaces are deprecated in favor of the Adapter class and MediationAdLoadCallback interface.

The table below lists the corresponding class or interface that should be used for each custom event interface starting from version 21.0.0:

Migrate from v19 to v20

There are many breaking changes in version 20.0.0. Version 19.7.0 introduced many new APIs, and deprecated or renamed many classes in preparation for version 20.0.0. This guide highlights the major changes in version 20.0.0.

Full-screen format API updates

Starting with version 20.0.0, interstitial, rewarded, rewarded interstitial, and App Open ad formats are standardized to follow a consistent API design.

All full-screen format APIs utilize the following principles:

• A static load method
• A similar load callback or handler mechanism
• Reliance on the FullScreenContentCallback class for presentation callbacks

Legacy RewardedVideoAd API removal

The newer RewardedAd API was first introduced back in March 2019 and has been the preferred rewarded API for over 18 months. It has had more enhancements compared to the legacy RewardedVideoAd API, including the ability to load more than one rewarded ad at a time.

The legacy RewardedVideoAd API is removed in SDK version 20.0.0.

Smart banner deprecation in favor of adaptive banner

Smart banner ads are deprecated in favor of adaptive banner ads. Adaptive banners provide superior performance and more flexibility in setting ad width. If you prefer to continue using full-width banners, that can still be done using adaptive banner, as shown in the following code snippet:

public class MyActivity extends AppCompatActivity {
  ...
  private AdSize getFullWidthAdaptiveSize() {
    Display display = getWindowManager().getDefaultDisplay();
    DisplayMetrics outMetrics = new DisplayMetrics();
    display.getMetrics(outMetrics);

    float widthPixels = outMetrics.widthPixels;
    float density = outMetrics.density;

    int adWidth = (int) (widthPixels / density);
    return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth);
  }
}

class MyActivity : AppCompatActivity() {
  ...
  private val adaptiveAdSize: AdSize
    get() {
      val display = windowManager.defaultDisplay
      val outMetrics = DisplayMetrics()
      display.getMetrics(outMetrics)

      val density = outMetrics.density

      var adWidthPixels = ad_view_container.width.toFloat()
      if (adWidthPixels == 0f) {
        adWidthPixels = outMetrics.widthPixels.toFloat()
      }

      val adWidth = (adWidthPixels / density).toInt()
      return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth)
    }
}

Leave application callback removal

The onAdLeftApplication callback for all ad formats has been removed in favor of ProcessLifecycleOwner. Using an OS-level API notifies you whenever users leave your app, regardless of whether or not it is due to an ad interaction.

Note that the onAdLeftApplication callback was never intended to be an ad click handler, and relying on this callback to report clicks did not produce an accurate metric. For example, a click on the AdChoices icon that launched an external browser invoked the callback but did not count as a click.

Class renames

The table below lists specific class names that have changed or been removed. In summary:

• Most classes related to UnifiedNativeAd have been renamed to NativeAd.
• The MobileAds.Settings, NativeExpressAdView, NativeAppInstallAd, NativeContentAd, and InstreamAd classes and views have been removed.
• All classes with the Publisher prefix have been replaced with an AdManager prefix.
• The InterstitialAd package name has changed.

Methods removed/replaced

The table below lists the specific changes in version 20.0.0. In summary:

• Outdated initialization methods have been removed from the MobileAds class.
• Some methods from the AdRequest.Builder() class have either been removed or moved to the RequestConfiguration class.
• RewardedAd and InterstitialAd APIs have been updated to align with all full-screen formats.
• Correlator features have been removed.