Google Mobile Ads Android Migrate To Next Gen

by google55b4e13eba6dNo license21K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated today

Migrates Android applications from the old, legacy Google Mobile Ads (GMA) SDK (com.google.android.gms:play-services-ads) to the new GMA Next-Gen SDK (com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk). Provides comprehensive mapping tables for imports, classes, and method signatures to help determine migration steps. Use when migrating an existing Android codebase from the old, legacy GMA SDK to GMA Next-Gen SDK.

FeaturedInstructions onlySoftware Development
AI-generated overview

Guides migration of Android apps from the legacy Google Mobile Ads SDK to the GMA Next-Gen SDK.

What it does
This skill provides instructions and mapping tables for migrating an Android codebase from the legacy Google Mobile Ads SDK (com.google.android.gms:play-services-ads) to the GMA Next-Gen SDK (com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk). It covers Gradle configuration changes, per-file refactoring of imports, classes and method signatures, and verification via a clean build. It also documents format-specific details for banner, native and preloaded ads, plus core rules on initialization, threading and mediation.
When to use it
Use it when migrating an existing Android app from the old GMA SDK to the GMA Next-Gen SDK. It is intended for developers who need concrete import, class and method mappings, and who must adjust Gradle dependencies and SDK initialization. It also helps when resolving compile errors or behavior changes introduced by the new SDK.
Requirements
Requires an Android project with Gradle and the Android SDK; instructions reference running a Gradle build and optionally fetching the latest SDK version from Google's Maven repository over the network. No scripts are shipped.

AI Migration Agent Instructions for the Google Mobile Ads SDK

Migration Workflow

Use this checklist to track your migration progress:

  • Configure Gradle:

    • Replace com.google.android.gms:play-services-ads with the latest stable version of com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk. If you cannot access Maven directly, run the following command to fetch the latest version. The version returned in the latest tag is the latest version of the GMA Next-Gen SDK:

      bash
      curl -sS https://dl.google.com/dl/android/maven2/com/google/android/libraries/ads/mobile/sdk/ads-mobile-sdk/maven-metadata.xml | sed -n 's/.*<latest>\(.*\)<\/latest>.*/\1/p'

    • Update minSdk (24+) and compileSdk (34+).

    • Exclude play-services-ads and play-services-ads-lite from all dependencies globally in the app-level build file to avoid duplicate symbol errors.

    • Sync Gradle before moving on to the next step.

  • Per-File Migration:
    • Refactor the codebase following the API Mapping and Method Mapping tables to migrate imports, class names, and method signature to GMA Next-Gen SDK.
  • Verify and Build:
    • Run gradle build -x test to confirm a successful clean build. Resolve any GMA SDK related compile errors.

Core Migration Rules

  • App ID Usage: Always use the value of the com.google.android.gms.ads.APPLICATION_ID meta-data tag from AndroidManifest.xml for the applicationId in InitializationConfig.
    • Constraint: Preserve the <meta-data> tag in the manifest; it is still required for publishers using the User Messaging Platform SDK.
  • Initialization Sequence:
    1. Call MobileAds.initialize() on a background thread.
    2. Ensure initialize() is called before any other SDK methods.
    3. If using RequestConfiguration, bundle it into InitializationConfig.Builder.setRequestConfiguration(). Do not call MobileAds.setRequestConfiguration() before initialization.
  • UI Threading: MANDATORY: Callbacks in GMA-Next Gen SDK are invoked on a background thread. ALL UI-RELATED OPERATIONS (e.g., Toasts, View updates, Fragment transactions) MUST be wrapped in runOnUiThread {} or Dispatchers.Main.launch {} within GMA SDK callbacks. SKIPPING THIS STEP WILL CAUSE THE APPLICATION TO CRASH.
  • Mediation: Classes implementing com.google.android.gms.ads.mediation.Adapter MUST continue using com.google.android.gms.ads.

Format Specifics

Banner Ads

  • Use com.google.android.libraries.ads.mobile.sdk.banner.AdView for loading GMA Next-Gen SDK banners.
  • The following API checks if a banner is collapsible: adView.getBannerAd().isCollapsible().

Native Ads

  • NativeAdLoader: NativeAdLoader is abstract and cannot be instantiated. It is used statically (e.g., NativeAdLoader.load(...)).
  • The following APIs are now set on the NativeAdRequest.Builder:
    • .setCustomFormatIds(customFormatIds: List<String>)
    • .disableImageDownloading()
    • .setMediaAspectRatio(mediaAspectRatio: NativeMediaAspectRatio)
    • .setAdChoicesPlacement(adChoicesPlacement: AdChoicesPlacement)
    • .setVideoOptions(videoOptions: VideoOptions)
  • Removal: Delete all "Mute This Ad" logic; it is unsupported in GMA Next-Gen SDK.
  • MediaView: NativeAd no longer has a direct mediaView variable; use registerNativeAd(nativeAd, mediaView) to associate the ad with the view.

Ad preloading

  • Unless specified in the mapping table, ad preloading methods in the GMA Next-Gen SDK retain the same API signatures and parameters as the Old SDK.

API Mapping

This table covers the main classes and their GMA Next-Gen SDK equivalents.

FeatureOld SDK Import (com.google.android.gms.ads...)GMA Next-Gen SDK Import (com.google.android.libraries.ads.mobile.sdk... )
Core
InitializationMobileAdsMobileAds, initialization.InitializationConfig
Initialization Listenerinitialization.OnInitializationCompleteListenerinitialization.OnAdapterInitializationCompleteListener
Ad RequestAdRequestFormat specific (e.g. common.AdRequest, banner.BannerAdRequest, nativead.NativeAdRequest) (Ad Unit ID is declared in Builder. Load() no longer takes an activity)
Load ErrorLoadAdErrorcommon.LoadAdError (LoadAdError no longer has a domain variable. REMOVE the domain variable if found.)
Full Screen Show ErrorAdError (within FullScreenContentCallback)common.FullScreenContentError (within format-specific AdEventCallback)
Request ConfigurationRequestConfigurationcommon.RequestConfiguration (Nested Enums/Constants for RequestConfiguration are now under common.RequestConfiguration.)
Event CallbacksFullScreenContentCallback (for full screen formats), AdListener (Banner, Native)Format Specific (e.g., interstitial.InterstitialAdEventCallback, banner.BannerAdEventCallback, native.NativeAdEventCallback). Variable on the ad format is adEventCallback.
Tools
Ad InspectorMobileAds.openAdInspector()MobileAds.openAdInspector() (openAdInspector no longer takes an activity)
Ad Inspector ListenerOnAdInspectorClosedListenercommon.OnAdInspectorClosedListener
Formats
App Openappopen.AppOpenAdappopen.AppOpenAd
App Open Loadappopen.AppOpenAd.AppOpenAdLoadCallbackcommon.AdLoadCallback<appopen.AppOpenAd>
BannerAdView, AdSizebanner.AdView, banner.AdSize (AdView no longer has pause(), resume(), setAdSize()). AdSize is declared in BannerAdRequest.
Banner LoadAdListenercommon.AdLoadCallback<banner.BannerAd>
Banner EventsAdListenerbanner.BannerAdEventCallback, banner.BannerAdRefreshCallback
Interstitialinterstitial.InterstitialAdinterstitial.InterstitialAd
Interstitial Loadinterstitial.InterstitialAd.InterstitialAdLoadCallbackcommon.AdLoadCallback<interstitial.InterstitialAd>
Ad LoaderAdLoadernativead.NativeAdLoader
Nativenativead.NativeAdnativead.NativeAd (No longer has a mediaView variable)
Native Custom Format Adnativead.NativeCustomFormatAdnativead.CustomNativeAd
Native Custom Clicknativead.NativeCustomFormatAd.OnCustomClickListenernativead.OnCustomClickListener (set on the CustomNativeAd object (e.g., .onCustomClickListener)
Native Loadnativead.NativeAd.OnNativeAdLoadedListenernativead.NativeAdLoaderCallback
Native Ad Viewnativead.NativeAdViewnativead.NativeAdView
Media ContentMediaContentnativead.MediaContent (hasVideoContent is declared as a val)
Media Aspect RatioMediaAspectRationativead.MediaAspectRatio
Video OptionsVideoOptionscommon.VideoOptions
Video ControllerVideoControllercommon.VideoController (VideoLifecycleCallbacks is now an interface, so instantiate with object : VideoController.VideoLifecycleCallbacks { ... })
Rewardedrewarded.RewardedAdrewarded.RewardedAd
Rewarded Loadrewarded.RewardedAd.RewardedAdLoadCallbackcommon.AdLoadCallback<rewarded.RewardedAd>
Rewarded Interstitialrewardedinterstitial.RewardedInterstitialAdrewardedinterstitial.RewardedInterstitialAd
Rewarded Interstitial Loadrewardedinterstitial.RewardedInterstitialAd.RewardedInterstitialAdLoadCallbackcommon.AdLoadCallback<rewardedinterstitial.RewardedInterstitialAd>
Paid Event ListenerOnPaidEventListenercommon.AdEventCallback
Response InfoResponseInfocommon.ResponseInfo
Adapter Response InfoAdapterResponseInfocommon.AdSourceResponseInfo
Rewards
Reward ListenerOnUserEarnedRewardListenerrewarded.OnUserEarnedRewardListener
Reward Itemrewarded.RewardItemrewarded.RewardItem (property access on RewardedAd and RewardedInterstitialAd is now getRewardItem())
Ad ValueAdValuecommon.AdValue
Preloading
Configurationpreload.PreloadConfigurationcommon.PreloadConfiguration
Callbackpreload.PreloadCallbackV2common.PreloadCallback (Now an interface instead of an abstract class)
Interstitial Preloaderinterstitial.InterstitialPreloaderinterstitial.InterstitialAdPreloader
Ad Manager
Ad Requestadmanager.AdManagerAdRequestcommon.AdRequest (Now directly implemented in the AdRequest class)
Ad Viewadmanager.AdViewbanner.AdView (No AdManagerAdView class)
App Event Listeneradmanager.AppEventListenercommon.OnAppEventListener

Method Mapping

This table covers the main methods and their GMA Next-Gen SDK equivalents.

FeatureOld SDK Method SignatureGMA Next-Gen SDK Method Signature
Core
MobileAds InitializationMobileAds.initialize(Context context, OnInitializationCompleteListener listener)MobileAds.initialize(Context context, InitializationConfig config, OnInitializationCompleteListener listener)
InitializationConfig BuilderN/AInitializationConfig.Builder(String applicationId)
Ad Request BuilderAdRequest.Builder().build()AdRequest.Builder(String adUnitId).build() (for App Open, Interstitial, Rewarded, Rewarded Interstitial) Banner: BannerAdRequest.Builder(String adUnitId, AdSize adSize).build() Native: NativeAdRequest.Builder(String adUnitId, nativeAdTypes: List<NativeAdType>).build()
Add Network Extras (AdMobAdapter)AdRequest.Builder().addNetworkExtrasBundle(Class<MediationExtrasReceiver>, Bundle networkExtras)AdRequest.Builder(String adUnitId).setGoogleExtrasBundle(Bundle extraBundle)
Add Network Extras (Ad Source Adapter)AdRequest.Builder().addNetworkExtrasBundle(Class<MediationExtrasReceiver>, Bundle networkExtras)AdRequest.Builder(String adUnitId).putAdSourceExtrasBundle(Class<MediationExtrasReceiver> adapterClass, Bundle adSourceExtras)
Custom TargetingAdRequest.Builder().setCustomTargeting(String key, String value)AdRequest.Builder(String adUnitId).putCustomTargeting(String key, String value)
Formats
App OpenAppOpenAd.load(Context context, String adUnitId, AdRequest request, AppOpenAdLoadCallback loadCallback)AppOpenAd.load(AdRequest request, AdLoadCallback<AppOpenAd> loadCallback)
BannerAdView.loadAd(AdRequest request)AdView.loadAd(BannerAdRequest request, AdLoadCallback<BannerAd> loadCallback)
InterstitialInterstitialAd.load(Context context, String adUnitId, AdRequest request, InterstitialAdLoadCallback loadCallback)InterstitialAd.load(AdRequest request, AdLoadCallback<InterstitialAd> loadCallback)
RewardedRewardedAd.load(Context context, String adUnitId, AdRequest request, RewardedAdLoadCallback loadCallback)RewardedAd.load(AdRequest request, AdLoadCallback<RewardedAd> loadCallback)
Rewarded InterstitialRewardedInterstitialAd.load(Context context, String adUnitId, AdRequest request, RewardedInterstitialAdLoadCallback loadCallback)RewardedInterstitialAd.load(AdRequest request, AdLoadCallback<RewardedInterstitialAd> loadCallback)
Native BuilderAdLoader.Builder(Context context, String adUnitId).forNativeAd(NativeAd.OnNativeAdLoadedListener onNativeAdLoadedListener)NativeAdRequest.Builder(String adUnitId, nativeAdTypes: List<NativeAdType>) (Include NativeAd.NativeAdType.NATIVE in nativeAdTypes)
Native LoadAdLoader.Builder(...).build().loadAd(AdRequest request)NativeAdLoader.load(NativeAdRequest request, NativeAdLoaderCallback callback)
Native Ad RegisterNativeAdView.setNativeAd(NativeAd nativeAd)NativeAdView.registerNativeAd(NativeAd nativeAd, mediaView: MediaView?)
Set an App Event Listener (Banner)AdManagerAdView.appEventListenerBannerAd.adEventCallback (onAppEvent(name: String, data: String?) is now part of the BannerAdEventCallback)
Set an App Event Listener (Interstitial)AdManagerInterstitialAd.appEventListenerInterstitialAd.adEventCallback (onAppEvent(name: String, data: String?) is now part of the InterstitialAdEventCallback)
Callbacks
onAdOpenedAdListener.onAdOpened()AdEventCallback.onAdShowedFullScreenContent()
onAdClosedAdListener.onAdClosed()AdEventCallback.onAdDismissedFullScreenContent()
onFailedToShowFullScreenContentonAdFailedToShowFullScreenContent(adError: AdError)onAdFailedToShowFullScreenContent(fullScreenContentError: FullScreenContentError)
onAdLoadedAdLoadCallback: onAdLoaded(ad: T) (e.g., InterstitialAdLoadCallback, RewardedAdLoadCallback, RewardedInterstitialAdLoadCallback)Parameter name is always ad Format specific: onAdLoaded(ad: InterstitialAd), onAdLoaded(ad: RewardedAd), onAdLoaded(ad: RewardedInterstitialAd)
onAdFailedToLoadonAdFailedToLoad(loadAdError: LoadAdError)onAdFailedToLoad(adError: LoadAdError)
onCustomFormatAdLoadedOnCustomFormatAdLoadedListener.onCustomFormatAdLoaded(NativeCustomFormatAd ad)NativeAdLoaderCallback.onCustomNativeAdLoaded(CustomNativeAd customNativeAd)
onPaidEventListenerOnPaidEventListener.onPaidEvent(AdValue value)AdEventCallback.onAdPaid(value: AdValue) (Format-specific e.g., banner.BannerAdEventCallback.onAdPaid(value: AdValue))
onVideoMuteonVideoMute(muted: Boolean)onVideoMute(isMuted: Boolean)
onAdPreloadedonAdPreloaded(preloadId: String, responseInfo: ResponseInfo?)onAdPreloaded(preloadId: String, responseInfo: ResponseInfo)
Preloading
ConfigurationPreloadConfiguration.Builder(String adUnitId).build()PreloadConfiguration(AdRequest request)
Response Info
Get Response Infoad.responseInfoad.getResponseInfo()
Loaded Adapter Responses InforesponseInfo.getLoadedAdapterResponseInfo()responseInfo.loadedAdSourceResponseInfo
Get Adapter ResponsesresponseInfo.getAdapterResponses()responseInfo.adSourceResponses
Get Mediation Adapter ClassresponseInfo.getMediationAdapterClassName()responseInfo.adapterClassName
Adapter Response Info
Ad Source IDAdapterResponseInfo.getAdSourceId()AdSourceResponseInfo.id
Ad Source NameAdapterResponseInfo.getAdSourceName()AdSourceResponseInfo.name
Ad Source Instance IDAdapterResponseInfo.getAdSourceInstanceId()AdSourceResponseInfo.instanceId
Ad Source Instance NameAdapterResponseInfo.getAdSourceInstanceName()AdSourceResponseInfo.instanceName

Source and attribution

Source:google/skillsinskills/ads/google-mobile-ads-android-migrate-to-next-genat commit55b4e13

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from google/skills

Dpop Adoption

google

Featured

Guides implementation of OAuth 2.0 DPoP (RFC 9449) sender-constrained refresh tokens for Google's OAuth platform.

Security21Kupdated today

Finding Google Skills

google

Featured

Google platform decision and setup guidance, loaded on demand from Google's skill catalog. Use when a developer is choosing or setting up part of their stack, such as where to run a service, a database, storage, messaging, authentication, analytics, ads, or AI model serving, and a Google product is a reasonable candidate - whether or not a vendor is named - or when a request names a Google product or API. Brings in the matching Google skill so the answer can weigh Google options, their trade-offs, and when they are not the right fit. Skip when the stack is already settled on another provider and no Google product is named, or the task involves no platform choice.

Awaiting classification21Kupdated today

Spanner Basics

google

Featured

Guides Google Cloud Spanner administration, schema design, querying and performance diagnosis.

Data & Analytics21Kupdated today

Secops Triage

google

Featured

Guides SOC analysts through triaging Google SecOps security alerts, from investigation to closure or escalation.

Security21Kupdated today

Secops Investigate

google

Featured

Guides SOC analysts through deep security incident and entity investigations in Google SecOps using UDM queries and timelines.

Security21Kupdated today

Secops Hunt

google

Featured

Guides proactive threat hunting in Google SecOps using UDM queries, IoC lookback, prevalence and outlier analysis.

Security21Kupdated today

More in Software Development

Playground

anthropics

Featured

Builds self-contained interactive HTML playgrounds with controls, live preview, and copyable prompt output.

Software Development37Kupdated today

M5 Onboard

anthropics

Featured

Provisions M5Stack ESP32 boards by detecting them on USB, flashing UIFlow 2.0 firmware, and installing a MicroPython app bundle.

Software Development37Kupdated today

Cardputer Buddy

anthropics

Featured

Guides iterating on a Cardputer-Adv MicroPython app bundle: adding apps, pushing files over USB-serial, tailing logs, and running REPL commands.

Software Development37Kupdated today

Gemini Live Api

google

Featured

Generates a Gemini Live API WebSocket client class, tests, docs, and a demo UI for bidirectional streaming.

Software Development21Kupdated today

Gemini Api

google

Featured

Guides use of the Gemini API on Google's Agent Platform with the Gen AI SDK across languages and capabilities.

Software Development21Kupdated today

Google Analytics Admin Api Basics

google

Featured

Guides programmatic configuration of Google Analytics accounts and properties via the Admin API, with client library setup references.

Software Development21Kupdated today