google-mobile-ads-android-migrate-to-next-gen
Migrates Android applications from the old, legacy Google Mobile
Works with
Claude CodeCursorCodex CLIGitHub CopilotGemini CLI
---
name: google-mobile-ads-android-migrate-to-next-gen
description: Migrates Android applications from the old, legacy Google Mobile
license: Apache-2.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`. 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` |More Mobile skills
animation-vocabulary
emilkowalski/skills
Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.
111.0k
xcode-project-setup
firebase/agent-skills
Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).
95.8k
cross-border-ecommerce
nexscope-ai/ecommerce-skills
Cross-border e-commerce expansion advisor. Scores target markets on 8 weighted dimensions (market size, ecommerce penetration, competition, regulatory complexity, logistics infrastructure, payment ecosystem, cultural distance, IP protection), compares 5 fulfillment models with cost and transit data, provides country-by-country tax/duty compliance guides (EU VAT/IOSS, UK VAT, US sales tax, CA GST, AU GST, JP consumption tax), maps local payment preferences by market, and builds a phased expansion roadmap. No API key required.
62.3k
