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

name: google-mobile-ads-android-migrate-to-next-gen
description: Migrates Android applications from the old, legacy Google Mobile
  Ads (GMA) SDK (com.google.android.gms:play-services-ads) to the new GMA
  Next-Gen SDK (com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk).
  Provides comprehensive mapping tables for imports, classes, and method
  signatures to help determine migration steps. Use when migrating an existing
  Android codebase from the old, legacy GMA SDK to GMA Next-Gen SDK.
metadata:
  version: "1.1.0"
  category: GoogleAds

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`