Unity iOS 接入 AppLovin MAX Native 广告：桥接、视图挂载与避坑指南

简介本资源面向使用 Unity 引擎开发 iOS 应用的开发者聚焦 AppLovin Max 平台 Native 原生广告的接入实践帮助解决广告变现流程中 SDK 集成、广告位配置与事件回调处理等关键问题适合具备一定 Unity 与 iOS 基础的中级开发者参考。资源包共 58 个文件约 367KB以 21 个 png 图片资源、15 个 meta 配置、8 个 json 数据文件为主另含 h、mm、swift 等源码文件及 MaxNativeAdFramework 框架、nib 视图与 plist 配置覆盖原生广告展示所需的素材、脚本与框架依赖。目前已有 106 人学习。通过该资源可获取 Native 广告接入所需的框架文件、视图布局与代码示例便于对照完成 SDK 初始化、广告加载展示及回调逻辑的落地并借助图片素材快速搭建广告展示区域减少自行摸索成本。1. 从一次真机崩溃说起Unity iOS 接入 Native 广告到底难在哪去年帮一个做超休闲游戏的朋友排查线上问题iOS 端接完广告 SDK 后编辑器里跑得好好的真机一上就崩日志只给一句SIGABRT连堆栈都看不全。折腾两天才发现是原生广告视图的层级挂载时机不对——Unity 侧还没准备好原生代码就急着往UIViewController上贴视图。这类问题在 Unity 接 iOS 原生广告时太常见了编辑器模拟不了真机的视图生命周期很多坑只有打包上机才会暴露。这份资源就是冲着这个场景来的Unity 项目接入 AppLovin MAX 的 Native 广告平台限定 iOS。它把桥接层、原生视图封装、回调透传这几块最容易翻车的地方整理成了可复用的工程代码。适合两类人一是第一次接 MAX Native 广告、被 iOS 原生交互绕晕的 Unity 开发二是接过 Banner 和插屏、但没碰过 Native 自渲染、想搞清楚原生视图怎么和 Unity 通信的老手。下面按「能干什么 → 怎么跑 → 怎么改」的顺序拆。2. 工程结构与桥接设计Unity 和 iOS 原生是怎么对上话的2.1 目录分层与文件职责拿到这份资源先别急着打开场景跑。花五分钟把目录结构过一遍后面改代码能省一半时间。整体是典型的 Unity iOS 插件工程布局核心分三层Assets/ ├── Plugins/ │ └── iOS/ │ ├── MAXNativeBridge.h/.mm # Objective-C 桥接层暴露给 Unity 的 C 接口 │ ├── MAXNativeAdView.h/.mm # 原生广告视图封装管理 UIView 生命周期 │ └── MAXNativeAdLoader.h/.mm # 广告加载器对接 AppLovin MAX SDK ├── Scripts/ │ ├── NativeAdController.cs # Unity 侧调用入口DllImport 声明 │ ├── NativeAdCallback.cs # 回调接收处理加载/展示/点击事件 │ └── NativeAdLayout.cs # 布局参数配置传给原生侧 └── Scenes/ └── NativeAdDemo.unity # 演示场景Plugins/iOS下的.mm文件是混编的 Objective-C之所以用.mm而不是.m是因为要直接调 C 标准库做字符串和容器处理跟 Unity 的Il2Cpp交互时更稳。Scripts下三个 C# 文件各管一摊NativeAdController负责发指令NativeAdCallback负责收结果NativeAdLayout负责传布局参数。这种职责分离的好处是改布局不用动加载逻辑排查回调问题也不用翻桥接代码。2.2 桥接层的 C 接口设计Unity 调 iOS 原生绕不开DllImport和extern C。这份资源里桥接层暴露的接口很克制就四个函数对应广告的加载、展示、销毁和布局更新// NativeAdController.cs using System.Runtime.InteropServices; public class NativeAdController { // 加载原生广告adUnitId 是 MAX 后台创建的广告单元 ID [DllImport(__Internal)] private static extern void _LoadNativeAd(string adUnitId); // 在指定屏幕坐标展示广告x/y 是 Unity 坐标系转过来的像素值 [DllImport(__Internal)] private static extern void _ShowNativeAd(float x, float y, float width, float height); // 销毁当前广告视图切场景时必须调否则视图泄漏 [DllImport(__Internal)] private static extern void _DestroyNativeAd(); // 更新布局用于屏幕旋转或动态调整位置 [DllImport(__Internal)] private static extern void _UpdateNativeAdLayout(float x, float y, float width, float height); public static void LoadAd(string adUnitId) _LoadNativeAd(adUnitId); public static void ShowAd(Rect rect) _ShowNativeAd(rect.x, rect.y, rect.width, rect.height); public static void DestroyAd() _DestroyNativeAd(); public static void UpdateLayout(Rect rect) _UpdateNativeAdLayout(rect.x, rect.y, rect.width, rect.height); }DllImport(__Internal)是 Unity iOS 静态链接的固定写法不能写成库名。四个函数的参数都刻意用了基础类型string、float没传结构体或对象因为跨语言传复杂类型容易在Il2Cpp下出内存对齐问题。adUnitId从 MAX 后台拿格式类似xxxxxxxxxxxxxxxx每个广告位一个测试阶段可以用 MAX 提供的测试 ID。对应的原生侧实现以加载函数为例// MAXNativeBridge.mm extern C void _LoadNativeAd(const char* adUnitId) { NSString *unitId [NSString stringWithUTF8String:adUnitId]; // 切回主线程MAX SDK 的加载必须在主线程发起 dispatch_async(dispatch_get_main_queue(), ^{ [[MAXNativeAdLoader sharedInstance] loadAdWithUnitId:unitId]; }); }这里有个血泪经验dispatch_async切主线程不能省。Unity 调原生时可能在渲染线程或子线程而 iOS 的 UI 操作和 MAX SDK 的加载都要求主线程不切就是玄学崩溃日志还看不出来。NSString stringWithUTF8String处理 C 字符串转 OC 字符串注意adUnitId不能传空指针Unity 侧调用前要判空。2.3 原生视图的挂载与生命周期Native 广告和 Banner 最大的区别是Banner 是 SDK 自己管视图Native 是你自己拿素材自己拼视图。这份资源里MAXNativeAdView继承自UIView内部用MANativeAdView承载素材挂载逻辑是这样的// MAXNativeAdView.mm - (void)attachToRootView:(CGRect)frame { // 获取当前 Unity 的根视图控制器 UIViewController *rootVC [self getUnityRootViewController]; if (!rootVC) { NSLog([MAXNative] root view controller not found); return; } self.frame frame; // 先移除旧的避免重复挂载导致视图叠加 [self removeFromSuperview]; [rootVC.view addSubview:self]; [rootVC.view bringSubviewToFront:self]; } - (UIViewController *)getUnityRootViewController { // Unity 的根视图控制器在 UIApplication 的 keyWindow 上 UIWindow *keyWindow [UIApplication sharedApplication].keyWindow; return keyWindow.rootViewController; }attachToRootView里先removeFromSuperview再addSubview这个顺序别反。重复挂载是 Native 广告最常见的翻车点表现是广告视图叠了好几层点击事件错乱或者内存涨得飞快。bringSubviewToFront保证广告在最上层不然可能被 Unity 的渲染视图盖住用户看得到点不到。生命周期这块viewDidDisappear和场景切换时要主动调_DestroyNativeAd。Unity 切场景不会自动销毁原生视图不手动清就是内存泄漏跑几个场景后UIViewController堆一堆最后 OOM。3. 从零跑通环境配置、打包与真机验证3.1 环境准备与依赖导入跑这个工程前环境得先对齐。Unity 版本建议 2021.3 LTS 及以上iOS 构建模块要装好。Xcode 版本 14 以上因为 AppLovin MAX SDK 较新版本对 Xcode 有要求。MAX SDK 本身不在这份资源里需要自己去 AppLovin 后台下载 iOS SDK 并导入常见做法是把AppLovinSDK.framework和AppLovinMediation相关文件拖进Assets/Plugins/iOSUnity 打包时会自动链接。导入后检查两个地方一是Assets/Plugins/iOS下有没有.framework文件夹二是 Player Settings 里Other Settings的Scripting Backend要选IL2CPPTarget Device选iPhone。Api Compatibility Level用.NET Standard 2.1就行别选.NET FrameworkiOS 上不支持。MAX 后台要创建广告单元类型选 Native拿到adUnitId。测试阶段可以用 MAX 的测试模式在初始化时调[ALSdk shared].settings.testDeviceAdvertisingIdentifiers加上测试设备 ID这样不会产生真实收益也不会被限流。3.2 初始化与加载流程广告加载前必须先初始化 MAX SDK这步在 Unity 侧通过桥接调原生完成// NativeAdController.cs 补充初始化 [DllImport(__Internal)] private static extern void _InitMAXSDK(string sdkKey); public static void InitSDK(string sdkKey) { if (string.IsNullOrEmpty(sdkKey)) { Debug.LogError([MAXNative] sdkKey is empty); return; } _InitMAXSDK(sdkKey); }sdkKey从 MAX 后台账户设置里拿一串字符。初始化是异步的原生侧会回调didInitializeWithAdInfoUnity 侧通过NativeAdCallback接收。初始化没完成就调加载MAX 会直接返回失败日志里是SDK not initialized。所以加载逻辑要放在初始化回调之后别在Start里直接调。加载和展示的调用顺序void Start() { NativeAdController.InitSDK(你的sdkKey); } // 初始化成功回调里触发加载 public void OnSDKInitialized() { NativeAdController.LoadAd(你的native广告单元ID); } // 加载成功回调里展示 public void OnAdLoaded() { Rect adRect new Rect(0, Screen.height - 300, Screen.width, 300); NativeAdController.ShowAd(adRect); }adRect的坐标是 Unity 屏幕坐标系左下角原点。原生侧拿到后要转成 iOS 的坐标系iOS 是左上角原点所以y要翻转iosY Screen.height - unityY - height。这个转换在桥接层做Unity 侧不用管。不转的话广告位置会上下颠倒这是新手最容易踩的坑之一。3.3 打包与真机调试Unity 导出 Xcode 工程后用 Xcode 打开先改 Bundle Identifier 和签名。签名用自动管理就行选自己的开发者账号。然后检查Build Phases里的Link Binary With Libraries确认AppLovinSDK.framework和StoreKit.framework、AdSupport.framework都在缺了会链接报错。真机跑之前Xcode 里开Console看日志。MAX 的日志默认是关的调试时在初始化前调[ALSdk shared].settings.verboseLoggingEnabled YES能看到加载各阶段的详细输出。广告加载失败常见原因就几个adUnitId填错、测试设备没加白名单、网络请求被拦、SDK 没初始化完就加载。日志里error code对照 MAX 文档查-1009是网络问题204是无填充。真机验证时重点看三件事广告视图位置对不对、点击能不能跳转、切场景后视图有没有销毁。位置不对查坐标转换点击没反应查bringSubviewToFront和视图层级切场景泄漏查_DestroyNativeAd有没有调。4. 避坑与排查Native 广告接入的五个高频翻车点4.1 编辑器正常真机崩溃现象Unity 编辑器里跑 Demo 场景一切正常打包到真机一加载广告就SIGABRT堆栈指向UIApplication相关调用。原因编辑器用的是模拟的 iOS 环境UIApplication sharedApplication和keyWindow在编辑器里不存在原生代码在编辑器下走的是空实现。真机上这些调用真实执行如果时机不对比如keyWindow还没创建就崩。解决所有原生 UI 操作加主线程判断和空值检查getUnityRootViewController里keyWindow为空时返回 nil 并打日志别硬用。加载逻辑放在didFinishLaunching之后别在Awake里就调。4.2 广告视图位置偏移或颠倒现象广告展示出来了但位置跟预期差一截或者上下颠倒。原因Unity 屏幕坐标系原点在左下角iOS 在左上角y轴方向相反。桥接层没做转换或者转换时用了错误的屏幕高度比如用了Screen.height但没考虑安全区。解决在_ShowNativeAd里统一转换iosY screenHeight - unityY - height。有刘海屏的机型还要减安全区高度rootVC.view.safeAreaInsets.top拿一下。4.3 点击事件无响应现象广告显示正常但点击没反应不跳转也不回调。原因广告视图被其他视图盖住了或者userInteractionEnabled被设成了NO。Unity 的渲染视图层级比较高addSubview后没bringSubviewToFront就会被盖。解决挂载后调bringSubviewToFront并确认self.userInteractionEnabled YES。如果用了透明遮罩层检查遮罩有没有拦截触摸。4.4 切场景后内存持续上涨现象反复切场景内存只涨不降跑十几分钟后 OOM。原因原生广告视图没销毁UIViewController的view上挂着一堆MAXNativeAdView实例。Unity 切场景不会自动清理原生视图。解决在OnDestroy或场景卸载回调里调NativeAdController.DestroyAd()原生侧removeFromSuperview并把引用置 nil。MAX 的MANativeAdView也要调destroy释放素材。4.5 回调丢失或重复触发现象加载成功回调偶尔收不到或者同一次加载触发了两次OnAdLoaded。原因桥接层的回调函数指针在 Unity 侧注册时如果多次注册没去重就会重复触发。回调丢失通常是原生侧dispatch_async切线程后Unity 对象已经被销毁回调发到了空对象上。解决回调注册用单例模式NativeAdCallback保证全局只有一个实例。原生侧发回调前检查 Unity 对象是否还存活用UnitySendMessage时目标 GameObject 要判空。5. 二次开发把 Native 广告做成可配置的通用组件5.1 布局参数外置与动态调整这份资源目前的布局是写死在 C# 里的二次开发第一步我一般会把布局参数抽成ScriptableObject让策划或运营能不改代码调位置// NativeAdConfig.cs using UnityEngine; [CreateAssetMenu(fileName NativeAdConfig, menuName MAX/NativeAdConfig)] public class NativeAdConfig : ScriptableObject { public string sdkKey; public string nativeAdUnitId; [Range(0, 1)] public float anchorX 0.5f; // 水平锚点0 左 1 右 [Range(0, 1)] public float anchorY 0.1f; // 垂直锚点0 下 1 上 public float adHeight 300f; // 广告高度像素 public bool autoReload true; // 展示后是否自动重载 }anchorX和anchorY用归一化值运行时乘屏幕宽高算实际坐标这样适配不同分辨率不用改配置。autoReload控制展示后是否自动加载下一条Native 广告通常需要预加载不然展示完再加载会有空窗期。5.2 多广告位与预加载队列单广告位跑通后实际项目往往要多个位置轮换。我一般会加一个简单的预加载队列public class NativeAdManager : MonoBehaviour { private Queuestring adUnitQueue new Queuestring(); private Dictionarystring, bool adReady new Dictionarystring, bool(); public void Preload(string adUnitId) { if (adReady.ContainsKey(adUnitId) adReady[adUnitId]) return; adUnitQueue.Enqueue(adUnitId); TryLoadNext(); } private void TryLoadNext() { if (adUnitQueue.Count 0) return; string unitId adUnitQueue.Dequeue(); NativeAdController.LoadAd(unitId); } public void OnAdLoaded(string adUnitId) { adReady[adUnitId] true; TryLoadNext(); // 加载完一个接着加载下一个 } }队列的好处是控制并发MAX 对同时加载的广告数有限制一次加载太多会被限流。adReady字典记录哪些广告位已就绪展示时直接从就绪的里取避免展示时才开始加载。5.3 验证改造是否生效改完代码别急着上真机先在编辑器里跑逻辑验证。把原生调用用条件编译包起来编辑器下走 Mockpublic static void LoadAd(string adUnitId) { #if UNITY_IOS !UNITY_EDITOR _LoadNativeAd(adUnitId); #else Debug.Log($[Mock] Load native ad: {adUnitId}); // 模拟延迟回调 NativeAdCallback.Instance?.OnAdLoaded(adUnitId); #endif }这样编辑器里能验证队列逻辑、回调处理、布局计算真机上只验证原生交互。改造完的验证清单编辑器跑通队列和回调、真机验证视图位置和点击、切场景验证销毁、弱网验证加载失败处理。从那以后我每次接原生广告都强制走一遍「编辑器 Mock 验证逻辑 → 真机验证交互 → 弱网验证异常」的流程不再直接上真机碰运气。这套流程帮我省了不少通宵排查的时间。希望这份拆解能帮你少走点弯路资源里的工程代码可以直接拿来当接入模板改改配置就能用。本文还有配套的精品资源点击获取