Stay organized with collections
Save and categorize content based on your preferences.
The IMA SDK supports preloading video ad assets.
You can enable this feature in your SDK integration
to provide a more seamless transition between ads and content.
This guide goes over the technical details of implementing
media preload with the IMA SDK.
Prerequisite
Preloading requires version 3.17.0 or higher of the IMA Android SDK.
We recommend the
ExoPlayer-IMA extension
that is used in the
Android ExoPlayer example app.
When integrated, the ExoPlayer-IMA extension has preloading enabled by default
and includes built-in preloading support.
If you are implementing preloading without the ExoPlayer-IMA extension,
additional changes are required once setEnablePreloading() is called. In order
for a video player to support preloading ads, it must keep track of the
AdMediaInfo objects which are passed in calls from loadAd() and playAd(),
and include the correct AdMediaInfo on the AdPlayerCallback calls. This may
require a data-structure to manage AdMediaInfo objects, given that loadAd()
for a subsequent AdMediaInfo may occur while a prior AdMediaInfo is
currently playing back. The following example demonstrates some of the changes
you may need to make for your app to support preloading:
//enumforcasesofPlayerState.staticenumPlayerState{IDLE,LOADED,PLAYING,PAUSED,}...privatefinalList<VideoAdPlayer.VideoAdPlayerCallback>callbacks;privatefinalArrayList<AdMediaInfo>mediaInfos=newArrayList<>();privatePlayerStateplayerState;privatebooleanadCurrentlyLoaded;...@OverridepublicvoidplayAd(AdMediaInfoadMediaInfo){switch(playerState){caseLOADED:for(VideoAdPlayerCallbackcallback:callbacks){callback.onPlay(adMediaInfo);}break;casePAUSED:for(VideoAdPlayerCallbackcallback:callbacks){callback.onResume(adMediaInfo);}break;casePLAYING://Intentionallyandsilentlyignoresinceitisalreadyplayingfromapriormediaitem,//notethatonPlayistriggeredbypositionDiscontinuity.return;caseIDLE:thrownewIllegalStateException("Call to playAd when player state is not LOADED.");}playerState=PlayerState.PLAYING;player.setPlayWhenReady(true);}@OverridepublicvoidloadAd(AdMediaInfoadMediaInfo,AdPodInfoadPodInfo){if(adCurrentlyLoaded==true){mediaInfos.add(adMediaInfo);return;}player.stop();player.seekTo(0);mediaInfos.clear();mediaInfos.add(adMediaInfo);player.setPlayWhenReady(false);player.loadMedia(adMediaInfo.getUrl());playerState=PlayerState.LOADED;adCurrentlyLoaded=true;}@OverridepublicvoidstopAd(AdMediaInfoadMediaInfo){if(allAdsInBreakHavePlayed()){if(isFinalAd(adMediaInfo)){//handlecleanupafteralladshaveplayed.}else{seekToNextItem(player);}}else{mediaInfos.remove(adMediaInfo);}}privatebooleanallAdsInBreakHavePlayed(){//Codetodetermineifalltheadsinthecurrentadbreakhavecompleted.}privatebooleanisFinalAd(AdMediaInfoadMediaInfo){//CodetodetermineifthisadMediaInfoisthefinalad.}privatevoidseekToNextItem(YourPlayerClassplayer){//Codetoseekyourplayertothenextmediaitem.}
Testing custom preloading implementations
For custom preloading implementations, testing the following edge-cases is
recommended to verify a correct preloading setup:
Single ad preroll
3 ad pod preroll
3 ad pod midroll
Seeking to a second midroll after the first midroll has begun preloading but before it has played
Postroll playback
Timing
The following table summarizes the changes in ad-load timing when preloading
is enabled:
Event
With Preload
Without Preload
Ad VAST requested
AdsLoader.requestAds()
AdsLoader.requestAds()
Pre-roll loaded (single ad)
AdsManager.init()
AdsManager.start()
Pre-roll loaded (VMAP/Ad rules)
AdsManager.init()
AdsManager.init()
Mid-roll or post-roll loaded
For the 1st ad in an ad break, 8 seconds before ad start time.
For consecutive ads, when the previous ad starts playing.
At ad start time.
FAQ
Does media preloading load the full creative?
No, the creative is usually not fully loaded when ad playback begins.
Preloading is intended for improving the user experience by minimizing the time
it takes for the ad to load. It is not intended to support offline ad serving.
Does media preloading need to be enabled for the ad's VAST as well as media?
No, the SDK always preloads the ad's VAST, regardless of this preload
setting.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eThe IMA SDK supports preloading video ad assets to create smoother transitions between ads and content, requiring version 3.17.0 or higher of the IMA Android SDK.\u003c/p\u003e\n"],["\u003cp\u003ePreloading is enabled using \u003ccode\u003eAdsRenderingSettings.setEnablePreloading(true)\u003c/code\u003e within the \u003ccode\u003eonAdsManagerLoaded()\u003c/code\u003e callback.\u003c/p\u003e\n"],["\u003cp\u003eWhile the ExoPlayer-IMA extension has built-in preloading, custom implementations require managing \u003ccode\u003eAdMediaInfo\u003c/code\u003e objects to ensure proper ad playback.\u003c/p\u003e\n"],["\u003cp\u003ePreloading primarily focuses on minimizing initial ad load times and does not guarantee full creative download or offline ad serving.\u003c/p\u003e\n"]]],[],null,["# Preload media\n\nThe IMA SDK supports preloading video ad assets.\nYou can enable this feature in your SDK integration\nto provide a more seamless transition between ads and content.\nThis guide goes over the technical details of implementing\nmedia preload with the IMA SDK.\n\nPrerequisite\n------------\n\nPreloading requires version 3.17.0 or higher of the IMA Android SDK.\n\nEnable preloading\n-----------------\n\nTo enable preloading, use [`AdsRenderingSettings.setEnablePreloading()`](/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/AdsRenderingSettings#setEnablePreloading(boolean)) to set preloading to true. This must be done within the `onAdsManagerLoaded()` callback:\n\n\u003cbr /\u003e\n\n @Override\n public void onAdsManagerLoaded(AdsManagerLoadedEvent adsManagerLoadedEvent) {\n ...\n AdsRenderingSettings adsRenderingSettings =\n ImaSdkFactory.getInstance().createAdsRenderingSettings();\n adsRenderingSettings.setEnablePreloading(true);\n mAdsManager.init(adsRenderingSettings);\n }\n\nSupporting preloading with a custom VideoAdPlayer\n-------------------------------------------------\n\nWe recommend the\n[ExoPlayer-IMA extension](//github.com/androidx/media/tree/release/libraries/exoplayer_ima)\nthat is used in the\n[Android ExoPlayer example app](//github.com/googleads/googleads-ima-android/tree/main/ExoPlayerExample).\nWhen integrated, the ExoPlayer-IMA extension has preloading enabled by default\nand includes built-in preloading support.\n\nIf you are implementing preloading without the ExoPlayer-IMA extension,\nadditional changes are required once `setEnablePreloading()` is called. In order\nfor a video player to support preloading ads, it must keep track of the\n`AdMediaInfo` objects which are passed in calls from `loadAd()` and `playAd()`,\nand include the correct `AdMediaInfo` on the `AdPlayerCallback` calls. This may\nrequire a data-structure to manage `AdMediaInfo` objects, given that `loadAd()`\nfor a subsequent `AdMediaInfo` may occur while a prior `AdMediaInfo` is\ncurrently playing back. The following example demonstrates some of the changes\nyou may need to make for your app to support preloading: \n\n // enum for cases of PlayerState.\n static enum PlayerState {\n IDLE,\n LOADED,\n PLAYING,\n PAUSED,\n }\n\n ...\n\n private final List\u003cVideoAdPlayer.VideoAdPlayerCallback\u003e callbacks;\n private final ArrayList\u003cAdMediaInfo\u003e mediaInfos = new ArrayList\u003c\u003e();\n private PlayerState playerState;\n private boolean adCurrentlyLoaded;\n\n ...\n\n @Override\n public void playAd(AdMediaInfo adMediaInfo) {\n switch (playerState) {\n case LOADED:\n for (VideoAdPlayerCallback callback : callbacks) {\n callback.onPlay(adMediaInfo);\n }\n break;\n case PAUSED:\n for (VideoAdPlayerCallback callback : callbacks) {\n callback.onResume(adMediaInfo);\n }\n break;\n case PLAYING:\n // Intentionally and silently ignore since it is already playing from a prior media item,\n // note that onPlay is triggered by positionDiscontinuity.\n return;\n case IDLE:\n throw new IllegalStateException(\"Call to playAd when player state is not LOADED.\");\n }\n playerState = PlayerState.PLAYING;\n player.setPlayWhenReady(true);\n }\n\n @Override\n public void loadAd(AdMediaInfo adMediaInfo, AdPodInfo adPodInfo) {\n if (adCurrentlyLoaded == true) {\n mediaInfos.add(adMediaInfo);\n return;\n }\n player.stop();\n player.seekTo(0);\n mediaInfos.clear();\n mediaInfos.add(adMediaInfo);\n player.setPlayWhenReady(false);\n player.loadMedia(adMediaInfo.getUrl());\n playerState = PlayerState.LOADED;\n adCurrentlyLoaded = true;\n }\n\n @Override\n public void stopAd(AdMediaInfo adMediaInfo) {\n if (allAdsInBreakHavePlayed()) {\n if (isFinalAd(adMediaInfo)) {\n // handle clean up after all ads have played.\n } else {\n seekToNextItem(player);\n }\n } else {\n mediaInfos.remove(adMediaInfo);\n }\n }\n\n private boolean allAdsInBreakHavePlayed() {\n // Code to determine if all the ads in the current ad break have completed.\n }\n\n private boolean isFinalAd(AdMediaInfo adMediaInfo) {\n // Code to determine if this adMediaInfo is the final ad.\n }\n\n private void seekToNextItem(YourPlayerClass player) {\n // Code to seek your player to the next media item.\n }\n\n### Testing custom preloading implementations\n\nFor custom preloading implementations, testing the following edge-cases is\nrecommended to verify a correct preloading setup:\n\n- Single ad preroll\n- 3 ad pod preroll\n- 3 ad pod midroll\n- Seeking to a second midroll after the first midroll has begun preloading but before it has played\n- Postroll playback\n\nTiming\n------\n\nThe following table summarizes the changes in ad-load timing when preloading\nis enabled:\n\n| Event | With Preload | Without Preload |\n|---------------------------------|--------------------------------------------------------------------------------------------------------------------------|--------------------------|\n| Ad VAST requested | `AdsLoader.requestAds()` | `AdsLoader.requestAds()` |\n| Pre-roll loaded (single ad) | `AdsManager.init()` | `AdsManager.start()` |\n| Pre-roll loaded (VMAP/Ad rules) | `AdsManager.init()` | `AdsManager.init()` |\n| Mid-roll or post-roll loaded | For the 1st ad in an ad break, 8 seconds before ad start time. For consecutive ads, when the previous ad starts playing. | At ad start time. |\n\nFAQ\n---\n\nDoes media preloading load the full creative?\n: No, the creative is usually not fully loaded when ad playback begins.\n Preloading is intended for improving the user experience by minimizing the time\n it takes for the ad to load. It is not intended to support offline ad serving.\n\nDoes media preloading need to be enabled for the ad's VAST as well as media?\n: No, the SDK always preloads the ad's VAST, regardless of this preload\n setting."]]