google-mobile-ads-android-migrate-to-next-gen

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.

Method Mapping

This table covers the main methods and their GMA Next-Gen SDK equivalents.