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:

``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/.*\(.*\).*/\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 `` 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)
• .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 | | 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 Events | AdListener | banner.BannerAdEventCallback, banner.BannerAdRefreshCallback | | Interstitial | interstitial.InterstitialAd | interstitial.InterstitialAd | | Interstitial Load | interstitial.InterstitialAd.InterstitialAdLoadCallback | common.AdLoadCallback | | 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 Interstitial | rewardedinterstitial.RewardedInterstitialAd | rewardedinterstitial.RewardedInterstitialAd | | Rewarded Interstitial Load | rewardedinterstitial.RewardedInterstitialAd.RewardedInterstitialAdLoadCallback | common.AdLoadCallback | | 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 | `rewar

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: google
• Source: google/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.