Google Mobile Ads Next-Gen 安卓横幅广告集成指南（Android Banner Ads）

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 SDK（com.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；若用户反馈大型锚定横幅过高，则回退到高度更矮的锚定自适应类型。

前置条件：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需为 24+，compileSdk需为 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：广告请求对象，承载广告单元 ID（ad unit ID）与AdSize。
• BannerAd：加载成功后的横幅广告对象。
• AdLoadCallback<T>：广告加载回调接口。
• LoadAdError：广告加载失败时携带的错误信息对象。

核心方法签名

1. 构建广告请求

BannerAdRequest通过Builder接收广告单元 ID 与AdSize：

BannerAdRequest.Builder(adUnitId: String, adSize: AdSize).build()

注意：AdSize与广告单元 ID 应通过BannerAdRequest.Builder传入，而不是直接设置在AdView上。

2. 加载横幅广告

从AdView加载横幅广告的方法签名：

fun loadAd( adRequest: BannerAdRequest, adLoadCallback: AdLoadCallback<BannerAd> ): Unit

AdLoadCallback同样是通过loadAd()方法传入，而非直接设置在AdView上。

3. 广告加载回调接口

interface AdLoadCallback<T> { 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 : AdLoadCallback<BannerAd> { 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与广告单元 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 : AdLoadCallback<BannerAd> { 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 均为测试 ID（ad-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/你的广告位ID，App ID 形如ca-app-pub-你的发布者ID~你的应用ID。

与 iOS / Unity 平台的对应关系

同为 Banner 广告集成，不同平台的 API 形态略有差异，便于多端维护时对照参考：

其中 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