Android SDK Reference
Introduction
Our Android SDK allows you to easily embed videos on Android environments.
In this article, you’ll find the exhaustive SDK Reference to help you tailor your unique video experience for your Android apps and explore the available runtime Player parameters, methods, events and states.
Getting started
If you’re new to our Android SDK, we recommend checking our Getting started guide to help you set up the SDK, get familiar with the embed basics and see how to use each element of the SDK.
Runtime Player parameters
While the main Player experience is controlled using the settings defined in your Player configuration, additional runtime customization is achievable using client-side parameters.
Check the dedicated guide to see how to add runtime Player parameters with the Android SDK.
Parameter | Default | Description | Type |
---|---|---|---|
video | undefined | The ID of the video to load | String |
playlist | undefined | The ID of the playlist to load | String |
customConfig | undefined | Define advertising configuration by passing in keys and values. More details E.g. customConfig[key]=values | Object |
scaleMode | fit | To adjust the player’s video focus Possible values: fit , fill , fillLeft , fillRight , fillTop & fillBottom | Enum |
mute | false | Whether to mute the video or not. To note, enabling mute may impact monetization. The Player provides smart mute behavior, it tries to automatically start the video playback with sound. If this isn’t possible due to browser prevention, there is a fallback mechanism and the Player reattempts to play the video but with the sound set to mute. Possible values: true or false | Boolean |
startTime | 0 | Specify the time (in seconds) from which the video should start playing | Number |
loop | false | To set the video to loop. Learn more Possible values: true or false | Boolean |
defaultFullscreenOrientation | Orientation.Landscape | Specify which orientation should be used for fullscreen. Possible values: Landscape , ReverseLandscape , Portrait or ReversePortrait | Sealed class |
Methods
API commands can be called to programmatically create and control the Player. Check the dedicated guide to see how to use methods.
Initialization methods
Name | Info | Example |
Create Player | To create the player object Player ID is mandatory and can be created and managed either through the “Players” tab in the Dailymotion Studio or programmatically via the player REST API. | Dailymotion.createPlayer( |
Player methods
Method | Info | Type |
loadContent(videoId: String?, playlistId: String?, startTime: Long?) | To load a video or a playlist. You can play a specific video followed by a playlist by specifying both the video and playlist IDs Note that the loaded content playback is based on the autostart configuration defined in the PlayerID settings | String?, |
play() | To play video playback | – |
pause() | To pause video playback | – |
setFullScreen(fullscreen: Boolean, orientation: Orientation) | To enable or disable fullscreen mode with fullscreen: true or false If fullscreen: true , fullscreen orientation is by default orientation: Landscape Other available values for orientation are Landscape , ReverseLandscape , Portrait or ReversePortrait E.g. setFullScreen(fullscreen: true, orientation: ReverseLandscape) | Boolean |
setSubtitles(wantedSubtitle: String) | To activate a subtitles track to a specified language if available | String |
setQuality(wantedQuality: String) | To set the video’s quality to the specified quality | String |
seek(seekTo:) | To seek to the specified time in video playback in seconds | Double |
SetMute() | Mute the player | Boolean |
setCustomConfig(customConfig:) | To set the config for ads Dynamically update the advertising parameter value, use the method to send a new value which then gets updated when the player loads the next video file Learn more | Map<String, String> |
setPlaybackSpeed(playbackSpeed: Double) | To modify the playback speed, if the value passed does not match one from the list, the playback speed is rounded to the superior one. The playback speed is kept across videos. Possible values: [0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2] | Double |
setScaleMode(wantedScaleMode: String) | To adjust the player view of the video screen Possible values: fit , fill , fillLeft , fillRight , fillTop & fillBottom | String |
getState(callback: PlayerStateCallback) | To retrieve the current state of the player | PlayerStateCallback |
setLogLevel(LogLevel.String) | To determine the level of details logs should return. Available values are None Info Warning Error and All | String |
destroy() | Destroy the Player. Once the Player is destroyed, PlayerView will become useless. |
Events
Check the dedicated guide to learn how to listen to events.
Player events
Event | INFO |
onPlayerError | Sent when the player triggers an error. |
onPlayerStart | Sent the first time the player attempts to start the playback, either because of user interaction, an autoplay parameter or an API call (e.g play() , loadContent() , etc.) |
onPlayerEnd | Sent when the playback of the content video, and eventual post-roll ad video is completed |
onPlayerVideoChange | Sent when a new video has been loaded in the player. (e.g. after calling loadContent({ video: 'xID' }) , or at player start-up) |
onPlayerVolumeChange | Sent when the volume level or mute state changes |
onFullscreenRequested | Sent when the fullscreen mode is requested |
onPlayerPlaybackPermission | Sent each time any playback request has failed or if the initial playback attempt has succeeded |
onPlayerPlaybackSpeedChange | Sent when the playback speed changes |
onPlayerScaleModeChange | Sent when the scale mode of the player changes after using setScaleMode() |
Video events
Event | Info |
onVideoSubtitlesChange | Sent when the current subtitle changes |
onVideoSubtitlesReady | Sent when subtitles are available |
onVideoDurationChange | Sent when the duration property of the video becomes available or changes after a new video load |
onVideoEnd | Sent when the player completes playback of the content video |
onVideoPause | Sent when the video playback has paused |
onVideoPlay | Sent when the playback state of the content video is no longer paused, as a result of the play method or the autoplay attribute |
onVideoPlaying | Sent when the content video starts playing, after the play or waiting event |
onVideoProgress | Sent when the browser is fetching the media data |
onVideoQualitiesReady | Sent when video qualities are available |
onVideoQualityChange | Sent when the video quality changes |
onVideoSeekEnd | Sent when the player has completed a seeking operation |
onVideoSeekStart | Sent when the player starts to seek to another position in the video timeline |
onVideoStart | Sent when the player begins playback of the content video |
onVideoTimeChange | Sent when the playback position changes |
onVideoBuffering | Sent when the player has to temporarily stop video playback for further buffering of content |
Ad events
Event | Info |
onAdCompanionsReady | Sent when a companion ad is received. Companion ads should be played in sync with the main ad (linear/non-linear) by listening to events AD_START and AD_END |
onAdDurationChange | Sent when the duration property of the video advertisement becomes available or changes after a new video load |
onAdEnd | Sent when the player completes playback of an ad |
onAdPause | Sent when the player pauses an ad |
onAdPlay | Sent when the ad playback starts or continues after being in a paused state |
onAdstart | Sent when the player begins playback of an ad video |
onAdTimeChange | Sent when the playback position of an ad changes |
onAdImpression | Sent when the first ad frame is displayed |
onAdLoaded | Sent when the player has loaded and buffered the creative’s media and assets either fully or to the extent that it is ready to play the media |
onAdClick | Sent when a user clicks on a video ad |
onAdReadyToFetch | Sent a few seconds before an request is made: – First preroll: 2 sec – Consecutive preroll: 4 sec – Midroll & postroll: 6 sec Important: Only sent when Player setting enable_wait_for_custom_config is true |
State
class PlayerState(
// The description of the ad
var adDescription: String? = null,
// The advertiser name
var adAdvertiserName: String? = null,
/// The universal ad id node from the VAST or the ad id of the creative node from the VAST
var adCreativeAdId: String? = null,
// The id of the creative node from the VAST
var adCreativeId: String? = null,
// The reason why the last ad ended
var adEndedReason: String? = null,
// Contains information about the last error that occurred with the ad
var adError: String? = null,
// The id of the ad
var adId: String? = null,
// If an ad resource is running
var adIsPlaying: Boolean? = null,
// If the ad can be skipped by the user at this moment
var adIsSkippable: Boolean? = null,
// The position of the ad in the video
var adPosition: String? = null,
// The remaining time before the ad can be skipped or -1 if no ad is running
var adSkipOffset: Long? = null,
// The title of the ad
var adTitle: String? = null,
// The player current aspect ratio
var playerAspectRatio: String? = null,
// If the player is ready to play
var playerIsCriticalPathReady: Boolean? = null,
// If the player is allowed to play, depending on the browser permissions
var playerIsPlaybackAllowed: Boolean? = null,
// The reason why the playback has been allowed or not
var playerPlaybackPermissionReason: String? = null,
// The current mode where the player is displayed
var playerPresentationMode: String? = null,
// The player’s current scale mode
var playerScaleMode: String? = null,
// If the video is created for Children
var videoIsCreatedForKids: Boolean? = null,
// If the player controls are enabled
var playerAreControlsEnabled: Boolean? = null,
// If the player is muted
var playerIsMuted: Boolean? = null,
// If the player is currently playing video or ad content
var playerIsPlaying: Boolean? = null,
// If the player is loading the media resource
var playerIsBuffering: Boolean? = null,
// The current playback speed
var playerPlaybackSpeed: Long? = null,
// If the next and previous controls in the PiP are enabled
var playerIsNavigationEnabled: Boolean? = null,
// If the player is in replay screen
var playerIsReplayScreen: Boolean? = null,
// If the video required a password to be read
var videoIsPasswordRequired: Boolean? = null,
// If the player is in start screen
var playerIsStartScreen: Boolean? = null,
// If the player has the alert dialog displayed
var playerIsAlertDialogDisplayed: Boolean? = null,
// The id of the video previous video which was played
var playerPrevVideo: String? = null,
// The id of the video next video in the queue
var playerNextVideo: String? = null,
// The id of the owner of the video
var videoOwnerId: String? = null,
// The user name of the owner of the video
var videoOwnerUsername: String? = null,
// The screen name of the owner of the video
var videoOwnerScreenName: String? = null,
// The video qualities that are available
var videoQualitiesList: List<String>? = null,
// The quality value of the video loaded
var videoQuality: String? = null,
// The language codes of the subtitle tracks which are available for the current media resource
var videoSubtitlesList: List<String>? = null,
// The language code of the subtitle track that is currently enabled
var videoSubtitles: String? = null,
// The unique Id of the video
var videoId: String? = null,
// The title of the video loaded
var videoTitle: String? = null,
// The timestamp that corresponds to the creation of the video
var videoCreatedTime: Double? = null,
// The current volume level. The volume and mute params operate separately, therefore, you could have a player with full volume, but also muted
var playerVolume: Double? = null,
// The current playback position of an ad in seconds
var adTime: Double? = null,
// The duration time of the ad resource in seconds
var adDuration: Double? = null,
// The current playback position of the video in seconds
var videoTime: Double? = null,
// The duration time of the video resource in seconds
var videoDuration: Double? = null,
var playerError: Error? = null,
var adCompanion: AdCompanion? = null
) : PlayerEvent(...) {
class Error(
val title: String? = null,
val message: String? = null
)
class AdCompanion(
val id: String? = null,
val adId: String? = null,
val sequence: String? = null,
val apiFramework: String? = null,
val type: String? = null,
val adCompanionRequired: Boolean? = null,
)
}
Check the guide to see how to retrieve a Player state.
Changelog
Version 1.2.5
Date: 2024-11-20
- Fix crash due to IMA SDK passing
null
parameter to an interface whose parameters are annotated with @NonNull
Version 1.2.4
Date: 2024-09-03
- Integrated new OM SDK 1.5.0
Version 1.2.3
Date: 2024-08-08
- Added new Player method
setPlaybackSpeed
- Added new Player event
onPlayerPlaybackSpeedChange
Version 1.2.2
Date: 2024-08-01
- Added new
onAdReadyToFetch
ad event
Version 1.2.1
Date: 2024-06-18
- Disable ad stack when Chromecast is running
- Fix SDK R8 Consumer proguard
Version 1.2.0
Date: 2024-04-26
Fixes:
- Fix on load command
startTime
argument - Fix on
adStart
event not being sent properly - Fixed desync between ad playing and ad play/pause button control states
- Hide ad controls based on Player configuration field
enable_ads_controls
- Removed Dailymotion branding on Chromecast receiver
Added support for IMA Android SDK 3.33.0:
- Previous Dailymotion Android SDK versions (before
1.2.0
) do not support IMA Android SDKv3.33.0.
- To use IMA SDK
v3.33.0.
, we invite you to update to Dailymotion SDK version1.2.0.
and above
Version 1.1.0
Date: 2024-03-06
- Added Chromecast integration
Version 1.0.9
Date: 2024-02-14
- Fix for Player initialization issue
- Set
targetSdk
to 34
Version 1.0.8
Date: 2023-11-07
- Fix for default fullscreen landscape orientation issue
Version 1.0.7
Date: 2023-10-19
- New public API method
setFullscreen()
for PlayerView - New public API method
destroy()
for PlayerView - Added gradient below IMA Native controls
Version 1.0.6
Date: 2023-08-31
- Fix on R8 configuration
Version 1.0.5
Date: 2023-08-30
- Fix for Player loading issue
Version 1.0.4
Date: 2023-08-08
- Added fullscreen behaviour: out of the box, jetpack navigation and custom
Version 1.0.3
Date: 2023-07-21
- Fix on R8 configuration
Version 1.0.2
Date: 2023-07-21
- Fix for IMA and DM Player muted state issue
Version 1.0.1
Date: 2023-07-18
- Fix for Player loading issue –
playerSetupFailed
issue
Version 1.0.0
Date: 2023-06-26
Initial release