Google Mobile Ads Next-Gen 安卓横幅广告集成指南Android Banner Ads【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读本文基于skills/ads/google-mobile-ads-banner技能集中的 Android 平台参考文档系统讲解如何在 Android 应用中通过 GMA Next-Gen SDKcom.google.android.libraries.ads.mobile.sdk实现 Banner横幅广告的完整流程从定义AdView、选择自适应广告尺寸、注册加载回调到调用loadAd()加载广告并覆盖构建验证与测试广告单元替换等上线前关键步骤。阅读完本文后你将能独立为 Android 应用接入大型锚定自适应横幅、内联自适应横幅等主流 Banner 广告位并规避 GMA Next-Gen SDK 中最容易导致崩溃的 UI 线程回调陷阱。Banner 广告类型速览在动手编码前先明确 Banner 广告的类型。根据 SKILL.md 中的定义Android 平台常用的 Banner 广告分为三类Banner 类型说明Large Anchored Adaptive大型锚定自适应默认推荐类型可锚定在屏幕顶部或底部宽度可自适应。Anchored Adaptive锚定自适应同样可锚定在屏幕顶部或底部但高度更矮。Inline Adaptive内联自适应仅 Android 与 iOS 可用嵌入在内容流中随内容滚动。默认策略是用户只说 banner 而未指定类型时优先使用Large Anchored Adaptive若用户反馈大型锚定横幅过高则回退到高度更矮的锚定自适应类型。前置条件GMA Next-Gen SDK 集成Banner 广告代码依赖 GMA Next-Gen SDK。按照 android-get-started.md 的指引集成前需完成添加 SDK 依赖在 app 级构建文件中引入最新稳定版com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk若无法直接访问 Maven可执行以下命令查询最新版本号latest标签即最新版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配置 SDK 版本minSdk需为 24compileSdk需为 34。排除旧版广告依赖在全局依赖中排除play-services-ads与play-services-ads-lite避免重复符号错误。初始化 SDK使用MobileAds.initialize()在后台线程完成初始化InitializationConfig.Builder中传入 AdMob App ID测试用ca-app-pub-3940256099942544~3347511713发布前必须替换为真实 App ID。Required Imports横幅广告所需导入根据 android-banner.md 的要求实现横幅广告需要以下导入语句import com.google.android.libraries.ads.mobile.sdk.banner.AdSize import com.google.android.libraries.ads.mobile.sdk.banner.AdView import com.google.android.libraries.ads.mobile.sdk.banner.BannerAd import com.google.android.libraries.ads.mobile.sdk.banner.BannerAdRequest import com.google.android.libraries.ads.mobile.sdk.common.AdLoadCallback import com.google.android.libraries.ads.mobile.sdk.common.LoadAdError关键类型职责如下AdView用于定义横幅广告的视图容器是 Next-Gen SDK 中定义横幅的唯一入口旧版BannerAd已废弃。BannerAdRequest广告请求对象承载广告单元 IDad unit ID与AdSize。BannerAd加载成功后的横幅广告对象。AdLoadCallbackT广告加载回调接口。LoadAdError广告加载失败时携带的错误信息对象。核心方法签名1. 构建广告请求BannerAdRequest通过Builder接收广告单元 ID 与AdSizeBannerAdRequest.Builder(adUnitId: String, adSize: AdSize).build()注意AdSize与广告单元 ID 应通过BannerAdRequest.Builder传入而不是直接设置在AdView上。2. 加载横幅广告从AdView加载横幅广告的方法签名fun loadAd( adRequest: BannerAdRequest, adLoadCallback: AdLoadCallbackBannerAd ): UnitAdLoadCallback同样是通过loadAd()方法传入而非直接设置在AdView上。3. 广告加载回调接口interface AdLoadCallbackT { fun onAdLoaded(ad: T): Unit fun onAdFailedToLoad(adError: LoadAdError): Unit }onAdLoaded(ad)广告加载成功后回调ad为BannerAd实例。onAdFailedToLoad(adError)广告加载失败时回调adError为LoadAdError可用于排查失败原因。关键陷阱UI 线程强制约束这是 GMA Next-Gen SDK 与旧版 SDK 最大的行为差异也是 android-banner.md 中特别标注为MANDATORY的注意事项GMA Next-Gen SDK 的AdLoadCallback回调运行在后台线程。所有 UI 相关操作如 Toast 提示、View 更新、Fragment 事务必须在runOnUiThread {}或Dispatchers.Main.launch {}中执行。跳过此步骤将导致应用崩溃。正确写法示例adView.loadAd(adRequest, object : AdLoadCallbackBannerAd { override fun onAdLoaded(ad: BannerAd) { runOnUiThread { // 在此更新 UI如显示 BannerAdView binding.bannerContainer.addView(ad.adView) } } override fun onAdFailedToLoad(adError: LoadAdError) { runOnUiThread { Toast.makeText(context, 广告加载失败: ${adError.message}, Toast.LENGTH_SHORT).show() } } })这一约束在 Unity 平台同样存在Unity 参考文档 unity-banner.md 明确要求所有涉及UnityEngine对象的回调必须通过MobileAdsEventExecutor.ExecuteInUpdate()调度到主线程因为 Unity API 非线程安全。Banner 广告五步工作流以下是 android-banner.md 给出的完整实施流程。第 1 步定义广告视图使用AdView定义 GMA Next-Gen SDK 横幅广告不要使用已废弃的BannerAd来定义视图。val adView AdView(context)第 2 步设置广告尺寸测试宽度建议为测试目的将AdSize使用的width设为360也可以使用设备实际宽度这也是常见做法。按广告类型选择对应方法同时使用对应的测试广告单元 IDca-app-pub-3940256099942544/9214589741广告类型尺寸方法大型锚定自适应横幅默认AdSize.getLargeAnchoredAdaptiveBannerAdSize(context, width)锚定自适应横幅当大型锚定过高时使用AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(context, width)内联自适应横幅AdSize.getCurrentOrientationInlineAdaptiveBannerAdSize(context, width)将AdSize与广告单元 ID 传入BannerAdRequest.Builder而不是直接设置在AdView上。val width 360 val adSize AdSize.getLargeAnchoredAdaptiveBannerAdSize(context, width) val adRequest BannerAdRequest.Builder( adUnitId ca-app-pub-3940256099942544/9214589741, adSize adSize ).build()第 3 步注册广告加载事件在loadAd()方法中传入AdLoadCallback实现而不是直接设置在AdView上见上文回调接口定义。第 4 步加载横幅广告adView.loadAd(adRequest, object : AdLoadCallbackBannerAd { override fun onAdLoaded(ad: BannerAd) { /* runOnUiThread 中更新 UI */ } override fun onAdFailedToLoad(adError: LoadAdError) { /* runOnUiThread 中处理失败 */ } })第 5 步验证实现执行gradle build -x test确认构建成功并解决所有与 GMA SDK 相关的编译错误gradle build -x test发布前必做替换测试广告单元Banner 广告工作流完成后SKILL.md 要求提醒用户将测试广告单元 ID 替换为自有 ID。这对应google-mobile-ads-validate技能的校验规则测试广告单元判定任何以ca-app-pub-3940256099942544/开头的 AdMob 广告单元 ID 均为测试 IDad-units.md。合法格式校验AdMob 广告单元 ID 必须匹配正则^(ca-app-pub-[a-zA-Z0-9\-])/([a-zA-Z0-9_\-])(/.*)?$格式错误即判为Fail源码中出现测试 ID即使被DEBUG开关保护也会给出Warning。App ID 校验AdMob App ID 必须匹配^(ca-app-pub-[a-zA-Z0-9\-])~(.*)$官方测试 App ID 为ca-app-pub-3940256099942544~1458002511发布前需替换application-id.md。因此生产环境的广告单元 ID 应形如ca-app-pub-你的发布者ID/你的广告位IDApp ID 形如ca-app-pub-你的发布者ID~你的应用ID。与 iOS / Unity 平台的对应关系同为 Banner 广告集成不同平台的 API 形态略有差异便于多端维护时对照参考步骤Android本文iOSios-banner.mdUnityunity-banner.md广告视图AdViewBannerViewrootViewController可选可传nilBannerViewGoogleMobileAds.Api测试广告单元 IDca-app-pub-3940256099942544/9214589741ca-app-pub-3940256099942544/2435281174按平台分别使用上述两个 ID测试宽度360375MobileAds.Utils.GetDeviceSafeWidth()大型锚定自适应尺寸getLargeAnchoredAdaptiveBannerAdSizelargeAnchoredAdaptiveBanner(width:)GetCurrentOrientationLargeAnchoredAdaptiveBannerAdSizeWithWidth(width)加载事件loadAd()传入AdLoadCallback设置delegate订阅OnBannerAdLoaded等事件可选加载广告loadAd(adRequest, callback)调用加载方法bannerView.LoadAd(new AdRequest())构建验证gradle build -x testxcodebuild不可用时在 Xcode 中手动验证dotnet build编译 csproj其中 iOS 的尺寸全局函数还包括与 Android 对应的currentOrientationAnchoredAdaptiveBanner(width:)大型锚定过高时使用与currentOrientationInlineAdaptiveBanner(width:)内联自适应Unity 的事件订阅还涵盖OnAdPaid记录预估广告收入、OnAdImpressionRecorded统计展示与OnAdFullScreenContentOpened/Closed暂停/恢复游戏逻辑等可作为跨端实现时的参考清单。小结Android 平台集成 GMA Next-Gen SDK 横幅广告的要点可概括为使用AdView定义视图、通过BannerAdRequest.Builder(adUnitId, adSize)组装请求、按广告类型选择自适应尺寸方法、在loadAd()中传入AdLoadCallback并始终在回调内用runOnUiThread包裹 UI 操作。最后以gradle build -x test验证构建并在发布前将测试广告单元 ID 与测试 App ID 替换为自有值。掌握这套流程后即可为应用稳定接入自适应横幅广告位。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考