--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ads.yandex.com/helpcenter/en/dev/android/interstitial.md - https://ads.yandex.com/helpcenter/pt/dev/android/interstitial.md - https://ads.yandex.com/helpcenter/ru/dev/android/interstitial.md - https://ads.yandex.com/helpcenter/zh/dev/android/interstitial.md --- > **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt # 插屏广告 插屏广告是一种全屏广告格式，嵌入在应用内容中，在自然暂停时显示，例如在游戏关卡之间过渡或完成目标操作时。 当应用呈现插屏广告时，用户有两个选择：点击广告并前往广告商网站或关闭广告并返回应用。 插屏广告中，用户注意力会完全集中在广告上，因此展示成本较高。 {% cut "外观" %} {% endcut %} 本指南将展示如何将插屏广告集成到 Android 应用中。除了代码示例和说明之外，它还包含特定格式的建议和其他资源的链接。 ## 前提条件 {#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)。 ## 实施 {#implement} 集成插屏广告的关键步骤： * 创建并配置 `InterstitialAdLoader` 广告加载器。 * 注册广告加载回调方法的监听器：`InterstitialAdLoadListener`。 * 加载广告。 * 如果您使用 Adfox，请传递 [其他设置](https://ads.yandex.com/helpcenter/zh/dev/android/target-adfox.md)。 * 为广告事件回调方法注册 `InterstitialAdEventListener` 监听器。 * 呈现 `InterstitialAd`。 ## 插屏广告集成的特点 {#features} 1. 所有调用 Yandex Mobile Ads SDK 方法的操作必须在主线程中完成。 2. 如果您在 `onAdFailedToLoad()` 回调中收到错误，请不要尝试再次加载新广告。如果没有其他选项，请限制广告加载重试次数。这将有助于避免出现限制时持续出现不成功的请求和连接问题。 3. 我们建议在承载与广告交互的屏幕的生命周期内，始终保持对加载器和广告的强引用，以避免垃圾清理器进行清理。 4. 我们建议对所有广告加载使用 `InterstitialAdLoader` 的单个实例，以提高性能。 ## 加载广告 {#load} 要上传插屏广告，请创建并设置 `InterstitialAdLoader` 对象。 为此，您需要活动或应用程序上下文。 要在广告加载或加载失败时发出通知，请为 `InterstitialAdLoader` 对象设置 `InterstitialAdLoadListener` 回调方法监听器。 要加载广告，您需要来自 Yandex Advertising Network 界面 (adUnitId) 的广告单元标识符。 您可以通过 `AdRequestConfiguration.Builder()` 传递用户兴趣、上下文应用数据、位置详细信息或其他数据来扩展广告请求参数。在请求中提供额外的上下文数据可以显著提高您的广告质量。请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/android/target.md)版块了解更多信息。 广告加载后（通过调用 `onAdLoaded(interstitialAd: InterstitialAd)`方法），在展示完成之前保存加载的 `InterstitialAd` 的链接。 以下示例展示了如何从活动加载插屏广告： {% list tabs %} - Kotlin ```kotlin class InterstitialAdActivity : AppCompatActivity(R.layout.activity_interstitial_ad) { private var interstitialAd: InterstitialAd? = null private var interstitialAdLoader: InterstitialAdLoader? = null private lateinit var binding: ActivityInterstitialAdBinding override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding = ActivityInterstitialAdBinding.inflate(layoutInflater) setContentView(binding.root) // 插屏广告加载应在 SDK 初始化后进行。 // 尽早初始化 SDK，例如在 Application.onCreate 或 Activity.onCreate 中 interstitialAdLoader = InterstitialAdLoader(this).apply { setAdLoadListener(object : InterstitialAdLoadListener { override fun onAdLoaded(ad: InterstitialAd) { interstitialAd = ad // 广告加载成功。您现在可以展示广告。 } override fun onAdFailedToLoad(adRequestError: AdRequestError) { // 广告加载失败，出现 AdRequestError。 // 强烈建议不要尝试通过 onAdFailedToLoad() 方法加载新广告。 } }) } loadInterstitialAd() } private fun loadInterstitialAd() { val adRequestConfiguration = AdRequestConfiguration.Builder("your-ad-unit-id").build() interstitialAdLoader?.loadAd(adRequestConfiguration) } } ``` - Java ```java public class InterstitialAdActivity extends AppCompatActivity { @Nullable private InterstitialAd mInterstitialAd = null; @Nullable private InterstitialAdLoader mInterstitialAdLoader = null; private ActivityInterstitialAdBinding mBinding; public InterstitialAdActivity() { super(R.layout.activity_interstitial_ad); } @Override protected void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); mBinding = ActivityInterstitialAdBinding.inflate(getLayoutInflater()); setContentView(mBinding.getRoot()); // 插屏广告加载应在 SDK 初始化后进行。 // 尽早初始化 SDK，例如在 Application.onCreate 或 Activity.onCreate 中 mInterstitialAdLoader = new InterstitialAdLoader(this); mInterstitialAdLoader.setAdLoadListener(new InterstitialAdLoadListener() { @Override public void onAdLoaded(@NonNull final InterstitialAd interstitialAd) { mInterstitialAd = interstitialAd; // 广告加载成功。您现在可以展示广告。 } @Override public void onAdFailedToLoad(@NonNull final AdRequestError adRequestError) { // 广告加载失败，出现 AdRequestError。 // 强烈建议不要尝试通过 onAdFailedToLoad() 方法加载新广告。 } }); loadInterstitialAd(); } private void loadInterstitialAd() { if (mInterstitialAdLoader != null ) { final AdRequestConfiguration adRequestConfiguration = new AdRequestConfiguration.Builder("your-ad-unit-id").build(); mInterstitialAdLoader.loadAd(adRequestConfiguration); } } } ``` {% endlist %} 如果您通过 Adfox 投放广告，则在横幅广告响应后，可以使用 `AdAttributes` 类型的 `adAttributes` 属性从 `interstitialAdLoader` 对象访问 `campaignId`、`bannerId` 和 `placeId` 数据。 ## 广告呈现 {#ad-view} 插屏广告应在应用运行的自然暂停期间展示。一个不错的选择是在游戏关卡之间或转换后（例如，下载文件时）插入插屏广告。 在呈现广告之前，设置 `InterstitialAdEventListener` 广告回调方法监听器。 要呈现广告，您需要将活动传递给已加载广告的展示方法： {% list tabs %} - Kotlin ```kotlin private fun showAd() { interstitialAd?.apply { setAdEventListener(object : InterstitialAdEventListener { override fun onAdShown() { // 广告展示时调用。 } override fun onAdFailedToShow(adError: AdError) { // 当 InterstitialAd 未能显示时调用。 // 广告关闭后清理资源 interstitialAd?.setAdEventListener(null) interstitialAd = null // 现在您可以预加载下一个插屏广告。 loadInterstitialAd() } override fun onAdDismissed() { // 广告关闭时调用。 // 广告关闭后清理资源 interstitialAd?.setAdEventListener(null) interstitialAd = null // 现在您可以预加载下一个插屏广告。 loadInterstitialAd() } override fun onAdClicked() { // 记录广告点击时调用。 } override fun onAdImpression(impressionData: ImpressionData?) { // 记录广告展示次数时调用。 } }) show(this@Activity) } } ``` - Java ```java private void showAd() { if (mInterstitialAd != null) { mInterstitialAd.setAdEventListener(new InterstitialAdEventListener() { @Override public void onAdShown() { // 广告展示时调用。 } @Override public void onAdFailedToShow(@NonNull final AdError adError) { // 当 InterstitialAd 未能显示时调用。 } @Override public void onAdDismissed() { // 广告关闭时调用。 // 广告关闭后清理资源 if (mInterstitialAd != null) { mInterstitialAd.setAdEventListener(null); mInterstitialAd = null; } // 现在您可以预加载下一个插屏广告。 loadInterstitialAd(); } @Override public void onAdClicked() { // 记录广告点击时调用。 } @Override public void onAdImpression(@Nullable final ImpressionData impressionData) { // 记录广告展示次数时调用。 } }); mInterstitialAd.show(this); } } ``` {% endlist %} ## 释放资源 {#destroy} 不要存储先前呈现的广告的链接。针对之前呈现的广告调用 `setAdEventListener(null)`。 如果不再使用加载器，请调用 `setAdLoadListener(null)`。 这可以释放资源并防止内存泄漏。 {% list tabs %} - Kotlin ```kotlin override fun onDestroy() { super.onDestroy() interstitialAdLoader?.setAdLoadListener(null) interstitialAdLoader = null destroyInterstitialAd() } private fun destroyInterstitialAd() { interstitialAd?.setAdEventListener(null) interstitialAd = null } ``` - Java ```java @Override protected void onDestroy() { super.onDestroy(); if (mInterstitialAdLoader != null) { mInterstitialAdLoader.setAdLoadListener(null); mInterstitialAdLoader = null; } destroyInterstitialAd(); } private void destroyInterstitialAd() { if (mInterstitialAd != null) { mInterstitialAd.setAdEventListener(null); mInterstitialAd = null; } } ``` {% endlist %} ## 测试插屏广告集成 {#test} ### 使用演示广告单元进行广告测试 {#demo-blocks} 使用测试广告来检查您的插播广告集成和应用本身。为了确保每次广告请求都能返回测试广告，您可以使用一个特殊的演示广告版位 ID。 演示广告单元 ID：`demo-interstitial-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 interstitial was integrated successfully ``` 如果存在任何插播广告集成问题，您将收到详细的问题报告和故障排除建议。 ## 其他资源 {#resources} * [GitHub](https://github.com/yandexmobile/yandex-ads-sdk-android) 链接。