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

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

github.com/google开发21.6k6.3k 次安装今天更新
代码仓库

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

面向开发者的迁移技能，帮助 Android 应用从 Google Mobile Ads SDK 转向 Next-Gen SDK，涵盖依赖、API、线程处理和构建验证。

主要功能

  1. 01Gradle 依赖与 SDK 级别更新
  2. 02新旧 API 对照
  3. 03初始化与回调规则
  4. 04广告格式迁移指引
  5. 05构建验证清单

适用场景

  1. 01将 Android 应用迁移至 Next-Gen SDK
  2. 02查找替换类和方法
  3. 03检查回调中的 UI 线程处理

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/google/skills --skill google-mobile-ads-android-migrate-to-next-gen

安装后在 Claude Code 中输入/google-mobile-ads-android-migrate-to-next-gen确认已加载。

详细介绍

Google Mobile Ads SDK 的 AI 迁移 Agent 指南

迁移工作流

使用此清单跟踪迁移进度：

  • 配置 Gradle：

    • 将 com.google.android.gms:play-services-ads 替换为最新的 稳定版本 com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk。如果 无法直接访问 Maven，请运行以下命令获取最新版本。latest 标签中 返回的版本即为 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'

    • 更新 minSdk（24+）和 compileSdk（34+）。

    • 在应用级构建文件中全局排除所有依赖项中的 play-services-ads 和 play-services-ads-lite，以避免重复符号错误。

    • 在继续下一步之前同步 Gradle。

  • 逐文件迁移：
    • 按照 API 映射表和方法映射表重构代码库，将导入项、类名和方法 签名迁移到 GMA Next-Gen SDK。
  • 验证并构建：
    • 运行 gradle build -x test，确认构建成功且无残留问题。 解决所有与 GMA SDK 相关的编译错误。

核心迁移规则

  • 应用 ID 用法：始终使用 AndroidManifest.xml 中 com.google.android.gms.ads.APPLICATION_ID 元数据标签的值，作为 InitializationConfig 中的 applicationId。
    • 约束：保留清单中的 <meta-data> 标签；使用 User Messaging Platform SDK 的发布者仍然需要此标签。
  • 初始化顺序：
    1. 在后台线程上调用 MobileAds.initialize()。
    2. 确保在调用任何其他 SDK 方法之前调用 initialize()。
    3. 如果使用 RequestConfiguration，请将其传入 InitializationConfig.Builder.setRequestConfiguration()。不要 在初始化前调用 MobileAds.setRequestConfiguration()。
  • UI 线程：必须：GMA-Next Gen SDK 的回调会在后台线程上执行。所有 与 UI 相关的操作（例如 Toast、View 更新、Fragment 事务）都必须 在 GMA SDK 回调中通过 runOnUiThread {} 或 Dispatchers.Main.launch {} 包装。跳过此步骤会导致应用崩溃。
  • 中介：实现 com.google.android.gms.ads.mediation.Adapter 的类必须继续使用 com.google.android.gms.ads。

格式特定说明

横幅广告
  • 使用 com.google.android.libraries.ads.mobile.sdk.banner.AdView 加载 GMA Next-Gen SDK 横幅广告。
  • 以下 API 可检查横幅广告是否可折叠： adView.getBannerAd().isCollapsible()。
原生广告
  • NativeAdLoader：NativeAdLoader 是抽象类，无法实例化。 它以静态方式使用（例如 NativeAdLoader.load(...)）。
  • 以下 API 现在设置在 NativeAdRequest.Builder 上：
    • .setCustomFormatIds(customFormatIds: List<String>)
    • .disableImageDownloading()
    • .setMediaAspectRatio(mediaAspectRatio: NativeMediaAspectRatio)
    • .setAdChoicesPlacement(adChoicesPlacement: AdChoicesPlacement)
    • .setVideoOptions(videoOptions: VideoOptions)
  • 移除：删除所有“静音此广告”逻辑；GMA Next-Gen SDK 不支持此功能。
  • MediaView：NativeAd 不再具有直接的 mediaView 变量；使用 registerNativeAd(nativeAd, mediaView) 将广告与视图关联。
广告预加载
  • 除非映射表中另有说明，否则 GMA Next-Gen SDK 中的广告预加载方法保留与 旧版 SDK 相同的 API 签名和参数。

API 映射

此表涵盖主要类及其在 GMA Next-Gen SDK 中的对应项。

功能旧版 SDK 导入（com.google.android.gms.ads...）GMA Next-Gen SDK 导入（com.google.android.libraries.ads.mobile.sdk... ）
核心
初始化MobileAdsMobileAds、initialization.InitializationConfig
初始化监听器initialization.OnInitializationCompleteListenerinitialization.OnAdapterInitializationCompleteListener
广告请求AdRequest特定格式（例如，common.AdRequest、banner.BannerAdRequest、nativead.NativeAdRequest）（广告单元 ID 在 Builder 中声明。Load() 不再接收 Activity）
加载错误LoadAdErrorcommon.LoadAdError（LoadAdError 不再包含 domain 变量。若存在，请移除 domain 变量。）
全屏展示错误AdError（位于 FullScreenContentCallback 中）common.FullScreenContentError（位于特定格式的 AdEventCallback 中）
请求配置RequestConfigurationcommon.RequestConfiguration（RequestConfiguration 的嵌套枚举/常量现在位于 common.RequestConfiguration 下。）
事件回调FullScreenContentCallback（用于全屏格式）、AdListener（横幅、原生）特定格式（例如，interstitial.InterstitialAdEventCallback、banner.BannerAdEventCallback、native.NativeAdEventCallback）。广告格式上的变量为 adEventCallback。
工具
广告检查器MobileAds.openAdInspector()MobileAds.openAdInspector()（openAdInspector 不再接收 Activity）
广告检查器监听器OnAdInspectorClosedListenercommon.OnAdInspectorClosedListener
格式
应用启动appopen.AppOpenAdappopen.AppOpenAd
应用启动加载appopen.AppOpenAd.AppOpenAdLoadCallbackcommon.AdLoadCallback<appopen.AppOpenAd>
横幅AdView、AdSizebanner.AdView、banner.AdSize（AdView 不再包含 pause()、resume()、setAdSize()。）AdSize 在 BannerAdRequest 中声明。
横幅加载AdListenercommon.AdLoadCallback<banner.BannerAd>
横幅事件AdListenerbanner.BannerAdEventCallback、banner.BannerAdRefreshCallback
插页式interstitial.InterstitialAdinterstitial.InterstitialAd
插页式加载interstitial.InterstitialAd.InterstitialAdLoadCallbackcommon.AdLoadCallback<interstitial.InterstitialAd>
广告加载器AdLoadernativead.NativeAdLoader
原生nativead.NativeAdnativead.NativeAd（不再包含 mediaView 变量）
原生自定义格式广告nativead.NativeCustomFormatAdnativead.CustomNativeAd
原生自定义点击nativead.NativeCustomFormatAd.OnCustomClickListenernativead.OnCustomClickListener（在 CustomNativeAd 对象上设置，例如 .onCustomClickListener）
原生加载nativead.NativeAd.OnNativeAdLoadedListenernativead.NativeAdLoaderCallback
原生广告视图nativead.NativeAdViewnativead.NativeAdView
媒体内容MediaContentnativead.MediaContent（hasVideoContent 声明为 val）
媒体宽高比MediaAspectRationativead.MediaAspectRatio
视频选项VideoOptionscommon.VideoOptions
视频控制器VideoControllercommon.VideoController（VideoLifecycleCallbacks 现在是一个接口，因此请使用 object : VideoController.VideoLifecycleCallbacks { ... } 实例化）
激励式rewarded.RewardedAdrewarded.RewardedAd
激励式加载rewarded.RewardedAd.RewardedAdLoadCallbackcommon.AdLoadCallback<rewarded.RewardedAd>
激励式插页广告rewardedinterstitial.RewardedInterstitialAdrewardedinterstitial.RewardedInterstitialAd
激励式插页广告加载rewardedinterstitial.RewardedInterstitialAd.RewardedInterstitialAdLoadCallbackcommon.AdLoadCallback<rewardedinterstitial.RewardedInterstitialAd>
付费事件监听器OnPaidEventListenercommon.AdEventCallback
响应信息ResponseInfocommon.ResponseInfo
适配器响应信息AdapterResponseInfocommon.AdSourceResponseInfo
奖励
奖励监听器OnUserEarnedRewardListenerrewarded.OnUserEarnedRewardListener
奖励项rewarded.RewardItemrewarded.RewardItem（现在通过 RewardedAd 和 RewardedInterstitialAd 上的 getRewardItem() 访问属性）
广告价值AdValuecommon.AdValue
预加载
配置preload.PreloadConfigurationcommon.PreloadConfiguration
回调preload.PreloadCallbackV2common.PreloadCallback（现在是接口，而不是抽象类）
插页式预加载器interstitial.InterstitialPreloaderinterstitial.InterstitialAdPreloader
Ad Manager
广告请求admanager.AdManagerAdRequestcommon.AdRequest（现在直接在 AdRequest 类中实现）
广告视图admanager.AdViewbanner.AdView（没有 AdManagerAdView 类）
应用事件监听器admanager.AppEventListenercommon.OnAppEventListener

方法映射

此表涵盖主要方法及其对应的 GMA Next-Gen SDK 方法。

功能旧版 SDK 方法签名GMA Next-Gen SDK 方法签名
核心
MobileAds 初始化MobileAds.initialize(Context context, OnInitializationCompleteListener listener)MobileAds.initialize(Context context, InitializationConfig config, OnInitializationCompleteListener listener)
InitializationConfig 构建器不适用InitializationConfig.Builder(String applicationId)
广告请求构建器AdRequest.Builder().build()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()
添加网络扩展（AdMobAdapter）AdRequest.Builder().addNetworkExtrasBundle(Class<MediationExtrasReceiver>, Bundle networkExtras)AdRequest.Builder(String adUnitId).setGoogleExtrasBundle(Bundle extraBundle)
添加网络扩展（广告来源适配器）AdRequest.Builder().addNetworkExtrasBundle(Class<MediationExtrasReceiver>, Bundle networkExtras)AdRequest.Builder(String adUnitId).putAdSourceExtrasBundle(Class<MediationExtrasReceiver> adapterClass, Bundle adSourceExtras)
自定义定向AdRequest.Builder().setCustomTargeting(String key, String value)AdRequest.Builder(String adUnitId).putCustomTargeting(String key, String value)
格式
App OpenAppOpenAd.load(Context context, String adUnitId, AdRequest request, AppOpenAdLoadCallback loadCallback)AppOpenAd.load(AdRequest request, AdLoadCallback<AppOpenAd> loadCallback)
BannerAdView.loadAd(AdRequest request)AdView.loadAd(BannerAdRequest request, AdLoadCallback<BannerAd> loadCallback)
InterstitialInterstitialAd.load(Context context, String adUnitId, AdRequest request, InterstitialAdLoadCallback loadCallback)InterstitialAd.load(AdRequest request, AdLoadCallback<InterstitialAd> loadCallback)
RewardedRewardedAd.load(Context context, String adUnitId, AdRequest request, RewardedAdLoadCallback loadCallback)RewardedAd.load(AdRequest request, AdLoadCallback<RewardedAd> loadCallback)
Rewarded InterstitialRewardedInterstitialAd.load(Context context, String adUnitId, AdRequest request, RewardedInterstitialAdLoadCallback loadCallback)RewardedInterstitialAd.load(AdRequest request, AdLoadCallback<RewardedInterstitialAd> loadCallback)
Native 构建器AdLoader.Builder(Context context, String adUnitId).forNativeAd(NativeAd.OnNativeAdLoadedListener onNativeAdLoadedListener)NativeAdRequest.Builder(String adUnitId, nativeAdTypes: List<NativeAdType>)（在 nativeAdTypes 中包含 NativeAd.NativeAdType.NATIVE）
Native 加载AdLoader.Builder(...).build().loadAd(AdRequest request)NativeAdLoader.load(NativeAdRequest request, NativeAdLoaderCallback callback)
Native 广告注册NativeAdView.setNativeAd(NativeAd nativeAd)NativeAdView.registerNativeAd(NativeAd nativeAd, mediaView: MediaView?)
设置应用事件监听器（Banner）AdManagerAdView.appEventListenerBannerAd.adEventCallback（onAppEvent(name: String, data: String?) 现在属于 BannerAdEventCallback 的一部分）
设置应用事件监听器（Interstitial）AdManagerInterstitialAd.appEventListenerInterstitialAd.adEventCallback（onAppEvent(name: String, data: String?) 现在属于 InterstitialAdEventCallback 的一部分）
回调
onAdOpenedAdListener.onAdOpened()AdEventCallback.onAdShowedFullScreenContent()
onAdClosedAdListener.onAdClosed()AdEventCallback.onAdDismissedFullScreenContent()
onFailedToShowFullScreenContentonAdFailedToShowFullScreenContent(adError: AdError)onAdFailedToShowFullScreenContent(fullScreenContentError: FullScreenContentError)
onAdLoadedAdLoadCallback：onAdLoaded(ad: T)（例如 InterstitialAdLoadCallback、RewardedAdLoadCallback、RewardedInterstitialAdLoadCallback）参数名称始终为 ad 特定格式：onAdLoaded(ad: InterstitialAd)、onAdLoaded(ad: RewardedAd)、onAdLoaded(ad: RewardedInterstitialAd)
onAdFailedToLoadonAdFailedToLoad(loadAdError: LoadAdError)onAdFailedToLoad(adError: LoadAdError)
onCustomFormatAdLoadedOnCustomFormatAdLoadedListener.onCustomFormatAdLoaded(NativeCustomFormatAd ad)NativeAdLoaderCallback.onCustomNativeAdLoaded(CustomNativeAd customNativeAd)
onPaidEventListenerOnPaidEventListener.onPaidEvent(AdValue value)AdEventCallback.onAdPaid(value: AdValue)（特定格式，例如 banner.BannerAdEventCallback.onAdPaid(value: AdValue)）
onVideoMuteonVideoMute(muted: Boolean)onVideoMute(isMuted: Boolean)
onAdPreloadedonAdPreloaded(preloadId: String, responseInfo: ResponseInfo?)onAdPreloaded(preloadId: String, responseInfo: ResponseInfo)
预加载
配置PreloadConfiguration.Builder(String adUnitId).build()PreloadConfiguration(AdRequest request)
响应信息
获取响应信息ad.responseInfoad.getResponseInfo()
已加载的适配器响应信息responseInfo.getLoadedAdapterResponseInfo()responseInfo.loadedAdSourceResponseInfo
获取适配器响应responseInfo.getAdapterResponses()responseInfo.adSourceResponses
获取中介适配器类responseInfo.getMediationAdapterClassName()responseInfo.adapterClassName
适配器响应信息
广告来源 IDAdapterResponseInfo.getAdSourceId()AdSourceResponseInfo.id
广告来源名称AdapterResponseInfo.getAdSourceName()AdSourceResponseInfo.name
广告来源实例 IDAdapterResponseInfo.getAdSourceInstanceId()AdSourceResponseInfo.instanceId
广告来源实例名称AdapterResponseInfo.getAdSourceInstanceName()AdSourceResponseInfo.instanceName

评论

支持 Markdown