1. 项目概述：为什么Unity广告集成是移动开发者的必修课？

如果你正在用Unity开发一款面向移动端的应用，无论是游戏还是工具，那么“变现”这个词迟早会摆在你面前。而广告，尤其是国内主流的穿山甲广告平台，几乎是所有开发者绕不开的一环。我见过太多团队，项目开发阶段顺风顺水，一到接入广告SDK就卡壳，不是配置繁琐就是测试不通，白白浪费几天时间。今天，我就以穿山甲广告为例，带你用5分钟的核心思路，搞定Banner、激励视频和插屏广告这三种最常用广告位的配置与实战。这不仅仅是粘贴几行代码，我会拆解每一步背后的逻辑，告诉你为什么这么配，以及我踩过哪些坑，让你真正实现“一次配置，稳定上线”。

穿山甲广告作为国内领先的广告联盟，其Unity SDK的集成流程已经相对标准化，但官方文档往往侧重于功能罗列，缺乏从项目工程角度出发的“串联”思维。新手容易在Android环境配置、SDK初始化、回调处理这些环节上栽跟头。本教程的目标，就是帮你建立一条清晰的集成路径，把看似复杂的配置拆解成几个必然成功的步骤，并重点讲解激励视频这种涉及虚拟奖励发放的关键广告类型，如何设计才能既保证用户体验，又确保收益不被作弊行为侵蚀。

2. 集成前准备：搭建坚如磐石的开发环境

在开始写任何广告代码之前，一个正确且干净的环境是成功的基石。很多“玄学”问题，比如SDK初始化失败、广告加载不出来，根源都出在环境上。

2.1 Unity工程与Android环境配置要点

首先，确保你的Unity项目已经切换为Android平台。在File -> Build Settings中选中Android，然后点击Switch Platform。这一步看似简单，但很多后续的包依赖问题都源于平台没有正确切换。

接下来是JDK、SDK和NDK的配置，这是Unity与Android原生代码通信的桥梁。在Edit -> Preferences -> External Tools中，你需要指定它们的路径。

• JDK：建议使用Unity Hub安装时自带的OpenJDK，路径通常类似Unity Hub/Editor/[版本号]/Editor/Data/PlaybackEngines/AndroidPlayer/OpenJDK。使用自带版本可以最大程度避免版本冲突。如果你之前配置过Java环境变量，这里指向你的本地JDK 8或11也可以，但务必确保版本兼容。
• Android SDK：同样推荐使用Unity Hub安装的Android SDK。如果你有Android Studio，也可以指向其SDK目录（例如C:\Users\[用户名]\AppData\Local\Android\Sdk）。关键点在于：你需要通过Android Studio的SDK Manager，确保安装了必要的API平台（如API Level 31或33，取决于你的targetSdkVersion）和构建工具。
• NDK：Unity对NDK版本有特定要求。最稳妥的做法是在Unity Hub -> Installs -> 对应版本编辑器右侧的三个点 -> Add modules中添加Android NDK组件。让Unity管理NDK版本能省去大量兼容性麻烦。

注意：经常有开发者反馈“unity关联jdk总是提示无法找到”，十有八九是因为路径中有中文或特殊字符，或者指向了JRE而非JDK。请检查路径，并确认指向的是包含bin、lib等文件夹的JDK根目录。

2.2 获取并导入穿山甲Unity SDK

前往穿山甲开发者平台，创建你的应用和广告位，获取对应的App ID和各个广告位的代码位 ID (Slot ID)。这是广告请求的身份凭证，务必保管好。

下载最新的Unity SDK包（通常是一个.unitypackage文件）。在Unity中，通过Assets -> Import Package -> Custom Package导入。导入后，检查Plugins/Android目录下是否包含了必要的.aar或.jar文件。穿山甲SDK可能会依赖一些第三方库，如GSON、OkHttp等，如果Unity打包时报告缺少类，可能需要手动将这些库的jar包放入Plugins/Android目录。

一个重要的实操心得：在导入SDK后，立即打开Player Settings（Edit -> Project Settings -> Player），查看Other Settings下的Configuration部分。确保Scripting Backend设置为IL2CPP，并且勾选了Target Architectures中的ARMv7和ARM64。穿山甲等许多国内SDK对64位架构的支持已是强制要求，不勾选ARM64可能导致在较新设备上崩溃或无法加载广告。

3. 核心广告位配置与代码实战

环境就绪，我们进入核心环节。我将分别详解Banner、激励视频、插屏广告的集成，并提供可直接复用的代码模板。

3.1 Banner广告：常驻底部的稳定收益单元

Banner广告通常显示在屏幕底部或顶部，是一种持续曝光的广告形式。它的集成相对简单，但要注意尺寸和刷新策略。

首先，你需要创建一个用于显示Banner的容器。通常，我会在UI Canvas下创建一个空GameObject，并为其添加一个RectTransform组件，通过锚点（Anchors）将其固定在屏幕底部。

using UnityEngine; using UnityEngine.UI; // 假设穿山甲SDK的命名空间为 ByteDance.SDK using ByteDance.SDK; public class BannerAdManager : MonoBehaviour { private BannerAd bannerAd; public string slotId; // 在Inspector面板中填入你的Banner代码位ID void Start() { // 强烈建议在SDK初始化成功后再加载广告 LoadBanner(); } void LoadBanner() { if (bannerAd != null) { DestroyBanner(); } // 1. 创建Banner广告实例 // 参数：代码位ID， 广告宽度， 广告高度， 是否支持深度链接 bannerAd = new BannerAd(slotId, AdSize.Banner320x50, true); // 2. 设置回调 bannerAd.OnAdLoaded += () => { Debug.Log("Banner广告加载成功"); }; bannerAd.OnAdError += (errorCode, message) => { Debug.LogError($"Banner广告加载失败: {errorCode} - {message}"); }; // 3. 加载广告 bannerAd.LoadAd(); // 4. 广告加载成功后，需要手动调用Show将其显示在之前设定的容器位置。 // 通常会在OnAdLoaded回调中调用Show。 } public void ShowBanner() { if (bannerAd != null) { // 获取之前设置的容器RectTransform RectTransform adContainer = GetComponent<RectTransform>(); bannerAd.Show(adContainer); } } public void DestroyBanner() { if (bannerAd != null) { bannerAd.Destroy(); bannerAd = null; } } void OnDestroy() { DestroyBanner(); } }

关键参数解析：

• AdSize.Banner320x50：这是标准Banner尺寸。穿山甲还提供Banner300x250,Banner468x60等。选择与你UI布局匹配的尺寸。
• 刷新策略：Banner广告默认会自动刷新。如果你需要控制刷新间隔或关闭自动刷新，需要在穿山甲开发者后台的代码位配置中进行设置，SDK层面通常通过初始化时的配置项控制。

避坑指南：

• 生命周期管理：务必在场景切换或对象销毁时（OnDestroy）调用DestroyBanner()，释放原生广告对象，避免内存泄漏和重复创建导致的异常。
• 显示时机：不要在广告加载完成前调用Show()。最佳实践是在OnAdLoaded回调中触发显示，或者由游戏逻辑（如某个界面打开时）来控制。
• 容器设置：确保传递给Show方法的RectTransform对象的锚点和轴心（Pivot）设置正确，否则广告可能显示在奇怪的位置。

3.2 激励视频广告：平衡用户体验与收益的关键

激励视频是收益最高，也是逻辑最复杂的广告类型。用户观看一段15-30秒的视频广告后，可以获得游戏内奖励（如金币、道具、复活机会）。其核心在于“奖励发放”的逻辑必须可靠且防作弊。

public class RewardVideoAdManager : MonoBehaviour { private RewardVideoAd rewardAd; public string slotId; // 激励视频代码位ID private bool isRewardEarned = false; // 标记奖励是否应被发放 public void LoadRewardAd() { if (rewardAd != null) { rewardAd.Dispose(); // 清理旧实例 } // 1. 创建激励视频广告实例 rewardAd = new RewardVideoAd(slotId); // 2. 设置关键回调 rewardAd.OnAdLoaded += () => { Debug.Log("激励视频广告加载成功，可以展示了"); // 可以在这里更新UI按钮状态，比如将“加载中”变为“观看广告” }; rewardAd.OnAdError += (errorCode, message) => { Debug.LogError($"激励视频广告加载/展示失败: {errorCode} - {message}"); // 加载失败，可以尝试重新加载或给用户提示 }; rewardAd.OnAdShow += () => { Debug.Log("激励视频广告开始播放"); isRewardEarned = false; // 每次展示重置奖励标记 }; // 这是最重要的回调！ rewardAd.OnRewardVerify += (bool verifySuccess, string rewardType, int rewardAmount) => { if (verifySuccess) { Debug.Log($"激励视频验证成功，奖励类型: {rewardType}, 数量: {rewardAmount}"); isRewardEarned = true; // 标记奖励已验证，可以发放 } else { Debug.LogWarning("激励视频验证失败，可能未完整观看"); isRewardEarned = false; } }; rewardAd.OnAdClose += () => { Debug.Log("激励视频广告关闭"); // 在广告关闭时，根据 isRewardEarned 决定是否发放奖励 if (isRewardEarned) { GrantRewardToPlayer(); // 发放奖励给玩家 isRewardEarned = false; // 重置标记 } // 无论是否获得奖励，广告关闭后都应重新加载下一个广告 LoadRewardAd(); }; rewardAd.OnAdClicked += () => { Debug.Log("用户点击了激励视频广告"); }; // 3. 加载广告 rewardAd.LoadAd(); } public void ShowRewardAd() { if (rewardAd != null && rewardAd.IsLoaded()) { rewardAd.Show(); } else { Debug.Log("激励视频广告未就绪，请先加载"); // 可以给用户一个“广告加载中，请稍候”的提示 LoadRewardAd(); } } private void GrantRewardToPlayer() { // 这里实现你的游戏内奖励逻辑 // 例如：PlayerData.Coins += 100; // GameManager.Instance.RevivePlayer(); Debug.Log("向玩家发放奖励！"); // 重要：建议在此处将奖励记录同步到服务器，防止本地篡改。 } void Start() { // 游戏启动后预加载一个激励视频 LoadRewardAd(); } }

核心逻辑深度解析：

1. 奖励验证 (OnRewardVerify)：这是穿山甲服务器对用户是否有效观看完成的回调。verifySuccess为true是发放奖励的唯一依据。绝不能仅凭广告关闭 (OnAdClose) 就发奖，因为用户可能中途跳过。
2. 奖励发放时机：必须在OnAdClose回调中，根据之前OnRewardVerify设置的标记 (isRewardEarned) 来发放奖励。切忌在OnRewardVerify回调中直接发奖，因为此时广告可能还未关闭，用户体验不佳。
3. 预加载机制：激励视频加载需要时间（网络请求+物料下载）。应在广告关闭后立即加载下一个 (LoadRewardAd)，并在用户可能触发广告的点（如进入结算界面）提前检查IsLoaded()，确保点击后能立即播放，减少等待。

防作弊设计心得：

• 服务端校验：对于重要的奖励（如稀有道具、大量货币），GrantRewardToPlayer中的操作应该是一个向你自己游戏服务器发送的请求，由服务器核实后发放。防止玩家通过修改本地内存或使用破解版来无限获取奖励。
• 客户端防连点：在ShowRewardAd方法开始时，可以设置一个标志位或禁用按钮，直到OnAdClose回调完成后再恢复，防止玩家快速连续点击导致异常。

3.3 插屏广告：场景转换间的填充利器

插屏广告通常在游戏关卡结束、应用切换界面时全屏或半屏弹出。它的集成模式与激励视频类似，但没有奖励回调。

public class InterstitialAdManager : MonoBehaviour { private InterstitialAd interstitialAd; public string slotId; // 插屏广告代码位ID public void LoadInterstitialAd() { if (interstitialAd != null) { interstitialAd.Dispose(); } interstitialAd = new InterstitialAd(slotId); interstitialAd.OnAdLoaded += () => { Debug.Log("插屏广告加载成功"); }; interstitialAd.OnAdError += (errorCode, message) => { Debug.LogError($"插屏广告错误: {errorCode} - {message}"); // 可以设置一个延迟重试机制，比如5秒后重新加载 Invoke("LoadInterstitialAd", 5f); }; interstitialAd.OnAdShow += () => { Debug.Log("插屏广告开始展示"); // 可以在这里暂停游戏背景音乐或逻辑 AudioManager.Instance.PauseBackgroundMusic(); }; interstitialAd.OnAdClose += () => { Debug.Log("插屏广告关闭"); // 恢复游戏逻辑 AudioManager.Instance.ResumeBackgroundMusic(); // 立即加载下一个插屏广告 LoadInterstitialAd(); }; interstitialAd.OnAdClicked += () => { Debug.Log("插屏广告被点击"); }; interstitialAd.LoadAd(); } public void ShowInterstitialAd() { if (interstitialAd != null && interstitialAd.IsLoaded()) { interstitialAd.Show(); } } void Start() { // 预加载第一个插屏广告 LoadInterstitialAd(); } // 提供一个静态方法，方便在其他场景中调用展示 public static void ShowAtBreakPoint() { // 这里需要根据你的架构获取InterstitialAdManager实例 // 例如：FindObjectOfType<InterstitialAdManager>()?.ShowInterstitialAd(); } }

展示策略建议：

• 自然断点：在关卡结束、返回主菜单、角色死亡复活前等自然停顿点展示插屏广告，对用户体验干扰最小。
• 频率控制：不要过度展示。可以设计一个简单的计数器，例如“每完成三个关卡展示一次插屏”，避免引起用户反感。
• 用户体验：如代码所示，在OnAdShow时暂停游戏音乐和可能的后台计时，在OnAdClose时恢复，保证体验连贯。

4. 高级配置与优化策略

基础功能实现后，以下优化能让你的广告系统更稳健、收益更高。

4.1 SDK初始化与全局配置

所有广告操作的前提是SDK初始化成功。这应该在游戏启动的早期完成。

public class AdSDKManager : MonoBehaviour { public string appId; // 你的穿山甲App ID public bool useTestMode = true; // 开发阶段开启测试模式 void Awake() { DontDestroyOnLoad(this.gameObject); // 保证全局唯一 InitSDK(); } void InitSDK() { var config = new SDKConfiguration.Builder() .AppId(appId) .UseTestMode(useTestMode) // 测试模式下会返回测试广告，避免误点击产生无效数据 .DebugLog(true) // 开发阶段开启日志，方便排查 .Build(); // 假设初始化接口为 Init bool initSuccess = ByteDanceAds.Init(config); if (initSuccess) { Debug.Log("穿山甲SDK初始化成功"); // 初始化成功后，再开始预加载各种广告 FindObjectOfType<BannerAdManager>()?.LoadBanner(); FindObjectOfType<RewardVideoAdManager>()?.LoadRewardAd(); FindObjectOfType<InterstitialAdManager>()?.LoadInterstitialAd(); } else { Debug.LogError("穿山甲SDK初始化失败！"); } } }

测试模式 (useTestMode)：在开发、调试阶段务必开启。它会请求专门的测试广告素材，你的点击、展示行为不会产生真实的广告消耗和收益，避免污染数据。应用上线前，必须将其设置为false。

4.2 广告加载策略与缓存管理

广告加载受网络影响，采用合适的策略能提升填充率和用户体验。

• 预加载：如上文代码所示，在一种广告展示完毕后，立即加载下一个。对于激励视频和插屏，始终保持一个“备用”广告在缓存中。
• 并行加载：如果应用内有多个不同代码位的激励视频（例如，一个用于金币加倍，一个用于复活），可以同时加载它们。
• 超时与重试：为广告加载设置超时逻辑（例如，10秒未加载成功则触发错误回调，并进行指数退避重试），防止因个别请求挂起导致广告位永远不可用。

4.3 适配Android构建设置

Unity打包Android APK时，一些设置会影响SDK的正常工作。

1. Minimum API Level：在Player Settings -> Other Settings中，Minimum API Level不宜设置过低，建议至少为API Level 21 (Android 5.0)。
2. Target API Level：必须设置为较新的版本（如31/33），这是Google Play商店的要求。高版本Target SDK涉及运行时权限（如READ_PHONE_STATE）的变更，穿山甲SDK所需的权限已在清单文件中声明，通常无需手动处理，但需要知晓。
3. Proguard混淆：如果你启用了代码混淆（Minify），必须在Proguard User File中添加穿山甲SDK的混淆保留规则，否则可能导致SDK的Java类或方法被错误移除，引发运行时崩溃。规则通常由SDK提供商提供。

5. 常见问题排查与调试技巧实录

即使按照教程操作，你可能还是会遇到一些问题。这里是我总结的常见“坑点”和解决方法。

5.1 广告加载失败或返回“No Fill”

• 现象：OnAdError回调被触发，错误码可能表示无填充。
• 排查步骤：
  1. 检查网络：真机测试时，确保设备网络通畅，可以尝试切换Wi-Fi和4G/5G。
  2. 检查ID：核对代码位ID (slotId) 和应用ID (appId) 是否与穿山甲后台创建的一致，尤其注意大小写和空格。
  3. 检查代码位状态：登录穿山甲后台，确认广告位是否已审核通过并处于“启用”状态。新创建的代码位需要审核。
  4. 测试模式：确保在开发阶段开启了测试模式 (useTestMode: true)。如果关闭了测试模式，在新应用或低流量时期，广告平台可能确实没有匹配的广告返回（No Fill）。
  5. 查看日志：开启SDK的Debug日志，在Unity Editor的Console或Android的Logcat中过滤穿山甲SDK的日志标签（如TTAdSdk），里面通常会有更详细的错误信息。

5.2 激励视频奖励回调不触发

• 现象：广告播放完了，但OnRewardVerify回调没被调用，或者verifySuccess为false。
• 原因与解决：
  1. 未完整观看：用户可能提前关闭了广告。激励视频要求观看至少15秒（具体以平台规则为准）才算有效。在UI设计上，可以提示用户“观看完整视频可获得奖励”。
  2. 网络延迟：奖励验证是服务器回调，在用户网络极差的情况下可能延迟或丢失。代码中已经通过isRewardEarned标记将验证与关闭回调解耦，是标准做法。
  3. 测试广告限制：部分测试广告可能不触发奖励验证。尝试使用穿山甲后台提供的“正式测试代码位ID”进行测试。

5.3 Android打包后崩溃或黑屏

• 现象：在Unity Editor中运行正常，打包成APK安装后，启动即崩溃或打开广告时黑屏/闪退。
• 系统性排查：
  1. 架构支持：确认Player Settings -> ARM64已勾选。
  2. SDK依赖冲突：这是最常见的原因。穿山甲SDK可能引入了与Unity工程中其他插件（如Firebase、某些Analytics SDK）相同但版本不同的库（如Android Support库、OkHttp等）。解决方法：
     • 使用Assets -> External Dependency Manager（如果SDK提供了）。
     • 手动检查Plugins/Android下的.aar.jar文件，移除重复的低版本库。
     • 在穿山甲开发者社区或文档中查找已知的冲突库列表和解决方案。
  3. Proguard混淆：如果开启了混淆，务必添加正确的-keep规则。崩溃日志（logcat）中如果看到ClassNotFoundException或NoSuchMethodError，很可能是混淆导致。
  4. 查看Logcat日志：这是定位Android原生层崩溃的终极手段。使用Android Studio的Logcat工具或adb logcat命令，在应用崩溃时过滤FATAL EXCEPTION或E/Unity等关键字，能找到崩溃的堆栈信息，直接指向问题代码行。

5.4 广告展示位置或尺寸异常

• Banner位置不对：检查传递给Show方法的RectTransform。确保其锚点（Anchors）和轴心（Pivot）设置正确。例如，一个锚点在底部拉伸、轴心在(0.5, 0)的矩形，适合显示底部Banner。
• 插屏/激励视频未全屏：检查广告初始化代码，确认没有设置额外的样式参数限制了窗口大小。全屏广告通常由SDK自动控制。

最后的叮嘱：广告集成是一个“配置敏感”的工作。最好的习惯是，每完成一个关键步骤（如导入SDK、配置ID、编写核心代码），就在真机上打包测试一次，及早发现问题。将广告管理代码模块化，与核心游戏逻辑解耦，这样未来需要更换或增加广告平台时，会轻松得多。