---
metadata:
- name: generator
content: Diplodoc Platform v5.55.0
alternate:
- https://ads.yandex.com/helpcenter/en/dev/ios/swiftui/app-open-ad.md
- https://ads.yandex.com/helpcenter/ru/dev/ios/swiftui/app-open-ad.md
- https://ads.yandex.com/helpcenter/zh/dev/ios/swiftui/app-open-ad.md
- href: zh/dev/ios/swiftui/app-open-ad.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)
# 开屏广告 (SwiftUI)
应用开屏广告是一种用于通过应用加载界面实现变现的特殊广告格式。此类广告可随时关闭，并设计用于在以下场景中展示：
* 应用启动时。
* 应用被调至前台时。
* 从后台返回应用时。
本指南展示了如何使用 **SwiftUI** 将开屏广告集成到 iOS 应用中。 除了代码示例和说明之外，它还提供使用此广告格式的建议和其他资源的链接。
## 外观
开屏广告显示 **Go to the app** 按钮，以便用户知道他们正在使用您的应用，并且可以关闭广告。 以下是广告外观的示例：
## 前提条件 {#pre}
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)。
### 术语
* **冷启动** — 当应用不在内存中时启动应用，并创建新的应用会话。
* **热启动** — 将应用从后台（当应用在内存中暂停时）切换到前台。
## 实施 {#implement}
1. 在应用启动时初始化 SDK。
2. 将 `.appOpenAd(request:onEvent:)` 修饰符添加到根 `View` 中（例如，在 `WindowGroup` 内部）。
3. 通过 `Binding` 控制加载：非 `nil` 值将开始加载。
4. 加载成功后，当应用进入已激活状态（前台）时，广告将**自动**展示，而 `request` 尚未重置。
5. 在 `onEvent` (`AppOpenAdEvent`) 中处理生命周期事件。
6. 广告关闭、出现展示错误或出现加载错误后， `request` 将被重置为 `nil` — 当需要进行下一次加载时（通常在场景阶段更改处理程序中），设置新的 `AdRequest`。
### 关键步骤
1. 在应用启动时初始化 SDK。
```swift
// 等待 sdk 初始化完成再加载广告
YandexAds.initializeSDK(completionHandler: completionHandler)
```
2. 将修饰符附加到根视图并存储请求状态。
您需要从 Yandex Advertising Network 界面获取广告单元 ID (`AD_UNIT_ID`)。
您可以通过 `AdRequest` 传递用户兴趣数据、页面上下文数据、位置或其他附加数据来扩展广告请求参数。 请求中的附加上下文数据可以显著提高广告质量。 有关更多信息，请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/ios/target.md)。
使用 `ScenePhase` 的 **iOS 14+** 示例（`request` 重置为 `nil` 后重新加载）：
```swift
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`，而非使用 `scenePhase`。
3. 加载并展示到达 `onEvent` 的事件：
```swift
.appOpenAd(request: $adRequest) { event in
switch event {
case .didLoad:
// 广告已就绪；将在下一个前台展示
break
case .didShow:
break
case .didDismiss:
// 请求已被修饰符重置
break
case .didFailToShow:
break
case .didFailToLoad:
// 请求已重置；不建议在循环中立即重试
break
case .didClick:
break
case .didTrackImpression(_):
break
}
}
```
{% note info %}
如果广告已经投放，调用 `show(from:)` 方法将在 `AppOpenAdDelegate.appOpenAd(_:didFailToShowError:)`中返回显示错误。
{% endnote %}
## 开屏广告集成说明 {#features}
1. 加载可能需要相当长的时间，因此如果广告未加载，请不要延迟冷启动。
2. 提前预加载广告以便后续在热启动时展示。 当 `nil` 在绑定中传递时，不会执行加载 — 当要展示的广告需要后台准备时，设置 `AdRequest`。
3. 不建议在应用启动时同时加载开屏广告和其他广告格式，因为应用此时可能正在下载所需数据。 这可能会使设备和互联网连接过载，从而导致广告加载速度变慢。
4. 如果您在 `.didFailToLoad` 事件中收到错误，请不要尝试立即在循环中加载新广告。 如果必须重试，请限制重新加载尝试次数，以避免在条件受限的情况下请求持续失败并出现连接问题。
## 测试开屏广告集成 {#test}
### 使用演示广告单元进行广告测试 {#demo-blocks}
我们建议使用测试广告来测试开屏广告集成和应用本身。
为了保证为每个广告请求返回测试广告，我们创建了一个特殊的演示广告版位 ID。用它来检查您的广告集成。
演示广告单元 ID：`demo-appopenad-yandex`。
{% note warning %}
在商店中发布您的应用程序之前，确保将演示版位 ID 替换为您在 Yandex Advertising Network 界面中获得的真实 ID。
{% endnote %}
您可以在 [用于测试的演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/ios/demo-blocks.md) 版块找到可用的演示广告版位 ID 列表。
### 验证广告集成的正确性
您可以使用本机控制台工具测试广告集成。
要查看详细日志，请调用 `YMAMobileAds` 类的 `enableLogging` 方法。
```swift
YMAMobileAds.enableLogging()
```
要查看 SDK 日志，请前往控制台工具并设置 `Subsystem = com.mobile.ads.ads.sdk`。您还可以按类别和错误级别过滤日志。
如果您在集成广告时遇到问题，您将获得有关问题的详细报告以及如何解决这些问题的建议。
## 建议
1. 不要在加载屏幕（启动画面）前展示开屏广告。
显示加载屏幕可以让用户获得更愉悦、清晰的应用体验。 这样可以避免用户感到意外或困惑，因为他们明确知道自己打开的是哪个应用。 在此屏幕上，您也可以通过加载指示器或文本消息提醒用户广告要来了，并告知用户广告结束后将恢复应用内容。
2. 如果广告请求与其展示之间存在延迟，用户可能会短暂打开您的应用，然后意外地看到与内容无关的广告。 这会对用户体验产生负面影响，因此应避免此类情况。 一种选项是在展示主应用内容之前使用加载屏幕并开始从该屏幕展示广告。 如果应用在加载屏幕后打开一些内容，此时最好不要展示广告。
3. 等待新用户打开应用并使用几次后，再展示开屏广告。 仅向应用中满足特定条件的用户展示广告（例如，完成了特定关卡、打开了特定次数的应用、未参与奖励活动等）。 不要在安装应用后立即展示广告。
4. 根据用户在应用中的行为调节展示频率。 不要在每次冷/热启动时展示广告。
5. 仅当应用在后台运行一段时间（如 30 秒、2 分钟、15 分钟）后才展示广告。
6. 务必进行测试，因为每款应用都是独特的，需采用适合自身的方法来最大限度地提高收入，而不降低用户留存率或应用使用时长。 用户行为和参与度会随时间变化，因此建议定期测试应用中的开屏广告展示策略。
## 其他资源 {#resources}
*
[GitHub](https://github.com/yandexmobile/yandex-ads-sdk-ios/blob/master/Examples/YandexMobileAdsExample/YandexMobileAdsExample/Yandex/AppOpenAd/AppOpenAdViewController.swift) 链接。