IMA (Interactive Media Ads) provides an easy way of integrating the multimedia Ads in your Android app. Our plugin is developed on top of Google IMA SDK.
Benefit of using our plugin with our Player is that you don't need to handle Content and Ad playback separately. It is very easy to integrate with in a very few lines on code where App needs to pass Ad url in our IMAConfig and our plugin will handle Ad playback. Switching between Content and Ad playback will be taken care by plugin.
It gives more out of the box features like Advertising Layout, Client Side Ad playback, Server Side Ad insertion or Dynamic Ad Insertion (DAI) and easy to use API mechanism.
For Client Side Ads, App should use IMAPlugin and for DAI, IMADAIPlugin should be used.
For IMA and IMADAI, there is single dependency.
Add IMA plugin dependency to build.gradle. In android, we keep all plugins aligned with same version.
implementation 'com.kaltura.playkit:imaplugin:x.x.x'
You can find the latest version here:
IMPORTANT NOTE: Starting from version IMAPlugin 4.23.0 (IMA SDK 3.25.1), includes the
com.google.android.gms.permission.AD_IDpermission in the SDK's manifest that is automatically merged into the app manifest by Android build tools. To learn more about the AD_ID permission declaration, including how to disable it, refer to this Play Console Help article.
val playerInitOptions = PlayerInitOptions(PARTNER_ID)
playerInitOptions.setAutoPlay(true)
...
...
// IMA Configuration
val pkPluginConfigs = PKPluginConfigs()
val adsConfig = IMAConfig().setAdTagUrl("AD_URL").setVideoMimeTypes("MIME_TYPES")
pkPluginConfigs.setPluginConfig(IMAPlugin.factory.name, adsConfig)
playerInitOptions.setPluginConfigs(pkPluginConfigs)
val playerInitOptions = PlayerInitOptions(PARTNER_ID)
playerInitOptions.setAutoPlay(true)
...
...
// IMADAI Live Configuration
val pkPluginConfigs = PKPluginConfigs()
val assetTitle = "Title"
val assetKey = "Asset_Key"
val apiKey: String? = "KEY"
val streamFormat = StreamRequest.StreamFormat.HLS OR DASH
val licenseUrl: String? = "License"
return IMADAIConfig.getLiveIMADAIConfig(assetTitle,
assetKey,
apiKey,
streamFormat, licenseUrl)
// IMADAI VOD Configuration
val assetTitle = "BBB-widevine"
val apiKey: String? = "KEY"
val contentSourceId = "Source_Id"
val videoId = "video_id"
val streamFormat = StreamRequest.StreamFormat.DASH OR HLS
val licenseUrl = "License"
return IMADAIConfig.getVodIMADAIConfig(assetTitle,
contentSourceId,
videoId,
apiKey,
streamFormat,
licenseUrl)
pkPluginConfigs.setPluginConfig(IMADAIPlugin.factory.name, assetTitle)
playerInitOptions.setPluginConfigs(pkPluginConfigs)
Once the plugin config is passed to the init options then PlayerInitOptions needs to be passed to the player creation.
Example for Kaltura OTT Player,
player = KalturaOttPlayer.create(this@MainActivity, playerInitOptions)
Application can call updatePluginConfig on Player object with the new IMAConfig.
player?.updatePluginConfig(IMAPlugin.factory.name, "new adsConfig")
In case, if App don't want to play the Ad for the next media then App can pass empty Ad URL in IMAConfig. By doing so, our plugin will drop the Ad player and will play the content.
NOTE: Few features are not configurable for IMADAI config.
Pass the VMAP or VAST Ad tag URL for the Ad Playback.
Pass the VAST or VMAP Ad response instead of making a request via an Ad tag URL.
Allows you to specify the language to be used to localize ads and the Ad player UI controls. The supported codes can be found in the locale codes and are closely related to the two-letter ISO 639-1 language codes. If invalid or unsupported, the language will default to "en" for English.
Default is AdTagType.VAST and support for AdTagType.VMAP as well. AdTagType.VPAID Ads are not supported on Android. Check the Support guide here.
This feature is Noop (No operation). Default is false.
Maximum recommended bitrate. The value is in "kbit/s". IMA SDK will pick media with bitrate below the specified max, or the closest bitrate if there is no media with lower bitrate found. Default value is -1, means the bitrate will be selected by the IMA SDK.
Both are true by default.
Sets the Ad UI elements to be rendered by the IMA SDK. If both are false, we remove the support int Ad count down in Ad.
Ad attribution true is required for a countdown timer to be displayed and set if Ad countdown will be shown or not.
All values in the list are instances of UiElement. Some elements may be required to be displayed, or unable to be displayed for a given Ad (for instance, the Ad UI may be customizable for DFP direct sold ads, but not for AdSense ads). In these cases, some modifications to the uiElements list may have no effect for specific ads.
Ad load timeout in seconds. Default is '8' seconds.
Default is false. This enables the App to see the underlying IMA SDK logs.
Default is false. If App has given startPosition to the content player which will start the player from the given position then inspite of having media starting from greater than 0th position where pre-roll is played; Pre-roll will be played.
Set whether to focus on the skip button when the skippable Ad can be skipped on Android TV. Default is true. This is a no-op on non-Android TV devices.
Notifies the IMA whether to launch the click-through URL using Custom Tabs feature. Default is false.
One simple example is 'Learn More' button on Ad. User can click on it. So if this feature is enables then URL will open in custom tab and performance
wise which is faster than Chrome or Custom WebView.
More information about Chrome Custom Tabs can be found here
Select the MIME TYPE that IMA will play instead of letting it select it by itself. Default selected MIME TYPE by plugin is "MP4". If null or empty list is set then it will be selected automatically. If MIME TYPE is sent it will try playing one of the given MIME TYPE in the list i.e "video/mp4", "video/webm", "video/3gpp", "application/x-mpegURL", "application/dash+xml".
This only refers to the mime types of videos to be selected for linear ads.
Optional field. It sets the partner Player type. This setting should be used to specify the name of the player being integrated with the SDK. Player type greater than 20 characters will be truncated. The player type specified should be short and unique. This is an optional setting used to improve SDK usability by tracking player types.
Optional field. It sets the partner Player version. This setting should be used to specify the name of the player version being integrated with the SDK. Player version greater than 20 characters will be truncated. The player version specified should be short and unique. This is an optional setting used to improve SDK usability by tracking player types.
DEFAULT_CONTENT_DURATION = -3
Specifies the duration of the content in seconds to be shown.This optional parameter is used by AdX requests. It is recommended for AdX users.
Default value is DEFAULT_CONTENT_DURATION. By default postroll preloading is disabled. DEFAULT_CONTENT_DURATION is the fixed value given by IMA.
If App will set any other value instead of DEFAULT_CONTENT_DURATION then
postroll will be preloaded.
Session ID is a temporary random ID. It is used exclusively for frequency capping. A session ID must be a UUID, or an empty string if app doesn't want the SDK to use capping (Useful for changeMedia).
Following are the AdEvents for IMA and IMADAI plugin. App can listen to any AdEvent as following,
player?.addListener(this, AdEvent.loaded) { event ->
log.d("AD LOADED")
}Fired when the VAST response has been received. Sends the AdInfo payload to the App.
Fired when an Ad starts playing. Sends the AdInfo payload to the App.
Fired when an Ad is paused. Sends the AdInfo payload to the App.
Fired when an Ad is resumed. Sends the AdInfo payload to the App.
Fired when an Ad was skipped. Sends the AdInfo payload to the App.
Fired when VOD stream cuepoints have changed. Sends the AdCuePoints payload to App. App can extract the cuepoints list from AdCuePoints object.
Sends the Ad current position payload.
Sends the adTagUrl and isAutoPlay payload.
Sends the Ad position when the Ad buffer starts.
Sends the Ad position when the Ad buffer ends.
Sends the Ad current position payload.
Whenever there is a video bitrate change for Ad, this event is fired with width, height and bitrate payload.
Fired when An Ad is clicked. Sends the clickThruUrl in payload.
Send PKError payload when the Ad fails. PKError contains the severity, error message etc.
Only for DAI Ads. Called when the Ad source is selected. Sends sourceURL in the payload.
Fired when the Ad is started the playback.
Not in use.
Fired when the Ad playhead crosses first quartile.
Fired when the Ad playhead crosses midpoint.
Fired when the Ad playhead crosses third quartile.
Fired when an Ad completes playing.
Fired when an Ad changes its skippable state.
Fired when a non-clickthrough portion of a video Ad is clicked.
This event only fires for Connected TV devices. The user has closed the icon fallback image dialog. This may be a good time to resume Ad playback if the user is ready to continue playing the Ad.
The user has tapped an Ad icon. On Android mobile apps, the SDK will navigate to the landing page. On Connected TV devices, the SDK will present a modal dialog containing the VAST icon fallback image.
Fired when an Ad break is ready from VMAP or Ad rule ads.
Fired when an Ad break in a stream starts. Communicated to the publisher via player APIs.
Fired when an Ad break will not play back any ads.
Fired when an Ad break is not played with in the timeout range. DEFAULT_AD_LOAD_TIMEOUT is 8 seconds.
Fired when content should be paused. This usually happens right before an Ad is about to hide the content.
Fired when content should be resumed. This usually happens when an Ad finishes or collapses.
Fired when the ads manager is done playing all the valid ads in the Ads response, or when the response doesn't return any valid Ads.
Not in use.
Only for AdLayout
Fired when an Ad request failed and the player is trying to request the fallback.
Only for AdLayout
Fired when the all fallback requests failed.
To setup companion Ads, App can create a ViewGroup as below in the Activity's layout.
<LinearLayout
android:layout_width="300dp"
android:layout_height="150dp"
android:layout_gravity="center_horizontal"
android:gravity="center"
android:textAlignment="center"
android:id="@+id/companionAdSlot"
android:background="#00000000">
<TextView
android:id="@+id/companionPlaceholder"
android:text="companionPlaceholder"
android:textAlignment="center"
android:gravity="center_horizontal"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:textSize="16dp"/>
</LinearLayout>Then after getting it's layout Id. App can using the following API,
setCompanionAdConfig(ViewGroup companionAdView, Integer companionAdWidth, Integer companionAdHeight)
Height and Width of the companion Ad can be passed to the API along with the ViewGroup.
NOTE:
CompanionAdSlot.FLUID_SIZEcan be passed forcompanionAdWidthandcompanionAdHeight. Fluid companion ads have no fixed size, but rather adapt to fit the creative content they display.
In order to clear the Companion Ad for the next media, App should not send anything with the new IMAConfig object.
Registers a view that overlays or obstructs this container as "friendly" for viewability measurement purposes. Please check OM SDK what is and what is not allowed to be registered.
API to register FriendlyObstructions,
addFriendlyObstruction(PKFriendlyObstruction friendlyObstruction)
PKFriendlyObstruction object can be created as below,
PKFriendlyObstruction(View friendlyView, FriendlyObstructionPurpose friendlyObstructionPurpose, String detailedReason)
FriendlyObstructionPurpose is an Enum having values VIDEO_CONTROLS, CLOSE_AD, NOT_VISIBLE and OTHER.
By default the details reason is DETAILED_REASON_UNAVAILABLE = "detailedReasonUnavailable"
With Ad Layout config app can create its own AdBreak timeline using your VAST tags. AdBreak can be set as Pre, Mid and Post rolls and each AdBreak can contain a single VAST tag or multiple tags, either as a AdPod, but also as a Waterfall.
This feature is only supported in Kaltura-Player.
See the migration guide to Kaltura-Player, if you are using Playkit
For more details about AdLayout, please check here.
setAdAutoPlayOnResume(boolean adAutoPlayOnResume)
This feature is hooked with PlayerSettings. PlayerSettings talks about more of the content playback rather than Ad playback.
But if App is using this API then if App goes to background and comes to foreground then Ad will autoplay. Default is true. In order to reverse the defined behavior, App can use this API.
Does app need to handle background/foreground when Ad is playing back ?
App needs to call player.onApplicationPaused() while going in background and player.onApplicationResumed(); when comes to foreground.
Please make sure that player instance is not null.
How to pause the Ad playback ?
App can call player.pause() simply. There is no special handling required for Ad playback. SDK handles the flow of Ad and Content playback internally.
What if app wants to show a Ad progress bar during the Ad playback ?
App can get AdController using the player instance val adController = player?.getController(AdController::class.java).
AdController has APIs to get the duration and current position. Please check the sample implementation here
How to show loader when Ad buffers in slow networks ?
App can listen to AdEvent.adBufferStart and AdEvent.adBufferEnd to show and hide loader.
How to know that content is paused for the Ad playback and content is resumed after the Ad completion?
App can listen to AdEvent.contentResumeRequested and AdEvent.contentPauseRequested.
How to find the reason behind Ad failure ?
App can listen to AdEvent.error. event payload has PKError object which contains the exception and the severity of the error.
Can app use IMA and IMADAI plugin together for one media?
For the time, No. We recommend to use the plugins standalone.
Can app play preroll using IMADAI plugin ?
For the time, No. App can not give a single preroll Ad to IMADAIConfig and then let the DAI media to playback.
Ads configured with in DAI streams can be played.
How to unregister the plugin ?
There is no API to unregister the plugin. In case, if app doesn't want to configure any Ad then pass null or empty AdTag in the configuration.
How to check the Google IMASDK version used by plugin ?
Google IMASDK version can be found here. You can change the Tag in Github repo as per your Kaltura-Player/Player version.
Can I use different version IMA plugin than Kaltura-Player/Playkit version ?
No. Because we sync the changes across the repositories hence recommendation is to use the same plugin version as Kaltura-Player/Playkit.
Why should we use Kaltura IMA plugin ?
Our plugin is developed by keeping in mind to let the App developers write minimum lines of Player of Ad playback code. Within few lines of code, developers can setup the content and Ad playback. Developers should not worry about the video switching from Ad to Content playback or vice-versa. Our plugin is doing all the heavy lifting internally.
Proguard configuration
Configuration can be found here