Unity iOS 接 MAX Native 广告：原生视图挂载与稳定展示

简介：面向使用Unity开发iOS应用的开发者，这份资料聚焦AppLovin Max平台Native原生广告的接入落地，适合具备基础Unity与iOS工程经验、希望提升广告变现效率的中级开发者参考。内容围绕SDK导入后的工程组织展开，含原生广告视图的界面素材、桥接与缓冲区管理的实现文件，以及MaxNativeAdFramework框架和模块配置，可用于对照理解原生广告在Unity与iOS原生层之间的衔接方式。压缩包为7z格式，共58个文件、约367KB，以21个png界面切图、8个json配置、15个meta描述文件及若干h/mm/m与Swift模块文件为主，涵盖广告素材、视图布局与框架头文件等组成部分，体量轻便，便于快速查阅与集成验证。已有106人学习，可作为Native广告接入过程中的结构参考与排错对照，帮助梳理广告位加载、事件回调与UI展示区域的衔接逻辑，减少自行摸索配置的时间。

1. 从一次 iOS 上架被拒说起：这套 Unity 接 MAX Native 广告资源到底解决什么

Unity iOS 项目接 MAX Native 广告，最容易翻车的不是 C# 调用，而是真机上原生视图没有挂到正确的 UIViewController 层级。某项目在 Editor 里点预览一切正常，打包到真机后广告位白屏，审核又卡在隐私清单和广告标识说明上。这套资源把 C# 控制层、Native 渲染 Prefab、iOS 原生桥接和 Xcode 构建检查表拆开，目标很明确：让已经能出包、但 Native 展示不稳的团队少走一轮返工。它不适合完全没碰过广告 SDK 的新手，适合手里有 Unity iOS 工程、需要把 MAX Native 广告跑到稳定展示和可排查状态的人。资源里的脚本和桥接层按最小闭环组织，先跑通一次真机展示，再谈缓存和收益回调。

2. 先把链路拆开：Unity、MAX 聚合与 iOS Native 广告的职责边界

2.1 为什么 Native 不是“换个 AdUnit 就行”

Banner 和插屏在 Unity 侧通常有现成的展示接口，广告 SDK 自己管理视图层级，业务代码只关心什么时候调用 show。Native 广告不一样，它把素材、标题、图标、CTA 按钮和落地页点击都交给你，聚合平台只负责请求、填充、竞价和回调，最终长什么样、放在哪、多大尺寸、什么时候销毁，全部由客户端决定。iOS 上更是如此，Native 广告最终是一个原生 UIView，Unity 的 Canvas 和 RectTransform 管不到它，只能靠桥接层把原生视图塞进 Unity 的视图树。

我一般把这条链路拆成四层：Unity 业务层决定展示场景和频次，C# 封装层负责初始化、加载、缓存和回调分发，iOS 桥接层负责创建原生视图并处理点击，MAX 聚合层负责填充和收益回传。四层里任何一层把职责搞混，后面就会遇到“加载成功但看不见”“看得见但点不动”“点得动但收益对不上”这类问题。资源包的价值不在于多写了几行 API，而在于把这四层的边界用脚本和 Prefab 固定下来，让排查时知道该看哪一层。

Native 广告的填充率通常比 Banner 更依赖 Ad Unit 配置和中介适配器状态。MAX 后台创建 Native Ad Unit 时，要选清楚是模板渲染还是自定义渲染；自定义渲染对客户端要求更高，但样式可控。常见做法是先用平台提供的 Native Ad View 模板跑通，再把模板换成资源包里的 Prefab 布局，这样至少能确认填充和回调是通的。直接一上来就写自定义视图，出了白屏很难判断是没填充、桥接没挂上，还是素材尺寸为 0。

还有一个容易被忽略的点：Native 广告的“展示”在聚合平台侧往往没有像插屏那样明确的 show 回调，更多是靠 loaded 之后你把视图挂上去。资源包里的MaxNativeAdView会记录一次Bind和一次SetActive(true)，业务埋点要把这两个动作和 MAX 的 loaded 回调分开记。否则报表里看到的展示量会虚高，因为 loaded 不等于用户真的看到了。这个边界先立住，后面调预加载和缓存才有意义。

2.2 资源包里的脚本、Prefab 与原生桥接层怎么分工

资源包里的 C# 脚本通常分三类：初始化入口、加载控制器、渲染绑定组件。初始化入口只做 SDK key 设置、隐私开关、ATT 时机和 mediation debugger 开关；加载控制器管 Ad Unit Id、加载回调、失败重试和缓存队列；渲染绑定组件负责把 MAX 返回的 NativeAd 对象塞进 Prefab 里的标题、图标、描述、CTA 和媒体容器。三类别混在一个 MonoBehaviour 里，否则场景切换时销毁顺序一乱，回调就会打到已销毁对象上。

Prefab 的职责是占位和布局，不是广告本身。资源里的 Prefab 一般会留一个媒体容器、一个标题文本、一个描述文本、一个图标 Image、一个 CTA Button，再加一个根节点控制显隐。原生视图挂进来之后，Unity 侧的 Text 和 Image 只负责兜底样式，真实内容由桥接层回填。常见翻车是 Prefab 根节点挂了CanvasGroup但原生视图不受 CanvasGroup 影响，透明度调了没反应；解决办法是把显隐控制放在原生容器上，Unity 侧只控制容器 GameObject 的 active 状态。

iOS 桥接层一般是一个.mm或.swift文件，暴露一个方法给 C#：传入 Ad Unit Id、容器指针、期望尺寸和对齐方式，内部创建 Native Ad Loader，加载成功后把原生视图加到容器上。容器指针通常来自UnityGetGLViewController().view或者资源包自己创建的UIView。这里要特别注意：不要把原生视图直接加到UIWindow上，否则旋转、安全区和键盘弹出时布局会飘。资源包里的桥接层会保留一个弱引用容器，场景销毁时先 removeFromSuperview，再置空 delegate。

C# 和 Objective-C 之间的字符串、回调函数指针、错误码都要约定清楚。资源包里用Action<string, string>这种简单签名传 adUnitId 和错误信息，避免跨语言传复杂对象。错误码不要只记一个-1，MAX 的ErrorInfo里有 code 和 message，桥接层原样透传，排查时才能区分是无填充、网络错误还是适配器初始化失败。这个设计看起来朴素，但比在原生层吞掉错误再返回 bool 要可靠得多。

2.3 版本矩阵与 Pod 依赖的选型理由

Unity iOS 接 MAX，版本矩阵不是越新越好，而是 Unity 插件版本、MAX SDK 版本、中介适配器版本和 Xcode 版本要能对上。资源包内一般会标注验证过的组合，正文不重复具体版本号，拿到后先看包里的说明文件。常见做法是把 Unity 插件固定在一个 minor 版本，不要每次打包都自动拉最新；中介适配器按实际投放网络勾选，没投的网络不要全量塞进 Podfile，包体积和初始化耗时都会涨。

CocoaPods 集成时，use_frameworks!和静态库/动态库的选择会影响签名和启动时间。MAX SDK 和多数中介适配器对动态库支持更成熟，但 Unity 导出工程里如果还有别的插件要求静态库，就要在 Podfile 里按 target 分开写。资源包的构建检查表里会提醒：先跑pod install --repo-update，再用.xcworkspace打开，不要直接开.xcodeproj。这一步错了，后面所有链接错误都是玄学。

隐私合规在 iOS 上不是可选项。ATT 弹窗时机、NSUserTrackingUsageDescription文案、SKAdNetworkItems清单、PrivacyInfo.xcprivacy里的 API 声明，缺一个都可能影响审核或归因。资源包把这几项放在 Xcode 检查表里，而不是塞在 C# 代码注释里。初始化顺序建议是：先设置 consent 和 do-not-sell，再初始化 SDK，ATT 弹窗放在用户进入主界面后、第一次加载广告前。不要一启动就弹 ATT，用户还没看到内容就拒绝，后续归因数据会很难看。

选型上还有一个现实问题：Native 广告在 iOS 上的收益并不总是比插屏高，它更适合信息流、商店页、任务列表这类有自然内容卡片的场景。如果项目是超休闲游戏，主页只有几个按钮，硬塞 Native 广告会拉低体验，展示率也上不去。资源包适合已经确定要做 Native 的场景，不是拿来做“广告位越多越好”的万能药。先想清楚广告位在用户路径里的位置，再决定预加载数量和缓存上限，这比调 API 参数更重要。

3. 从空工程到可展示：MAX Native 广告的接入步骤与关键参数

3.1 初始化 SDK 与隐私合规开关的落地写法

初始化阶段只做三件事：设置 SDK key、设置隐私开关、注册 SDK 初始化回调。资源包里的入口脚本通常挂在启动场景的一个常驻 GameObject 上，不要挂到会销毁的 UI 根节点。下面这段是资源包封装层的调用示意，方法名以包内实际脚本为准，关键在参数顺序和时机。

using UnityEngine; using System; public class MaxNativeEntry : MonoBehaviour { [SerializeField] private string sdkKey = "YOUR_MAX_SDK_KEY"; [SerializeField] private bool useMediationDebugger = false; private bool sdkReady; void Awake() { DontDestroyOnLoad(gameObject); MaxSdkCallbacks.OnSdkInitializedEvent += OnSdkInitialized; MaxSdk.SetSdkKey(sdkKey); MaxSdk.InitializeSdk(); } private void OnSdkInitialized(MaxSdkBase.SdkConfiguration config) { sdkReady = true; MaxSdk.SetHasUserConsent(true); // 按实际合规弹窗结果设置 MaxSdk.SetDoNotSell(false); // 按地区合规要求设置 if (useMediationDebugger) { MaxSdk.ShowMediationDebugger(); } Debug.Log($"[Native] sdk ready, consent={MaxSdk.IsUserConsentSet()}"); } public bool IsReady() => sdkReady; }

这段代码的逻辑很直白：Awake里把入口对象设为常驻，注册初始化回调后立刻设置 key 并初始化。OnSdkInitialized里再设置 consent 和 do-not-sell，是因为部分聚合平台要求在 SDK 初始化后调用隐私接口，具体顺序以资源包说明为准。useMediationDebugger只建议在调试包打开，正式包关掉，否则会多一个调试入口。sdkReady不要只用来判断能不能加载广告，还要在场景切换时检查入口对象是否还活着，避免回调打到已销毁对象。

参数说明：sdkKey从 MAX 后台复制，不要写死在多个脚本里；SetHasUserConsent(true)表示用户同意个性化广告，未弹窗之前不要默认 true；SetDoNotSell(false)按投放地区合规要求设置，不确定时先走合规弹窗再赋值。初始化回调可能早于或晚于场景加载，业务层不要假设Start里一定能加载广告，用IsReady()或事件订阅做门禁。

ATT 弹窗不要塞进Awake。常见做法是在第一个可交互界面出现后，调用ATTrackingManager.RequestTrackingAuthorization，回调里再设置 consent。资源包里的桥接层会暴露一个RequestAttIfNeeded方法，C# 侧只传一个回调。这样做的好处是用户至少看到了内容再决定，拒绝率不会因为冷启动弹窗而飙升。注意 iOS 15 之后 ATT 状态可能是restricted或denied，不要只判断authorized，其他状态也要能继续走非个性化广告加载。

3.2 创建 Native Ad Unit 并绑定 Unity 回调

MAX 后台创建 Native Ad Unit 时，先选自定义渲染还是模板渲染。资源包默认走自定义渲染，因为要挂自己的 Prefab 布局。Ad Unit Id 创建后复制到 C# 配置里，不要和 Banner、插屏的 Id 混用。加载前把回调注册好，加载成功后在回调里绑定视图，失败时记录 code 和 message。下面这段是加载控制器的核心逻辑。

using UnityEngine; public class NativeAdLoader : MonoBehaviour { [SerializeField] private string adUnitId = "NATIVE_IOS_AD_UNIT"; [SerializeField] private MaxNativeAdView nativeAdView; [SerializeField] private MaxNativeEntry entry; private bool loading; public void Load() { if (!entry.IsReady() || loading) return; loading = true; MaxSdkCallbacks.NativeAd.OnNativeAdLoadedEvent += OnLoaded; MaxSdkCallbacks.NativeAd.OnNativeAdLoadFailedEvent += OnLoadFailed; MaxSdkCallbacks.NativeAd.OnNativeAdClickedEvent += OnClicked; nativeAdView.gameObject.SetActive(false); MaxSdk.LoadNativeAd(adUnitId); Debug.Log($"[Native] load start, unit={adUnitId}"); } private void OnLoaded(string unitId, MaxNativeAdView adView) { loading = false; UnregisterLoadEvents(); if (unitId != adUnitId) return; nativeAdView.Bind(adView); nativeAdView.gameObject.SetActive(true); Debug.Log($"[Native] loaded, unit={unitId}"); } private void OnLoadFailed(string unitId, MaxSdkBase.ErrorInfo error) { loading = false; UnregisterLoadEvents(); Debug.LogError($"[Native] load failed, unit={unitId}, code={error.Code}, msg={error.Message}"); } private void OnClicked(string unitId, MaxSdkBase.AdInfo info) { Debug.Log($"[Native] clicked, unit={unitId}, revenue={info.Revenue}"); } private void UnregisterLoadEvents() { MaxSdkCallbacks.NativeAd.OnNativeAdLoadedEvent -= OnLoaded; MaxSdkCallbacks.NativeAd.OnNativeAdLoadFailedEvent -= OnLoadFailed; MaxSdkCallbacks.NativeAd.OnNativeAdClickedEvent -= OnClicked; } }

逻辑说明：Load先做 SDK ready 和 loading 双门禁，避免重复请求；注册 loaded、failed、clicked 三个事件，加载前把展示视图隐藏，防止旧素材闪现；OnLoaded里先注销加载事件，再校验unitId，最后Bind并激活视图。OnLoadFailed记录错误码和消息，不要只打一句“加载失败”。OnClicked里拿AdInfo.Revenue只用于日志，不要在客户端把它当最终收益。

参数说明：adUnitId用 Native 专用 Id；nativeAdView是资源包里的渲染组件，Bind方法内部会调用 iOS 桥接层挂载原生视图；loading是单次请求锁，但不要用它做全局缓存锁，缓存逻辑在下一章单独写。事件注销必须成对，否则场景切换后旧对象会继续收到回调，出现“二次展示无回调”或“空引用”的血泪经验。

3.3 用原生模板渲染：尺寸、字体与安全区参数

Native 广告的尺寸不是随便给一个 RectTransform 就完事。iOS 原生视图按 point 布局，Unity 的 Canvas 可能做了缩放，桥接层拿到的容器尺寸要换算成原生 point。资源包里的MaxNativeAdView会暴露几个参数：mediaAspectRatio、cornerRadius、contentPadding、safeAreaMode。mediaAspectRatio常见取值 1.91:1 或 1:1，按后台素材比例和设计稿定；cornerRadius要和 Unity 侧卡片圆角一致，否则原生视图和背景会有割裂感。

安全区是 iOS Native 最容易翻车的地方。原生视图加到UnityGetGLViewController().view上之后，不会自动受 Unity SafeArea 组件影响。资源包的桥接层会在viewDidLayoutSubviews里读取safeAreaInsets，把容器 frame 往里缩。C# 侧传入的锚点建议用顶部或底部固定，不要用居中，否则 iPhone 刘海和 Home Indicator 区域会遮挡 CTA 按钮。下面这段是桥接层的关键参数示意。

// 资源包内桥接层示意，方法名以实际工程为准 - (void)attachNativeView:(UIView *)nativeView container:(UIView *)container { UIEdgeInsets safe = container.safeAreaInsets; CGRect frame = container.bounds; frame.origin.y += safe.top; frame.size.height -= (safe.top + safe.bottom); nativeView.frame = frame; nativeView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight; [container addSubview:nativeView]; }

逻辑说明：container.safeAreaInsets在布局完成后才有值，所以这段要放在viewDidLayoutSubviews或布局回调里，不要放在viewDidLoad。autoresizingMask让原生视图跟随容器尺寸变化，旋转和分屏时不用重新创建。frame.size.height减掉上下安全区，避免 CTA 被 Home Indicator 压住。

参数说明：safeAreaMode可以设成none、top、bottom、all，游戏内嵌广告位一般用all；contentPadding是原生视图内部边距，单位是 point，不要直接拿 Unity 的像素值；cornerRadius超过素材高度一半会被系统裁切，设 8 到 12 比较稳。字体不要指望原生模板和 Unity Text 完全一致，资源包里的 Prefab 字体只做兜底，真实标题和描述由原生视图渲染，字号在桥接层按UIFontTextStyle或设计稿 point 值设置。

3.4 构建 Xcode 工程与 Info.plist 必改项

Unity 导出 iOS 工程后，先确认 Podfile 是否由插件生成，再执行安装。不要直接打开.xcodeproj，否则 Pod 依赖不会链接进来。构建脚本可以固定成两步：先pod install --repo-update，再打开.xcworkspace。如果资源包内自带构建检查脚本，先跑一遍，它会检查NSUserTrackingUsageDescription、SKAdNetworkItems和隐私清单是否存在。

# 在 Unity 导出的 iOS 工程目录执行 pod install --repo-update open Unity-iPhone.xcworkspace

逻辑说明：--repo-update只在第一次或 Pod 版本变更时加，日常构建可以去掉以节省时间。打开 workspace 后先选真机 target，检查 Signing & Capabilities 里的 Team 和 Bundle Identifier，再检查 Build Phases 里有没有重复的 MAX SDK 静态库。资源包里的检查表会提醒删除旧版 adapter 残留，否则会出现 duplicate symbols。

Info.plist 至少补三项：ATT 用途描述、SKAdNetworkItems、隐私清单。ATT 文案要写清楚用途，不要写“为了广告”这种模糊表述；SKAdNetworkItems 从 MAX 后台复制，不要手写猜测；隐私清单按资源包里的PrivacyInfo.xcprivacy模板合并，声明 UserDefaults、文件时间戳、系统启动时间等 API 的使用原因。

<key>NSUserTrackingUsageDescription</key> <string>用于衡量广告展示与归因，以便控制广告频次和内容相关性</string> <key>SKAdNetworkItems</key> <array> <dict> <key>SKAdNetworkIdentifier</key> <string>从 MAX 后台复制的标识</string> </dict> </array>

参数说明：NSUserTrackingUsageDescription不超过系统限制，文案要面向用户；SKAdNetworkItems是一个数组，每个投放网络一条，缺失会影响归因，不会直接导致崩溃；PrivacyInfo.xcprivacy要放在主 target 和插件 target 都能扫到的位置。构建前把useMediationDebugger关掉，检查 Bitcode 设置（新 Xcode 已不需要），再跑一次真机归档。归档失败先看 Pods 里的 adapter 是否和 MAX SDK 版本匹配，不要盲目升级 Xcode。

4. 把展示率拉起来：预加载、缓存池与生命周期管理

4.1 预加载队列：什么时候 load 才不浪费填充

Native 广告的加载耗时波动很大，冷启动第一次请求可能几秒，有缓存时几百毫秒。业务层如果在用户已经滑到广告位时才 load，大概率看到空白占位。预加载的时机要卡在“用户可能进入广告场景之前”，而不是 App 启动就猛拉。资源包里的做法是：主界面加载完成后预加载 1 条，进入信息流或商店页前再补 1 条，缓存上限设 2。超过 2 条不仅浪费填充，还会增加内存和回调管理复杂度。

预加载队列要有状态机：idle、loading、ready、failed。loading时不要重复发请求；ready时业务层直接取；failed后等一个退避时间再重试，不要立刻循环重试。下面这段是缓存队列的简化实现，资源包里会多一层过期和场景校验。

using System.Collections.Generic; using UnityEngine; public class NativeAdCache : MonoBehaviour { [SerializeField] private string adUnitId = "NATIVE_IOS_AD_UNIT"; [SerializeField] private int maxCache = 2; [SerializeField] private float expireSeconds = 45f; private readonly Queue<CachedNative> cache = new Queue<CachedNative>(); private bool loading; public bool TryTake(out MaxNativeAdView ad) { ad = null; while (cache.Count > 0) { var item = cache.Dequeue(); if (Time.realtimeSinceStartup - item.LoadedAt <= expireSeconds) { ad = item.View; return true; } item.View.Destroy(); // 过期视图走资源包回收接口 } return false; } public void EnsureCache() { if (loading || cache.Count >= maxCache) return; loading = true; MaxSdkCallbacks.NativeAd.OnNativeAdLoadedEvent += OnLoaded; MaxSdkCallbacks.NativeAd.OnNativeAdLoadFailedEvent += OnFailed; MaxSdk.LoadNativeAd(adUnitId); } private void OnLoaded(string unitId, MaxNativeAdView ad) { loading = false; Unregister(); cache.Enqueue(new CachedNative(ad, Time.realtimeSinceStartup)); } private void OnFailed(string unitId, MaxSdkBase.ErrorInfo error) { loading = false; Unregister(); Debug.LogWarning($"[NativeCache] fail code={error.Code}, msg={error.Message}"); } private void Unregister() { MaxSdkCallbacks.NativeAd.OnNativeAdLoadedEvent -= OnLoaded; MaxSdkCallbacks.NativeAd.OnNativeAdLoadFailedEvent -= OnFailed; } private struct CachedNative { public readonly MaxNativeAdView View; public readonly float LoadedAt; public CachedNative(MaxNativeAdView view, float loadedAt) { View = view; LoadedAt = loadedAt; } } }

逻辑说明：TryTake从队列头取，过期就销毁并继续取；EnsureCache用loading防止并发请求，缓存满了直接返回；OnLoaded把视图和时间戳入队，OnFailed只记日志，重试交给上层退避。expireSeconds设 45 秒是经验值，太短会频繁丢弃，太长会拿到旧素材，具体按广告位刷新频率调。

参数说明：maxCache建议 1 到 2，Native 视图占内存，缓存太多容易在低端机触发内存警告；expireSeconds和后台素材更新频率有关，信息流场景可以设 30 到 60 秒；adUnitId和加载控制器保持一致。注意Destroy是资源包封装的方法，内部会先 remove 原生视图再销毁 GameObject，不要直接Destroy(gameObject)。

4.2 缓存池上限与过期回收

缓存池不是越大越好。Native 广告每条都带原生视图，iOS 上每个视图都有图层和图片解码开销，缓存 5 条以上在低端机上很容易被系统回收。资源包默认上限 2，信息流连续滑动场景可以到 3，但要在didReceiveMemoryWarning时主动清空。过期回收要同时处理 Unity 对象和原生视图，只销毁 GameObject 不 removeFromSuperview，原生视图会挂在 VC 上变成幽灵视图，用户可能看到两个广告叠在一起。

回收顺序建议是：先从缓存队列移除，再调用桥接层Detach，最后销毁 Prefab 实例。Detach里做三件事：removeFromSuperview、置空 delegate、释放 loader。不要依赖 C# 的OnDestroy去调原生方法，场景销毁时顺序不可控，容易出现“对象已销毁但原生回调还在”。资源包里的MaxNativeAdView.Destroy就是按这个顺序封装的。

过期时间不要写死在多个地方，用一个 ScriptableObject 配置广告位参数：Ad Unit Id、缓存上限、过期秒数、重试退避、是否走 SafeArea。这样运营调频次时不用改代码，测试也能快速切参数。常见误用是把过期时间设成 0，以为“每次取都是新的”，实际会变成每次展示都重新 load，展示率反而下降。

4.3 场景切换时的销毁与重建

Unity 场景切换时，常驻入口对象不销毁，但广告视图所在的 Canvas 会销毁。如果缓存里还留着绑定到旧 Canvas 的 NativeAdView，下一次展示就会空引用。资源包的做法是给每个缓存项记一个sceneTag，TryTake时校验当前场景 tag，不匹配就丢弃。场景卸载前调用NativeAdCache.Clear()，把队列里的视图全部 Detach 并销毁。

重建时机放在新场景Start之后，不要放在Awake。Awake阶段 UI 还没布局，原生视图拿到的容器尺寸可能是 0，挂上去也会白屏。常见做法是等一帧，或者等 Canvas 的RectTransform尺寸大于 0 再EnsureCache。如果广告位在 ScrollRect 里，还要监听滚动可见性，用户滑到附近再挂载原生视图，避免一次性创建太多。

场景切换还有一个坑：MAX 的回调可能跨场景回来。加载请求发出后用户切了场景，OnLoaded回来时旧的nativeAdView已经销毁。资源包在回调里先检查this != null和gameObject.scene.isLoaded，再决定是否入缓存。这个检查很土，但能省掉很多空引用日志。

4.4 用日志和回调时序验证展示链路

Native 广告的展示链路长，光看“加载成功”不够。资源包里的日志按阶段打时间戳：load_start、load_success、bind_start、bind_success、show、click、fail。每个阶段带 adUnitId 和场景名，真机连 Xcode 控制台就能看到时序。下面这段是日志封装，字段名和资源包保持一致，方便后面做埋点表。

using System; using UnityEngine; public static class NativeTrace { public static void Mark(string stage, string adUnitId, string extra = "") { Debug.Log($"[NativeTrace] {DateTime.UtcNow:O}|{stage}|{adUnitId}|{extra}"); } }

逻辑说明：stage用固定枚举值，不要写自由文本，否则后面统计没法聚合；DateTime.UtcNow统一时区，和后台报表对齐；extra放错误码、耗时、场景名。真机测试时把 Xcode 控制台过滤[NativeTrace]，能看到一次完整展示从 load 到 click 的间隔。如果load_success到show超过 2 秒，说明缓存或场景挂载有问题。

参数说明：adUnitId必须传，否则多广告位排查时分不清；extra不要塞太长，控制台会截断。验证时至少跑三种场景：冷启动首次展示、缓存命中展示、场景切换后展示。每种场景各看一遍时序，确认没有重复 loaded、没有跨场景回调、没有 show 之后才 bind 的倒挂。

5. 避坑与排查：iOS Native 广告最常见的 5 个翻车点

5.1 现象：Editor 正常、真机白屏

现象很典型：Unity Editor 里点加载，控制台打印 loaded，Prefab 也能看到占位图，但打包到 iPhone 后广告位一片白，点击也没反应。原因不复杂，Editor 根本不渲染 iOS 原生 UIView，资源包里的 Prefab 只是占位，真机上原生视图没有挂到正确的容器，或者容器尺寸为 0。另一个常见原因是桥接层把视图加到了UIWindow而不是UnityGetGLViewController().view，层级被 Unity 的 Metal 视图盖住。

解决步骤：先用 Xcode 连真机，过滤[NativeTrace]，确认bind_success有没有打；再在桥接层attachNativeView里打印container.bounds和safeAreaInsets，尺寸为 0 就往上查 Canvas 布局；最后用 Xcode 的 View Hierarchy 看原生视图是否在层级里、是否被其他视图遮挡。资源包里的MaxNativeAdView有一个debugShowBorder开关，打开后给原生容器加红色边框，真机上一眼能看出挂没挂上。

5.2 现象：审核被拒，提示广告标识或隐私清单缺失

现象是归档提交后收到审核拒绝，理由集中在广告标识、ATT 用途描述或隐私清单。原因通常是NSUserTrackingUsageDescription文案缺失、SKAdNetworkItems没从后台同步、PrivacyInfo.xcprivacy没有合并进主 target。还有一种情况是 ATT 弹窗在 SDK 初始化之前弹，用户拒绝后 SDK 仍然按个性化广告请求，合规链路对不上。

解决：先把 MAX 后台的 SKAdNetwork 清单完整复制到 Info.plist，不要只放一两条；再检查PrivacyInfo.xcprivacy是否在 Build Phases 的 Copy Bundle Resources 里；ATT 文案改成用户能看懂的目的说明，不要写“提升广告体验”这种空话。初始化顺序按第 3 章走：先 consent 和 do-not-sell，再初始化 SDK，ATT 弹窗放在首屏可交互后。资源包的 Xcode 检查表里有一项“归档前搜一遍 NSUserTrackingUsageDescription”，就是防这个。

5.3 现象：首次加载成功，二次展示无回调

现象是第一次展示正常，退出重进或切场景后再次调用加载，控制台没有任何回调，广告位一直空白。原因多半是事件订阅没有注销，旧对象的回调把新请求的回调顶掉；或者缓存里的MaxNativeAdView已经销毁，OnLoaded回来时找不到绑定目标；还有一种是loading锁没有在失败分支复位，后续请求全被门禁挡住。

解决：每次Load前先Unregister再注册，确保同一 adUnitId 只有一个监听者；失败分支和成功分支都要复位loading；缓存项取出后置空引用，不要重复使用已销毁的视图。资源包里的加载控制器把注册和注销成对放在方法里，场景OnDestroy再补一次兜底注销。真机复现时连续切三次场景，看[NativeTrace]里有没有重复的load_start没有对应load_success/fail。

5.4 现象：Native 高度塌陷或遮挡 SafeArea

现象是广告卡片在 iPhone 上高度变成 0，或者 CTA 按钮被 Home Indicator 压住，刘海区域文字被裁。原因是原生视图的 frame 用了 Unity 的像素尺寸，没有换算成 point；或者safeAreaInsets在viewDidLoad里读，拿到的全是 0；还有一种是 Prefab 根节点用了ContentSizeFitter，原生视图不受 Unity 布局系统控制，父容器高度塌陷。

解决：桥接层在viewDidLayoutSubviews里重算 frame，用safeAreaInsets缩进；C# 侧给容器一个最小高度，不要依赖ContentSizeFitter撑开；资源包里的MaxNativeAdView暴露minHeight和safeAreaMode，按广告位设 90 到 120 point。真机验证时至少看一台带刘海和一台带 Home Indicator 的机型，旋转一次再切回来，确认 frame 没有漂。

5.5 现象：收益回调延迟与归因对不上

现象是客户端日志里OnAdRevenuePaidEvent很久才来，或者后台报表的收益和客户端累计对不上。原因是收益回调本身有延迟，聚合平台还要做归因和去重；客户端拿AdInfo.Revenue做实时报表，时区和货币单位没统一；测试模式下的收益是模拟值，不能和正式报表比。

解决：客户端只记adUnitId、revenue、currency、precision和回调时间，不在客户端算 eCPM；报表对齐用后台的时区和结算口径；测试包打开 mediation debugger 时明确标记，不要混入正式埋点。资源包里的OnClicked日志带AdInfo.Revenue，只用于排查展示链路，不作为结算依据。发现延迟先看 MAX 后台的回调状态，再查 App 是否在后台被挂起。

6. 进阶验证：用一套最小埋点把 eCPM、展示率和崩溃率串起来

6.1 三个必须打的时间戳

Native 广告的验证不需要一上来就上全套数据平台，先打三个时间戳就够：load_start、load_success、show。load_start到load_success是填充耗时，load_success到show是缓存和场景挂载耗时，show到click是素材吸引力。三个时间戳都带 adUnitId 和场景名，真机日志和后台报表才能对上。资源包里的NativeTrace就是按这个粒度封装的，字段不要自己另起一套。

6.2 用表格对照 MAX 回调与业务埋点

表格里的业务埋点不要和 MAX 回调同名，否则日志里分不清是 SDK 回调还是业务上报。show要在原生视图真正可见后打，不要和load_success合并。load_fail的 code 要原样保留，后面按错误码聚合，能看出是无填充多还是适配器初始化失败多。

6.3 上线前我固定跑的 20 分钟检查清单

上线前我会拿真机跑一轮固定检查：冷启动进主界面，等 3 秒看预加载是否完成；进广告场景，看load_success到show是否小于 1 秒；连续切三次场景，看有没有重复回调；断网再恢复，看失败重试是否退避；打开 Xcode View Hierarchy，看原生视图有没有超出 SafeArea；最后归档前搜一遍NSUserTrackingUsageDescription、SKAdNetworkItems和PrivacyInfo.xcprivacy。这套流程不长，但能挡住大部分白屏和审核问题。

资源我放在文末的下载入口里，拿到后先按第 3 章跑通一次真机展示，再按第 4 章把缓存和回收加上，最后用第 6 章的埋点表对一遍。从那以后我每次接 Native 广告都强制走一遍真机层级检查和回调注销检查，不再相信 Editor 里的“看起来正常”。希望帮到你。

本文还有配套的精品资源，点击获取