---
metadata:
- name: generator
content: Diplodoc Platform v5.50.6
alternate:
- https://ads.yandex.com/helpcenter/en/dev/compose-multiplatform/app-open-ad.md
- https://ads.yandex.com/helpcenter/ru/dev/compose-multiplatform/app-open-ad.md
- https://ads.yandex.com/helpcenter/zh/dev/compose-multiplatform/app-open-ad.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt
# 开屏广告
应用开屏广告是一种用于通过应用加载界面实现变现的特殊广告格式。此类广告可随时关闭，并设计用于在以下场景中展示：
* 应用启动时。
* 应用被调至前台时。
* 从后台返回应用时。
本指南展示如何将开屏广告集成到 Compose Multiplatform 应用中。 除了代码示例和说明之外，它还包含特定格式的建议和其他资源的链接。
{% note alert %}
应用开屏广告仅支持纵向布局的应用。对于横向布局的应用，此类广告将不会展示。
{% endnote %}
## 外观
开屏广告提供 **Go to the app** 按钮，以便用户知道他们正在使用您的应用，并且可以关闭广告。 以下是广告的示例：
## 前提条件 {#pre}
1. 按照[快速入门](https://ads.yandex.com/helpcenter/zh/dev/compose-multiplatform/quick-start.md)中的流程集成 Yandex Mobile Ads Compose Multiplatform 插件。
2. 确保您运行的是最新的 [Yandex Mobile Ads Compose Multiplatform 插件](https://ads.yandex.com/helpcenter/zh/dev/platforms.md)版本。 如果您使用聚合，请确保运行最新版本的[统一构建](https://ads.yandex.com/helpcenter/zh/dev/platforms.md)。
### 术语和定义
* **冷启动** — 当应用不在 RAM 中时启动应用，并创建新的应用会话。
* **热启动** — 将应用从后台（在 RAM 中暂停）切换到前台。
## 实施 {#implement}
1. 使用 `rememberAppOpenAdLoader()` 创建广告加载器。
2. 通过挂起函数 `loadAd()` 加载广告。
3. 在调用 `show()` 之前，可选择为已加载的广告设置 `AppOpenAdEventListener`。
4. 使用 `show()` 展示广告。
### 主要步骤
1. 创建 `AppOpenAdLoader` 广告加载器
```kotlin
@Composable
fun AppOpenRoot() {
val loader = rememberAppOpenAdLoader()
// ...
}
```
2. 配置广告请求。
```kotlin
val adUnitId = "demo-appopenad-yandex" // 替换为 "R-M-XXXXXX-Y"
val request = AdRequest(adUnitId = adUnitId)
```
`adUnitId` 是在 Yandex Advertising Network 界面中发布的唯一标识符，格式为 R-M-XXXXXX-Y。
{% note tip %}
出于测试目的，您可以使用演示广告单元 `"demo-appopenad-yandex"`。 在发布之前，请将其替换为您的真实广告单元 ID。
您可以通过 `AdRequest` 扩展广告请求（`targeting`、`parameters`、`preferredTheme` 和其他字段）。 在请求中提供额外的上下文数据可以显著提高您的广告质量。 详情请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/compose-multiplatform/target.md)部分。
{% endnote %}
3. 在与 UI 范围相关的协程中加载广告。 在加载失败时，`loadAd` 会从 `com.yandex.mobile.ads.kmp.common` 中抛出 `AdLoadException`。
```kotlin
val scope = rememberCoroutineScope()
var appOpenAd by remember { mutableStateOf(null) }
var isLoading by remember { mutableStateOf(false) }
fun loadAppOpen() {
isLoading = true
scope.launch {
try {
val ad = loader.loadAd(request)
appOpenAd = ad
isLoading = false
} catch (e: AdLoadException) {
isLoading = false
// 加载错误：e.error (AdRequestError)。 不建议无限制重试。
}
}
}
```
4. 决定何时展示广告。 在 Compose Multiplatform 中，通常使用 AndroidX Lifecycle 跟踪应用生命周期。
5. 为用户可见事件注册监听器。
```kotlin
val ad = appOpenAd ?: return
ad.setAdEventListener(
object : AppOpenAdEventListener {
override fun onAdShown() {
// 广告展示时调用。
}
override fun onAdFailedToShow(adError: AdError) {
// 广告无法展示时调用。
appOpenAd = null
// 在适当情况下预加载下一个广告。
}
override fun onAdDismissed() {
// 广告关闭时调用。
appOpenAd = null
// 在适当情况下预加载下一个广告。
}
override fun onAdClicked() {
// 记录广告点击时调用。
}
override fun onAdImpression(impressionData: ImpressionData?) {
// 记录广告展示时调用。
}
},
)
ad.show()
```
6. 在调用 `show()` 后，只要 `AppOpenAd` 实例在屏幕上，便会将其保留。 当触发关闭回调时，请先清除引用，然后再下载其他创意。
7. 如果您不再需要已加载的广告，请清除可空引用，这样便可以收集对象。
```kotlin
appOpenAd = null
```
### 完整代码示例
公开的示例应用使用专用屏幕控制加载与展示。 以下模式在单个可组合项中镜像了这一流程，仅供参考：
```kotlin
@Composable
fun AppOpenSample(adUnitId: String) {
val loader = rememberAppOpenAdLoader()
val scope = rememberCoroutineScope()
var appOpenAd by remember { mutableStateOf(null) }
var isLoading by remember { mutableStateOf(false) }
Column {
Button(
onClick = {
isLoading = true
scope.launch {
try {
appOpenAd = loader.loadAd(AdRequest(adUnitId = adUnitId))
} catch (e: AdLoadException) {
// 加载错误：e.error (AdRequestError)。 不建议无限制重试。
}
isLoading = false
}
},
enabled = !isLoading,
) {
Text(if (isLoading) "Loading..." else "Load app open")
}
Button(
onClick = { appOpenAd?.show() },
enabled = appOpenAd != null,
) {
Text("Show app open")
}
}
}
```
在移至生产环境时，会将加载/显示调用接入真实的生命周期入口点，而非按钮。
## 开屏广告集成的特性 {#features}
1. 加载可能需要一段时间，因此如果广告尚未加载，请勿增加冷启动时间。
2. 预加载广告以便后续在热启动期间显示。
3. 我们不建议在应用启动时并行加载开屏广告和其他广告格式：此时应用可能正在下载运行数据，与广告加载同时进行可能会导致设备与网络过载，并延长加载时间。
4. 如果加载返回错误，请不要立即再次尝试加载新广告。 如果必须这样做，请限制重试次数 — 这有助于避免在出现限制时请求持续失败。
## 测试开屏广告集成 {#test}
{% list tabs %}
- Android
### 使用演示广告单元进行广告测试 {#demo-blocks}
使用测试广告来检查您的广告集成和应用本身。为了确保每次广告请求都能返回测试广告，您可以使用一个特殊的演示广告版位 ID。
演示广告单元 ID：`demo-appopenad-yandex`。
{% note warning %}
在应用商店发布应用前，请务必将演示广告版位 ID 替换为您在 Yandex Advertising Network 接口中获取的真实 ID。
{% endnote %}
有关所有可用演示广告版位 ID 的列表，请参阅[用于测试的演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/android/demo-blocks.md)。
### 测试广告集成 {#test-int}
您可以使用 SDK 的内置分析工具检查应用的开屏广告是否已正确集成。日志中将显示包含测试结果的详细报告。
要查看报告，请在 Android 应用调试工具 [Logcat](https://developer.android.com/studio/command-line/logcat) 中搜索关键词“YandexAds”。
```bash
adb logcat -v brief '*:S YandexAds'
```
如果集成成功，将返回以下消息：
```bash
adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type App Open Ad was integrated successfully
```
如果存在任何广告集成问题，您将收到详细的问题报告和故障排除建议。
- iOS
### 使用演示广告单元进行广告测试 {#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`。您还可以按类别和错误级别过滤日志。
如果您在集成广告时遇到问题，您将获得有关问题的详细报告以及如何解决这些问题的建议。
{% endlist %}
## 建议
1. 不要在启动画面之前展示广告。 启动画面使应用更易使用：用户可以确定他们打开了正确的应用。
在同一屏幕上，您可以提醒用户广告要来了。 使用加载指示器或短消息提示用户广告结束后将继续展示内容。
2. 考虑请求与广告展示之间的延迟。
如果有延迟，用户可能会看到与上下文不符的广告。 一种方法是在主内容之前使用启动画面，并从那里开始展示广告。 如果应用在启动后直接进入内容页面，则最好不要展示广告。
3. 安装后不要立即展示广告。 等到新用户打开应用并使用该应用几次。
仅向符合您定义的条件的用户展示广告 — 例如，已完成某个关卡、打开应用达到一定次数，或当前不在奖励提供流程中。
4. 不要在每次冷启动或热启动时展示广告。 根据用户使用应用的习惯调整频率。
5. 仅当应用在后台停留超过最短时间（例如 30 秒、2 分钟或 15 分钟）时，才展示广告。
6. 持续进行测试。 每个应用都需要找到适合自己的方式来最大化收益。 用户行为会发生变化，因此请定期回顾并调整您的广告展示策略。
## 其他资源 {#resources}
完整集成示例：
*
[GitHub](https://github.com/yandexmobile/yandex-ads-multiplatform) 链接。