Migrates Android applications from the old, legacy Google Mobile
Scanned 9/22/2026
Install to Claude Code
Skills Directorynpx -y skills add NVlabs/Skill2Env --skill google-mobile-ads-android-migrate-to-next-gen --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Google Mobile Ads Android Migrate To Next Gen?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/nvlabs-google-mobile-ads-android-migrate-to-next-gen)More formats (shields.io, HTML) on the badges page.
---
name: google-mobile-ads-android-migrate-to-next-gen
description: 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.
metadata:
version: 1.1.0
category: GoogleAds
---
# 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.
| 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` |
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
