---
metadata:
- name: generator
content: Diplodoc Platform v5.52.0
alternate:
- https://ads.yandex.com/helpcenter/en/dev/android/compose/app-open-ad.md
- https://ads.yandex.com/helpcenter/ru/dev/android/compose/app-open-ad.md
- https://ads.yandex.com/helpcenter/zh/dev/android/compose/app-open-ad.md
- href: zh/dev/android/compose/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
# 开屏广告
应用开屏广告是一种用于通过应用加载界面实现变现的特殊广告格式。此类广告可随时关闭，并设计用于在以下场景中展示：
* 应用启动时。
* 应用被调至前台时。
* 从后台返回应用时。
本指南展示了如何使用 Jetpack Compose 扩展将开屏广告集成到 Android 应用中。 除了代码示例和说明之外，它还提供使用此广告格式的建议和其他资源的链接。
{% note alert %}
应用开屏广告仅支持纵向布局的应用。对于横向布局的应用，此类广告将不会展示。
{% endnote %}
## 外观
开屏广告显示 **Go to the app** 按钮，以便用户知道他们正在使用您的应用，并且可以关闭广告。 以下是广告外观的示例：
## 前提条件 {#pre}
1. 按照[快速入门](https://ads.yandex.com/helpcenter/zh/dev/android/quick-start.md) 中描述的 SDK 集成步骤进行操作。
2. 首先，您需要[初始化](https://ads.yandex.com/helpcenter/zh/dev/android/quick-start.md#init) 广告 SDK。
3. 确保您使用的是[最新Yandex Mobile Ads SDK 版本](https://ads.yandex.com/helpcenter/zh/dev/android/changelog-android.md)。如果您使用的是广告中介服务，请更新至最新的[单一构建版本](https://ads.yandex.com/helpcenter/zh/dev/android/changelog-android.md)。
要使用 Compose 扩展，请在 `build.gradle.kts` 中添加依赖：
```kotlin
dependencies {
implementation("com.yandex.android:mobileads:8.2.0")
implementation("com.yandex.android:mobileads-compose:8.2.0")
// Compose BOM (最低版本 2024.01.00)
implementation(platform("androidx.compose:compose-bom:2025.03.00"))
}
```
### 术语
* **冷启动** — 当应用不在内存中时启动应用，并创建新的应用会话。
* **热启动** — 将应用从后台（当应用在内存中暂停时）切换到前台。
## 实施 {#implement}
1. 在应用启动时初始化 SDK。
2. 使用 `rememberAppOpenAdLoader()` 创建广告加载器。
3. 使用挂起函数 `loadAd()` 加载广告。
4. 使用 `show(Activity)` 方法展示广告。
### 关键步骤
1. 在应用启动时初始化 SDK。
```kotlin
YandexAds.initialize(this) {
// 现在您可以使用广告
}
```
2. 使用 `rememberAppOpenAdLoader()` 创建广告加载器。
您需要从 Yandex Advertising Network 界面获取广告单元 ID (`AD_UNIT_ID`)。
您可以通过 `AdRequest.Builder()` 传递用户兴趣数据、页面上下文数据、位置或其他附加数据来扩展广告请求参数。 请求中的附加上下文数据可以显著提高广告质量。 有关更多信息，请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/android/target.md)。
```kotlin
import com.yandex.mobile.ads.compose.rememberAppOpenAdLoader
@Composable
fun SplashScreen(activity: Activity) {
val loader = rememberAppOpenAdLoader()
val AD_UNIT_ID = "R-M-XXXXXX-Y" // 出于测试目的，您可以使用 "demo-appopenad-yandex"
}
```
3. 通过 `LaunchedEffect` 使用挂起函数 `loadAd()` 加载广告。
```kotlin
LaunchedEffect(Unit) {
val adRequest = AdRequest.Builder(AD_UNIT_ID).build()
when (val result = loader.loadAd(adRequest)) {
is AppOpenAdLoadResult.Success -> appOpenAd = result.ad
is AppOpenAdLoadResult.Failure -> {
// Ad failed to load with AdRequestError.
// Attempting to load a new ad from here is strongly discouraged.
}
}
}
```
4. 使用 `show` 方法展示广告。
```kotlin
LaunchedEffect(appOpenAd) {
appOpenAd?.show(activity)
}
```
{% note info %}
如果广告已经投放，调用 `show(Activity)` 方法将在 `AppOpenAdEventListener.onAdFailedToShow(AdError)` 中返回显示错误。
{% endnote %}
### 完整示例
```kotlin
@Composable
fun SplashScreen(activity: Activity) {
var appOpenAd by remember { mutableStateOf(null) }
val loader = rememberAppOpenAdLoader()
// 输入可组合项时立即加载
LaunchedEffect(Unit) {
val adRequest = AdRequest.Builder("R-M-XXXXXX-Y").build()
when (val result = loader.loadAd(adRequest)) {
is AppOpenAdLoadResult.Success -> appOpenAd = result.ad
is AppOpenAdLoadResult.Failure -> Log.e("YandexAds", result.error.description)
}
}
LaunchedEffect(appOpenAd) {
appOpenAd?.show(activity)
}
}
```
## 开屏广告集成说明 {#features}
1. 所有 Yandex Mobile Ads SDK 方法调用都必须在主线程中进行。
2. 加载可能需要相当长的时间，因此如果广告未加载，请不要延迟冷启动。
3. 提前预加载广告以便后续在热启动时展示。
4. 不建议在应用启动时同时加载开屏广告和其他广告格式，因为应用此时可能正在下载所需数据。 这可能会使设备和互联网连接过载，从而导致广告加载速度变慢。
5. 如果您在 `AppOpenAdLoadResult.Failure` 中收到错误，请不要尝试立即加载新广告。 如果必须重试，请限制重新加载尝试次数，以避免在条件受限的情况下请求持续失败并出现连接问题。
## 测试开屏广告集成 {#test}
### 使用演示广告单元进行广告测试 {#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
```
如果存在任何广告集成问题，您将收到详细的问题报告和故障排除建议。
## 建议
1. 不要在加载屏幕（Splash screen）前展示开屏广告。
显示加载屏幕可以让用户获得更愉悦、清晰的应用体验。 这样可以避免用户感到意外或困惑，因为他们明确知道自己打开的是哪个应用。 在此屏幕上，您也可以通过加载指示器或文本消息提醒用户广告要来了，并告知用户广告结束后将恢复应用内容。
2. 如果广告请求与其展示之间存在延迟，用户可能会短暂打开您的应用，然后意外地看到与内容无关的广告。 这会对用户体验产生负面影响，因此应避免此类情况。 一种选项是在展示主应用内容之前使用加载屏幕并开始从该屏幕展示广告。 如果应用在加载屏幕后打开一些内容，此时最好不要展示广告。
3. 等待新用户打开应用并使用几次后，再展示开屏广告。 仅向应用中满足特定条件的用户展示广告（例如，完成了特定关卡、打开了特定次数的应用、未参与奖励活动等）。 不要在安装应用后立即展示广告。
4. 根据用户在应用中的行为调节展示频率。 不要在每次冷/热启动时展示广告。
5. 仅当应用在后台运行一段时间（如 30 秒、2 分钟、15 分钟）后才展示广告。
6. 务必进行测试，因为每款应用都是独特的，需采用适合自身的方法来最大限度地提高收入，而不降低用户留存率或应用使用时长。 用户行为和参与度会随时间变化，因此建议定期测试应用中的开屏广告展示策略。
## 其他资源 {#resources}
*
[GitHub](https://github.com/yandexmobile/yandex-ads-sdk-android) 链接。