1. 项目概述：为什么需要一个可复用的广告管理模块？

在移动游戏和应用开发中，广告变现是绝大多数开发者绕不开的核心环节。无论是为了增加收入来源，还是平衡免费玩家的体验，广告的集成与管理都至关重要。然而，很多团队，尤其是中小型团队或独立开发者，在初期往往会采取一种“快速实现”的策略：直接把Unity Ads的SDK拖进项目，在需要展示广告的地方调用几行API，然后祈祷它能正常工作。

这种做法在项目初期或许可行，但随着项目迭代、广告位增加、需要接入多家广告平台（如AdMob、AppLovin等）进行聚合时，问题就会集中爆发。你会发现，广告代码像藤蔓一样缠绕在游戏逻辑的各个角落，修改一个广告格式需要搜索整个项目，测试广告逻辑变得异常困难，更别提应对不同平台SDK的初始化、回调处理等差异性带来的维护噩梦。

这正是“构建可复用的广告管理模块”这个项目的核心价值所在。它不是一个简单的API封装，而是一个系统性的工程解决方案。其目标是将广告功能从游戏业务逻辑中彻底解耦，形成一个独立、健壮、可配置、易测试的中间层。通过这个模块，开发者可以像使用游戏内的音频管理器或资源加载器一样，以统一、简洁的接口调用各种广告，而无需关心底层是Unity Ads还是其他平台。这不仅提升了开发效率，降低了出错概率，更为未来的商业化策略调整（如A/B测试不同广告平台的填充率和eCPM）奠定了坚实的技术基础。

2. 模块核心架构设计

一个优秀的广告管理模块，其架构设计必须遵循高内聚、低耦合的原则，并充分考虑扩展性、可测试性和易用性。下面是我在实践中总结出的一套分层架构。

2.1 分层架构解析

整个模块可以清晰地划分为四个层次：接口层、管理层、适配器层和平台层。

接口层是面向游戏逻辑的“服务窗口”。它定义了一套与具体广告平台无关的、面向业务的抽象接口。例如，IAdService接口会提供ShowRewardedAd(string placementId, Action<bool> onCompleted)这样的方法。游戏代码只需要知道“请求播放一个激励视频”，并通过回调得知“用户是否成功观看并应获得奖励”，完全不用管这个视频来自哪里。这一层确保了游戏核心逻辑的纯净与稳定。

管理层是模块的“大脑”和“调度中心”。它负责广告系统的生命周期管理，包括：

• 初始化管理：按需或按序初始化一个或多个广告平台SDK。
• 配置管理：从本地配置文件（如JSON、ScriptableObject）或远程服务器加载广告位ID、频率控制策略、平台权重等配置信息。
• 策略执行：根据配置决定当前请求应该分配给哪个广告平台（在聚合场景下）。例如，实现一个简单的瀑布流或实时竞价（Bidding）逻辑。
• 全局事件与状态：维护广告是否准备好、是否正在展示等全局状态，并提供相应的事件供游戏逻辑订阅。

适配器层是关键的“翻译官”和“适配器”。它为每一个集成的第三方广告平台（如UnityAdsAdapter, AdMobAdapter）实现统一的接口层契约。每个适配器内部封装了该平台SDK特有的初始化流程、广告加载、展示、回调监听以及错误处理逻辑。这样，当某个平台SDK的API发生变更时，你只需要修改对应的适配器，而游戏代码和上层管理逻辑完全不受影响。

平台层即各个广告平台官方的SDK，如Unity Ads SDK、Google Mobile Ads SDK等。我们的模块通过适配器层与它们交互，将它们视为提供具体服务的“供应商”。

2.2 关键设计模式应用

在这个架构中，几个设计模式起到了至关重要的作用：

• 桥接模式：接口层与适配器层的关系就是典型的桥接模式。抽象（广告服务）与实现（具体平台）分离，可以独立变化。
• 策略模式：在管理层进行广告平台选择时（比如是优先展示高eCPM的广告，还是优先展示准备好最快的广告），可以使用策略模式来灵活切换选择算法。
• 观察者模式：广告的各种回调（加载成功、展示完成、奖励发放）本质上都是事件，非常适合用C#的event或UnityEvent来实现，让游戏逻辑模块订阅自己关心的事件，实现松耦合通信。
• 单例模式（谨慎使用）：广告管理模块通常在整个游戏生命周期中只需要一个实例。可以使用一个经过封装的服务定位器或依赖注入框架来提供全局访问点，而非简单的静态单例，以提高可测试性。

注意：避免在适配器层或管理层中编写过多的游戏业务逻辑。例如，发放玩家奖励（如金币、道具）的逻辑应该在订阅了广告回调的游戏逻辑模块中处理，而不是在广告适配器内部。这保持了模块的职责单一。

3. Unity Ads适配器深度实现

以Unity Ads为例，它是Unity引擎生态内的首选变现方案之一，集成相对顺畅。但即便如此，一个健壮的适配器也需要考虑诸多细节。

3.1 初始化与元数据配置

Unity Ads的初始化需要在游戏启动早期完成，通常是在一个不销毁的GameObject的Awake或Start方法中。初始化需要两个关键参数：gameId（iOS和Android不同）和testMode。

// 在UnityAdsAdapter的初始化方法中 public void Initialize(string gameIdiOS, string gameIdAndroid, bool enableTestMode) { #if UNITY_IOS string gameId = gameIdiOS; #elif UNITY_ANDROID string gameId = gameIdAndroid; #else string gameId = “”; #endif if (!Advertisement.isInitialized) { Advertisement.Initialize(gameId, enableTestMode, this); } // ... 其他初始化后逻辑，如预加载广告 }

这里有一个关键细节：testMode在开发阶段务必开启，它会让你看到测试广告，避免因误点真实广告导致账户问题。但如何区分开发环境和生产环境？我推荐使用自定义的编译符号（如DEVELOPMENT_BUILD）或通过一个可配置的ScriptableObject资产来动态控制，而不是手动修改代码。

3.2 广告加载与缓存策略

Unity Ads SDK对于激励视频和插页式广告（Interstitial）采用了“按需加载”的机制，即在调用Advertisement.Load(placementId)时才开始加载。但为了提供最佳用户体验（广告点击后立即播放，无等待），我们需要实现一个预加载策略。

在适配器初始化后，或某个广告位展示完成后，立即异步加载下一个广告。我们可以维护一个字典来记录每个广告位的加载状态。

private Dictionary<string, bool> _adReadyStatus = new Dictionary<string, bool>(); public void LoadAd(string placementId) { if (_adReadyStatus.ContainsKey(placementId) && _adReadyStatus[placementId]) { return; // 已经加载好，无需重复加载 } Advertisement.Load(placementId, new LoadCallback { OnLoadSuccess = (id) => { _adReadyStatus[id] = true; OnAdLoaded?.Invoke(id); // 触发加载成功事件 }, OnLoadFailed = (id, error, message) => { Debug.LogWarning($“UnityAds加载失败: {id}, {error} - {message}”); _adReadyStatus[id] = false; // 可以在此实现重试逻辑，例如30秒后重试 StartCoroutine(RetryLoadAfterDelay(id, 30f)); } }); }

实操心得：不要无限制地频繁调用Load。如果广告加载失败，应该加入指数退避的重试机制，避免在短时间内对服务器造成压力或触发风控。同时，在玩家网络环境较差时，频繁的加载失败日志也会干扰调试。

3.3 广告展示与回调处理

展示广告相对直接，但回调处理是确保业务逻辑正确的核心。Unity Ads提供了ShowOptions类来传递回调，但更现代和清晰的做法是使用SDK的事件系统（如果支持）或自己在适配器层封装事件。

public void ShowRewardedAd(string placementId, Action<bool> onUserEarnedReward) { if (!IsAdReady(placementId)) { onUserEarnedReward?.Invoke(false); return; } var showOptions = new ShowOptions { resultCallback = (ShowResult result) => { bool rewardGranted = (result == ShowResult.Finished); onUserEarnedReward?.Invoke(rewardGranted); // 广告展示结束，无论成功与否，立即重新加载该广告位，为下一次展示做准备 if (rewardGranted || result == ShowResult.Skipped || result == ShowResult.Failed) { LoadAd(placementId); } } }; Advertisement.Show(placementId, showOptions); }

一个至关重要的坑：ShowResult.Finished代表用户观看了广告直至结束，应该发放奖励。ShowResult.Skipped代表用户提前关闭了广告（对于激励视频，通常不允许跳过，但其他类型可能有），不应发放奖励。ShowResult.Failed代表展示本身失败。务必在游戏逻辑中清晰地区分这些状态，错误的奖励发放会导致严重的经济失衡。

3.4 平台特定问题与优化

Unity Ads在集成中可能会遇到一些平台相关问题：

• Android Build：确保在Player Settings中包含了必要的权限（如INTERNET）和Proguard规则（如果启用了Minify），避免Release包中广告功能失效。
• iOS SKAdNetwork：为了支持iOS 14+的隐私追踪框架，需要在Info.plist文件中正确配置SKAdNetwork Items。Unity Ads文档会提供最新的标识符列表，需要将其加入你的Xcode工程或通过Unity的Post-Process Build脚本来添加。
• 模拟器测试：Unity Ads在Unity编辑器和某些模拟器上可能无法正常工作。对于Android，使用真机测试是更可靠的选择。对于iOS，可以使用Xcode的模拟器，但测试广告可能受限。

4. 可配置化与数据驱动设计

硬编码的广告位ID和策略是模块复用的最大敌人。我们必须将配置数据外置。

4.1 使用ScriptableObject管理配置

在Unity中，ScriptableObject是存储静态配置数据的绝佳选择。我们可以创建一个AdConfig资产。

[CreateAssetMenu(fileName = “AdConfig”, menuName = “Ad System/Ad Config”)] public class AdConfig : ScriptableObject { public string unityAdsGameIdIOS; public string unityAdsGameIdAndroid; public bool enableTestModeInEditor = true; public List<AdUnitConfig> adUnits; } [System.Serializable] public class AdUnitConfig { public string placementId; // 广告位唯一标识，如 “rewarded_video_end_level” public AdType adType; // 枚举：RewardedVideo, Interstitial, Banner public string platformId; // 对应广告平台的实际广告位ID public AdPlatform platform; // 枚举：UnityAds, AdMob, etc. public int loadRetryCount = 3; // 加载重试次数 public float loadRetryInterval = 5f; // 重试间隔秒数 }

在游戏启动时，广告管理模块读取这个AdConfig资产，根据其中的adUnits列表自动初始化所有广告位。这样，策划或运营人员无需开发介入，就能在Unity编辑器中轻松修改广告位ID或切换广告平台。

4.2 远程配置与热更新

对于线上运营的游戏，能够动态调整广告策略至关重要。我们可以将核心配置（如某个广告位的平台优先级、展示频率上限）存放在远程服务器（如Firebase Remote Config，或自建的配置中心）。游戏启动时，广告管理模块先加载本地默认配置，然后异步请求远程配置并合并更新。

例如，远程配置可以下发一个JSON：

{ “ad_priority”: { “rewarded_video_end_level”: [“UnityAds”, “AdMob”], “interstitial_level_start”: [“AdMob”, “UnityAds”] }, “frequency_caps”: { “interstitial_level_start”: { “max_show_per_hour”: 3 } } }

管理层解析这份配置后，动态调整其广告调度策略。这实现了商业策略的“热更新”，无需客户端发版即可进行A/B测试或优化广告收入。

5. 模块集成与游戏逻辑交互

设计好模块后，如何优雅地集成到游戏中是下一步关键。

5.1 服务提供与依赖注入

避免使用AdManager.Instance.ShowRewardedAd(...)这样的静态调用。更好的做法是通过一个中央服务容器（Service Locator）或依赖注入框架（如Zenject, VContainer）来提供IAdService的实例。

// 在安装器或启动脚本中注册服务 public class GameInstaller : MonoInstaller { [SerializeField] private AdConfig _adConfig; public override void InstallBindings() { Container.Bind<IAdService>().To<AdManager>().FromNewComponentOnNewGameObject().AsSingle().NonLazy(); Container.Bind<AdConfig>().FromInstance(_adConfig).AsSingle(); } } // 在需要广告的游戏逻辑类中（如奖励箱UI） public class RewardChestUI : MonoBehaviour { [Inject] private IAdService _adService; // 依赖被自动注入 public void OnWatchAdForRewardButtonClick() { _adService.ShowRewardedAd(“rewarded_chest”, (success) => { if (success) { // 发放宝箱奖励 GrantChestReward(); } else { // 提示用户广告未完成 ShowMessage(“需要完整观看广告才能获得奖励哦~”); } }); } }

这种方式使得单元测试变得容易，你可以轻松地为IAdService创建一个模拟（Mock）实现，在不启动真实广告SDK的情况下测试游戏逻辑。

5.2 广告展示时机与用户体验

广告模块不仅要“能用”，更要“好用”，这关乎用户体验和留存。

• 激励视频：提供明确的价值交换。按钮文案应是“观看广告获得双倍金币”，而不是模糊的“获取奖励”。在广告加载期间，按钮应显示为“加载中...”并禁用，准备好后再变为可点击状态。
• 插页式广告：选择合适的打断时机，如游戏关卡结束、返回主菜单时。避免在玩家紧张操作时（如Boss战中途）弹出。必须设置展示频率上限（如每小时不超过3次），防止过度打扰。
• 横幅广告：提供可关闭的选项，并谨慎选择放置位置，避免遮挡核心游戏UI。

在广告管理模块中，可以为IAdService接口增加状态查询方法，如IsAdReady(string placementId)和GetAdReadyEvent(string placementId)，方便UI层更新按钮状态。

6. 调试、测试与性能监控

一个可复用的模块必须具备完善的调试支持。

6.1 内置调试面板

在开发阶段，可以创建一个仅在开发版本中激活的调试UI面板。这个面板可以：

• 列出所有配置的广告位及其当前状态（未加载/加载中/就绪）。
• 提供按钮手动触发任意广告位的加载和展示。
• 模拟广告回调成功或失败，用于快速测试游戏内的奖励发放逻辑。
• 查看当前生效的远程配置。

这能极大提升开发和测试效率，QA人员也可以利用它进行特定场景的测试。

6.2 日志与性能追踪

模块内部需要有一套详尽的日志系统，使用Debug.Log（开发时）和更正式的日志框架（如上传到服务器）。关键节点需要记录：

• 广告初始化开始与结束。
• 每个广告位的加载请求、成功、失败及失败原因。
• 广告展示请求、展示开始、展示完成及结果。
• 平台切换决策的过程（在聚合场景下）。

这些日志不仅是调试的利器，更是进行线上问题排查和收入数据分析的原始依据。可以考虑将关键指标（如广告请求数、展示数、成功率、展示时长）集成到你的游戏数据分析平台中。

6.3 真机测试清单

在将游戏提交商店前，必须进行全面的真机广告流程测试：

1. 测试模式验证：在开发版本上，确认测试广告能正常加载和展示。
2. 生产模式验证：使用一个隔离的、配置了真实广告位ID的测试版本，确保真实广告流能正常拉取（虽然可能没有填充）。
3. 网络环境测试：在Wi-Fi、4G/5G以及弱网环境下测试广告加载的稳定性和超时处理。
4. 中断测试：在广告播放过程中，接听电话、切换应用、锁屏，观察恢复后广告和游戏的状态是否正常。
5. 回调测试：确保每种广告结果（完成、跳过、失败）都能正确触发游戏内的逻辑，特别是奖励发放的准确性。

7. 从单一平台到广告聚合的演进

项目初期可能只接入了Unity Ads。但商业化的需求必然会推动你接入第二、第三家广告平台，以提升填充率和竞争eCPM。此时，我们前期设计的模块架构优势就体现出来了。

7.1 集成新平台适配器

要接入AdMob，你只需要做两件事：

1. 引入AdMob SDK。
2. 创建一个新的AdMobAdapter类，实现统一的IAdPlatformAdapter接口（或直接在现有适配器结构上实现），将AdMob的初始化、加载、展示逻辑封装进去。

游戏逻辑代码和核心管理模块完全不需要修改。这就是接口抽象和适配器模式带来的威力。

7.2 实现简单的瀑布流管理

当多个平台都有广告可展示时，需要一套决策机制。最简单且常用的是“瀑布流”。在管理层维护一个广告平台的优先级列表。当请求一个广告位时：

1. 按优先级顺序检查各平台适配器，该广告位是否已准备好。
2. 选择第一个准备好的平台进行展示。
3. 如果都没有准备好，则触发一个异步等待流程，并尝试加载所有平台的该广告位，谁先加载好就展示谁。

你可以在AdUnitConfig中增加一个List<AdPlatform> priority字段来定义每个广告位的平台优先级，管理层根据这个配置进行调度。

7.3 向实时竞价进阶

瀑布流是静态的、顺序的选择。更先进的方案是实时竞价（Bidding）。在这种模式下，当需要展示广告时，同时向所有集成的广告平台（支持Bidding的）发起竞价请求，各平台在极短时间内返回一个出价（eCPM），管理层选择出价最高的那个平台来展示广告。

这需要广告平台SDK支持Bidding接口（如Unity Ads的LevelPlay，AdMob的Bidding）。实现起来比瀑布流复杂，需要对管理层的调度逻辑进行重大升级，但它能最大化每一次广告展示的收入，是商业化深度优化的方向。

构建一个可复用的广告管理模块，看似是增加前期工作量，实则是为整个项目的商业化生命周期进行的战略性投资。它带来的代码清晰度、维护便利性、测试覆盖能力和商业灵活性，会在项目发展的中后期回报以十倍百倍的效率提升。这个模块一旦建成，便可以成为你后续所有Unity项目的标准资产，真正做到“一次构建，处处复用”。