To optimize migrating from Google Mobile Ads SDK to GMA Next-Gen SDK with your AI tool, add a skill to your AI environment. By adding a skill, you provide your AI tool with context specific to GMA Next-Gen SDK and improve the output of AI-assisted code generation.
This guide covers optimizing your AI model to help migrate from Google Mobile Ads SDK to GMA Next-Gen SDK .
Prerequisites
If you use Android Studio, do the following:
- Learn About Gemini in Android Studio .
- Set up Gemini in Android Studio using Android Studio Panda 3 Canary 2 or later.
Add a skill
Google provides a SKILL.md
file with instructions for your AI tool to help you
with migration steps.
To use a skill specific to GMA Next-Gen SDK with your AI tool, follow these steps:
Android Studio
-
In your project's root directory, create a folder named
.skills/. -
Create a directory for your skill named
gma-migrate-to-next-gen. -
In the
gma-migrate-to-next-gendirectory, create a file namedSKILL.md. -
In your
SKILL.mdfile, add the following instructions:--- name: gma-migrate-to-next-gen description: Migrates applications from the old 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). Use when migrating an existing codebase from the old SDK to the new Next-Gen SDK. Includes comprehensive mapping tables for imports, classes, and method signatures to help determine migration steps. metadata: version: 1.0 --- # 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` . - [ ] Update `minSdk` (24+) and `compileSdk` (35+). - [ ] 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** : - [ ] Confirm a successful clean build. ## Core Migration Rules * **SDK Versions** : **ALWAYS** look up and use the latest stable version for `com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk` . Do not assume a version number. * **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. Wrap UI-related operations (Toasts, View updates) in `runOnUiThread {}` or `Dispatchers.Main.launch {}` within SDK callbacks. * **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 * 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` | | 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` (property access is now `getResponseInfo()` . `loadedAdapterResponseInfo` is now `loadedAdSourceResponseInfo` .) | | **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)` |
For details, see Extend Agent Mode with skills .
Invoke the skill in your prompt
After you have added the skill to your project, use the following example prompts to invoke it in your AI tool:
Android Studio
To invoke the skill, type @
and select the gma-migrate-to-next-gen
skill.
@gma-migrate-to-next-gen Migrate the files in my project from the old Google Mobile Ads SDK
to the new GMA Next-Gen SDK
Leave feedback
We are continuing to evaluate and optimize context provided to AI code assist tools to improve their responses on GMA Next-Gen SDK topics.
If you have feedback on optimizing Gemini for GMA Next-Gen SDK , join the GMA Next-Gen SDK Discord channel .
