基于 Google Mobile Ads SDK 的 Unity 横幅广告（Banner Ads）接入与实现指南-创锋一号

基于 Google Mobile Ads SDK 的 Unity 横幅广告（Banner Ads）接入与实现指南

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

本文以本仓库 google-mobile-ads-banner 技能为骨架，完整讲解在 Unity 工程中使用 Google Mobile Ads（GMA）SDK 实现横幅广告（Banner Ads）的五个标准步骤：定义广告视图、设置广告尺寸、注册加载事件、加载广告与编译验证。读者读完将掌握 BannerView 的完整用法、自适应横幅尺寸的选取策略、广告回调必须在主线程调度的硬性要求，以及上线前替换测试广告单元 ID 的检查清单。

前置准备：Unity 工程中的 GMA SDK 集成

在实现横幅广告之前，需要先确认 Unity 工程已正确集成 Google Mobile Ads SDK。本仓库提供了独立的 unity-get-started.md 指南，其中明确了三个关键步骤：

通过 OpenUPM 引入 SDK 依赖：修改Packages/manifest.json，加入com.google作用域的 OpenUPM scoped registry，并在dependencies中声明com.google.ads.mobile（示例版本为11.2.0，实际以 OpenUPM 上发布的最新稳定版为准）。
设置应用标识符（App ID）：修改Assets/GoogleMobileAds/Resources/GoogleMobileAdsSettings.asset，设置adMobAndroidAppId与adMobIOSAppId。官方样例 App ID 为 Androidca-app-pub-3940256099942544~3347511713、iOSca-app-pub-3940256099942544~1458002511，正式发布前必须替换为自己的 AdMob App ID。
初始化 SDK：调用MobileAds.Initialize()，并且不要将MobileAds.RaiseAdEventsOnUnityMainThread设置为true（该 API 已废弃）。

同时需要特别注意：SDK 初始化等后台回调若需要操作 Unity 对象，必须通过MobileAdsEventExecutor.ExecuteInUpdate()显式调度到主线程执行——这与下文横幅广告回调的处理原则完全一致。

横幅广告类型与选择策略

横幅广告（Banner Ads）是矩形的图片或文字广告，占据应用布局中的固定位置，在用户交互期间保持展示并可自动刷新。在开始写代码前，应先根据 SKILL.md 中给出的类型矩阵确定广告形态：

广告类型	说明
Large Anchored Adaptive（大号锚定自适应）	默认推荐。可锚定在屏幕顶部或底部，高度较大、展示效果更好。
Anchored Adaptive（锚定自适应）	可锚定在屏幕顶部或底部，高度较小。
Inline Adaptive（内联自适应）	仅适用于 Android 和 iOS，放置于滚动内容流内部。

SKILL.md 明确建议：当用户只说"banner"而未指定类型时，默认选择 Large Anchored Adaptive；若用户反馈大号锚定自适应横幅过高，再降级为普通锚定自适应。这一点在 Unity 端同样适用（Unity 端不支持 Inline Adaptive，因为它是仅限 Android/iOS 的特性）。

必需的命名空间导入

在 Unity 中实现横幅广告，需要导入以下命名空间：

using System; using UnityEngine; using GoogleMobileAds.Api; using GoogleMobileAds.Common;

GoogleMobileAds.Api：提供BannerView、AdRequest、AdSize、AdPosition等核心类型；
GoogleMobileAds.Common：提供MobileAdsEventExecutor等主线程调度工具；
UnityEngine：用于在回调中安全操作游戏对象与 UI。

第一步：定义广告视图（BannerView）

横幅广告使用GoogleMobileAds.Api命名空间下的BannerView类来定义。创建BannerView时需要传入广告单元 ID（ad unit ID）、广告尺寸（AdSize）与广告位置（AdPosition）。

创建广告视图时应使用测试广告单元 ID，本仓库 unity-banner.md 给出了两个官方测试 ID：

平台	测试广告单元 ID
Android（锚定自适应）	`ca-app-pub-3940256099942544/9214589741`
iOS（锚定自适应）	`ca-app-pub-3940256099942544/2435281174`

注意：测试广告单元 ID 前缀为ca-app-pub-3940256099942544/。正式上架前必须替换成自己在 AdMob 后台创建的广告单元 ID，具体校验规则可参见仓库中的 ad-units.md（它同时给出了 AdMob 与 Ad Manager 广告单元 ID 的格式校验正则）。

第二步：设置广告尺寸与位置

尺寸选择

BannerView构造函数接受AdSize.Banner（标准横幅），也可以传入自适应（adaptive）尺寸。对于锚定自适应横幅，应优先使用大号锚定自适应尺寸，除非用户反馈高度过大或确实需要更小的尺寸。

计算大号锚定自适应尺寸的标准做法是：先用MobileAds.Utils.GetDeviceSafeWidth()获取设备安全区宽度，再基于该宽度构造对应方向的尺寸：

int width = MobileAds.Utils.GetDeviceSafeWidth(); AdSize adSize = AdSize .GetCurrentOrientationLargeAnchoredAdaptiveBannerAdSizeWithWidth(width); BannerView bannerView = new BannerView(_adUnitId, adSize, AdPosition.Bottom);

GetDeviceSafeWidth()：返回设备当前安全区域的可用宽度（已考虑刘海屏等安全区约束），确保横幅宽度不会超出可视区域；
GetCurrentOrientationLargeAnchoredAdaptiveBannerAdSizeWithWidth(width)：根据当前设备方向计算大号锚定自适应横幅的尺寸。自适应横幅的高度会随设备与方向动态变化，宽度则固定为你传入的值。

位置选择

位置通过AdPosition枚举指定，常见取值包括AdPosition.Top与AdPosition.Bottom，分别锚定在屏幕顶部与底部（与锚定自适应横幅的定义一致）。

第三步：注册广告加载与交互事件

在BannerView对象上订阅广告事件是可选的，取决于应用的实际需求。本仓库文档列出了七个常用事件及其典型用途：

事件	典型用途
`OnBannerAdLoaded`	横幅广告加载完成并展示时更新 UI 状态
`OnBannerAdLoadFailed`	广告加载失败时记录错误日志
`OnAdPaid`	记录估算广告收入（`AdValue`），用于展示级变现跟踪
`OnAdImpressionRecorded`	在内部遥测或第三方分析平台中跟踪广告展示
`OnAdClicked`	记录用户对广告的点击
`OnAdFullScreenContentOpened`	点击横幅跳转全屏落地页时，暂停游戏音频、计时器或游戏循环
`OnAdFullScreenContentClosed`	全屏落地页关闭时，恢复游戏音频或游戏循环

关键约束：回调必须调度到主线程

CRITICAL（强制要求）：Unity 的 API 不是线程安全的，GMA SDK 的广告回调可能运行在后台线程。任何在回调中操作UnityEngine对象的代码，都必须通过MobileAdsEventExecutor.ExecuteInUpdate()显式调度到主线程执行。忽略这一步会导致随机崩溃或 UI 状态异常。

bannerView.OnBannerAdLoaded += () => { MobileAdsEventExecutor.ExecuteInUpdate(() => { // 在主线程中安全地操作 UnityEngine 对象。 }); };

这一约束与本仓库 unity-get-started.md 中 SDK 初始化回调的处理方式完全一致：由于RaiseAdEventsOnUnityMainThread已废弃，主线程调度必须由开发者显式完成。

第四步：加载横幅广告

定义好BannerView并注册事件后，调用LoadAd()方法并传入一个新的AdRequest对象即可触发加载：

bannerView.LoadAd(new AdRequest());

AdRequest用于封装本次请求的定向信息（如需个性化配置可继续扩展），空构造即可发起一次标准的横幅广告请求。加载结果会通过第三步注册的OnBannerAdLoaded/OnBannerAdLoadFailed回调通知应用。

第五步：验证实现（编译检查）

完成代码编写后，需要对 Unity 生成的 csproj 工程执行编译验证：

dotnet build

编译通过后，逐一解决所有与 GMA SDK 相关的编译错误。如果编译失败，优先检查：命名空间是否完整导入、BannerView构造函数参数类型是否匹配、事件订阅写法是否正确。

（注：若工程同时包含 Android / iOS 原生实现，对应的验证方式分别见仓库中的 android-banner.md 与 ios-banner.md，前者使用gradle build -x test，后者使用xcodebuild。）

上线前检查：替换测试广告单元 ID

SKILL.md 的工作流最后一步明确要求：横幅广告实现完成后，必须提醒用户将测试广告单元 ID 替换为真实广告单元 ID。结合仓库 ad-units.md 的校验规则，上线前可按下述标准自检：

测试 ID 检查：源码中是否仍残留ca-app-pub-3940256099942544/前缀的 AdMob 测试 ID，或/6499/、/21775744923/前缀的 Ad Manager 测试 ID；即使测试 ID 被DEBUG标志门控，也应给出警告；
格式检查：AdMob 广告单元 ID 应符合^(ca-app-pub-[a-zA-Z0-9\-]+)/([a-zA-Z0-9_\-]+)(/.*)?$正则，Ad Manager 广告单元 ID 应符合^/[0-9]*/.*|^/[0-9]*,[0-9]*/.*正则。

企业官网建设流程全解析