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, useAdsRenderingSettings.setEnablePreloading()
to set preloading to true. This must be done within the onAdsManagerLoaded()
callback: @
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 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:
//
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.
