---
metadata:
  - name: generator
    content: Diplodoc Platform v5.55.0
alternate:
  - https://ads.yandex.com/helpcenter/en/dev/ios/swiftui/interstitial.md
  - https://ads.yandex.com/helpcenter/ru/dev/ios/swiftui/interstitial.md
  - https://ads.yandex.com/helpcenter/zh/dev/ios/swiftui/interstitial.md
  - href: zh/dev/ios/swiftui/interstitial.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt

[//]: # (This page is also translated into Brazilian Portuguese — pt-BR)

<!--
Used in Boost: boost/ru/ad-monetization/dev/ios
-->

# 插屏广告 (SwiftUI)

<!-- source: zh/dev/_includes/interstitial.md -->
插屏广告是一种全屏广告格式，嵌入在应用内容中，在自然暂停时显示，例如在游戏关卡之间过渡或完成目标操作时。
<!-- endsource: zh/dev/_includes/interstitial.md -->

当应用展示插屏广告时，用户可以选择：点击广告并前往广告主的网站，或关闭广告并返回应用。

插屏广告吸引了用户对广告的全部注意力，这便是其 CPM 更高的原因。

{% cut "外观" %}

<img src="https://yastatic.net/s3/doc-binary/src/docs/support/mobile-ads/zh/monetization/_images/interstitial-zh-ex.png" width="200">

{% endcut %}

本指南展示了如何使用 **SwiftUI** 将开屏广告集成到 iOS 应用中。 除了代码示例和说明之外，它还提供使用此广告格式的建议和其他资源的链接。

## 前提条件 {#pre}

<!-- source: zh/dev/_includes/pre-ios.md -->
1. 请按照 [快速入门](https://ads.yandex.com/helpcenter/zh/dev/ios/quick-start.md) 中描述的 SDK 集成步骤进行操作。
2. 提前 [初始化](https://ads.yandex.com/helpcenter/zh/dev/ios/quick-start.md#init) 您的广告 SDK。
3. 确保您运行的是最新的 [Yandex Mobile Ads SDK](https://ads.yandex.com/helpcenter/zh/dev/platforms.md) 版本。如果您使用聚合，请同时确保您运行的是最新版本的 [统一构建](https://ads.yandex.com/helpcenter/zh/dev/platforms.md)。
<!-- endsource: zh/dev/_includes/pre-ios.md -->

## 实施 {#implement}

在 SwiftUI 中集成插屏广告的关键步骤：

- 将 `.interstitialAd(isPresented:request:onEvent:)` 修饰符附加到根（或相关）`View`。
- 通过 `Binding<AdRequest?>` 控制加载：非 `nil` 值将开始加载。
- 通过 `Binding<Bool>` 控制展示：值为 `true` 时展示已加载的广告（如果加载仍在进行中，展示将延迟至加载完成）。
- 如果您通过 Adfox 工作（通过 `AdRequest` 参数），请传递[其他设置](https://ads.yandex.com/helpcenter/zh/dev/ios/target-adfox.md)。
- 在 `onEvent` 闭包中处理生命周期 (`InterstitialAdEvent`)。

## 插屏广告集成说明 {#features}

1. 强烈建议在 `.didFailToLoad` 事件回调中收到错误时不要尝试加载新广告。 如果需要从错误处理程序中重试加载，请限制重新加载尝试次数，以避免在网络连接受限的情况下广告请求连续失败。

2. 将修饰符保留在整个展示场景中一直存在的视图上（例如，在某个屏幕或导航根视图上），以避免丢失加载状态。

## 加载并展示广告

对于 SwiftUI 中的插屏广告，使用包含广告单元 ID 和两个状态的 `AdRequest`：可选请求和展示标记。

要接收有关加载成功或失败、展示、关闭和错误的通知，请将 `onEvent` 闭包与 `InterstitialAdEvent` 枚举一起使用。

```swift
import SwiftUI
import YandexMobileAds

struct InterstitialView: View {
    @State private var adRequest: AdRequest?
    @State private var isPresented = false

    var body: some View {
        VStack {
            Button("Load and show") {
                adRequest = AdRequest(adUnitID: "R-M-XXXXX-YY")
            }
        }
        .interstitialAd(isPresented: $isPresented, request: $adRequest) { event in
            switch event {
            case .didLoad:
                isPresented = true
            case .didDismiss, .didFailToShow, .didFailToLoad:
                adRequest = nil
            default:
                break
            }
        }
    }
}
```

广告单元 ID (adUnitId) 从 Yandex Advertising Network 界面获取。

您可以通过 `AdRequest` 在初始化器中传递用户兴趣数据、页面上下文数据、位置或其他附加数据来扩展广告请求参数。 请求中的附加上下文数据可以显著提高广告质量。 有关更多信息，请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/ios/target.md)。

示例：单独启动加载，然后在准备就绪时展示广告：

```swift
struct InterstitialView: View {
    @State private var adRequest: AdRequest?
    @State private var isPresented = false

    func loadAd() {
        adRequest = AdRequest(adUnitID: "R-M-XXXXX-YY")
    }

    func showAd() {
        isPresented = true
    }

    var body: some View {
        VStack {
            Button("Load", action: loadAd)
            Button("Show", action: showAd)
        }
        .interstitialAd(isPresented: $isPresented, request: $adRequest) { event in
            if case .didLoad = event {
                // 您可以调用 showAd() 或设置 isPresented = true
            }
        }
    }
}
```

如果在加载完成前设置 `isPresented = true`，则在成功加载后会自动执行展示。

## 展示广告

插屏广告应在应用使用的自然暂停期间展示。 一个很好的例子是在游戏关卡间或完成目标操作后，例如在文件下载完成后。

加载成功后，将触发 `.didLoad` 事件 — 设置 `isPresented = true` 以展示广告（或提前设置展示标记，请参见上文）。

广告关闭、展示错误发生或加载错误发生后，`isPresented` 标记将被重置为 `false`。

## 测试插屏广告集成

### 使用演示版位进行广告测试

<!-- source: zh/dev/_includes/test-ios-interstitial.md -->
我们建议使用测试广告来测试您的广告集成和应用本身。

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

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

{% note warning %}

在商店中发布您的应用程序之前，确保将演示版位 ID 替换为您在 Yandex Advertising Network 界面中获得的真实 ID。

{% endnote %}

您可以在 [用于测试的演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/ios/demo-blocks.md) 部分找到可用的演示广告版位 ID 列表。
<!-- endsource: zh/dev/_includes/test-ios-interstitial.md -->

### 验证广告集成的正确性

<!-- source: zh/dev/_includes/test-integration-ios.md -->
您可以使用本机控制台工具测试广告集成。

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

```swift
YMAMobileAds.enableLogging()
```

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

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

<img src= "https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/common/integration-ios-2.png">
<!-- endsource: zh/dev/_includes/test-integration-ios.md -->

## 其他资源 {#resources}

* <!-- source: zh/dev/_includes/github-pubdev-links.md -->
  [GitHub](https://github.com/yandexmobile/yandex-ads-sdk-ios/blob/master/Examples/YandexMobileAdsExample/YandexMobileAdsExample/Yandex/Interstitial/InterstitialAdViewController.swift) 链接。
  <!-- endsource: zh/dev/_includes/github-pubdev-links.md -->