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:
• Call MobileAds.initialize() on a background thread.
• Ensure initialize() is called before any other SDK methods.
• 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 |