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-adswith the latest stable version ofcom.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 thelatesttag 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+) andcompileSdk(34+).Exclude
play-services-adsandplay-services-ads-litefrom 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 testto confirm a successful clean build. Resolve any GMA SDK related compile errors.
- Run
Core Migration Rules
- App ID Usage: Always use the value of the
com.google.android.gms.ads.APPLICATION_IDmeta-data tag fromAndroidManifest.xmlfor theapplicationIdinInitializationConfig.- Constraint: Preserve the
<meta-data>tag in the manifest; it is still required for publishers using the User Messaging Platform SDK.
- Constraint: Preserve the
- Initialization Sequence:
- Call
MobileAds.initialize()on a background thread. - Ensure
initialize()is called before any other SDK methods. - If using
RequestConfiguration, bundle it intoInitializationConfig.Builder.setRequestConfiguration(). Do not callMobileAds.setRequestConfiguration()before initialization.
- Call
- 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 {}orDispatchers.Main.launch {}within GMA SDK callbacks. SKIPPING THIS STEP WILL CAUSE THE APPLICATION TO CRASH. - Mediation: Classes implementing
com.google.android.gms.ads.mediation.AdapterMUST continue usingcom.google.android.gms.ads.
Format Specifics
Banner Ads
- Use
com.google.android.libraries.ads.mobile.sdk.banner.AdViewfor loading GMA Next-Gen SDK banners. - The following API checks if a banner is collapsible:
adView.getBannerAd().isCollapsible().
Native Ads
- NativeAdLoader:
NativeAdLoaderis 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:
NativeAdno longer has a directmediaViewvariable; useregisterNativeAd(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 |