google-mobile-ads-android-migrate-to-next-gen
Migrates Android applications from the old, legacy Google Mobile
google · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add google/skills --skill 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-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 |