Agent-Skills.md

Agent Skills: AI Migration Agent Instructions for the Google Mobile Ads SDK

Migrates Android applications from the old, legacy Google Mobile

GoogleAdsID: aibangjuxin/knowledge/google-mobile-ads-android-migrate-to-next-gen

Repository

aibangjuxin/knowledge
aibangjuxin
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/aibangjuxin/knowledge/tree/HEAD/skills/.kiro/skills/google-mobile-ads-android-migrate-to-next-gen

Skill Files

Browse the full folder contents for google-mobile-ads-android-migrate-to-next-gen.

Download Skill

Loading file tree…

skills/.kiro/skills/google-mobile-ads-android-migrate-to-next-gen/SKILL.md

Skill Metadata

Name
google-mobile-ads-android-migrate-to-next-gen
Description
Migrates Android applications from the old, legacy Google Mobile

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 |