--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ads.yandex.com/helpcenter/en/dev/android/app-open-ad.md - https://ads.yandex.com/helpcenter/pt/dev/android/app-open-ad.md - https://ads.yandex.com/helpcenter/ru/dev/android/app-open-ad.md - https://ads.yandex.com/helpcenter/zh/dev/android/app-open-ad.md --- > **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt # 开屏广告 应用开屏广告是一种用于通过应用加载界面实现变现的特殊广告格式。此类广告可随时关闭，并设计用于在以下场景中展示： * 应用启动时。 * 应用被调至前台时。 * 从后台返回应用时。 本指南将展示如何在打开 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)。 ### 术语和定义 * **冷启动**是指启动一个不在 RAM 中的应用，创建一个新的应用会话。 * **热启动**是指当应用在 RAM 中暂停时，将应用从后台模式切换到前台模式。 ## 实施 {#implement} 1. 在应用启动时初始化 SDK。 2. 创建并设置 `AppOpenAdLoader` 广告加载器对象。 3. 设置 `AppOpenAdLoadListener` 回调方法监听器，以在广告加载成功或失败时发出通知。 4. 使用 `loadAd(AdRequestConfiguration)` 方法加载广告。 5. 使用 [LifecycleEventObserver](https://developer.android.com/reference/androidx/lifecycle/LifecycleEventObserver) 处理应用状态变更并展示开屏广告。 6. 在渲染广告之前，请先设置 `AppOpenAdEventListener` 广告回调方法监听器。 7. 使用 `show(Activity)` 方法渲染广告。 8. 释放资源。 ### 主要步骤 1. 在应用启动时初始化 SDK。 {% list tabs %} - Kotlin ```kotlin YandexAds.initialize(this) { // 现在您可以使用广告 } ``` - Java ```java YandexAds.initialize(this, () -> { // 现在您可以使用广告 }); ``` {% endlist %} 2. 创建并设置 `AppOpenAdLoader` 广告加载器对象。 您需要从 Yandex Advertising Network 界面获取广告单元 ID (`AD_UNIT_ID`)。 您可以通过 `AdRequestConfiguration.Builder()` 传递用户兴趣、上下文应用数据、位置详细信息或其他数据来扩展广告请求参数。 在请求中提供额外的上下文数据可以显著提高您的广告质量。 详情请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/android/target.md)部分。 {% list tabs %} - Kotlin ```kotlin val appOpenAdLoader: AppOpenAdLoader = AppOpenAdLoader(application) val AD_UNIT_ID = "R-M-XXXXXX-Y" // 要进行调试，您可以使用 "demo-appopenad-yandex" val adRequestConfiguration = AdRequestConfiguration.Builder(AD_UNIT_ID).build() ``` - Java ```java final AppOpenAdLoader appOpenAdLoader = AppOpenAdLoader(application); final String AD_UNIT_ID = "R-M-XXXXXX-Y"; // 要进行调试，您可以使用 "demo-appopenad-yandex" final AdRequestConfiguration adRequestConfiguration = new AdRequestConfiguration.Builder(AD_UNIT_ID).build(); ``` {% endlist %} 3. 设置 `AppOpenAdLoadListener` 回调方法监听器，以在广告加载成功或失败时发出通知。 {% list tabs %} - Kotlin ```kotlin val appOpenAdLoadListener = object : AppOpenAdLoadListener { override fun onAdLoaded(appOpenAd: AppOpenAd) { // 广告已成功加载。 您现在可以展示广告。 this@Activity.appOpenAd = appOpenAd } override fun onAdFailedToLoad(adRequestError: AdRequestError) { // 广告因 AdRequestError 无法加载。 // 强烈建议不要尝试通过 onAdFailedToLoad() 方法加载新广告。 } } appOpenAdLoader.setAdLoadListener(appOpenAdLoadListener) ``` - Java ```java AppOpenAdLoadListener appOpenAdLoadListener = new AppOpenAdLoadListener() { @Override public void onAdLoaded(@NonNull final AppOpenAd appOpenAd) { // 广告已成功加载。 您现在可以展示广告。 mAppOpenAd = appOpenAd; } @Override public void onAdFailedToLoad(@NonNull final AdRequestError adRequestError) { // 广告因 AdRequestError 无法加载。 // 强烈建议不要尝试通过 onAdFailedToLoad() 方法加载新广告。 } }; appOpenAdLoader.setAdLoadListener(appOpenAdLoadListener); ``` {% endlist %} 4. 使用 `loadAd(AdRequestConfiguration)` 方法加载广告。 {% list tabs %} - Kotlin ```kotlin appOpenAdLoader.loadAd(adRequestConfiguration) ``` - Java ```java appOpenAdLoader.loadAd(adRequestConfiguration); ``` {% endlist %} 5. 使用 `LifecycleEventObserver` 处理应用状态变更并展示开屏广告。 {% list tabs %} - Kotlin ```kotlin val processLifecycleObserver = DefaultProcessLifecycleObserver( onProcessCameForeground = ::showAppOpenAd ) ProcessLifecycleOwner.get().lifecycle.addObserver(processLifecycleObserver) ``` - Java ```java final DefaultProcessLifecycleObserver processLifecycleObserver = new DefaultProcessLifecycleObserver() { @Override public void onProcessCameForeground() { showAppOpenAd(); } } ProcessLifecycleOwner.get().getLifecycle().addObserver(processLifecycleObserver); ``` {% endlist %} 6. 在渲染广告之前，请先设置 `AppOpenAdEventListener` 广告回调方法监听器。 {% list tabs %} - Kotlin ```kotlin private inner class AdEventListener : AppOpenAdEventListener { override fun onAdShown() { // 广告展示时调用。 } override fun onAdFailedToShow(adError: AdError) { // 广告无法展示时调用。 } override fun onAdDismissed() { // 广告关闭时调用。 // 关闭后清理资源并预加载新广告。 clearAppOpenAd() loadAppOpenAd() } override fun onAdClicked() { // 记录广告点击时调用。 } override fun onAdImpression(impressionData: ImpressionData?) { // 记录广告展示时调用。 // 在参数中获取展示层级收入数据。 } } private val appOpenAdEventListener = AdEventListener() appOpenAd?.setAdEventListener(appOpenAdEventListener) ``` - Java ```java AppOpenAdEventListener appOpenAdEventListener = new AppOpenAdEventListener() { @Override public void onAdShown() { // 广告展示时调用。 } @Override public void onAdFailedToShow(@NonNull final AdError adError) { // 广告无法展示时调用。 } @Override public void onAdDismissed() { // 广告关闭时调用。 // 关闭后清理资源并预加载新广告。 clearAppOpenAd(); loadAppOpenAd(); } @Override public void onAdClicked() { // 记录广告点击时调用。 } @Override public void onAdImpression(@Nullable final ImpressionData impressionData) { // 记录广告展示时调用。 } }; if (mAppOpenAd != null) { mAppOpenAd.setAdEventListener(appOpenAdEventListener); } ``` {% endlist %} 7. 使用 `show` 方法呈现广告。 {% list tabs %} - Kotlin ```kotlin private fun showAppOpenAd() { appOpenAd?.show(activity) } ``` - Java ```java private void showAppOpenAd() { if (mAppOpenAd != null) { mAppOpenAd.show(activity); } } ``` {% endlist %} {% note info %} 如果广告已经投放，调用 `show(Activity)` 方法将在 `AppOpenAdEventListener.onAdFailedToShow(AdError)` 中返回显示错误。 {% endnote %} 8. 释放资源。 这可以防止内存泄漏。 {% list tabs %} - Kotlin ```kotlin private fun clearAppOpenAd() { appOpenAd?.setAdEventListener(null) appOpenAd = null } ``` - Java ```java private void clearAppOpenAd() { if (mAppOpenAd != null) { mAppOpenAd.setAdEventListener(null); mAppOpenAd = null; } } ``` {% endlist %} ## 开屏广告集成的特性 {#features} 1. 所有 Yandex Mobile Ads SDK 方法调用都必须在主线程中进行。 2. 加载可能需要一段时间，因此如果广告尚未加载，请勿增加冷启动时间。 3. 预加载广告以便后续在热启动期间显示。 4. 我们不建议您在应用启动期间同时加载开屏广告和其他广告格式，因为此时应用可能正在下载运行数据。 这可能会使设备和互联网连接超载，从而导致广告加载时间变长。 5. 如果您在 `onAdFailedToLoad()` 回调中收到错误，请不要尝试再次加载新广告。 如果必须这样做，请限制广告重新加载尝试的次数。 这将有助于避免出现限制时持续出现不成功的请求和连接问题。 ## 在发布时测试广告集成 {#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. 不要在启动画面之前渲染开屏广告。 通过显示启动画面，您可以增强用户的应用体验，使其更加流畅，令用户愉悦。 这将避免用户感到惊讶或困惑，并确保他们打开了正确的应用。 在同一屏幕上，您可以提醒用户即将展示的广告。 使用加载指示器或简单的文本信息告知用户他们将在广告结束后继续查看应用内容。 2. 如果广告请求与广告渲染之间存在延迟，用户可能会短暂打开您的应用，然后意外地看到与内容无关的广告。 这会对用户体验产生负面影响，因此需要避免。 一种解决方案是在显示主应用内容之前使用启动画面，并从该屏幕开始广告渲染。 如果应用在启动画面后打开一些内容，则最好不要渲染广告。 3. 等到新用户打开应用并使用几次后，再渲染开屏广告。 仅向应用中满足特定条件（例如，通过了特定关卡、打开了特定次数的应用或未参与奖励活动）的用户渲染广告。 不要在用户安装应用后立即渲染广告。 4. 根据应用用户行为调节广告渲染频率。 不要在每次冷/热应用启动时渲染广告。 5. 仅当应用在后台运行一段时间（如 30 秒、2 分钟、15 分钟）后才渲染广告。 6. 确保运行了彻底的测试，因为每款应用都是独特的，并且需要特殊的方法来最大限度地提高收入，而不降低用户留存率或应用使用时长。 用户行为和参与度可能会随着时间的推移而发生变化，因此我们建议定期测试您用于开屏广告的策略。 ## 其他资源 {#resources} * [GitHub](https://github.com/yandexmobile/yandex-ads-sdk-android) 链接。