开屏广告（SwiftUI）

开屏广告是一种特殊的广告格式，用于通过应用加载屏幕变现。这些广告可以随时关闭，并且旨在当用户将您的应用带到前台时（无论是在启动时还是从后台返回时）投放。

本指南介绍如何在 iOS 应用中使用 SwiftUI 集成开屏广告。除代码示例外，还包含格式使用建议及其他资源链接。

外观

开屏广告会显示 Go to the app 按钮，让用户知道当前在您的应用中并可以关闭广告。 广告展示效果示例：

前提条件

1. 请按照 快速入门 中描述的 SDK 集成步骤进行操作。
2. 提前 初始化 您的广告 SDK。
3. 确保您运行的是最新的 Yandex Mobile Ads SDK 版本。如果您使用聚合，请同时确保您运行的是最新版本的 统一构建。

术语

• 冷启动 — 应用不在内存中时启动，开启新的会话。
• 热启动 — 应用从后台（仍驻留内存的挂起状态）回到前台。

实施

1. 在应用启动时初始化 SDK。
2. 在根 View 上（例如在 WindowGroup 内）添加 .appOpenAd(request:onEvent:) 修饰符。
3. 通过 Binding<AdRequest?> 控制加载：非 nil 即开始加载。
4. 加载成功后，当应用进入活跃（前台）状态且尚未重置 request 时，广告会自动展示。
5. 在 onEvent（AppOpenAdEvent）中处理生命周期事件。
6. 广告关闭、展示失败或加载失败后，request 会重置为 nil — 需要再次加载时请设置新的 AdRequest（常在场景阶段变化回调中处理）。

主要步骤

1. 在应用启动时初始化 SDK。

   // 加载广告前请等待 SDK 初始化完成
   YandexAds.initializeSDK(completionHandler: completionHandler)
   

2. 将修饰符挂到根视图并保存请求状态。

   需要您在 Yandex Advertising Network 中获取的广告位 ID（AD_UNIT_ID）。

   可通过 AdRequest 传入用户兴趣、页面上下文、位置等数据扩展请求参数。请求中的额外上下文可显著提升广告质量。详见广告定向。

   iOS 14+ 配合 ScenePhase 的示例（在 request 被置为 nil 后重新加载）：

   import SwiftUI
   import YandexMobileAds
   
   @main
   struct MyApp: App {
       @State private var adRequest: AdRequest?
       @Environment(\.scenePhase) private var scenePhase
   
       var body: some Scene {
           WindowGroup {
               ContentView()
                   .appOpenAd(request: $adRequest) { event in
                       if case .didFailToLoad = event {
                           // 如需延迟重试，见下文建议
                       }
                   }
           }
           .onChange(of: scenePhase) {
               if scenePhase == .active, adRequest == nil {
                   adRequest = AdRequest(adUnitID: "demo-appopenad-yandex")
               }
           }
       }
   }
   

   在 iOS 13 上请使用 UIApplication.didBecomeActiveNotification 或等效生命周期逻辑，在 nil 之后设置新的 AdRequest。

3. 加载与展示事件在 onEvent 中接收：

   .appOpenAd(request: $adRequest) { event in
       switch event {
       case .didLoad:
           // 广告已就绪；下次进入前台时展示
           break
       case .didShow:
           break
       case .didDismiss:
           // request 已由修饰符重置
           break
       case .didFailToShow:
           break
       case .didFailToLoad:
           // request 已重置；不建议在循环中立即重试
           break
       case .didClick:
           break
       case .didTrackImpression(_):
           break
       }
   }
   

   备注

   如果广告已经投放，调用 show(from:) 方法将在 AppOpenAdDelegate.appOpenAd(_:didFailToShowError:) 中返回显示错误。

开屏广告集成说明

1. 加载可能耗时较长，若广告未加载完成，请勿因此拖慢冷启动。
2. 请提前预加载，以便热启动时展示。绑定为 nil 时不会加载 — 需要在后台准备展示时再设置 AdRequest。
3. 不建议在应用启动时同时加载开屏广告与其他广告格式，此时应用可能在下载数据，容易加重设备与网络负担，使广告加载变慢。
4. 若在 .didFailToLoad 中收到错误，请勿在循环中立即反复加载。若必须重试，请限制次数，以免在受限网络下连续失败。

测试开屏广告集成

使用演示广告单元进行广告测试

我们建议使用测试广告来测试开屏广告集成和应用本身。

为了保证为每个广告请求返回测试广告，我们创建了一个特殊的演示广告版位 ID。用它来检查您的广告集成。

演示广告单元 ID：demo-appopenad-yandex。

您可以在 用于测试的演示广告单元 版块找到可用的演示广告版位 ID 列表。

验证广告集成是否正确

您可以使用本机控制台工具测试广告集成。

要查看详细日志，请调用 YMAMobileAds 类的 enableLogging 方法。

YMAMobileAds.enableLogging()

要查看 SDK 日志，请前往控制台工具并设置 Subsystem = com.mobile.ads.ads.sdk。您还可以按类别和错误级别过滤日志。

如果您在集成广告时遇到问题，您将获得有关问题的详细报告以及如何解决这些问题的建议。

建议

1. 不要在启动画面（Splash）之前展示开屏广告。

   启动画面让体验更清晰，用户能确认打开的是您的应用。可在该画面用加载指示或文案提示广告结束后将继续应用内容。

2. 若请求与展示之间存在延迟，用户可能短暂进入应用后看到与当前内容无关的广告，影响体验。可考虑在展示主内容前使用启动画面，并从该画面开始展示广告；若启动画面后立刻进入某段内容，则不宜此时展示广告。

3. 新用户安装后不要立刻展示开屏广告。可等用户多次打开并使用应用后，再向满足条件（例如完成某关卡、打开次数达标、未参与激励任务等）的用户展示。

4. 根据应用内行为调节展示频次，不要在每次冷/热启动都展示。

5. 仅当应用在后台停留一定时间后再展示（例如 30 秒、2 分钟、15 分钟）。

6. 请充分测试：每款应用不同，需在收入与留存、使用时长之间取舍；用户行为会变化，建议定期评估开屏策略。

其他资源

• GitHub 链接。