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:
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`