google-mobile-ads-android-migrate-to-next-gen

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:

    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.

Feature	Old SDK Import (com.google.android.gms.ads...)	GMA Next-Gen SDK Import (com.google.android.libraries.ads.mobile.sdk... )
Core
Initialization	MobileAds	MobileAds, initialization.InitializationConfig
Initialization Listener	initialization.OnInitializationCompleteListener	initialization.OnAdapterInitializationCompleteListener
Ad Request	AdRequest	Format specific (e.g. common.AdRequest, banner.BannerAdRequest, nativead.NativeAdRequest) (Ad Unit ID is declared in Builder. Load() no longer takes an activity)
Load Error	LoadAdError	common.LoadAdError (LoadAdError no longer has a domain variable. REMOVE the domain variable if found.)
Full Screen Show Error	AdError (within FullScreenContentCallback)	common.FullScreenContentError (within format-specific AdEventCallback)
Request Configuration	RequestConfiguration	common.RequestConfiguration (Nested Enums/Constants for RequestConfiguration are now under common.RequestConfiguration.)
Event Callbacks	FullScreenContentCallback (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 Inspector	MobileAds.openAdInspector()	MobileAds.openAdInspector() (openAdInspector no longer takes an activity)
Ad Inspector Listener	OnAdInspectorClosedListener	common.OnAdInspectorClosedListener
Formats
App Open	appopen.AppOpenAd	appopen.AppOpenAd
App Open Load	appopen.AppOpenAd.AppOpenAdLoadCallback	common.AdLoadCallback<appopen.AppOpenAd>
Banner	AdView, AdSize	banner.AdView, banner.AdSize (AdView no longer has pause(), resume(), setAdSize()). AdSize is declared in BannerAdRequest.
Banner Load	AdListener	common.AdLoadCallback<banner.BannerAd>
Banner Events	AdListener	banner.BannerAdEventCallback, banner.BannerAdRefreshCallback
Interstitial	interstitial.InterstitialAd	interstitial.InterstitialAd
Interstitial Load	interstitial.InterstitialAd.InterstitialAdLoadCallback	common.AdLoadCallback<interstitial.InterstitialAd>
Ad Loader	AdLoader	nativead.NativeAdLoader
Native	nativead.NativeAd	nativead.NativeAd (No longer has a mediaView variable)
Native Custom Format Ad	nativead.NativeCustomFormatAd	nativead.CustomNativeAd
Native Custom Click	nativead.NativeCustomFormatAd.OnCustomClickListener	nativead.OnCustomClickListener (set on the CustomNativeAd object (e.g., .onCustomClickListener)
Native Load	nativead.NativeAd.OnNativeAdLoadedListener	nativead.NativeAdLoaderCallback
Native Ad View	nativead.NativeAdView	nativead.NativeAdView
Media Content	MediaContent	nativead.MediaContent (hasVideoContent is declared as a val)
Media Aspect Ratio	MediaAspectRatio	nativead.MediaAspectRatio
Video Options	VideoOptions	common.VideoOptions
Video Controller	VideoController	common.VideoController (VideoLifecycleCallbacks is now an interface, so instantiate with object : VideoController.VideoLifecycleCallbacks { ... })
Rewarded	rewarded.RewardedAd	rewarded.RewardedAd
Rewarded Load	rewarded.RewardedAd.RewardedAdLoadCallback	common.AdLoadCallback<rewarded.RewardedAd>
Rewarded Interstitial	rewardedinterstitial.RewardedInterstitialAd	rewardedinterstitial.RewardedInterstitialAd
Rewarded Interstitial Load	rewardedinterstitial.RewardedInterstitialAd.RewardedInterstitialAdLoadCallback	common.AdLoadCallback<rewardedinterstitial.RewardedInterstitialAd>
Paid Event Listener	OnPaidEventListener	common.AdEventCallback
Response Info	ResponseInfo	common.ResponseInfo
Adapter Response Info	AdapterResponseInfo	common.AdSourceResponseInfo
Rewards
Reward Listener	OnUserEarnedRewardListener	rewarded.OnUserEarnedRewardListener
Reward Item	rewarded.RewardItem	rewarded.RewardItem (property access on RewardedAd and RewardedInterstitialAd is now getRewardItem())
Ad Value	AdValue	common.AdValue
Preloading
Configuration	preload.PreloadConfiguration	common.PreloadConfiguration
Callback	preload.PreloadCallbackV2	common.PreloadCallback (Now an interface instead of an abstract class)
Interstitial Preloader	interstitial.InterstitialPreloader	interstitial.InterstitialAdPreloader
Ad Manager
Ad Request	admanager.AdManagerAdRequest	common.AdRequest (Now directly implemented in the AdRequest class)
Ad View	admanager.AdView	banner.AdView (No AdManagerAdView class)
App Event Listener	admanager.AppEventListener	common.OnAppEventListener

Method Mapping

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

Feature	Old SDK Method Signature	GMA Next-Gen SDK Method Signature
Core
MobileAds Initialization	MobileAds.initialize(Context context, OnInitializationCompleteListener listener)	MobileAds.initialize(Context context, InitializationConfig config, OnInitializationCompleteListener listener)
InitializationConfig Builder	N/A	InitializationConfig.Builder(String applicationId)
Ad Request Builder	AdRequest.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 Targeting	AdRequest.Builder().setCustomTargeting(String key, String value)	AdRequest.Builder(String adUnitId).putCustomTargeting(String key, String value)
Formats
App Open	AppOpenAd.load(Context context, String adUnitId, AdRequest request, AppOpenAdLoadCallback loadCallback)	AppOpenAd.load(AdRequest request, AdLoadCallback<AppOpenAd> loadCallback)
Banner	AdView.loadAd(AdRequest request)	AdView.loadAd(BannerAdRequest request, AdLoadCallback<BannerAd> loadCallback)
Interstitial	InterstitialAd.load(Context context, String adUnitId, AdRequest request, InterstitialAdLoadCallback loadCallback)	InterstitialAd.load(AdRequest request, AdLoadCallback<InterstitialAd> loadCallback)
Rewarded	RewardedAd.load(Context context, String adUnitId, AdRequest request, RewardedAdLoadCallback loadCallback)	RewardedAd.load(AdRequest request, AdLoadCallback<RewardedAd> loadCallback)
Rewarded Interstitial	RewardedInterstitialAd.load(Context context, String adUnitId, AdRequest request, RewardedInterstitialAdLoadCallback loadCallback)	RewardedInterstitialAd.load(AdRequest request, AdLoadCallback<RewardedInterstitialAd> loadCallback)
Native Builder	AdLoader.Builder(Context context, String adUnitId).forNativeAd(NativeAd.OnNativeAdLoadedListener onNativeAdLoadedListener)	NativeAdRequest.Builder(String adUnitId, nativeAdTypes: List<NativeAdType>) (Include NativeAd.NativeAdType.NATIVE in nativeAdTypes)
Native Load	AdLoader.Builder(...).build().loadAd(AdRequest request)	NativeAdLoader.load(NativeAdRequest request, NativeAdLoaderCallback callback)
Native Ad Register	NativeAdView.setNativeAd(NativeAd nativeAd)	NativeAdView.registerNativeAd(NativeAd nativeAd, mediaView: MediaView?)
Set an App Event Listener (Banner)	AdManagerAdView.appEventListener	BannerAd.adEventCallback (onAppEvent(name: String, data: String?) is now part of the BannerAdEventCallback)
Set an App Event Listener (Interstitial)	AdManagerInterstitialAd.appEventListener	InterstitialAd.adEventCallback (onAppEvent(name: String, data: String?) is now part of the InterstitialAdEventCallback)
Callbacks
onAdOpened	AdListener.onAdOpened()	AdEventCallback.onAdShowedFullScreenContent()
onAdClosed	AdListener.onAdClosed()	AdEventCallback.onAdDismissedFullScreenContent()
onFailedToShowFullScreenContent	onAdFailedToShowFullScreenContent(adError: AdError)	onAdFailedToShowFullScreenContent(fullScreenContentError: FullScreenContentError)
onAdLoaded	AdLoadCallback: onAdLoaded(ad: T) (e.g., InterstitialAdLoadCallback, RewardedAdLoadCallback, RewardedInterstitialAdLoadCallback)	Parameter name is always ad Format specific: onAdLoaded(ad: InterstitialAd), onAdLoaded(ad: RewardedAd), onAdLoaded(ad: RewardedInterstitialAd)
onAdFailedToLoad	onAdFailedToLoad(loadAdError: LoadAdError)	onAdFailedToLoad(adError: LoadAdError)
onCustomFormatAdLoaded	OnCustomFormatAdLoadedListener.onCustomFormatAdLoaded(NativeCustomFormatAd ad)	NativeAdLoaderCallback.onCustomNativeAdLoaded(CustomNativeAd customNativeAd)
onPaidEventListener	OnPaidEventListener.onPaidEvent(AdValue value)	AdEventCallback.onAdPaid(value: AdValue) (Format-specific e.g., banner.BannerAdEventCallback.onAdPaid(value: AdValue))
onVideoMute	onVideoMute(muted: Boolean)	onVideoMute(isMuted: Boolean)
onAdPreloaded	onAdPreloaded(preloadId: String, responseInfo: ResponseInfo?)	onAdPreloaded(preloadId: String, responseInfo: ResponseInfo)
Preloading
Configuration	PreloadConfiguration.Builder(String adUnitId).build()	PreloadConfiguration(AdRequest request)
Response Info
Get Response Info	ad.responseInfo	ad.getResponseInfo()
Loaded Adapter Responses Info	responseInfo.getLoadedAdapterResponseInfo()	responseInfo.loadedAdSourceResponseInfo
Get Adapter Responses	responseInfo.getAdapterResponses()	responseInfo.adSourceResponses
Get Mediation Adapter Class	responseInfo.getMediationAdapterClassName()	responseInfo.adapterClassName
Adapter Response Info
Ad Source ID	AdapterResponseInfo.getAdSourceId()	AdSourceResponseInfo.id
Ad Source Name	AdapterResponseInfo.getAdSourceName()	AdSourceResponseInfo.name
Ad Source Instance ID	AdapterResponseInfo.getAdSourceInstanceId()	AdSourceResponseInfo.instanceId
Ad Source Instance Name	AdapterResponseInfo.getAdSourceInstanceName()	AdSourceResponseInfo.instanceName