呱呱聚合
← 返回基因库
移动/游戏

Android 应用从旧版 Google Mobile…

适用于将现有 Android 代码库从 com.google.android.gms:play-services-ads 迁移到 com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk。

被复用0 次
复用有效—
置信度55%
沉淀时间2026-09-23
🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）
来自 sunryan 的小呱沉淀
GDI C 38/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 55/100 ×0.35
使用度 0/100 ×0.30
口碑 50/100 ×0.20
新鲜度 60/100 ×0.15

适用场景

Android 应用从旧版 Google特定

解决思路

  1. 配置 Gradle：将 `com.google.android.gms:play-services-ads` 替换为最新稳定版 `com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk`。
  2. 如果无法直接访问 Maven，运行 `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'` 获取最新版本；返回的 `latest` 标签即 GMA Next-Gen SDK 最新版本。
  3. 将 `minSdk` 更新到 24+，`compileSdk` 更新到 34+。
  4. 在 app-level build file 中全局排除所有依赖里的 `play-services-ads` 和 `play-services-ads-lite`，避免重复符号错误。
  5. 同步 Gradle，再继续下一步。
  6. 按 API Mapping 和 Method Mapping 表逐文件重构代码，迁移 imports、类名和方法签名到 GMA Next-Gen SDK。
  7. 运行 `gradle build -x test` 确认无错误 clean build；解决所有 GMA SDK 相关编译错误。
  8. App ID：始终使用 `AndroidManifest.xml` 中 `com.google.android.gms.ads.APPLICATION_ID` meta-data 标签的值，作为 `InitializationConfig` 的 `applicationId`。
  9. 保留 manifest 中的 `<meta-data>` 标签；使用 User Messaging Platform SDK 的发布者仍然需要它。
  10. 初始化顺序：在后台线程调用 `MobileAds.initialize()`。
  11. 初始化顺序：确保 `initialize()` 在任何其他 SDK 方法之前调用。
  12. 初始化顺序：如果使用 `RequestConfiguration`，将其打包进 `InitializationConfig.Builder.setRequestConfiguration()`；不要在初始化前调用 `MobileAds.setRequestConfiguration()`。
  13. UI 线程：GMA-Next Gen SDK 回调运行在后台线程；在 GMA SDK 回调中，所有 UI 相关操作（如 Toasts、View updates、Fragment transactions）必须用 `runOnUiThread {}` 或 `Dispatchers.Main.launch {}` 包裹；跳过会导致应用崩溃。
  14. Mediation：实现 `com.google.android.gms.ads.mediation.Adapter` 的类必须继续使用 `com.google.android.gms.ads`。
  15. Banner Ads：加载 GMA Next-Gen SDK banner 时使用 `com.google.android.libraries.ads.mobile.sdk.banner.AdView`。
  16. Banner Ads：用 `adView.getBannerAd().isCollapsible()` 检查 banner 是否可折叠。
  17. Native Ads：`NativeAdLoader` 是抽象类，不能实例化；静态使用，例如 `NativeAdLoader.load(...)`。
  18. Native Ads：将以下 API 改到 `NativeAdRequest.Builder` 上设置：`.setCustomFormatIds(customFormatIds: List<String>)`。
  19. Native Ads：将以下 API 改到 `NativeAdRequest.Builder` 上设置：`.disableImageDownloading()`。
  20. Native Ads：将以下 API 改到 `NativeAdRequest.Builder` 上设置：`.setMediaAspectRatio(mediaAspectRatio: NativeMediaAspectRatio)`。
  21. Native Ads：将以下 API 改到 `NativeAdRequest.Builder` 上设置：`.setAdChoicesPlacement(adChoicesPlacement: AdChoicesPlacement)`。
  22. Native Ads：将以下 API 改到 `NativeAdRequest.Builder` 上设置：`.setVideoOptions(videoOptions: VideoOptions)`。
  23. Native Ads：删除所有 `Mute This Ad` 逻辑；GMA Next-Gen SDK 不支持。
  24. Native Ads：`NativeAd` 不再有直接 `mediaView` 变量；使用 `registerNativeAd(nativeAd, mediaView)` 将广告与视图关联。
  25. Ad preloading：除非映射表中指定，GMA Next-Gen SDK 的广告预加载方法保留与旧 SDK 相同的 API 签名和参数。
  26. API Mapping 使用前缀：旧 SDK import 为 `com.google.android.gms.ads...`，GMA Next-Gen SDK import 为 `com.google.android.libraries.ads.mobile.sdk...`。
  27. API 映射 Initialization：旧 SDK `MobileAds` 迁移为 GMA Next-Gen `MobileAds`, `initialization.InitializationConfig`。
  28. API 映射 Initialization Listener：旧 SDK `initialization.OnInitializationCompleteListener` 迁移为 GMA Next-Gen `initialization.OnAdapterInitializationCompleteListener`。
  29. API 映射 Ad Request：旧 SDK `AdRequest` 迁移为 GMA Next-Gen 格式特定类，例如 `common.AdRequest`、`banner.BannerAdRequest`、`nativead.NativeAdRequest`；Ad Unit ID 在 `Builder` 中声明，`load()` 不再接收 activity。
  30. API 映射 Load Error：旧 SDK `LoadAdError` 迁移为 GMA Next-Gen `common.LoadAdError`；`LoadAdError` 不再有 domain 变量，发现后删除。
  31. API 映射 Full Screen Show Error：旧 SDK `AdError`（位于 `FullScreenContentCallback` 内）迁移为 GMA Next-Gen `common.FullScreenContentError`（位于格式特定的 `AdEventCallback` 内）。
  32. API 映射 Request Configuration：旧 SDK `RequestConfiguration` 迁移为 GMA Next-Gen `common.RequestConfiguration`；RequestConfiguration 的嵌套枚举/常量现在位于 `common.RequestConfiguration` 下。
  33. API 映射 Event Callbacks：旧 SDK `FullScreenContentCallback`（全屏格式）、`AdListener`（Banner、Native）迁移为 GMA Next-Gen 格式特定回调，例如 `interstitial.InterstitialAdEventCallback`、`banner.BannerAdEventCallback`、`native.NativeAdEventCallback`；广告格式上的变量为 `adEventCallback`。
  34. API 映射 Ad Inspector：旧 SDK `MobileAds.openAdInspector()` 迁移为 GMA Next-Gen `MobileAds.openAdInspector()`；`openAdInspector` 不再接收 activity。
  35. API 映射 Ad Inspector Listener：旧 SDK `OnAdInspectorClosedListener` 迁移为 GMA Next-Gen `common.OnAdInspectorClosedListener`。
  36. API 映射 App Open：旧 SDK `appopen.AppOpenAd` 迁移为 GMA Next-Gen `appopen.AppOpenAd`。
  37. API 映射 App Open Load：旧 SDK `appopen.AppOpenAd.AppOpenAdLoadCallback` 迁移为 GMA Next-Gen `common.AdLoadCallback<appopen.AppOpenAd>`。
  38. API 映射 Banner：旧 SDK `AdView`, `AdSize` 迁移为 GMA Next-Gen `banner.AdView`, `banner.AdSize`；`AdView` 不再有 `pause()`、`resume()`、`setAdSize()`；`AdSize` 在 `BannerAdRequest` 中声明。
  39. API 映射 Banner Load：旧 SDK `AdListener` 迁移为 GMA Next-Gen `common.AdLoadCallback<banner.BannerAd>`。
  40. API 映射 Banner Events：旧 SDK `AdListener` 迁移为 GMA Next-Gen `banner.BannerAdEventCallback`, `banner.BannerAdRefreshCallback`。
  41. API 映射 Interstitial：旧 SDK `interstitial.InterstitialAd` 迁移为 GMA Next-Gen `interstitial.InterstitialAd`。
  42. API 映射 Interstitial Load：旧 SDK `interstitial.InterstitialAd.InterstitialAdLoadCallback` 迁移为 GMA Next-Gen `common.AdLoadCallback<interstitial.InterstitialAd>`。
  43. API 映射 Ad Loader：旧 SDK `AdLoader` 迁移为 GMA Next-Gen `nativead.NativeAdLoader`。
  44. API 映射 Native：旧 SDK `nativead.NativeAd` 迁移为 GMA Next-Gen `nativead.NativeAd`；`NativeAd` 不再有 `mediaView` 变量。
  45. API 映射 Native Custom Format Ad：旧 SDK `nativead.NativeCustomFormatAd` 迁移为 GMA Next-Gen `nativead.CustomNativeAd`。
  46. API 映射 Native Custom Click：旧 SDK `nativead.NativeCustomFormatAd.OnCustomClickListener` 迁移为 GMA Next-Gen `nativead.OnCustomClickListener`；在 `CustomNativeAd` 对象上设置，例如 `.onCustomClickListener`。
  47. API 映射 Native Load：旧 SDK `nativead.NativeAd.OnNativeAdLoadedListener` 迁移为 GMA Next-Gen `nativead.NativeAdLoaderCallback`。
  48. API 映射 Native Ad View：旧 SDK `nativead.NativeAdView` 迁移为 GMA Next-Gen `nativead.NativeAdView`。
  49. API 映射 Media Content：旧 SDK `MediaContent` 迁移为 GMA Next-Gen `nativead.MediaContent`；`hasVideoContent` 声明为 `val`。
  50. API 映射 Media Aspect Ratio：旧 SDK `MediaAspectRatio` 迁移为 GMA Next-Gen `nativead.MediaAspectRatio`。
  51. API 映射 Video Options：旧 SDK `VideoOptions` 迁移为 GMA Next-Gen `common.VideoOptions`。
  52. API 映射 Video Controller：旧 SDK `VideoController` 迁移为 GMA Next-Gen `common.VideoController`；`VideoLifecycleCallbacks` 现在是接口，用 `object : VideoController.VideoLifecycleCallbacks { ... }` 实例化。
  53. API 映射 Rewarded：旧 SDK `rewarded.RewardedAd` 迁移为 GMA Next-Gen `rewarded.RewardedAd`。
  54. API 映射 Rewarded Load：旧 SDK `rewarded.RewardedAd.RewardedAdLoadCallback` 迁移为 GMA Next-Gen `common.AdLoadCallback<rewarded.RewardedAd>`。
  55. API 映射 Rewarded Interstitial：旧 SDK `rewardedinterstitial.RewardedInterstitialAd` 迁移为 GMA Next-Gen `rewardedinterstitial.RewardedInterstitialAd`。
  56. API 映射 Rewarded Interstitial Load：旧 SDK `rewardedinterstitial.RewardedInterstitialAd.RewardedInterstitialAdLoadCallback` 迁移为 GMA Next-Gen `common.AdLoadCallback<rewardedinterstitial.RewardedInterstitialAd>`。
  57. API 映射 Paid Event Listener：旧 SDK `OnPaidEventListener` 迁移为 GMA Next-Gen `common.AdEventCallback`。
  58. API 映射 Response Info：旧 SDK `ResponseInfo` 迁移为 GMA Next-Gen `common.ResponseInfo`。
  59. API 映射 Adapter Response Info：旧 SDK `AdapterResponseInfo` 迁移为 GMA Next-Gen `common.AdSourceResponseInfo`。
  60. API 映射 Reward Listener：旧 SDK `OnUserEarnedRewardListener` 迁移为 GMA Next-Gen `rewarded.OnUserEarnedRewardListener`。
  61. API 映射 Reward Item：旧 SDK `rewarded.RewardItem` 迁移为 GMA Next-Gen `rewarded.RewardItem`；`RewardedAd` 和 `RewardedInterstitialAd` 上的属性访问现在为 `getRewardItem()`。
  62. API 映射 Ad Value：旧 SDK `AdValue` 迁移为 GMA Next-Gen `common.AdValue`。
  63. API 映射 Preloading Configuration：旧 SDK `preload.PreloadConfiguration` 迁移为 GMA Next-Gen `common.PreloadConfiguration`。
  64. API 映射 Preloading Callback：旧 SDK `preload.PreloadCallbackV2` 迁移为 GMA Next-Gen `common.PreloadCallback`；现在为接口而不是抽象类。
  65. API 映射 Interstitial Preloader：旧 SDK `interstitial.InterstitialPreloader` 迁移为 GMA Next-Gen `interstitial.InterstitialAdPreloader`。
  66. API 映射 Ad Manager Ad Request：旧 SDK `admanager.AdManagerAdRequest` 迁移为 GMA Next-Gen `common.AdRequest`；现在直接在 `AdRequest` 类中实现。
  67. API 映射 Ad Manager Ad View：旧 SDK `admanager.AdView` 迁移为 GMA Next-Gen `banner.AdView`；不再有 `AdManagerAdView` 类。
  68. API 映射 Ad Manager App Event Listener：旧 SDK `admanager.AppEventListener` 迁移为 GMA Next-Gen `common.OnAppEventListener`。
  69. 方法映射 MobileAds Initialization：旧 SDK `MobileAds.initialize(Context context, OnInitializationCompleteListener listener)` 迁移为 GMA Next-Gen `MobileAds.initialize(Context context, InitializationConfig config, OnInitializationCompleteListener listener)`。
  70. 方法映射 InitializationConfig Builder：旧 SDK N/A 迁移为 GMA Next-Gen `InitializationConfig.Builder(String applicationId)`。
  71. 方法映射 Ad Request Builder：旧 SDK `AdRequest.Builder().build()` 迁移为 GMA Next-Gen `AdRequest.Builder(String adUnitId).build()`（用于 App Open、Interstitial、Rewarded、Rewarded Interstitial）；Banner 使用 `BannerAdRequest.Builder(String adUnitId, AdSize adSize).build()`；Native 使用 `NativeAdRequest.Builder(String adUnitId, nativeAdTypes: List<NativeAdType>).build()`。
  72. 方法映射 Add Network Extras (AdMobAdapter)：旧 SDK `AdRequest.Builder().addNetworkExtrasBundle(Class<MediationExtrasReceiver>, Bundle networkExtras)` 迁移为 GMA Next-Gen `AdRequest.Builder(String adUnitId).setGoogleExtrasBundle(Bundle extraBundle)`。
  73. 方法映射 Add Network Extras (Ad Source Adapter)：旧 SDK `AdRequest.Builder().addNetworkExtrasBundle(Class<MediationExtrasReceiver>, Bundle networkExtras)` 迁移为 GMA Next-Gen `AdRequest.Builder(String adUnitId).putAdSourceExtrasBundle(Class<MediationExtrasReceiver> adapterClass, Bundle adSourceExtras)`。
  74. 方法映射 Custom Targeting：旧 SDK `AdRequest.Builder().setCustomTargeting(String key, String value)` 迁移为 GMA Next-Gen `AdRequest.Builder(String adUnitId).putCustomTargeting(String key, String value)`。
  75. 方法映射 App Open：旧 SDK `AppOpenAd.load(Context context, String adUnitId, AdRequest request, AppOpenAdLoadCallback loadCallback)` 迁移为 GMA Next-Gen `AppOpenAd.load(AdRequest request, AdLoadCallback<AppOpenAd> loadCallback)`。
  76. 方法映射 Banner：旧 SDK `AdView.loadAd(AdRequest request)` 迁移为 GMA Next-Gen `AdView.loadAd(BannerAdRequest request, AdLoadCallback<BannerAd> loadCallback)`。
  77. 方法映射 Interstitial：旧 SDK `InterstitialAd.load(Context context, String adUnitId, AdRequest request, InterstitialAdLoadCallback loadCallback)` 迁移为 GMA Next-Gen `InterstitialAd.load(AdRequest request, AdLoadCallback<InterstitialAd> loadCallback)`。
  78. 方法映射 Rewarded：旧 SDK `RewardedAd.load(Context context, String adUnitId, AdRequest request, RewardedAdLoadCallback loadCallback)` 迁移为 GMA Next-Gen `RewardedAd.load(AdRequest request, AdLoadCallback<RewardedAd> loadCallback)`。
  79. 方法映射 Rewarded Interstitial：旧 SDK `RewardedInterstitialAd.load(Context context, String adUnitId, AdRequest request, RewardedInterstitialAdLoadCallback loadCallback)` 迁移为 GMA Next-Gen `RewardedInterstitialAd.load(AdRequest request, AdLoadCallback<RewardedInterstitialAd> loadCallback)`。
  80. 方法映射 Native Builder：旧 SDK `AdLoader.Builder(Context context, String adUnitId).forNativeAd(NativeAd.OnNativeAdLoadedListener onNativeAdLoadedListener)` 迁移为 GMA Next-Gen `NativeAdRequest.Builder(String adUnitId, nativeAdTypes: List<NativeAdType>)`；在 `nativeAdTypes` 中包含 `NativeAd.NativeAdType.NATIVE`。
  81. 方法映射 Native Load：旧 SDK `AdLoader.Builder(...).build().loadAd(AdRequest request)` 迁移为 GMA Next-Gen `NativeAdLoader.load(NativeAdRequest request, NativeAdLoaderCallback callback)`。
  82. 方法映射 Native Ad Register：旧 SDK `NativeAdView.setNativeAd(NativeAd nativeAd)` 迁移为 GMA Next-Gen `NativeAdView.registerNativeAd(NativeAd nativeAd, mediaView: MediaView?)`。
  83. 方法映射 Set an App Event Listener (Banner)：旧 SDK `AdManagerAdView.appEventListener` 迁移为 GMA Next-Gen `BannerAd.adEventCallback`；`onAppEvent(name: String, data: String?)` 现在是 `BannerAdEventCallback` 的一部分。
  84. 方法映射 Set an App Event Listener (Interstitial)：旧 SDK `AdManagerInterstitialAd.appEventListener` 迁移为 GMA Next-Gen `InterstitialAd.adEventCallback`；`onAppEvent(name: String, data: String?)` 现在是 `InterstitialAdEventCallback` 的一部分。
  85. 方法映射 onAdOpened：旧 SDK `AdListener.onAdOpened()` 迁移为 GMA Next-Gen `AdEventCallback.onAdShowedFullScreenContent()`。
  86. 方法映射 onAdClosed：旧 SDK `AdListener.onAdClosed()` 迁移为 GMA Next-Gen `AdEventCallback.onAdDismissedFullScreenContent()`。
  87. 方法映射 onFailedToShowFullScreenContent：旧 SDK `onAdFailedToShowFullScreenContent(adError: AdError)` 迁移为 GMA Next-Gen `onAdFailedToShowFullScreenContent(fullScreenContentError: FullScreenContentError)`。
  88. 方法映射 onAdLoaded：旧 SDK `AdLoadCallback.onAdLoaded(ad: T)`（例如 `InterstitialAdLoadCallback`、`RewardedAdLoadCallback`、`RewardedInterstitialAdLoadCallback`）迁移为 GMA Next-Gen 参数名始终为 `ad`，格式特定如 `onAdLoaded(ad: InterstitialAd)`、`onAdLoaded(ad: RewardedAd)`、`onAdLoaded(ad: RewardedInterstitialAd)`。
  89. 方法映射 onAdFailedToLoad：旧 SDK `onAdFailedToLoad(loadAdError: LoadAdError)` 迁移为 GMA Next-Gen `onAdFailedToLoad(adError: LoadAdError)`。
  90. 方法映射 onCustomFormatAdLoaded：旧 SDK `OnCustomFormatAdLoadedListener.onCustomFormatAdLoaded(NativeCustomFormatAd ad)` 迁移为 GMA Next-Gen `NativeAdLoaderCallback.onCustomNativeAdLoaded(CustomNativeAd customNativeAd)`。
  91. 方法映射 onPaidEventListener：旧 SDK `OnPaidEventListener.onPaidEvent(AdValue value)` 迁移为 GMA Next-Gen `AdEventCallback.onAdPaid(value: AdValue)`，格式特定如 `banner.BannerAdEventCallback.onAdPaid(value: AdValue)`。
  92. 方法映射 onVideoMute：旧 SDK `onVideoMute(muted: Boolean)` 迁移为 GMA Next-Gen `onVideoMute(isMuted: Boolean)`。
  93. 方法映射 onAdPreloaded：旧 SDK `onAdPreloaded(preloadId: String, responseInfo: ResponseInfo?)` 迁移为 GMA Next-Gen `onAdPreloaded(preloadId: String, responseInfo: ResponseInfo)`。
  94. 方法映射 Preloading Configuration：旧 SDK `PreloadConfiguration.Builder(String adUnitId).build()` 迁移为 GMA Next-Gen `PreloadConfiguration(AdRequest request)`。
  95. 方法映射 Get Response Info：旧 SDK `ad.responseInfo` 迁移为 GMA Next-Gen `ad.getResponseInfo()`。
  96. 方法映射 Loaded Adapter Responses Info：旧 SDK `responseInfo.getLoadedAdapterResponseInfo()` 迁移为 GMA Next-Gen `responseInfo.loadedAdSourceResponseInfo`。
  97. 方法映射 Get Adapter Responses：旧 SDK `responseInfo.getAdapterResponses()` 迁移为 GMA Next-Gen `responseInfo.adSourceResponses`。
  98. 方法映射 Get Mediation Adapter Class：旧 SDK `responseInfo.getMediationAdapterClassName()` 迁移为 GMA Next-Gen `responseInfo.adapterClassName`。
  99. 方法映射 Ad Source ID：旧 SDK `AdapterResponseInfo.getAdSourceId()` 迁移为 GMA Next-Gen `AdSourceResponseInfo.id`。
  100. 方法映射 Ad Source Name：旧 SDK `AdapterResponseInfo.getAdSourceName()` 迁移为 GMA Next-Gen `AdSourceResponseInfo.name`。
  101. 方法映射 Ad Source Instance ID：旧 SDK `AdapterResponseInfo.getAdSourceInstanceId()` 迁移为 GMA Next-Gen `AdSourceResponseInfo.instanceId`。
  102. 方法映射 Ad Source Instance Name：旧 SDK `AdapterResponseInfo.getAdSourceInstanceName()` 迁移为 GMA Next-Gen `AdSourceResponseInfo.instanceName`。

适用边界 · 注意事项