简介面向Unity iOS开发者这份资料包聚焦AppLovin Max Native广告的接入与展示提供可直接参考的工程级示例涵盖SDK初始化、广告位加载、原生模板视图与事件回调等关键环节适合已具备基础Unity与iOS打包经验、希望提升广告变现能力的中级开发者。包内共58个文件约367KB。以21张png界面素材和若干json配置、meta文件为主辅以Objective-C/C混编源码、Swift模块说明文件、nib视图、framework及Assets.car资源能较完整地呈现原生广告的UI布局与桥接结构。已有106人学习。读者可从中获得Native广告视图的搭建思路、素材组织方式、Unity与iOS原生层交互的参考实现以及接入过程中常见配置与回调处理的可复用代码片段。1. 一个 Native 广告位为什么最后靠 Objective-C 才贴得准设计稿发过来时是一张卡片左上 48×48 的 icon右侧两行标题加一行描述底部一条 CTA 按钮圆角 12半透明底。接入 Unity 侧现成的横幅和 MREC 接口后实际出来的是一条 320×50 的横条位置、比例、样式全对不上美术看过一眼就摇头。AppLovin MAX 聚合里能按你自己的版式渲染素材的只有 Native 这一路而 Native 在 iOS 上最终落到的是一个原生 UIView不是 UGUI 里能直接塞进 RawImage 的贴图。所以只要 Unity 项目要在 iOS 上做原生卡片位就绕不开一层 Objective-C 桥接把 MANativeAdLoader 包成 Unity 能调的函数再把原生广告视图按 UGUI 的位置贴到画面上。下面按加载链路、桥接层、坐标与层级、翻车现场、上线自测五段讲适合已经跑通横幅和激励视频、准备上原生位的团队。2. MAX 的 Native 链路从 MANativeAdLoader 到能点的 UIView2.1 请求、填充、渲染是三步不是一步MAX 后台创建 Ad Unit 时要选 Native 格式这是第一步选错了后面全白搭。一个 Ad Unit 一旦建成其他格式改格式等于新建历史数据不继承。创建完把 Ad Unit ID 抄到 Unity 侧配置里同时确认这个 Unit 在后台挂了至少一条 Bidding 或 Waterfall 线路否则本地请求会稳定返回空。iOS 侧的加载入口是 MANativeAdLoader。它和横幅、插屏的最大区别是加载成功的回调给你的不是“一个可以 show 的视图”而是“一份素材对象”。素材里有标题、描述、CTA 文案、icon、主图或视频容器怎么摆、摆多大、什么背景色全是你的代码决定的。这一步想不通的人会在文档里找 show 方法找半天——Native 没有传统意义上的 show只有“把素材渲染进我提供的视图然后把视图加到屏幕上”。渲染这一步有两个选择。一是用 SDK 提供的原生广告视图模板xib 形态通过 binder 把素材字段绑上去省事但版式固定二是自己用 UIView 拼一个容器手动把 titleLabel、bodyLabel、ctaButton、iconImageView、mediaViewContainer 一个个赋值。设计稿越花越要走第二条。无论哪条mediaView 容器必须存在且尺寸非零视频类素材就是往这里渲染的缺了它你会看到“广告加载成功但一片空白”这个问题后面避坑章还会再提一次。2.2 纹理回传看起来省事但走不远我见过最常见的偷懒方案是把原生广告视图渲染成 UIImage转成 Texture2D塞进 UGUI 的 RawImage。代码量小布局用 UGUI 的 RectTransform 调产品改稿也快第一天跑起来确实爽。但这条路在真实场景里会接连出问题。第一素材里的视频不会动静态首帧就是永远的首帧点击率会被拉低。第二每帧或每次刷新截图有性能成本中低端机上滑动手感会掉。第三点击热区要自己从 UGUI 坐标反算到原生视图坐标CTA 按钮的点击判定一旦偏十几个点用户点不动就是点不动。第四Retina 下放大后边缘发虚设计验收过不了。第五无障碍和系统级的广告标识会被截断。常见做法是原生视图覆盖广告视图真真实实加在 UIKit 层级上Unity 只负责告诉它“放在屏幕的哪个矩形里”点击、视频播放、跳转全部由原生层自己处理。代价是坐标和层级要自己算准而这正是最容易翻车的地方。2.3 工程接线Podfile 会被覆盖源头在 Dependencies.xmlUnity 导出 iOS 工程后依赖管理有两种情况。如果工程里用了 EDM4UExternal Dependency ManagerPodfile 是自动生成的你手动加一行 pod下次构建会被原样覆盖掉白改。这时候真正的源头是工程里的 Dependencies.xml把 iOS 依赖写进去让 EDM4U 去生成 Podfile。!-- Assets/Plugins/Editor/Dependencies.xml 片段 -- dependencies iosPods !-- 聚合 SDK 本体版本区间按后台文档锁不要写 latest -- iosPod nameAppLovinSDK version~ 12.0 minTargetSdk13.0 / !-- mediation adapter 按后台给的清单逐个加全量接入会让包体明显膨胀 -- iosPod nameAppLovinMediationXXXAdapters version~ 1.0 minTargetSdk13.0 / /iosPods /dependencies如果工程没接 EDM4U直接维护 Podfile# Podfile只在没有 EDM4U 的工程里手写 platform :ios, 13.0 target UnityFramework do # 注意 target 是 UnityFramework不是 Unity-iPhone # 桥接代码编译在 framework 里pod 也要跟着进去 pod AppLovinSDK pod AppLovinMediationXXXAdapters end两个容易忽略的点。第一target 必须是 UnityFramework写错 target 后桥接文件找不到头文件报一堆 use of undeclared identifier。第二桥接的 .mm 文件放在 Assets/Plugins/iOS/ 下Unity 会自动加进 Xcode 工程但如果你手动改过导出工程重新导出会丢养成“改 Unity 侧源文件、不改导出产物”的习惯。2.4 方法签名以头文件为准别照抄旧博客MAX 的 Native 回调签名在小版本之间调整过参数列表里多一个 adView 或少一个编译期就报错或者编译过了但拿到的对象是 nil。接手项目第一件事不是写代码是确认手上的 SDK 到底长什么样# 在导出的 iOS 工程根目录执行确认 native 相关类和方法签名 grep -rn MANativeAdLoader Pods/AppLovinSDK/ --include*.h | head -20 grep -rn didLoadNativeAd Pods/AppLovinSDK/ --include*.h grep -rn MANativeAdViewBinder Pods/AppLovinSDK/ --include*.h | head -20这三条命令的输出就是你的“正确文档”。参数名、是否带 adView、binder 的属性叫什么全部以这里为准。网上抄来的代码如果和头文件对不上别怀疑头文件怀疑抄来的代码。提示把这三条命令的输出贴进项目 README下次升级 SDK 时先跑一遍对比能省掉一次通宵排查。3. 桥接层怎么写把 Native 广告包成 Unity 能 DllImport 的四个函数3.1 接口只留四个别把整个 SDK 都暴露出去Unity 和原生之间的边界越窄越好维护。我的习惯是只导出四个 C 函数Unity 侧不需要知道 MAX 的任何类名。C 函数作用调用时机MaxNative_Init初始化聚合 SDK打开测试模式开关启动时一次MaxNative_Load按 Ad Unit ID 发起加载同时传入屏幕矩形页面打开、失败重试MaxNative_Show把已渲染好的容器挂到窗口上加载成功且页面可见时MaxNative_Hide从父视图移除并释放素材引用页面关闭、切场景四个函数都是幂等的Load 在加载中时直接忽略、Show 在没素材时返回、Hide 调两次不出错。这个约束看着笨但能挡掉 Unity 侧绝大多数乱序调用。3.2 Objective-C 实现骨架// MaxNativeBridge.mm // 放在 Assets/Plugins/iOS/ 下Unity 自动加入 Xcode 工程 #import AppLovinSDK/AppLovinSDK.h #import UIKit/UIKit.h #import UnityInterface.h // UnitySendMessage / UnityGetMainWindow static MANativeAdLoader *gLoader nil; static MANativeAd *gNativeAd nil; static UIView *gContainer nil; // 我们自己的卡片容器 static UIWindow *gAdWindow nil; // 覆盖在 Unity 之上的窗口 extern C { void MaxNative_Init(const char *sdkKey, BOOL testMode) { // 初始化必须走主线程Unity 启动早期调用要切一下 dispatch_async(dispatch_get_main_queue(), ^{ ALSdk *sdk [ALSdk sharedWithKey:[NSString stringWithUTF8String:sdkKey] settings:[ALSdkSettings new]]; [sdk initializeSdkWithCompletionHandler:nil]; // 测试设备用 SDK 内部日志开关别把测试标识写进线上包 (void)testMode; }); } void MaxNative_Load(const char *adUnitId, float px, float py, float pw, float ph, float unityScreenW, float unityScreenH) { dispatch_async(dispatch_get_main_queue(), ^{ NSString *unit [NSString stringWithUTF8String:adUnitId]; if (!gLoader) { gLoader [[MANativeAdLoader alloc] initWithAdUnitIdentifier:unit]; // delegate 是弱引用代理对象要用 static 持有别用局部变量 gLoader.delegate (idMANativeAdLoaderDelegate)[MaxNativeDelegate shared]; } // 每次加载都重建 loader 时记得重置 adUnitId复用 loader 时只改 id CGRect uikitRect UnityPixelRectToUIKit(CGRectMake(px, py, pw, ph), CGSizeMake(unityScreenW, unityScreenH)); [MaxNativeDelegate shared].pendingRect uikitRect; [gLoader loadAd]; }); } void MaxNative_Show(void) { dispatch_async(dispatch_get_main_queue(), ^{ if (!gContainer || !gAdWindow) { return; } gAdWindow.hidden NO; [gAdWindow makeKeyAndVisible]; }); } void MaxNative_Hide(void) { dispatch_async(dispatch_get_main_queue(), ^{ [gContainer removeFromSuperview]; gAdWindow.hidden YES; gNativeAd nil; // 断掉素材引用避免退出页面后仍占内存 }); } } // extern C几个关键点。第一所有 UI 和 SDK 操作都 dispatch 到主线程Unity 的调用线程不保证是主线程省这一步会出现偶发的 Main Thread Checker 报错。第二delegate 必须是长期存活的对象写成一个单例写成局部变量会在方法返回后变成野指针回调时直接崩。第三Hide 里显式置空 gNativeAd这是内存增长问题最常见的一处遗漏。3.3 加载回调只做两件事// MaxNativeDelegate.mm 核心回调 - (void)didLoadNativeAd:(MANativeAd *)nativeAd forAdUnitIdentifier:(NSString *)adUnitIdentifier { gNativeAd nativeAd; // 渲染进自己的容器第二步再挂窗口 [self renderNativeAd:nativeAd intoRect:self.pendingRect]; UnitySendMessage(MaxNativeReceiver, OnNativeAdLoaded, adUnitIdentifier.UTF8String); } - (void)didFailToLoadNativeAdForAdUnitIdentifier:(NSString *)adUnitIdentifier withError:(MAError *)error { gNativeAd nil; // 把 code 和 message 一起回传Unity 侧才好决定是重试还是报错埋点 NSString *payload [NSString stringWithFormat:%ld|%, (long)error.code, error.message ?: ]; UnitySendMessage(MaxNativeReceiver, OnNativeAdFailed, payload.UTF8String); }回调方法名以 2.4 节 grep 出来的头文件为准参数列表不一致时按头文件改逻辑不变。回传给 Unity 的错误信息里带上 code非常重要——后续按错误码分类统计能一眼看出是“没库存”还是“配置写错了”。3.4 Unity 侧平台宏 回调派发// MaxNativeBridge.cs using System; using System.Runtime.InteropServices; using UnityEngine; public static class MaxNativeBridge { #if UNITY_IOS !UNITY_EDITOR [DllImport(__Internal)] private static extern void MaxNative_Init(string sdkKey, bool testMode); [DllImport(__Internal)] private static extern void MaxNative_Load( string adUnitId, float x, float y, float w, float h, float screenW, float screenH); [DllImport(__Internal)] private static extern void MaxNative_Show(); [DllImport(__Internal)] private static extern void MaxNative_Hide(); #endif public static void Load(string adUnitId, Rect rectInPixels, Vector2 screenInPixels) { #if UNITY_IOS !UNITY_EDITOR MaxNative_Load(adUnitId, rectInPixels.x, rectInPixels.y, rectInPixels.width, rectInPixels.height, screenInPixels.x, screenInPixels.y); #else // 编辑器和其他平台走假数据保证 UI 流程能跑通 MaxNativeReceiver.Instance?.OnNativeAdFailed(-1|editor_mock); #endif } }这里有一个必须做的设计Rect 用像素传不要传 UGUI 的锚点或归一化坐标。UGUI 的锚点、CanvasScaler 的匹配模式、安全区补偿全在 Unity 侧算完原生层只接受“屏幕左下角为原点的像素矩形”职责单一出问题好定位。回调统一走 UnitySendMessage 到一个常驻 GameObject// MaxNativeReceiver.cs using UnityEngine; public class MaxNativeReceiver : MonoBehaviour { public static MaxNativeReceiver Instance { get; private set; } public event System.Actionstring OnLoaded; public event System.Actionstring OnFailed; private void Awake() { if (Instance ! null) { Destroy(gameObject); return; } Instance this; DontDestroyOnLoad(gameObject); // 切场景时不销毁否则原生回调找不到接收方 } // 原生层通过 UnitySendMessage 调到这里方法名必须完全一致 public void OnNativeAdLoaded(string adUnitId) OnLoaded?.Invoke(adUnitId); public void OnNativeAdFailed(string payload) OnFailed?.Invoke(payload); }DontDestroyOnLoad 这一行别省。切场景时接收方被销毁原生层回调打过来会静默失败表现是“广告加载成功但界面永远不刷新”排查起来非常耗时间。4. 坐标系与视图层级把原生 UIView 精确贴到 UGUI 的坑位4.1 像素、点、nativeScale 三个概念先分清Unity 的 Screen.width 返回像素UIKit 的 bounds 用点中间隔着一个缩放比。直接拿 Unity 矩形除以[UIScreen mainScreen].scale在多数机型上对得上在 Plus 系列和历史缩放模式上会偏。我的做法是用两端上报的屏幕宽度反算比例不依赖任何固定常量// 用 Unity 上报的屏幕像素宽 / UIKit 的屏幕点宽得到真实换算比 static CGRect UnityPixelRectToUIKit(CGRect pixelRect, CGSize unityScreenPx) { CGFloat uiWidthPt [UIScreen mainScreen].bounds.size.width; if (uiWidthPt 0 || unityScreenPx.width 0) { return CGRectZero; } CGFloat ratio unityScreenPx.width / uiWidthPt; // 像素 / 点 CGFloat x pixelRect.origin.x / ratio; CGFloat w pixelRect.size.width / ratio; CGFloat h pixelRect.size.height / ratio; // Unity 原点在左下UIKit 原点在左上纵向要翻一次 CGFloat y (unityScreenPx.height - pixelRect.origin.y - pixelRect.size.height) / ratio; return CGRectMake(x, y, w, h); }纵向翻转是最容易写错的一行。写错的表现是广告出现在屏幕顶部而不是 UGUI 里预留的位置很多人第一反应是“坐标传错了”实际是忘了翻 Y。4.2 安全区和旋转刘海屏上 CTA 被切一半原生窗口如果覆盖全屏容器贴到屏幕底部时会被 Home Indicator 压住贴到顶部会被灵动岛区域盖住。处理方式是在容器的 layoutSubviews 里读 safeAreaInsets 做内缩- (void)layoutSubviews { [super layoutSubviews]; if (available(iOS 11.0, *)) { UIEdgeInsets inset self.safeAreaInsets; CGRect frame self.frame; // 只在广告矩形与安全区重叠时才内缩避免整体位移 if (CGRectGetMaxY(frame) CGRectGetHeight(self.superview.bounds) - inset.bottom) { frame.origin.y - inset.bottom; } self.frame frame; } }旋转的处理更麻烦。Unity 旋转后屏幕宽高互换原生窗口不会自动跟着重排。可靠做法是监听UIDeviceOrientationDidChangeNotification在回调里延迟一帧旋转动画结束重新向 Unity 请求当前矩形而不是自己猜新坐标。让 Unity 侧每次屏幕尺寸变化都重新调一次 Load 或一个新的 UpdateRect 函数逻辑只有一份不会两边算出不同结果。注意游戏锁定竖屏时也要处理“设备旋转但界面不转”的情况部分机型会因此触发一次多余的布局导致广告位置瞬移。4.3 层级方案三选一选错就是点不动方案实现方式优点风险独立 UIWindow新建 UIWindowwindowLevel 高于主窗口不被 Unity 视图裁剪弹窗层级可控键盘、旋转要自己转发容易被误做成全屏遮挡挂 rootViewController.viewaddSubview 到 Unity 根视图跟随旋转改动最小会被 Unity 后添加的视图盖住需要手动置顶挂 UnityView 子视图直接加到渲染视图上最简单Unity 渲染层可能覆盖它触摸事件容易冲突我一般选独立 UIWindow因为它把“广告层”和“游戏层”彻底解耦页面关闭时整窗隐藏不留残余视图。代价是要把窗口的isUserInteractionEnabled和 frame 管好——窗口如果铺满全屏用户点游戏其他地方就会被吞掉。4.4 素材绑定mediaView 容器必须有尺寸无论用 SDK 模板还是自绘容器绑定时有几个字段不能漏// 自绘容器的绑定顺序先赋值再布局避免首帧空白 - (void)bindAd:(MANativeAd *)ad { self.titleLabel.text ad.title; self.bodyLabel.text ad.body; [self.ctaButton setTitle:ad.callToAction forState:UIControlStateNormal]; self.iconImageView.image ad.icon.image; // mediaView 容器必须先有非零 frame视频素材才会渲染 self.mediaContainer.frame CGRectMake(0, 0, self.bounds.size.width, 180); [ad prepareViewForAd:self.adView]; }prepareViewForAd:这类方法名同样以头文件为准。顺序上先把容器尺寸算好再调渲染反过来会出现“素材已绑定但区域高度为 0”的白屏肉眼看起来就是加载失败实际是布局时序问题。5. 避坑Native 广告在 iOS 上最容易翻车的 5 个现场5.1 测试机永远 no fill线上填充率像过山车现象同一份代码开发机连续几天一条广告都不出日志里全是加载失败换台设备又正常。上线后后台看填充率早上 90%、晚上 40%波动没有规律。原因有两个层面。一是测试设备没有在后台登记MAX 对未登记设备可能返回测试素材或直接不填充尤其在你开了测试模式之后测试模式下只走测试源真实库存根本不参与。二是填充率本身和地域、时段、广告位类型强相关Native 在部分地区的库存本就比激励视频薄拿单一设备的观感去判断“SDK 有问题”是误判。解决先在后台把测试设备的标识登记进测试设备列表测试阶段只看“能不能加载出素材、样式对不对”不看收益。判断填充是否正常用后台按国家和广告位维度看趋势连续观察三天再下结论。本地排查时把错误码打全区分“无库存”和“配置错误”两类前者重试有意义后者重试一万次也没用。5.2 广告明明在那儿手指戳上去毫无反应现象卡片渲染出来了图片文字都对点 CTA 按钮没有任何跳转连按下的高亮都没有。原因通常出在视图层级和触摸传递上。最常见的是容器外层包了一个透明遮罩视图isUserInteractionEnabled默认是 YES 但没实现任何手势触摸全被它吃掉。其次是广告窗口虽然显示但windowLevel设得比某个全屏 UI 低视觉上能看到触摸却落到了上层视图。还有一种隐蔽情况Unity 侧在广告上方盖了一个透明的 UGUI 面板用于拦截游戏输入UGUI 的射线检测和 UIKit 的 hitTest 是两套体系肉眼看不出来谁在上面。解决用 Xcode 的 View Debugger 逐层看 hitTest 落到哪个视图比打印日志快十倍。广告容器的父级链上除按钮和可点击区域外其余视图一律设isUserInteractionEnabled NO。Unity 侧的拦截面板在广告展示期间关掉或者把广告窗口层级抬高到它之上。5.3 首帧白屏或者高度塌成 0现象加载成功回调也收到了广告区域一片白过一两秒偶尔自己出现滚动列表时又变白。原因渲染发生在布局之前。容器 frame 还是 CGRectZeromediaView 容器没有尺寸SDK 把素材塞进去也显示不出来。列表复用时更明显容器被复用但没重新绑定。解决绑素材前强制[container layoutIfNeeded]确保约束已经算出实际尺寸容器每次复用时先清空所有子视图再绑定给容器一个最小高度兜底比如 80pt避免极端情况下高度为 0 导致整块消失。5.4 提审被打回理由和广告有关现象功能都正常审核反馈说广告展示存在问题或者要求补充隐私相关说明。原因集中在三处缺少跟踪授权相关的用途描述系统弹窗弹不出来广告遮挡了游戏关键操作区域或者关闭入口广告样式诱导点击比如把 CTA 做得像游戏内按钮。这几条都是审核的高频关注点。解决Info.plist 里补齐用途描述文案启动后合适的时机请求授权被拒绝也要保证广告能正常展示非个性化素材。广告位不要压在主操作按钮上卡片之间留出足够间距。CTA 文案用 SDK 给的原值不要自己改成“领取奖励”之类的诱导话术。5.5 来回切场景几次之后崩在回调里现象单次展示正常进游戏、退出、再进第三次左右崩溃堆栈指向原生广告的回调或者 delegate。原因Unity 侧的接收对象被销毁了原生层还在往一个不存在的对象发消息或者 Hide 只做了 hidden 没有 removeFromSuperview素材对象越积越多又或者 delegate 被设成了局部对象方法返回即成野指针。解决接收对象挂 DontDestroyOnLoadHide 里做完整的三件事——removeFromSuperview、置空素材引用、把 delegate 置回单例页面销毁时先调 Hide 再销毁 GameObject顺序反了就会出现“对象已销毁、回调还在路上”的经典组合。6. 上线前的一次量化自测填充率、eCPM 和脚本化回归怎么跑功能跑通不等于能上线。我一般在提测前做一轮量化自测把“感觉能用”变成“数据上能用”。先做一个最小回归脚本在真机上连续跑 50 次加载统计成功率和平均耗时// 只用于测试包的批量加载统计正式包不打包 IEnumerator LoadLoop(int times) { int ok 0; for (int i 0; i times; i) { float t0 Time.realtimeSinceStartup; MaxNativeBridge.Load(adUnitId, rect, screenSize); yield return new WaitForSeconds(8f); // 给加载留足超时窗口 // 结果由 OnLoaded / OnFailed 回调累加这里只统计次数 Debug.Log($[NativeTest] round{i} cost{Time.realtimeSinceStartup - t0:F1}s); } Debug.Log($[NativeTest] success{ok}/{times}); }观察三个数成功率低于 70% 说明配置或地域库存有问题别急着怪代码平均耗时超过 5 秒说明聚合层线路太多、超时设置偏长连续失败集中在同一个错误码直接去后台核对那个网络的接入状态。再看一张自测项表逐项过一遍再发包自测项判定标准出问题先看哪里冷启动首次加载3 秒内出素材初始化时机是否早于广告请求列表复用滚动 20 次无白屏、无错位容器是否每次重新绑定横竖屏切换位置跟随、不遮挡安全区是否重新请求矩形点击跳转CTA 可点、返回后游戏正常视图层级与 hitTest连续 50 次加载无崩溃、内存无持续增长Hide 是否完整释放弱网有超时兜底、不卡主线程加载是否在主线程同步等待最后是收益侧的观察。上线后按国家和广告位维度看 eCPMNative 的 eCPM 通常低于激励视频但展示频次高两个指标要一起看只盯 eCPM 会得出“原生位不值得做”的错误结论。开启 Bidding 后前三天数据波动大别急着调价等填充稳定再看。说个我自己的教训早期做原生位我把“加载成功”当成“展示成功”上报结果后台数据和真实曝光差了将近四成花了很久才定位到是布局时序导致的白屏。从那以后我坚持两条——曝光埋点必须放在原生层确认视图真正可见之后任何涉及坐标和层级的改动都要在三种机型上各走一遍。原生广告这层桥接不难难的是把每一个“看起来正常”的环节都验证一遍。希望帮到你。本文还有配套的精品资源点击获取