--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://ads.yandex.com/helpcenter/en/easy/integration/android/formats/interstitial.md - https://ads.yandex.com/helpcenter/ru/easy/integration/android/formats/interstitial.md - https://ads.yandex.com/helpcenter/zh/easy/integration/android/formats/interstitial.md - href: en/easy/integration/android/formats/interstitial.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/en/llms.txt # Interstitial ads A fullscreen ad format, interstitial ads are integrated in the app content at natural breaks, such as when the user transitions to the next game level or completes a conversion action. {% note info %} Examples showing how all the format types work are available in the [demo project](https://ads.yandex.com/helpcenter/en/easy/integration/android/testing.md#demo). {% endnote %} #| || **Entity** | **Description** || || `onAdFailedToLoad` | If `onAdFailedToLoad()` reports an error, do not try to load a new ad again **from this same method**. || || `InterstitialAdEventListener` | Do not keep references to ads that have already been shown. Call `setAdEventListener(null)` for ads that have finished displaying. Call `setAdLoadListener(null)` on the loader when you no longer use it. This frees resources and prevents memory leaks. || || `adUnitId` | Use: - **development mode** — to work with [demo ad units](https://ads.yandex.com/helpcenter/en/easy/integration/android/testing.md#blocks); - **production mode** — to work with `R-M-XXXXXX-Y` (for the actual ID, check the Yandex Advertising Network interface). `R-M-XXXXXX-Y` is a template for your actual ad unit ID that will be used to receive various creatives. || |# ## Implementation {#implement} Main steps for integrating interstitial ads: * Create and configure the ad loader `InterstitialAdLoader`. * Register the load callback listener `InterstitialAdLoadListener`. * Load the ad. * Pass additional settings if you work through the Adfox system. * Register the ad event callback listener `InterstitialAdEventListener`. * Show the `InterstitialAd` ad. ## Interstitial integration specifics {#features} 1. All calls to Yandex Mobile Ads SDK methods must be made from the main thread. 2. If you receive an error in the `onAdFailedToLoad()` callback, do not try to load a new ad again immediately. If you still need to retry, limit how many times you reload. That helps avoid endless failed requests and connectivity issues when the network is limited. 3. Keep a strong reference to the loader and the ad for the entire lifetime of the screen where the user interacts with the ad, so they are not reclaimed by the garbage collector too early. 4. Use a single `InterstitialAdLoader` instance for all interstitial loads to improve performance. ## Loading ads {#load} To load interstitial ads, create and configure an `InterstitialAdLoader` object. You need an Activity or Application `Context`. To receive success or failure load notifications, set an `InterstitialAdLoadListener` on the `InterstitialAdLoader`. You need the ad unit ID from the Yandex Advertising Network interface (`adUnitId`). You can extend the ad request via `AdRequest.Builder()` by passing user interests, page context, location, or other data. Extra contextual data in the request can significantly improve ad quality. After the ad loads (`onAdLoaded(interstitialAd: InterstitialAd)`), keep a reference to the loaded `InterstitialAd` until the ad has finished showing. The example below shows how to load an interstitial ad from an Activity: {% 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) // Interstitial ads loading should occur after initialization of the SDK. // Initialize SDK as early as possible, for example in Application.onCreate or Activity.onCreate interstitialAdLoader = InterstitialAdLoader(this) loadInterstitialAd() } private fun loadInterstitialAd() { val adRequest = AdRequest.Builder("your-ad-unit-id").build() interstitialAdLoader?.loadAd(adRequest, object : InterstitialAdLoadListener { override fun onAdLoaded(ad: InterstitialAd) { interstitialAd = ad // The ad was loaded successfully. Now you can show loaded ad. } override fun onAdFailedToLoad(adRequestError: AdRequestError) { // Ad failed to load with AdRequestError. // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged. } }) } } ``` - 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()); // Interstitial ads loading should occur after initialization of the SDK. // Initialize SDK as early as possible, for example in Application.onCreate or Activity.onCreate mInterstitialAdLoader = new InterstitialAdLoader(this); loadInterstitialAd(); } private void loadInterstitialAd() { if (mInterstitialAdLoader != null) { final AdRequest adRequest = new AdRequest.Builder("your-ad-unit-id").build(); mInterstitialAdLoader.loadAd(adRequest, new InterstitialAdLoadListener() { @Override public void onAdLoaded(@NonNull final InterstitialAd interstitialAd) { mInterstitialAd = interstitialAd; // The ad was loaded successfully. Now you can show loaded ad. } @Override public void onAdFailedToLoad(@NonNull final AdRequestError adRequestError) { // Ad failed to load with AdRequestError. // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged. } }); } } } ``` {% endlist %} ## Displaying the ad {#ad-view} Interstitial ads should be shown during natural pauses in your app—for example between game levels or after the user completes an action, such as finishing a file download. Before showing the ad, set the ad event callback listener `InterstitialAdEventListener` on the ad. To show the ad, pass an `Activity` to the `show` method of the loaded ad object: {% list tabs %} - Kotlin ```kotlin private fun showAd() { interstitialAd?.apply { setAdEventListener(object : InterstitialAdEventListener { override fun onAdShown() { // Called when ad is shown. } override fun onAdFailedToShow(adError: AdError) { // Called when an InterstitialAd failed to show. // Clean resources after Ad dismissed interstitialAd?.setAdEventListener(null) interstitialAd = null // Now you can preload the next interstitial ad. loadInterstitialAd() } override fun onAdDismissed() { // Called when ad is dismissed. // Clean resources after Ad dismissed interstitialAd?.setAdEventListener(null) interstitialAd = null // Now you can preload the next interstitial ad. loadInterstitialAd() } override fun onAdClicked() { // Called when a click is recorded for an ad. } override fun onAdImpression(impressionData: ImpressionData?) { // Called when an impression is recorded for an ad. } }) show(this@InterstitialAdActivity) } } ``` - Java ```java private void showAd() { if (mInterstitialAd != null) { mInterstitialAd.setAdEventListener(new InterstitialAdEventListener() { @Override public void onAdShown() { // Called when ad is shown. } @Override public void onAdFailedToShow(@NonNull final AdError adError) { // Called when an InterstitialAd failed to show. } @Override public void onAdDismissed() { // Called when ad is dismissed. // Clean resources after Ad dismissed if (mInterstitialAd != null) { mInterstitialAd.setAdEventListener(null); mInterstitialAd = null; } // Now you can preload the next interstitial ad. loadInterstitialAd(); } @Override public void onAdClicked() { // Called when a click is recorded for an ad. } @Override public void onAdImpression(@Nullable final ImpressionData impressionData) { // Called when an impression is recorded for an ad. } }); mInterstitialAd.show(this); } } ``` {% endlist %} ## Releasing resources {#destroy} Do not keep references to ads that have finished their lifecycle. Call `setAdEventListener(null)` for such ads. This frees resources in use and prevents memory leaks. {% list tabs %} - Kotlin ```kotlin override fun onDestroy() { super.onDestroy() interstitialAdLoader = null destroyInterstitialAd() } private fun destroyInterstitialAd() { interstitialAd?.setAdEventListener(null) interstitialAd = null } ``` - Java ```java @Override protected void onDestroy() { super.onDestroy(); mInterstitialAdLoader = null; destroyInterstitialAd(); } private void destroyInterstitialAd() { if (mInterstitialAd != null) { mInterstitialAd.setAdEventListener(null); mInterstitialAd = null; } } ``` {% endlist %} ## Checking integration Build and run your project. You can check if the integration is successful by searching the `YandexAds` keyword in **Logcat**: ``` [Integration] Ad type interstitial was integrated successfully ```