简介面向Unity开发者的AppLovin Max原生广告iOS接入资料包聚焦在iOS平台将Native广告集成进Unity项目的完整流程适合需要提升广告变现效率的Unity开发者查阅。压缩包采用7z格式共58个文件约367KB内容以png图片素材、json配置、Objective-C/Swift源文件、MaxNativeAdFramework框架及plist配置为主文件类型覆盖广告视图资源、原生桥接代码与工程配置便于对照官方文档快速定位所需模块。目前已有100人学习虽然包体不大但包含原生广告手动加载视图、素材目录、Swift/OC桥接及框架封装等关键内容可直接用于理解Native广告在iOS侧的加载、展示和事件回调实现。借助这套资料开发者可以少走弯路快速完成SDK初始化、广告位设置、广告位加载示例及UI适配等步骤降低接入门槛同时为后续广告策略优化和合规调整提供参考。1. 为什么 iOS 端的 Native 广告比你想的麻烦AppLovin Max 接入的第一道坎在 Unity 里做广告变现Banner 和插屏基本是「照着文档写就能跑」但 Native 广告在 iOS 端完全是另一回事。它不是一张图加一行字而是一套由广告平台提供的原生 UI 组件需要你手动把它嵌进游戏场景的某个位置还要处理点击区域、生命周期、ATT 授权弹窗的时序。我最早接 AppLovin Max 的 Native 广告时把 Android 端的代码几乎原样搬到 iOS结果真机上白屏、点击没反应、审核被拒前后折腾了将近一周。这篇笔记就是把那次接入的完整过程拆开从版本匹配、初始化、广告位规划到 UI 绑定和真机踩坑给做 Unity iOS 变现的从业者一条能直接照着走的路。重点覆盖 Native 广告在 iOS 端的特殊性、参数设置和那几个最容易翻车的细节适合已经跑通 Max 插屏、正要接 Native 的开发者。2. 接入前的准备版本匹配与 iOS 构建环境2.1 Unity 版本与 AppLovin Max SDK 的匹配关系先说最容易被忽略的一点AppLovin Max 的 Unity 插件对 Unity 版本有明确要求。我这次用的是 Unity 2021.3 LTS搭配 AppLovin MAX Unity Plugin 6.x 版本。如果你还在用 2019 或 2020 的老版本不要直接拖最新插件进去Max 的 SDK 从 6.0 开始要求 iOS 最低版本 12.0并且对 Unity 2020 以下版本的 IL2CPP 构建支持不完整编译期会报一堆ScriptingGCHandle相关的错误。常见做法是先去 AppLovin 的官方 GitHub Releases 页面看插件对应的 Unity 版本表选一个比你当前版本低一个主版本的插件而不是无脑追新。另一个容易踩的坑是 iOS MinimumOSVersion。Max SDK 6.x 要求 iOS 12.0 以上如果你的 Player Settings 里 Target minimum iOS Version 还停在 11.0构建虽然能过但真机上会出现dyld: Library not loaded的崩溃因为系统版本低于 SDK 的硬性要求。这个崩溃发生在启动阶段日志里能看到AppLovinSDK相关的加载失败记录。// Player Settings 检查项 // Edit Project Settings Player Other Settings Target minimum iOS Version: 12.0或更高 Architecture: ARM64 Scripting Backend: IL2CPP这里的Scripting Backend我一般建议直接选 IL2CPP。原因不是 Mono 不能用而是 Max SDK 的 iOS 原生层是静态库Mono 下某些回调会丢线程切换尤其是 Native 广告的点击回调偶尔会出现点击后没有跳转的情况。IL2CPP 在这方面的行为稳定得多。2.2 iOS 构建三件套开发者证书、设备权限与 Player SettingsNative 广告在 iOS 端一次性牵扯三个权限相关的东西App Tracking TransparencyATT、定位权限部分广告源需要、以及 Info.plist 里的网络配置。三者缺一个轻则广告加载失败重则直接被 App Store 审核打回。先说 ATT。iOS 14.5 之后任何追踪用户跨应用活动的行为都必须弹授权框。AppLovin Max 的 SDK 会自己检测 ATT 授权状态但弹出时机由你控制。我一般这样处理在游戏启动后、加载广告之前先调用一次 ATT 请求。注意ATTrackingManager的requestTrackingAuthorization方法必须在主线程调用而且弹窗是一次性的用户点了「允许」或「拒绝」之后不会再出现。所以这个调用建议放在首屏场景的Start()里。using UnityEngine; using UnityEngine.iOS; public class AttPermissionHandler : MonoBehaviour { IEnumerator Start() { // iOS 14.5 必须先请求 ATT 权限Max 初始化需要知道授权结果 yield return new WaitForSeconds(1f); // 这里调用 iOS 原生 ATT 请求Unity 没有封装需要自己发 // 常见做法是通过 AndroidJavaObject 或自定义 iOS Plugin 调用 } }为什么这里没法直接给一行能跑的代码因为 Unity 官方没有把 ATT 封装进UnityEngine.iOS你需要在 Xcode 工程里手写一个 Objective-C 的桥接或者用第三方库。我用的方案是直接在 Xcode 的 ViewController.mm 里写一段然后 Unity 侧通过Application.SendMessage接收结果。代码逻辑不复杂但时序要特别注意。在隐私设置之外Info.plist 里也要声明用途字符串。项目构建后在Build Settings Player Settings Other Settings Configuration里找到Info.plist的按键设置手动添加KeyValueNSUserTrackingUsageDescription用于提供个性化广告体验SKAdNetworkItems必须包含 AppLovin 提供的 SKAdNetwork ID 列表SKAdNetworkItems 很多人会漏。AppLovin 官方文档里有一份很长的 ID 列表如果你不填iOS 端广告的归因数据会断掉广告主不愿意出价你的 eCPM 会直接掉一个量级。这个列表不是几个 ID而是几十个我从 Max 官网的 iOS 集成文档里复制了一份逐个加进 Info.plist 的数组里构建后检查无误才继续。3. SDK 初始化与广告位规划先跑通测试模式3.1 初始化代码与位置选择AppLovin Max 的初始化在 Unity 里是通过MaxSdk静态类完成的。它可以在任意场景调用但我建议放在一个专门的AppLovinManager单例里挂在游戏入口场景的 GameObject 上。原因有两个一是初始化是一个异步过程你需要一个存活周期覆盖整个游戏的对象来接收回调二是后续的广告位管理、监听器、日志开关都集中在一个地方排查问题时不用翻好几个场景去找代码。标准初始化代码using AppLovinMax.ThirdParty.SimpleJSON; using UnityEngine; public class AppLovinManager : MonoBehaviour { public static AppLovinManager Instance { get; private set; } private void Awake() { if (Instance null) { Instance this; DontDestroyOnLoad(gameObject); } else { Destroy(gameObject); return; } // MaxSdk 的初始化键从 AppLovin 后台复制 MaxSdk.SetSdkKey(YOUR_SDK_KEY_HERE); MaxSdk.InitializeSdk(); MaxSdk.SetVerboseLogging(true); } }这段代码有两个关键点。SetSdkKey必须在InitializeSdk之前调用否则初始化直接失败日志里会报SDK key is missing这个错误在 iOS 上不会弹窗只有在 Xcode 控制台里能看到。SetVerboseLogging(true)建议在联调阶段一直开着它输出的日志比 Max 自带的调试面板更细能看到每个广告源的加载耗时、填充率、失败原因。初始化完成后的回调private void OnEnable() { MaxSdk.OnSdkInitializedEvent OnSdkInitialized; } private void OnDisable() { MaxSdk.OnSdkInitializedEvent - OnSdkInitialized; } private void OnSdkInitialized(MaxSdkBase.SdkConfiguration sdkConfiguration) { Debug.Log(Max SDK 初始化完成); // 在这里根据 sdkConfiguration.ConsentDialogState 判断是否弹出 GDPR 弹窗 // 国内 iOS 一般不需要处理 GDPR但如果你的包上架海外区必须在这里触发 }这里有个细节OnSdkInitializedEvent只会在初始化完成后触发一次。如果你的广告位加载方法写在Start()里而Start()的执行时机早于 SDK 初始化完成就永远收不到OnNativeAdLoadedEvent回调。我见过不少人把这个回调注册放在Awake()里结果初始化完成后场景里的广告位管理脚本还没OnEnable事件直接丢了。稳妥做法是所有广告位都等OnSdkInitialized里拿到SdkConfiguration之后再调用LoadNextNativeAd。3.2 广告单元 ID 规划与测试模式开关广告单元 ID 是 Max 后台创建的一条记录代表一个具体的广告位。Native 广告在 iOS 端建议创建一个单独的 AdUnitId不要和 Android 共用一个。原因有两种一是两个平台的 eCPM 差异大广告主在 iOS 端更愿意出高价共用一个 ID 会导致调价范围被拉平二是 Max 后台的瀑布流配置是按平台分别生效的共用一个 ID 时某个平台的水印配置会互相干扰。创建完广告位后后台会分配一个格式为xxxxxxxxxxxxxxxx的字符串 ID。拿到之后先不要直接跑真机先在 Max 后台把该广告位的状态设为「测试模式」。AppLovin Max 有一个测试模式开关在后台的 Mediation Manage Ad Units 里点击广告位右侧的编辑按钮找到 Test Mode 选项开启后所有真实广告请求都会被拦截退回测试广告。这个模式下的广告填充率是 100%点击之后不会跳转商店方便你验证 UI 绑定和点击事件。private const string NativeAdUnitId YOUR_IOS_NATIVE_AD_UNIT_ID; private void LoadNativeAd() { // 必须先初始化完成再加载 if (!MaxSdk.IsInitialized()) { Debug.LogWarning(Max SDK 尚未初始化跳过 Native 广告加载); return; } // iOS 端加载 Native 广告的方法 MaxNativeAd.LoadNativeAd(NativeAdUnitId, this); }MaxNativeAd.LoadNativeAd是 iOS 与 Android 共用的接口但它的监听回调在 iOS 端有一些需要特别注意的字段我会在下一章详细说。4. Native 广告的加载与渲染从回调到 UI 绑定4.1 加载流程与监听回调的完整实现Native 广告的加载在 Max 里是异步的你需要实现一个继承自MaxNativeAd.NativeAdListener的类来接收结果。这个监听器和插屏的监听器不一样它不是一个委托而是一个需要using的对象每次加载广告都要重新实例化。如果你把监听器做成MonoBehaviour的成员加载多次后会积累无用对象内存会缓慢上涨。完整监听器实现using AppLovinMax.ThirdParty.SimpleJSON; private class NativeAdListener : MaxNativeAd.NativeAdListener { public override void OnNativeAdLoaded(MaxNativeAd maxNativeAd) { Debug.Log(Native 广告加载成功: maxNativeAd.AdUnitIdentifier); // maxNativeAd 里包含标题、描述、图标、广告主名称等信息 // 渲染工作要在这里做因为广告对象在回调结束后可能被回收 } public override void OnNativeAdLoadFailed(string adUnitId, int errorCode, string errorMessage) { Debug.Log(Native 广告加载失败: adUnitId 错误码: errorCode errorMessage); } public override void OnNativeAdClicked(MaxNativeAd maxNativeAd) { Debug.Log(Native 广告被点击); } public override void OnNativeAdExpired(MaxNativeAd maxNativeAd) { Debug.Log(Native 广告已过期需要重新加载); } }这里有个核心结论OnNativeAdLoaded回调里的maxNativeAd对象必须在回调方法内完成 UI 绑定。Max 的 iOS 原生层在回调结束后可能销毁这个对象如果你把它保存在成员变量里供后续使用轻则 UI 空白重则崩溃。我习惯在回调里直接调用渲染方法把广告数据拷贝到 UI 组件上。4.2 原生广告元素的 UI 绑定与点击处理Max 的 Native 广告在 Unity 侧暴露了几个关键字段Title标题、Advertiser广告主、CallToAction行动号召按钮文案、Icon图标纹理、MediaView媒体视图。其中MediaView是一个Texture2DiOS 端有时会是null因为部分广告源不提供视频素材只有图片。UI 绑定代码要处理这个空值情况否则渲染时material.mainTexture null会导致 iOS 端白屏。private void BindNativeAdToUI(MaxNativeAd maxNativeAd) { // 标题 adTitleText.text maxNativeAd.Title; // 广告主名称 adAdvertiserText.text maxNativeAd.Advertiser; // 行动按钮文案 adCallToActionButton.GetComponentInChildrenText().text maxNativeAd.CallToAction; // 图标 if (maxNativeAd.Icon ! null maxNativeAd.Icon.Texture ! null) { adIconImage.sprite Sprite.Create(maxNativeAd.Icon.Texture, new Rect(0, 0, maxNativeAd.Icon.Texture.width, maxNativeAd.Icon.Texture.height), new Vector2(0.5f, 0.5f)); } else { adIconImage.gameObject.SetActive(false); // iOS 端部分广告源不返回 Icon隐藏图标位即可不要报错 } // 媒体视图 if (maxNativeAd.MediaView ! null) { adMediaImage.texture maxNativeAd.MediaView; adMediaImage.gameObject.SetActive(true); } else { adMediaImage.gameObject.SetActive(false); } // 整个广告容器接收点击 adContainerButton.onClick.AddListener(() { MaxNativeAd.ClickNativeAd(); }); }点击处理是这个环节最容易出问题的点。MaxNativeAd.ClickNativeAd()是一个静态方法但它只对「最后一次成功加载的 Native 广告」生效。这意味着如果你在OnNativeAdLoaded之后又加载了一次广告比如自动刷新上一次的点击方法会被覆盖。iOS 端的点击是明文跳转需要准确的点击坐标如果你的 UI 容器上还有其他可点击元素要确保它们不重叠否则广告点击会被吞掉。我记得有一个很隐蔽的坑如果adContainerButton是一个Button而它所在的父节点上有ScrollRect或Drag相关的组件iOS 端的触摸检测会先被 ScrollRect 拦截导致广告永远点不中。常见的解决办法是给广告容器单独挂一个EventTrigger只处理PointerClick不参与滚动事件。5. AppLovin Max 接入避坑笔记我从 iOS 真机里捞出来的经验5.1 ATT 授权弹窗与广告加载时序冲突现象首次启动游戏时Native 广告位加载失败日志报ATT not determined之后无论怎么重新加载都失败必须杀掉进程才能恢复。原因ATT 授权弹窗出现时App 会进入前台暂停状态而 Max SDK 的初始化和广告加载是在启动后立刻触发的。弹窗弹出后所有网络请求被系统挂起Max SDK 的请求超时广告源返回失败。用户点击弹窗后SDK 已经进入失败状态不会自动重试。解决把 Max SDK 初始化和 Native 广告加载都放到 ATT 弹窗结果回调之后。具体做法是启动后先弹 ATT 授权框在用户做出选择后再调用MaxSdk.InitializeSdk()。虽然这会让广告加载延迟几秒但比失败一次强。注意ATT 的用户选择结果要保存到本地第二次启动时不再弹窗此时可以跳过等待直接初始化。IEnumerator Start() { // 先等一帧确保场景 UI 加载完成 yield return null; // 检查是否已请求过 ATT if (!PlayerPrefs.HasKey(att_requested)) { PlayerPrefs.SetInt(att_requested, 1); // 调用原生 ATT 请求... // 在回调中继续执行 InitializeMaxSdk() } else { // 用户已选择过直接初始化 InitializeMaxSdk(); } }5.2 模拟器上正常、真机上白屏现象Native 广告在 iOS 模拟器上加载成功UI 绑定后正常展示但部署到 iPhone 真机上广告区域是纯白色的文字、图片都不显示。原因Max SDK 在模拟器上走的是x86_64架构的模拟器库渲染路径和真机的arm64不一样。真机白屏是因为广告的媒体素材加载是异步的UI 绑定时maxNativeAd.MediaView还是null纹理没有及时填充。模拟器上由于 CPU 架构差异时序碰巧对上了。解决不要依赖OnNativeAdLoaded回调里的MediaView数据改用在回调之后延迟一帧再绑定 UI。或者更稳妥的方案是在绑定 UI 时不显示媒体区域等MediaView非空后再填充。我最终用的是延迟绑定IEnumerator BindNativeAdUIAfterDelay(MaxNativeAd maxNativeAd) { yield return new WaitForEndOfFrame(); BindNativeAdToUI(maxNativeAd); }5.3 点击回调与触摸穿透现象真机上点击广告区域有时能触发跳转有时没反应点击广告按钮但点击穿透到下面的游戏 UI触发了游戏里的其他逻辑。原因Native 广告的容器如果是一个Button它占满的整个透明区域都会响应触摸。而广告的实际可点击区域通常只有素材本身的范围。iOS 端的点击分发和 Android 不一样Unity 的Button在 iOS 上会有触摸穿透的问题尤其是在EventSystem的First Selected对象不是广告容器的情况下。解决不要用Button作为广告容器改用Image组件加EventTrigger把点击处理限定在图像区域。同时给广告容器单独挂一个CanvasGroup设置blocksRaycasts true阻止点击穿透到游戏 UI。5.4 内存泄漏与事件重复注册现象游戏运行时间越久内存越高且每次回到主场景后Native 广告的加载速度越来越慢最终卡死。原因监听器实例没有释放。MaxNativeAd.LoadNativeAd每次调用都会创建一个新的NativeAdListener如果你在OnNativeAdLoaded回调里没有移除旧监听器Max SDK 会持有所有历史监听器的引用导致内存泄漏。另外adContainerButton.onClick每次绑定 UI 时都会加一个监听重复添加多次后点击一次会触发多次跳转。解决在绑定新广告之前先清空旧监听器。加载广告时用一个字段保存当前监听器下次加载前先释放。按钮的点击监听也改成赋值覆盖而不是AddListenerprivate NativeAdListener currentListener; private void LoadNativeAd() { if (currentListener ! null) { // 释放旧监听器防止内存泄漏 currentListener null; } currentListener new NativeAdListener(); MaxNativeAd.LoadNativeAd(NativeAdUnitId, currentListener); }6. 上线前的验证套路用调试面板和日志把问题挡在审核之前6.1 用 MAX 调试面板确认广告位配置Max SDK 自带一个调试面板在 iOS 真机上摇一摇或者通过代码调用MaxSdk.ShowMediationDebugger()可以打开。面板会显示当前设备上所有广告位的状态包括 SDK 初始化状态、每个广告源的填充率、错误码。上线前我习惯拿着这个面板逐项核对SDK 初始化是否为Initialized、Native 广告位是否Active、每个 waterfall 是否有Filled记录。如果某个广告源显示No Fill多半是广告单元 ID 配错或地区定向问题这时候先回后台检查广告位 ID 是否与代码一致。6.2 真机日志的四个关键字拿到真机跑一遍完整流程Xcode 控制台里过滤四个关键字关键字含义正常表现MaxAds SDK initializedSDK 初始化完成出现一次Native ad loaded广告加载成功每次加载出现一次Ad unit广告位 ID 日志与后台一致ERROR错误信息不应有SDK key is missing或Banner failed最常遇到的情况是日志里显示Ad unit is not enabled这表示广告位在后台被暂停了去 Max 后台重新激活即可。6.3 自动刷新与请求频率Native 广告不建议做无限自动刷新。iOS 端广告平台的频控策略很严格高频刷新同一个广告位会导致 eCPM 下降甚至封广告位。我一般用一个 30 秒的定时器广告显示超过 30 秒后自动重新加载且只在广告区域可见时才刷新。这个逻辑上线前要单独测试一轮让 App 在后台运行 5 分钟回前台后检查广告是否正常刷新避免系统挂起后触摸事件堆积导致点击错乱。从那以后我每次接入 iOS 端的 Native 广告都会强制走一遍 ATT 时序确认、模拟器白屏验证、点击穿透测试这三个环节再跑一遍调试面板。这套流程帮我挡掉了至少四次审核被拒的风险希望这一次的拆解也能帮到你。本文还有配套的精品资源点击获取