Select platform: [HTML5](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/preload.md.txt "View this page for the HTML5 platform docs.") [Android](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/preload.md.txt "View this page for the Android platform docs.")

<br />

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.

## Enable preloading

To enable preloading, use [`AdsRenderingSettings.setEnablePreloading()`](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/AdsRenderingSettings.md.txt#setEnablePreloading(boolean)) to set preloading to true. This must be done within the `onAdsManagerLoaded()` callback:

<br />

    @Override
    public void onAdsManagerLoaded(AdsManagerLoadedEvent adsManagerLoadedEvent) {
      ...
      AdsRenderingSettings adsRenderingSettings =
          ImaSdkFactory.getInstance().createAdsRenderingSettings();
      adsRenderingSettings.setEnablePreloading(true);
      mAdsManager.init(adsRenderingSettings);
    }

## Supporting preloading with a custom VideoAdPlayer

We recommend the
[ExoPlayer-IMA extension](https://github.com/androidx/media/tree/release/libraries/exoplayer_ima)
that is used in the
[Android ExoPlayer example app](https://github.com/googleads/googleads-ima-android/tree/main/ExoPlayerExample).
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:

    // enum for cases of PlayerState.
    static enum PlayerState {
      IDLE,
      LOADED,
      PLAYING,
      PAUSED,
    }

    ...

    private final List<VideoAdPlayer.VideoAdPlayerCallback> callbacks;
    private final ArrayList<AdMediaInfo> mediaInfos = new ArrayList<>();
    private PlayerState playerState;
    private boolean adCurrentlyLoaded;

    ...

    @Override
    public void playAd(AdMediaInfo adMediaInfo) {
      switch (playerState) {
        case LOADED:
          for (VideoAdPlayerCallback callback : callbacks) {
            callback.onPlay(adMediaInfo);
          }
          break;
        case PAUSED:
          for (VideoAdPlayerCallback callback : callbacks) {
            callback.onResume(adMediaInfo);
          }
          break;
        case PLAYING:
          // Intentionally and silently ignore since it is already playing from a prior media item,
          // note that onPlay is triggered by positionDiscontinuity.
          return;
        case IDLE:
          throw new IllegalStateException("Call to playAd when player state is not LOADED.");
      }
      playerState = PlayerState.PLAYING;
      player.setPlayWhenReady(true);
    }

    @Override
    public void loadAd(AdMediaInfo adMediaInfo, AdPodInfo adPodInfo) {
      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;
    }

    @Override
    public void stopAd(AdMediaInfo adMediaInfo) {
      if (allAdsInBreakHavePlayed()) {
        if (isFinalAd(adMediaInfo)) {
          // handle clean up after all ads have played.
        } else {
          seekToNextItem(player);
        }
      } else {
        mediaInfos.remove(adMediaInfo);
      }
    }

    private boolean allAdsInBreakHavePlayed() {
      // Code to determine if all the ads in the current ad break have completed.
    }

    private boolean isFinalAd(AdMediaInfo adMediaInfo) {
      // Code to determine if this adMediaInfo is the final ad.
    }

    private void seekToNextItem(YourPlayerClass player) {
      // Code to seek your player to the next media item.
    }

### 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.